Guidelines Block Implementation

Author: debritto

CHANGELOG.md

@@ -5,6 +5,21 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] - 2026-03-06
+
+### Added
+- `grammar/synesis.lark`: keyword `KW_GUIDELINES` e regras `guidelines_block` / `guidelines_lines`
+  para suporte ao bloco `GUIDELINES...END GUIDELINES` dentro de `FIELD...END FIELD`.
+- `ast/nodes.py`: campo `guidelines: Optional[str] = None` em `FieldSpec`; serializado
+  automaticamente via `to_dict()` como `"guidelines"` no JSON exportado.
+- `parser/transformer.py`: handler `KW_GUIDELINES`, transformers `guidelines_lines` e
+  `guidelines_block`, detecção em `field_props()`, extração em `field_def_block()`.
+
+### Notes
+- Adição aditiva: templates sem `GUIDELINES` continuam compilando sem alteração.
+- Semântica pass-through: o compilador armazena e exporta o conteúdo sem interpretá-lo.
+- Consumidores (MCP Server, agentes de IA) lêem `guidelines` via `synesis.load()` → JSON.
+
 ## [0.2.11] - 2026-03-06
 
 ### Fixed

bug-report-lark-vargs-meta.md

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "synesis"
-version = "0.2.11"
+version = "0.3.0"
 description = "The confluence of information into intelligence - A DSL compiler that transforms qualitative research annotations into canonical knowledge structures"
 readme = "README.md"
 requires-python = ">=3.10"

pyproject.toml

@@ -96,6 +96,7 @@ class FieldSpec:
     values: Optional[List[OrderedValue]] = None
     relations: Optional[Dict[str, str]] = None
     arity: Optional[str] = None
+    guidelines: Optional[str] = None
     location: Optional[SourceLocation] = None
 
     def to_dict(self) -> Dict[str, Any]:
@@ -108,6 +109,7 @@ def to_dict(self) -> Dict[str, Any]:
             "values": [v.to_dict() for v in self.values] if self.values else None,
             "relations": self.relations,
             "arity": self.arity,
+            "guidelines": self.guidelines,
             "location": self.location.to_dict() if self.location else None,
         }
 

synesis/ast/nodes.py

@@ -67,6 +67,7 @@ KW_SCALE.5: /scale/i
 KW_ENUMERATED.5: /enumerated/i
 KW_ORDERED.5: /ordered/i
 KW_TOPIC.5: /topic/i
+KW_GUIDELINES.5: /guidelines/i
 
 // ============================================
 // BLOCO PROJECT
@@ -88,6 +89,9 @@ metadata_line: TEXT_LINE NEWLINE
 description: KW_DESCRIPTION NEWLINE description_lines KW_END KW_DESCRIPTION NEWLINE?
 description_lines: (TEXT_LINE NEWLINE | NEWLINE)+
 
+guidelines_block: KW_GUIDELINES NEWLINE guidelines_lines KW_END KW_GUIDELINES
+guidelines_lines: (_INDENT | _DEDENT | TEXT_LINE NEWLINE | NEWLINE)*
+
 // ============================================
 // BLOCOS DE ANOTACAO
 // ============================================
@@ -144,6 +148,7 @@ field_props: KW_SCOPE scope_type
            | KW_ARITY COMPARATOR NUMBER
            | KW_VALUES value_list KW_END KW_VALUES
            | KW_RELATIONS relation_list KW_END KW_RELATIONS
+           | guidelines_block
 
 format_spec: IDENTIFIER | scale_format
 scale_format: "[" NUMBER ".." NUMBER "]"

synesis/grammar/synesis.lark

@@ -378,6 +378,9 @@ def KW_ORDERED(self, token: Token) -> str:  # noqa: N802
     def KW_TOPIC(self, token: Token) -> str:  # noqa: N802
         return token.value.upper()
 
+    def KW_GUIDELINES(self, token: Token) -> str:  # noqa: N802
+        return token.value.upper()
+
     def COMPARATOR(self, token: Token) -> str:  # noqa: N802
         return token.value
 
@@ -529,6 +532,36 @@ def description(self, items: List[Any]) -> str:
     def description_lines(self, items: List[Any]) -> List[Any]:
         return items
 
+    def guidelines_lines(self, items: List[Any]) -> List[Any]:
+        return items
+
+    def guidelines_block(self, items: List[Any]) -> Tuple[str, Any]:
+        lines: List[str] = []
+        pending_blank = False
+        keywords = {"GUIDELINES", "END"}
+        flattened: List[Any] = []
+        for item in items:
+            if isinstance(item, list):
+                flattened.extend(item)
+            else:
+                flattened.append(item)
+        for item in flattened:
+            if isinstance(item, Token) and item.type in {"NEWLINE", "_INDENT", "_DEDENT"}:
+                if item.type == "NEWLINE":
+                    if pending_blank:
+                        lines.append("")
+                        pending_blank = False
+                    else:
+                        pending_blank = True
+                continue
+            if isinstance(item, str):
+                if item.upper() in keywords:
+                    continue
+                lines.append(item)
+                pending_blank = False
+        text = "\n".join(lines).strip()
+        return ("guidelines", text if text else None)
+
     @v_args(tree=True)
     def source_block(self, tree: Any) -> SourceNode:
         meta = tree.meta
@@ -745,6 +778,7 @@ def field_def_block(self, tree: Any) -> FieldSpec:
         values = None
         relations = None
         arity = None
+        guidelines = None
         for prop in props:
             key, value = prop
             if key == "scope":
@@ -759,6 +793,8 @@ def field_def_block(self, tree: Any) -> FieldSpec:
                 relations = value
             elif key == "arity":
                 arity = value
+            elif key == "guidelines":
+                guidelines = value
         if scope is None:
             scope = Scope.ITEM
         return FieldSpec(
@@ -770,6 +806,7 @@ def field_def_block(self, tree: Any) -> FieldSpec:
             values=values,
             relations=relations,
             arity=arity,
+            guidelines=guidelines,
             location=_source_location(self.file_path, meta),
         )
 
@@ -790,6 +827,8 @@ def field_props(self, items: List[Any]) -> Tuple[str, Any]:
             return ("arity", f"{items[1]} {items[2]}")
         if items[0] == "VALUES":
             return ("values", items[1])
+        if isinstance(items[0], tuple) and items[0][0] == "guidelines":
+            return items[0]
         return ("relations", items[1])
 
     def scope_type(self, items: List[Any]) -> str: