grain-kit 0.2.0__tar.gz → 0.3.1__tar.gz

{grain_kit-0.2.0/src/grain_kit.egg-info → grain_kit-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: grain-kit
-Version: 0.2.0
+Version: 0.3.1
 Summary: CLI-first workflow toolkit for structured AI-assisted software development.
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/Diwata-Labs/Grain
@@ -22,11 +22,15 @@ License-File: LICENSE
 Requires-Dist: click>=8.1
 Requires-Dist: PyYAML>=6.0
 Requires-Dist: networkx>=3.3
+Requires-Dist: textual>=0.67
 Requires-Dist: tree-sitter>=0.25.2
 Requires-Dist: tree-sitter-language-pack>=0.13.0
 Requires-Dist: openpyxl>=3.1
 Requires-Dist: python-docx>=1.1
 Requires-Dist: pdfplumber>=0.11
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
 Provides-Extra: release
 Requires-Dist: build>=1.4.3; extra == "release"
 Requires-Dist: twine>=5.1; extra == "release"
@@ -235,6 +239,87 @@ In practice, the agent should use Grain as the workflow layer for the repository
 The CLI is the delivery surface.
 The product value is the workflow structure it gives the agent.
 
+### Codex and CLI-first usage
+
+For Codex or any environment that can invoke local commands directly, the canonical integration path is still the Grain CLI.
+
+Preferred operating pattern:
+
+```bash
+grain --format json workflow next
+grain prompt show --format json
+```
+
+Use JSON output when the calling environment wants structured state.
+Use text output when a human operator is driving the loop directly.
+
+For Codex-style usage:
+- call `grain` commands directly
+- prefer `grain workflow next` to decide the next legal state transition
+- use `grain prompt show` to surface the stable prompt entrypoint
+- keep task execution packet-first and file-backed
+- treat `grain mcp` as optional, not required
+
+### Claude Desktop and MCP-style usage
+
+For desktop clients that prefer MCP tools over direct CLI execution, use the local MCP wrapper:
+
+```bash
+grain --format json mcp manifest
+grain mcp serve
+```
+
+Current intent:
+- Codex/tool-execution path: direct CLI
+- Claude/Desktop-style path: local stdio MCP wrapper over the same Grain services
+- both paths preserve the same workflow rules and packet-first boundaries
+
+### Assay verification loop
+
+Phase 28 adds the first packet-local verification bridge for Assay-backed review.
+
+Current commands:
+
+```bash
+grain verify submit --id TASK-0001
+grain verify status --verification-id VERIFY-0001-001
+grain verify ingest --verification-id VERIFY-0001-001 --payload payload.json
+```
+
+Operator rules for this slice:
+- submit verification only after the packet has `results.md` and is in `review` or `done`
+- treat `verification_request.json` and `verification_result.json` as packet-local workflow artifacts
+- do not close a task while verification is `pending`
+- if verification is `failed`, resolve the findings or explicitly waive verification before closure
+- keep the loop file-backed: Assay can produce the payload elsewhere, but Grain only reads and records the packet-local artifacts
+
+### Obsidian vault usage
+
+For Obsidian vault work, keep the CLI and packet workflow canonical:
+
+- declare `obsidian_adapter` on the active packet when the task is about vault notes
+- let `grain context build` and the normal workflow loop assemble context from the target note and nearby wiki-linked notes
+- treat `.obsidian/` config as secondary context unless the task is explicitly about vault settings
+- use the local MCP wrapper only as a desktop invocation surface; it does not replace the Grain workflow rules
+
+### Database workflow usage
+
+For database work, keep the same packet-first and local-first posture:
+
+- declare `database_adapter` on the active packet when the task is about schema, migrations, queries, or persistence layers
+- let `grain context build` assemble focused schema, migration, query, and repository context instead of loading broad app code by default
+- review destructive migration risk, rollback expectations, and schema/query drift before closing the task
+- treat database execution or live mutation tooling as separate future work; the current `v0.3.0` slice is about context, review, and validation guidance
+
+### Crawler workflow usage
+
+For crawler work, keep the same packet-first and local-first posture:
+
+- declare `crawler_adapter` on the active packet when the task is about crawl configs, selectors, extraction schemas, or output validation
+- let `grain context build` assemble focused crawl, selector, extraction, and validation context instead of loading broad app code by default
+- review robots constraints, rate limits, retry policy risk, selector brittleness, and extraction drift before closing the task
+- treat broad crawl execution or live scraping automation as separate future work; the current `v0.3.0` slice is about context, review, and validation guidance
+
 Example instruction for an agent:
 
 ```text
@@ -257,6 +342,8 @@ Your role is to execute work through Grain's state-driven workflow.
 
 Rules:
 - Run `grain workflow next` before deciding what to do.
+- If Grain stops or the repo state looks inconsistent, run `grain workflow explain` before improvising.
+- If the explanation points to drift, run `grain workflow reconcile --dry-run` before making manual repairs.
 - Run `grain prompt show` before executing the next step.
 - Follow the recommended prompt exactly.
 - Work on only one active task packet at a time.
@@ -293,11 +380,20 @@ Typical commands:
 
 ```bash
 grain workflow next
+grain workflow explain
+grain workflow reconcile --dry-run
 grain prompt show
 grain review check --id TASK-0001
 grain task close --id TASK-0001
+grain tui
 ```
 
+When Grain stops:
+
+- use `grain workflow explain` to translate the current gate into concrete operator actions
+- use `grain workflow reconcile --dry-run` when the explanation points to packet/backlog drift
+- return to `grain workflow next` only after the file-backed issue is repaired
+
 If you want Grain to execute one legal state transition and stop at gates:
 
 ```bash
@@ -318,6 +414,55 @@ Grain controls:
 The agent controls:
 - executing the current step correctly
 
+## Terminal UI
+
+`grain tui` is the first operator shell over Grain’s existing CLI and file-backed workflow.
+
+Current TUI surfaces:
+- workflow dashboard and current task status
+- phase backlog and packet artifact inspection
+- prompt preview and compact context summary
+- blocker detail and action feedback
+- execute, review, and close launchers that delegate to the normal Grain workflow services
+
+The TUI is intentionally thin:
+- it reads the same repo files and service outputs the CLI already uses
+- it does not maintain hidden workflow state
+- it does not bypass review or close gates
+
+Current deferrals:
+- deep packet content editors
+- full prompt-body rendering
+- full context export rendering
+- embedded agent terminals
+- multi-project views
+- broad GUI beyond the terminal shell
+
+## Writable office artifacts
+
+Phase 23 adds the first packet-first office mutation workflow for `.docx` and spreadsheets.
+
+Current commands:
+
+```bash
+grain office docx propose --source docs/brief.docx --replace "old=new"
+grain office docx export --source docs/brief.docx --replace "old=new"
+grain office spreadsheet propose --source data/report.xlsx --set "Sheet1!B2=14"
+grain office spreadsheet export --source data/report.xlsx --set "Sheet1!B2=14"
+grain office review show --task-id TASK-0001
+```
+
+Operator rules for this slice:
+- run office commands inside an active task packet, or pass `--task-id` explicitly
+- `.docx` and spreadsheet writes currently support `propose` and `export-as-new-file`
+- every office command persists `office_review.json` into the packet for review inspection
+- review the artifact summary and validator results before closing the packet
+
+What this does not do yet:
+- in-place `apply` for `.docx` or spreadsheets
+- TUI-native office editors
+- desktop/MCP office invocation layers
+
 ## Onboarding flow
 
 Onboarding is one of the most important workflows in Grain because it gives the agent the initial structure it will follow later.

{grain_kit-0.2.0 → grain_kit-0.3.1}/README.md

@@ -198,6 +198,87 @@ In practice, the agent should use Grain as the workflow layer for the repository
 The CLI is the delivery surface.
 The product value is the workflow structure it gives the agent.
 
+### Codex and CLI-first usage
+
+For Codex or any environment that can invoke local commands directly, the canonical integration path is still the Grain CLI.
+
+Preferred operating pattern:
+
+```bash
+grain --format json workflow next
+grain prompt show --format json
+```
+
+Use JSON output when the calling environment wants structured state.
+Use text output when a human operator is driving the loop directly.
+
+For Codex-style usage:
+- call `grain` commands directly
+- prefer `grain workflow next` to decide the next legal state transition
+- use `grain prompt show` to surface the stable prompt entrypoint
+- keep task execution packet-first and file-backed
+- treat `grain mcp` as optional, not required
+
+### Claude Desktop and MCP-style usage
+
+For desktop clients that prefer MCP tools over direct CLI execution, use the local MCP wrapper:
+
+```bash
+grain --format json mcp manifest
+grain mcp serve
+```
+
+Current intent:
+- Codex/tool-execution path: direct CLI
+- Claude/Desktop-style path: local stdio MCP wrapper over the same Grain services
+- both paths preserve the same workflow rules and packet-first boundaries
+
+### Assay verification loop
+
+Phase 28 adds the first packet-local verification bridge for Assay-backed review.
+
+Current commands:
+
+```bash
+grain verify submit --id TASK-0001
+grain verify status --verification-id VERIFY-0001-001
+grain verify ingest --verification-id VERIFY-0001-001 --payload payload.json
+```
+
+Operator rules for this slice:
+- submit verification only after the packet has `results.md` and is in `review` or `done`
+- treat `verification_request.json` and `verification_result.json` as packet-local workflow artifacts
+- do not close a task while verification is `pending`
+- if verification is `failed`, resolve the findings or explicitly waive verification before closure
+- keep the loop file-backed: Assay can produce the payload elsewhere, but Grain only reads and records the packet-local artifacts
+
+### Obsidian vault usage
+
+For Obsidian vault work, keep the CLI and packet workflow canonical:
+
+- declare `obsidian_adapter` on the active packet when the task is about vault notes
+- let `grain context build` and the normal workflow loop assemble context from the target note and nearby wiki-linked notes
+- treat `.obsidian/` config as secondary context unless the task is explicitly about vault settings
+- use the local MCP wrapper only as a desktop invocation surface; it does not replace the Grain workflow rules
+
+### Database workflow usage
+
+For database work, keep the same packet-first and local-first posture:
+
+- declare `database_adapter` on the active packet when the task is about schema, migrations, queries, or persistence layers
+- let `grain context build` assemble focused schema, migration, query, and repository context instead of loading broad app code by default
+- review destructive migration risk, rollback expectations, and schema/query drift before closing the task
+- treat database execution or live mutation tooling as separate future work; the current `v0.3.0` slice is about context, review, and validation guidance
+
+### Crawler workflow usage
+
+For crawler work, keep the same packet-first and local-first posture:
+
+- declare `crawler_adapter` on the active packet when the task is about crawl configs, selectors, extraction schemas, or output validation
+- let `grain context build` assemble focused crawl, selector, extraction, and validation context instead of loading broad app code by default
+- review robots constraints, rate limits, retry policy risk, selector brittleness, and extraction drift before closing the task
+- treat broad crawl execution or live scraping automation as separate future work; the current `v0.3.0` slice is about context, review, and validation guidance
+
 Example instruction for an agent:
 
 ```text
@@ -220,6 +301,8 @@ Your role is to execute work through Grain's state-driven workflow.
 
 Rules:
 - Run `grain workflow next` before deciding what to do.
+- If Grain stops or the repo state looks inconsistent, run `grain workflow explain` before improvising.
+- If the explanation points to drift, run `grain workflow reconcile --dry-run` before making manual repairs.
 - Run `grain prompt show` before executing the next step.
 - Follow the recommended prompt exactly.
 - Work on only one active task packet at a time.
@@ -256,11 +339,20 @@ Typical commands:
 
 ```bash
 grain workflow next
+grain workflow explain
+grain workflow reconcile --dry-run
 grain prompt show
 grain review check --id TASK-0001
 grain task close --id TASK-0001
+grain tui
 ```
 
+When Grain stops:
+
+- use `grain workflow explain` to translate the current gate into concrete operator actions
+- use `grain workflow reconcile --dry-run` when the explanation points to packet/backlog drift
+- return to `grain workflow next` only after the file-backed issue is repaired
+
 If you want Grain to execute one legal state transition and stop at gates:
 
 ```bash
@@ -281,6 +373,55 @@ Grain controls:
 The agent controls:
 - executing the current step correctly
 
+## Terminal UI
+
+`grain tui` is the first operator shell over Grain’s existing CLI and file-backed workflow.
+
+Current TUI surfaces:
+- workflow dashboard and current task status
+- phase backlog and packet artifact inspection
+- prompt preview and compact context summary
+- blocker detail and action feedback
+- execute, review, and close launchers that delegate to the normal Grain workflow services
+
+The TUI is intentionally thin:
+- it reads the same repo files and service outputs the CLI already uses
+- it does not maintain hidden workflow state
+- it does not bypass review or close gates
+
+Current deferrals:
+- deep packet content editors
+- full prompt-body rendering
+- full context export rendering
+- embedded agent terminals
+- multi-project views
+- broad GUI beyond the terminal shell
+
+## Writable office artifacts
+
+Phase 23 adds the first packet-first office mutation workflow for `.docx` and spreadsheets.
+
+Current commands:
+
+```bash
+grain office docx propose --source docs/brief.docx --replace "old=new"
+grain office docx export --source docs/brief.docx --replace "old=new"
+grain office spreadsheet propose --source data/report.xlsx --set "Sheet1!B2=14"
+grain office spreadsheet export --source data/report.xlsx --set "Sheet1!B2=14"
+grain office review show --task-id TASK-0001
+```
+
+Operator rules for this slice:
+- run office commands inside an active task packet, or pass `--task-id` explicitly
+- `.docx` and spreadsheet writes currently support `propose` and `export-as-new-file`
+- every office command persists `office_review.json` into the packet for review inspection
+- review the artifact summary and validator results before closing the packet
+
+What this does not do yet:
+- in-place `apply` for `.docx` or spreadsheets
+- TUI-native office editors
+- desktop/MCP office invocation layers
+
 ## Onboarding flow
 
 Onboarding is one of the most important workflows in Grain because it gives the agent the initial structure it will follow later.

{grain_kit-0.2.0 → grain_kit-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "grain-kit"
-version = "0.2.0"
+version = "0.3.1"
 description = "CLI-first workflow toolkit for structured AI-assisted software development."
 readme = "README.md"
 license = "MIT"
@@ -31,6 +31,7 @@ dependencies = [
     "click>=8.1",
     "PyYAML>=6.0",
     "networkx>=3.3",
+    "textual>=0.67",
     "tree-sitter>=0.25.2",
     "tree-sitter-language-pack>=0.13.0",
     "openpyxl>=3.1",
@@ -42,6 +43,10 @@ dependencies = [
 grain = "grain.cli:cli"
 
 [project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "ruff>=0.4",
+]
 release = [
     "build>=1.4.3",
     "twine>=5.1",

{grain_kit-0.2.0 → grain_kit-0.3.1}/src/grain/adapters/manifest.py

@@ -98,6 +98,110 @@ def load_grain_config(root: Path) -> GrainConfig:
     )
 
 
+@dataclass
+class UpgradePolicy:
+    """upgrade_policy block from docs_manifest.yaml."""
+
+    min_version: str = ""
+    min_version_set_at: str = ""
+    enforce: bool = False
+    enforce_after_days: int = 0
+    message: str = ""
+
+
+def load_upgrade_policy(root: Path) -> UpgradePolicy:
+    """Read the optional ``upgrade_policy:`` block from docs_manifest.yaml.
+
+    Returns an :class:`UpgradePolicy` with defaults for any field not present.
+    Never raises.
+    """
+    try:
+        manifest = load_manifest(root)
+    except Exception:
+        return UpgradePolicy()
+
+    raw = manifest.get("upgrade_policy")
+    if not isinstance(raw, dict):
+        return UpgradePolicy()
+
+    def _str(key: str) -> str:
+        val = raw.get(key, "")
+        return str(val).strip() if val is not None else ""
+
+    def _bool_val(key: str) -> bool:
+        val = raw.get(key, False)
+        return val if isinstance(val, bool) else False
+
+    def _int_val(key: str) -> int:
+        val = raw.get(key, 0)
+        try:
+            return int(val)
+        except (TypeError, ValueError):
+            return 0
+
+    return UpgradePolicy(
+        min_version=_str("min_version"),
+        min_version_set_at=_str("min_version_set_at"),
+        enforce=_bool_val("enforce"),
+        enforce_after_days=_int_val("enforce_after_days"),
+        message=_str("message"),
+    )
+
+
+@dataclass
+class BranchPolicy:
+    """branch_policy block from docs_manifest.yaml."""
+
+    mode: str = "off"           # "phase" | "task" | "off"
+    pattern: str = ""           # optional override; empty = use mode default
+    enforce: bool = False
+    enforce_after_days: int = 0
+    message: str = ""
+
+
+def load_branch_policy(root: Path) -> BranchPolicy:
+    """Read the optional ``branch_policy:`` block from docs_manifest.yaml.
+
+    Returns a :class:`BranchPolicy` with defaults (mode: off) for any field not present.
+    Never raises.
+    """
+    try:
+        manifest = load_manifest(root)
+    except Exception:
+        return BranchPolicy()
+
+    raw = manifest.get("branch_policy")
+    if not isinstance(raw, dict):
+        return BranchPolicy()
+
+    def _str(key: str, default: str = "") -> str:
+        val = raw.get(key, default)
+        return str(val).strip() if val is not None else default
+
+    def _bool_val(key: str) -> bool:
+        val = raw.get(key, False)
+        return val if isinstance(val, bool) else False
+
+    def _int_val(key: str) -> int:
+        val = raw.get(key, 0)
+        try:
+            return int(val)
+        except (TypeError, ValueError):
+            return 0
+
+    mode = _str("mode", "off")
+    if mode not in {"phase", "task", "off"}:
+        mode = "off"
+
+    return BranchPolicy(
+        mode=mode,
+        pattern=_str("pattern"),
+        enforce=_bool_val("enforce"),
+        enforce_after_days=_int_val("enforce_after_days"),
+        message=_str("message"),
+    )
+
+
 def load_completion_policy(root: Path) -> CompletionPolicy:
     try:
         manifest = load_manifest(root)