From e1afa510e4f5fa2c202a420398507b0ff5a970b9 Mon Sep 17 00:00:00 2001 From: Atri10 <64589033+Atri10@users.noreply.github.com> Date: Mon, 19 Oct 2026 15:47:15 +0530 Subject: [PATCH] feat(skills): ship the engine inside the executor skill MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit An installed skill is a copied directory, so the engine at engine/ — a sibling of skills/ — never reached users and the bare 'executor' command the skills name did not exist. The router skill now carries a generated mirror of the engine at scripts/lib/executor/ plus a launcher that resolves it relative to itself, so installation needs no pip, no PYTHONPATH, and no PATH edit. engine/executor/ remains the source the suite imports; scripts/sync_engine.py is the only writer of the bundle and --check is a CI gate, with a drift test in the suite. CI also copies the skill out of the tree, drops PYTHONPATH, and runs the launcher from an unrelated directory. Docs: README install path rewritten around the launcher, CONTRIBUTING describes the Python entry points and bundle rule, every skill states the invocation spelling, and source citations point inside the skill. Bumps the engine to 2.0.2. --- .github/workflows/ci.yml | 14 + CHANGELOG.md | 50 + CONTRIBUTING.md | 93 +- README.md | 82 +- engine/executor/__init__.py | 2 +- engine/tests/test_engine_ships_with_skill.py | 233 +++ scripts/sync_engine.py | 94 ++ skills/executor-brainstorm/SKILL.md | 4 + skills/executor-critique/SKILL.md | 4 + skills/executor-discovery/SKILL.md | 4 + skills/executor-execution/SKILL.md | 4 + skills/executor-handoff/SKILL.md | 4 + skills/executor-plan-regression/SKILL.md | 4 + skills/executor-planning/SKILL.md | 4 + skills/executor-review/SKILL.md | 4 + skills/executor-spec/SKILL.md | 4 + skills/executor/SKILL.md | 32 +- skills/executor/references/frontmatter.md | 2 +- skills/executor/references/layout.md | 4 +- skills/executor/references/rejections.md | 2 +- skills/executor/scripts/executor | 33 + .../executor/scripts/lib/executor/__init__.py | 6 + .../executor/scripts/lib/executor/__main__.py | 16 + skills/executor/scripts/lib/executor/cli.py | 255 +++ .../executor/scripts/lib/executor/engine.py | 1478 +++++++++++++++++ skills/executor/scripts/lib/executor/paths.py | 421 +++++ .../executor/scripts/lib/executor/policy.py | 123 ++ .../executor/scripts/lib/executor/schemas.py | 535 ++++++ skills/executor/scripts/lib/executor/store.py | 455 +++++ skills/executor/scripts/lib/executor/views.py | 201 +++ 30 files changed, 4105 insertions(+), 62 deletions(-) create mode 100644 engine/tests/test_engine_ships_with_skill.py create mode 100755 scripts/sync_engine.py create mode 100755 skills/executor/scripts/executor create mode 100644 skills/executor/scripts/lib/executor/__init__.py create mode 100755 skills/executor/scripts/lib/executor/__main__.py create mode 100755 skills/executor/scripts/lib/executor/cli.py create mode 100644 skills/executor/scripts/lib/executor/engine.py create mode 100644 skills/executor/scripts/lib/executor/paths.py create mode 100644 skills/executor/scripts/lib/executor/policy.py create mode 100644 skills/executor/scripts/lib/executor/schemas.py create mode 100644 skills/executor/scripts/lib/executor/store.py create mode 100644 skills/executor/scripts/lib/executor/views.py diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 6a33819..45d0361 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -58,6 +58,20 @@ jobs: # payload-writing prompt states the refusal contract, and that no # ID example or JSON skeleton teaches something the engine rejects. run: python scripts/validate_skills.py + - name: The bundled engine matches the engine source + # Users install the skill, and the skill carries the engine. The + # bundle is generated, so a change to engine/executor/ that misses + # the bundle would ship one engine and test another. + run: python scripts/sync_engine.py --check + - name: The installed skill runs with no PYTHONPATH + # The claim in the README, executed: copy the skill out of the repo, + # drop PYTHONPATH, and run the launcher from an unrelated directory. + run: | + set -e + dest="$(mktemp -d)" + cp -R skills/executor "$dest/executor" + cd "$dest" + env -u PYTHONPATH python3 executor/scripts/executor --version - name: Prompt-injection lint # Every SKILL.md is executed as instruction by agents. This blocks # override directives, concealment, exfiltration endpoints, diff --git a/CHANGELOG.md b/CHANGELOG.md index ffa0b6a..ad7ffee 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,56 @@ project is tagged; between releases, entries are dated and `main` moves. ## [Unreleased] +## [2.0.2] — 2026-10-19 + +Patch release: the engine ships with the skill. Installing the skills used +to leave `executor` undefined — the skills call a bare command that only +existed for someone who had cloned the repository and exported +`PYTHONPATH`. Now the engine travels inside the router skill and a +launcher beside it resolves the copy relative to itself, so an install +needs no path setup at all. + +### Fixed — an install is now a complete install + +- **The engine ships inside `skills/executor/`.** `npx skills add` copies a + skill directory and nothing outside it, so `engine/executor/` — a sibling + of `skills/` — never reached a user. The package now also lives at + `skills/executor/scripts/lib/executor/`, which the installer copies, and + `skills/executor/scripts/executor` is the launcher the skills name. +- **No `PYTHONPATH`, no `pip`, no `PATH` edit.** The launcher resolves + `scripts/lib/` from `__file__`, so it works from any project directory. + Python 3.11+ is the only requirement; the engine remains standard + library only. +- **`scripts/sync_engine.py` is the one writer of the shipped copy**, and + `--check` is a CI gate. `engine/executor/` stays the source the suite + tests; the bundle is generated, so a hand edit to either side fails + `test_engine_ships_with_skill.py` rather than shipping an engine the + repository never tested. +- **A real install is exercised in CI**, not just the repository layout: + the skill is copied out of the tree, `PYTHONPATH` is dropped, and the + launcher runs from an unrelated directory. + +### Changed — the documents name the command a reader can run + +- **Every skill states the spelling.** `executor ` is defined once in + the router and restated at the top of each phase skill, so loading + `executor-execution` directly no longer leaves an agent to guess at an + executable that is not on `PATH`. +- **Engine source citations point inside the skill.** The references cited + `engine/executor/paths.py` and `schemas.py` — paths an installed user + does not have. They now cite `scripts/lib/executor/`, which exists + wherever the skill was copied. A test walks the skills tree to keep it + that way. +- **The README install section is the install path.** The `PYTHONPATH` + step, the one-paste prompt's profile edit, and the `python3 -m executor` + examples are replaced by the launcher; working from a clone is documented + separately, where `PYTHONPATH` is still the honest spelling. +- **`CONTRIBUTING.md` describes this repository.** It documented + `exec-scan-secrets`, `validate-skills.sh`, `test-executor.sh`, and a + ShellCheck gate — all deleted in the v2 shell-to-Python cutover. The + file now names the Python entry points, the 100% branch floor, the + bundle rule, and the CI jobs that actually exist. + ## [2.0.1] — 2026-10-16 Patch release: the documents say what the engine enforces. The README's diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f9ddedf..a51a514 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,14 +1,14 @@ # Contributing to The Executor Thanks for your interest in improving The Executor. This repository is a -library of agent-readable skill documents plus the shell scripts they call — -no build step, no test framework, no runtime. The contributions that matter -most are: +library of agent-readable skill documents plus the Python engine those +skills drive — no build step, no runtime dependency beyond Python 3.11+. The +contributions that matter most are: 1. **Skill edits** — clearer routing, better gates, sharper prompts. -2. **Script fixes** — the `skills/executor/scripts/` helpers must keep - resolving paths from `skills/executor/references/layout.md`, never - inventing locations. +2. **Engine fixes** — the engine in `engine/executor/` is the enforcer of + every contract the skills describe; a rule stated in prose and not + enforced in code is a rule that will drift. 3. **Documentation** — anything a reader of this README would find confusing or missing. @@ -16,27 +16,52 @@ most are: | Path | What lives there | |---|---| +| `engine/executor/` | The engine source: `cli.py`, `engine.py`, `schemas.py`, `paths.py`, `store.py`, `views.py`, `policy.py` | +| `engine/tests/` | The suite, including the tree-walking contract tests | | `skills/executor/` | Router skill: contract, ID grammar, phase gates | | `skills/executor/references/` | The normative documents: layout, branches, frontmatter, indexes, safety, test-quality | -| `skills/executor/scripts/` | Executable helpers (`exec-id`, `exec-workspace`, `exec-scan-secrets`, …) | +| `skills/executor/scripts/executor` | The launcher users run; resolves the engine relative to itself | +| `skills/executor/scripts/lib/executor/` | The shipped engine — a generated mirror of `engine/executor/` | | `skills/executor-*/` | One skill per lifecycle phase, each with its own `SKILL.md` | - -There is no `docs/` directory: normative content lives in -`skills/executor/references/`, which is what the skills cite. +| `scripts/` | `run_tests.py`, `sync_engine.py`, `mutate.py`, the validators | `skills/executor/references/layout.md` is normative: paths, document types, and directory names resolve from it. If you move or add a document type, update it first. +### The bundled engine + +The engine ships **inside** the router skill because an installed skill is a +copied directory: `npx skills add` copies `skills/executor/` and nothing +outside it, so an engine kept only at `engine/` would never reach a user. +`skills/executor/scripts/lib/executor/` is that shipped copy. + +**Never edit the bundle by hand.** `engine/executor/` is the source; the +bundle is generated from it. After changing the engine: + +```bash +python3 scripts/sync_engine.py # rewrite the bundle +python3 scripts/sync_engine.py --check # what CI runs +``` + +A change that edits only one side fails `test_engine_ships_with_skill.py` +and the `--check` CI step, by design — two copies of one package that are +allowed to differ means the repository tests one engine and ships another. + ## Getting started ```bash git clone git@github.com:Atri10/executor.git cd executor +pip install -r requirements-dev.txt # coverage, the one dev tool ``` -That's the whole setup — the skills are plain Markdown and the scripts are -POSIX-ish bash with no dependencies beyond `git` and `find`. +The engine itself has zero third-party dependencies. From a clone it also +runs as a package: + +```bash +PYTHONPATH=engine python3 -m executor --version +``` ## How changes are reviewed @@ -54,55 +79,57 @@ POSIX-ish bash with no dependencies beyond `git` and `find`. `references/branches.md`, `references/frontmatter.md`, or `references/indexes.md` in the same change, and call out the behavioral delta in the PR description. +- **A behavior change needs a test that would fail without it.** The suite + holds a 100% branch-coverage floor, so an uncovered branch fails CI rather + than being merged untested. ## Submitting changes 1. Branch from `main`: `git checkout -b feature/` (or `fix/`, `docs/`). 2. Make the change in a focused commit. Conventional Commits style: - `feat(skills): ...`, `fix(scripts): ...`, `docs: ...`. -3. Before committing, check the diff for accidental secrets — this repo + `feat(engine): ...`, `fix(skills): ...`, `docs: ...`. +3. Before committing, check the diff for accidental secrets — the engine includes a scanner you can borrow for the check: - `skills/executor/scripts/exec-scan-secrets `. + `python3 skills/executor/scripts/executor check --secrets`. 4. Open a pull request describing **what behavior changes for an agent** and **why**. Link any issue it resolves. ## Reporting issues -- **Bug in a skill or script** — open a regular issue with the exact skill - text or script invocation, what the agent did, and what it should have - done. +- **Bug in a skill or the engine** — open a regular issue with the exact + skill text or command invocation, what the agent did, and what it should + have done. - **Docs unclear or wrong** — same channel; wrong docs are bugs. - **Security-sensitive disclosure** — do not open a public issue. See [SECURITY.md](SECURITY.md). ## CI -Every PR runs five checks; all must pass before merge: +Every PR runs these checks; all must pass before merge: | Check | What it enforces | |---|---| -| **ShellCheck** (`--severity=warning`) | Every `exec-*` script parses and is warning-clean — these run inside users' agents with git and filesystem access | -| **Prompt-injection lint** | Skill markdown is *executed as instruction by agents*; the linter blocks override directives, concealment, exfiltration endpoints, fetch-and-execute, and credential literals | +| **Engine suite** (macOS, Linux, Windows) | The full suite at a 100% branch-coverage floor, plus `python -m executor --version` on each OS | +| **Bundled-engine sync** | `scripts/sync_engine.py --check`: the shipped copy is byte-identical to `engine/executor/` | +| **Installed-skill smoke** | The skill is copied out of the repo, `PYTHONPATH` is dropped, and the launcher runs — the install path users actually take | | **Skill validation** | Frontmatter + `Use when` trigger, balanced fences, no duplicate names; every `SKILL.md` carries `## Self-Critique` and `## Verification`; every dispatch role in `references/layout.md` has a registered prompt template carrying the required markers; no `*-prompt.md` exists unregistered; no ASCII-art diagrams | -| **Secret scan** | The Executor's own `exec-scan-secrets` over the repo, plus gitleaks over full history | -| **Script smoke** | Usage paths work; the plan-lint and run-audit gates actually fire on known violations | +| **Prompt-injection lint** | Skill markdown is *executed as instruction by agents*; the linter blocks override directives, concealment, exfiltration endpoints, fetch-and-execute, and credential literals | +| **Secret scan** | The engine's own `executor check --secrets` against a fresh initiative, plus gitleaks over full history | -Run all of them locally before pushing: +Run them locally before pushing: ```bash -find skills/executor/scripts scripts -type f \( -name 'exec-*' -o -name '*.sh' \) -print0 \ - | xargs -0 shellcheck --severity=warning +python3 scripts/run_tests.py # suite + coverage floor +python3 scripts/sync_engine.py --check # bundle drift +python3 scripts/validate_skills.py # skill contract python3 scripts/lint-prompt-injection.py skills/ -bash scripts/validate-skills.sh skills -bash skills/executor/scripts/exec-scan-secrets . -bash scripts/test-executor.sh ``` -`test-executor.sh` is the regression suite: thirty-seven fixture cases -that rebuild disposable repositories and assert each enforced contract. Add -a case whenever a fix teaches a script to refuse something it used to -accept. +Mutation testing is available for a module whose tests you changed: +`python3 scripts/mutate.py engine/executor/.py`. A surviving mutant +is either a missing assertion or a genuinely equivalent change, and the +latter belongs in `scripts/mutation-allow.json` with its reason. The injection linter is heuristic and errs toward false positives — a flagged line is a human-review prompt in the PR diff, not an accusation. diff --git a/README.md b/README.md index 99ebd20..cf5e7aa 100644 --- a/README.md +++ b/README.md @@ -25,10 +25,10 @@ on macOS, Linux, and Windows. ## In sixty seconds ```text -$ npx skills add Atri10/executor # skills into your harness -$ export PYTHONPATH=/path/to/executor/engine # the engine on the path +$ npx skills add Atri10/executor # skills + engine into your harness +$ EXEC=~/.agents/skills/executor/scripts/executor # the launcher, no PATH setup -$ python3 -m executor new "Tenant isolation cells" +$ python3 "$EXEC" new "Tenant isolation cells" { "created": "INIT-0001", "title": "Tenant isolation cells", @@ -36,10 +36,10 @@ $ python3 -m executor new "Tenant isolation cells" "docs": ".../docs/executor/INIT-0001" } -$ python3 -m executor next +$ python3 "$EXEC" next {"action":"PHASE-ENTER","initiative":"INIT-0001","phase":"intake", ...} -$ python3 -m executor status +$ python3 "$EXEC" status INITIATIVE INIT-0001 - Tenant isolation cells phase: intake (in_progress) events: 3 | artifacts: 0 | tasks: 0 @@ -61,19 +61,33 @@ discovers every skill in the repo and wires them into your harness: npx skills add Atri10/executor ``` -Or clone and copy `skills/` into whatever directory your agent loads from, -and put `engine/` on your `PYTHONPATH`: +**The engine ships inside the `executor` skill**, at +`skills/executor/scripts/lib/executor/`, with a launcher beside it. An +install therefore needs no `pip`, no virtualenv, no `PYTHONPATH`, and no +command on `PATH`: the launcher resolves its engine relative to itself, so +it works from any project directory. Python 3.11+ is the only requirement, +and the engine is standard library only. + +```bash +python3 ~/.agents/skills/executor/scripts/executor --version +``` + +`~/.agents/skills/` is where `npx skills add` puts a globally installed +skill; use `./.agents/skills/` for a project-local install, or your +harness's own skills directory if it keeps one. Throughout this README and +every skill, `executor ` means that launcher. + +Or clone and copy `skills/` into whatever directory your agent loads from: ```bash git clone git@github.com:Atri10/executor.git cp -R executor/skills/* / -export PYTHONPATH=/engine ``` Pin to a release tag instead of `main` for stability: ```bash -git clone --branch v2.0.1 git@github.com:Atri10/executor.git +git clone --branch v2.0.2 git@github.com:Atri10/executor.git ``` There are no dependencies to install: the engine is the standard library, @@ -87,7 +101,7 @@ other harness. It discovers the right directories itself and verifies the install: ```text -Install The Executor skill library and engine for me: +Install The Executor skill library for me: 1. Clone https://github.com/Atri10/executor.git into a temp directory 2. Find my agent's skills directory. Candidates, in order — use the first @@ -99,14 +113,15 @@ Install The Executor skill library and engine for me: - as my harness documents 3. Copy every directory from the clone's skills/ folder into that skills directory (each is one skill: skills/executor, skills/executor-spec, ...). - Tell me the PYTHONPATH line that points at the clone's engine/ directory, - and add it to my shell profile if I confirm. -4. Verify: run PYTHONPATH=/engine python3 -m executor --version - (prints 2.0.1), then PYTHONPATH=/engine python3 -m executor - --help (lists the command surface). Also confirm every copied - skills// directory contains a SKILL.md — count the directories, - not a remembered number: the skill set grows, and a stale count fails - an install that is actually fine. + The engine ships inside skills/executor/scripts/lib/, so copy the whole + directory — do not copy only the .md files. +4. Verify: run python3 /executor/scripts/executor --version + (prints 2.0.2), then python3 /executor/scripts/executor + --help (lists the command surface). Do not set PYTHONPATH and do not + install a package: the launcher carries its engine. Also confirm every + copied skills// directory contains a SKILL.md — count the + directories, not a remembered number: the skill set grows, and a stale + count fails an install that is actually fine. 5. Tell me which directory you installed into, and how to invoke the router in my harness (usually /skill:executor or just asking for "the executor"). @@ -124,6 +139,20 @@ Then invoke the root router: or say *"start an initiative"* — normal requests route by each skill's description. +### Working in this repository + +From a clone, the engine is also a package under `engine/`, which is what +the test suite imports: + +```bash +export PYTHONPATH=/engine +python3 -m executor --version +``` + +Both spellings run the same code. `scripts/sync_engine.py` mirrors +`engine/executor/` into the skill bundle and `--check` fails CI when they +differ, so the two copies cannot drift. + ## How a run is driven One loop, and the controller holds no judgment: run `executor next`, read @@ -402,6 +431,9 @@ the decision table is an engine gap to record, not to approximate). ### The CLI is the whole surface +`executor` below is `python3 /scripts/executor`; the +launcher passes its arguments straight through. + ```text executor new "" scaffold INIT-NNNN executor next [INIT] one typed action + its prompt @@ -528,21 +560,25 @@ archivable — open the folder and every pointer resolves inside it. ```mermaid flowchart TD - R["repository root"] --> E["engine/ — the engine, stdlib only"] + R["repository root"] --> E["engine/ — the engine source, stdlib only"] R --> S["skills/ — one directory per skill"] - R --> SC["scripts/ — run_tests.py, mutate.py, validators"] + R --> SC["scripts/ — run_tests.py, sync_engine.py, mutate.py, validators"] R --> CI[".github/workflows/ — the gates"] R --> DOC["docs/executor/ — the committed record of each initiative"] E --> ET["engine/tests/ — the suite"] + S --> B["executor/scripts/lib/executor/ — the shipped copy"] ``` | Path | What it is | |---|---| -| `engine/executor/` | the engine: `cli.py`, `engine.py`, `schemas.py`, `paths.py`, `store.py`, `views.py`, `policy.py` | -| `engine/tests/` | the suite (722 tests), including the tree-walking contract tests | -| `skills/executor/` | the router skill, its prompt templates, and the references | +| `engine/executor/` | the engine source: `cli.py`, `engine.py`, `schemas.py`, `paths.py`, `store.py`, `views.py`, `policy.py` | +| `engine/tests/` | the suite (739 tests), including the tree-walking contract tests | +| `skills/executor/` | the router skill, its prompt templates, the references, and the engine that ships with it | +| `skills/executor/scripts/executor` | the launcher; resolves `scripts/lib/executor/` relative to itself | +| `skills/executor/scripts/lib/executor/` | the installed engine — a generated mirror of `engine/executor/` | | `skills/executor-*/` | one directory per phase skill | | `scripts/run_tests.py` | the test runner; enforces the branch-coverage floor | +| `scripts/sync_engine.py` | mirrors the engine into the skill; `--check` is the drift gate | | `scripts/mutate.py` | mutation testing; the allow list records equivalent survivors | | `scripts/validate_skills.py` | the skill contract: registry, references, payload shapes | | `scripts/lint-prompt-injection.py` | blocks override directives and concealment in skill text | diff --git a/engine/executor/__init__.py b/engine/executor/__init__.py index 90371a5..10b8802 100644 --- a/engine/executor/__init__.py +++ b/engine/executor/__init__.py @@ -1,6 +1,6 @@ # Executor v2 engine — single-writer, typed-payload, event-sourced. # # Public surface is the CLI in executor.cli; this package is the kernel. -__version__ = "2.0.1" +__version__ = "2.0.2" SCHEMA_VERSION = "v1" STORE_VERSION = "v1" diff --git a/engine/tests/test_engine_ships_with_skill.py b/engine/tests/test_engine_ships_with_skill.py new file mode 100644 index 0000000..39dbe8f --- /dev/null +++ b/engine/tests/test_engine_ships_with_skill.py @@ -0,0 +1,233 @@ +# SPDX-License-Identifier: MIT +# Copyright (c) 2026 Atri10 +"""The engine ships inside the skill, and the two copies cannot drift. + +The skills call `executor <verb>` and nothing installs a command, so the +engine travels inside the router skill and the launcher resolves it from +its own directory. These tests pin the three properties that make that +true for a user who only ran `npx skills add`: + +1. the bundle is byte-identical to `engine/executor/` — one package, two + copies, no drift; +2. the launcher runs from a copied skill directory in an unrelated working + directory, with no `PYTHONPATH`, which is what an install produces; +3. every `engine/executor/...` path a skill document cites resolves + inside the installed skill, never to a clone the user does not have. +""" +from __future__ import annotations + +import io +import os +import runpy +import shutil +import subprocess +import sys +import tempfile +import unittest +from contextlib import redirect_stderr, redirect_stdout +from pathlib import Path +from unittest import mock + +from _scripts import REPO, load + +sync_engine = load("sync_engine.py") +SKILL = REPO / "skills" / "executor" +LAUNCHER = SKILL / "scripts" / "executor" + + +class BundleMatchesSource(unittest.TestCase): + """The bundled copy is generated, so a hand edit to either side is the + failure this catches: the repository would test one engine and ship + another.""" + + def test_the_bundle_is_in_sync(self): + self.assertEqual(sync_engine.drift(), [], + "run python scripts/sync_engine.py") + + def test_the_launcher_is_executable(self): + self.assertTrue(os.access(LAUNCHER, os.X_OK), + "the launcher lost its exec bit") + + def test_the_bundle_carries_every_module(self): + shipped = set(sync_engine.modules(sync_engine.BUNDLE)) + source = set(sync_engine.modules(sync_engine.SOURCE)) + self.assertEqual(shipped, source) + + def test_drift_names_both_directions(self): + with tempfile.TemporaryDirectory() as tmp: + root = Path(tmp) + src, dst = root / "engine", root / "bundle" + for d in (src, dst): + d.mkdir() + (src / "a.py").write_text("A = 1\n", encoding="utf-8") + (src / "b.py").write_text("B = 1\n", encoding="utf-8") + (dst / "a.py").write_text("A = 2\n", encoding="utf-8") + (dst / "c.py").write_text("C = 1\n", encoding="utf-8") + with mock.patch.object(sync_engine, "SOURCE", src), \ + unittest.mock.patch.object(sync_engine, "BUNDLE", dst): + problems = sync_engine.drift() + text = "\n".join(problems) + self.assertIn("stale in the bundle: a.py", text) + self.assertIn("missing from the bundle: b.py", text) + self.assertIn("not in the engine source: c.py", text) + + def test_sync_rewrites_a_stale_bundle_and_drops_orphans(self): + with tempfile.TemporaryDirectory() as tmp: + root = Path(tmp) + src, dst = root / "engine", root / "bundle" + for d in (src, dst): + d.mkdir() + (src / "a.py").write_text("A = 1\n", encoding="utf-8") + (dst / "a.py").write_text("A = 2\n", encoding="utf-8") + (dst / "orphan.py").write_text("X = 1\n", encoding="utf-8") + with mock.patch.object(sync_engine, "SOURCE", src), \ + unittest.mock.patch.object(sync_engine, "BUNDLE", dst): + changed = sync_engine.sync() + self.assertEqual(sync_engine.drift(), []) + self.assertEqual(sorted(changed), ["-orphan.py", "a.py"]) + self.assertEqual((dst / "a.py").read_text(encoding="utf-8"), + "A = 1\n") + + +class SyncEngineCli(unittest.TestCase): + """`sync_engine.py` is the only writer of the bundle, so its own exit + codes are what CI depends on: 0 in sync, 1 drifted, 2 no source.""" + + def setUp(self) -> None: + self._tmp = tempfile.TemporaryDirectory() + self.addCleanup(self._tmp.cleanup) + root = Path(self._tmp.name) + self.src, self.dst = root / "engine", root / "bundle" + self.src.mkdir() + (self.src / "a.py").write_text("A = 1\n", encoding="utf-8") + patcher = unittest.mock.patch.object(sync_engine, "SOURCE", self.src) + patcher.start() + self.addCleanup(patcher.stop) + patcher = unittest.mock.patch.object(sync_engine, "BUNDLE", self.dst) + patcher.start() + self.addCleanup(patcher.stop) + + def run_main(self, *argv: str) -> tuple[int, str, str]: + out, err = io.StringIO(), io.StringIO() + with redirect_stdout(out), redirect_stderr(err): + code = sync_engine.main(list(argv)) + return code, out.getvalue(), err.getvalue() + + def test_check_passes_on_a_mirrored_bundle(self): + sync_engine.sync() + code, out, _ = self.run_main("--check") + self.assertEqual(code, 0) + self.assertIn("in sync", out) + + def test_check_fails_and_names_the_drift(self): + self.dst.mkdir() + (self.dst / "a.py").write_text("A = 2\n", encoding="utf-8") + code, _, err = self.run_main("--check") + self.assertEqual(code, 1) + self.assertIn("stale in the bundle: a.py", err) + self.assertIn("python scripts/sync_engine.py", err) + + def test_write_reports_what_it_changed(self): + code, out, _ = self.run_main() + self.assertEqual(code, 0) + self.assertIn("a.py", out) + self.assertEqual((self.dst / "a.py").read_text(encoding="utf-8"), + "A = 1\n") + + def test_write_says_so_when_nothing_changed(self): + self.run_main() + code, out, _ = self.run_main() + self.assertEqual(code, 0) + self.assertIn("already in sync", out) + + def test_a_missing_source_is_an_error_not_a_silent_empty_bundle(self): + shutil.rmtree(self.src) + code, _, err = self.run_main() + self.assertEqual(code, 2) + self.assertIn("engine source missing", err) + + def test_the_module_guard_exits_with_mains_code(self): + with mock.patch("sys.argv", ["sync_engine.py", "--check"]), \ + redirect_stdout(io.StringIO()): + with self.assertRaises(SystemExit) as se: + runpy.run_path(str(Path(sync_engine.__file__)), + run_name="__main__") + self.assertEqual(se.exception.code, 0) + + +class InstalledSkillRuns(unittest.TestCase): + """The install path, exercised as an install: copy the skill directory + somewhere unrelated, drop `PYTHONPATH`, and run the launcher from a + project that is not the repository.""" + + def setUp(self) -> None: + self._tmp = tempfile.TemporaryDirectory() + self.addCleanup(self._tmp.cleanup) + self.root = Path(self._tmp.name) + self.skills = self.root / "agent" / "skills" + self.skills.mkdir(parents=True) + self.installed = self.skills / "executor" + shutil.copytree(SKILL, self.installed) + self.project = self.root / "project" + self.project.mkdir() + self.env = {k: v for k, v in os.environ.items() + if k != "PYTHONPATH"} + + def run_launcher(self, *argv: str) -> subprocess.CompletedProcess: + return subprocess.run( + [sys.executable, str(self.installed / "scripts" / "executor"), + *argv], + cwd=self.project, env=self.env, capture_output=True, text=True) + + def test_version_runs_with_no_pythonpath_and_no_clone(self): + proc = self.run_launcher("--version") + self.assertEqual(proc.returncode, 0, proc.stderr) + self.assertRegex(proc.stdout.strip(), r"^\d+\.\d+\.\d+$") + + def test_help_lists_the_command_surface(self): + proc = self.run_launcher("--help") + self.assertEqual(proc.returncode, 0, proc.stderr) + self.assertIn("executor new", proc.stdout) + self.assertIn("executor next", proc.stdout) + + def test_a_full_command_runs_in_a_fresh_git_repo(self): + subprocess.run(["git", "init", "-q", str(self.project)], check=True) + proc = self.run_launcher("new", "Installed run") + self.assertEqual(proc.returncode, 0, proc.stderr) + self.assertIn("INIT-0001", proc.stdout) + status = self.run_launcher("status") + self.assertEqual(status.returncode, 0, status.stderr) + self.assertIn("INIT-0001", status.stdout) + + def test_the_exec_bit_runs_it_directly(self): + """Where the exec bit survived the copy, the bare form works.""" + proc = subprocess.run( + [str(self.installed / "scripts" / "executor"), "--version"], + cwd=self.project, env=self.env, capture_output=True, text=True) + self.assertEqual(proc.returncode, 0, proc.stderr) + self.assertRegex(proc.stdout.strip(), r"^\d+\.\d+\.\d+$") + + def test_a_launcher_with_no_bundle_fails_loudly(self): + shutil.rmtree(self.installed / "scripts" / "lib") + proc = self.run_launcher("--version") + self.assertEqual(proc.returncode, 127) + self.assertIn("bundled engine is missing", proc.stderr) + + +class SkillPathsResolveInstalled(unittest.TestCase): + """A skill document that cites `engine/executor/x.py` teaches a reader to + open a path an install does not have. The engine is cited under the + skill's own scripts/lib/, which exists wherever the skill was copied.""" + + def test_no_skill_document_cites_the_repository_engine_path(self): + offenders = [] + for f in sorted((REPO / "skills").rglob("*.md")): + for i, line in enumerate( + f.read_text(encoding="utf-8").splitlines(), 1): + if "engine/executor/" in line: + offenders.append(f"{f.relative_to(REPO)}:{i}") + self.assertEqual(offenders, []) + + +if __name__ == "__main__": + unittest.main() diff --git a/scripts/sync_engine.py b/scripts/sync_engine.py new file mode 100755 index 0000000..44217cc --- /dev/null +++ b/scripts/sync_engine.py @@ -0,0 +1,94 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: MIT +# Copyright (c) 2026 Atri10 +"""Mirror `engine/executor/` into the skill that ships it. + +The skills call a bare `executor` command. Nothing puts one on `PATH`, so +the engine travels inside the router skill at +`skills/executor/scripts/lib/executor/` and the launcher beside it resolves +that copy relative to itself. Users run the bundle; this repository tests +`engine/executor/`. Two copies of one package drift the moment an edit +lands in one, so this script is the only writer of the bundle and +`--check` is the gate that keeps them identical. + + python scripts/sync_engine.py rewrite the bundled copy + python scripts/sync_engine.py --check exit 1 if it differs + +Exit 0 clean, 1 drifted (check mode), 2 when the source is missing. +""" +from __future__ import annotations + +import argparse +import filecmp +import sys +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[1] +SOURCE = ROOT / "engine" / "executor" +BUNDLE = ROOT / "skills" / "executor" / "scripts" / "lib" / "executor" + + +def modules(directory: Path) -> dict[str, Path]: + """The shipped modules, by name. `__pycache__` is residue from running + the engine here, not something a user installs.""" + return {p.name: p for p in sorted(directory.glob("*.py")) if p.is_file()} + + +def drift() -> list[str]: + """Every way the bundle disagrees with the source, as readable lines.""" + src, dst = modules(SOURCE), modules(BUNDLE) + problems = [f"missing from the bundle: {name}" + for name in sorted(set(src) - set(dst))] + problems += [f"not in the engine source: {name}" + for name in sorted(set(dst) - set(src))] + problems += [f"stale in the bundle: {name}" + for name in sorted(set(src) & set(dst)) + if not filecmp.cmp(src[name], dst[name], shallow=False)] + return problems + + +def sync() -> list[str]: + """Rewrite the bundle to match the source. Returns what changed, with a + leading `-` for a removed module, so a caller can print it.""" + BUNDLE.mkdir(parents=True, exist_ok=True) + src, dst = modules(SOURCE), modules(BUNDLE) + changed = [] + for name in sorted(src): + target = BUNDLE / name + if name in dst and filecmp.cmp(src[name], target, shallow=False): + continue + target.write_bytes(src[name].read_bytes()) + changed.append(name) + for name in sorted(set(dst) - set(src)): + (BUNDLE / name).unlink() + changed.append(f"-{name}") + return changed + + +def main(argv: list[str] | None = None) -> int: + ap = argparse.ArgumentParser( + description=__doc__, + formatter_class=argparse.RawDescriptionHelpFormatter) + ap.add_argument("--check", action="store_true", + help="report drift instead of writing it") + args = ap.parse_args(argv) + + if not SOURCE.is_dir(): + print(f"engine source missing: {SOURCE}", file=sys.stderr) + return 2 + if args.check: + problems = drift() + if problems: + print("\n".join(problems), file=sys.stderr) + print("the bundled engine is stale: run " + "python scripts/sync_engine.py", file=sys.stderr) + return 1 + print("bundled engine: in sync") + return 0 + changed = sync() + print("\n".join(changed) if changed else "bundled engine: already in sync") + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/skills/executor-brainstorm/SKILL.md b/skills/executor-brainstorm/SKILL.md index 5b23d68..8b4e94c 100644 --- a/skills/executor-brainstorm/SKILL.md +++ b/skills/executor-brainstorm/SKILL.md @@ -5,6 +5,10 @@ description: Use when a new feature, use case, or product capability must be des # Executor — Brainstorm +> **Engine.** `executor <verb>` means +> `python3 <skills-dir>/executor/scripts/executor <verb>`; the engine ships +> inside the router skill, so nothing is on `PATH`. + The design skill. Every other skill converges — specs fix requirements, plans fix tasks, verdicts fix judgments. This one explores first: it turns a rough idea into a small set of genuinely different, complete designs, diff --git a/skills/executor-critique/SKILL.md b/skills/executor-critique/SKILL.md index e2c06a5..55ab613 100644 --- a/skills/executor-critique/SKILL.md +++ b/skills/executor-critique/SKILL.md @@ -5,6 +5,10 @@ description: Audit an initiative's authored artifacts against each other, repair # Critique — the gate every authoring phase passes through +> **Engine.** `executor <verb>` means +> `python3 <skills-dir>/executor/scripts/executor <verb>`; the engine ships +> inside the router skill, so nothing is on `PATH`. + ## Why this exists Before this discipline existed, two of eleven phases could reject a bad diff --git a/skills/executor-discovery/SKILL.md b/skills/executor-discovery/SKILL.md index aea28db..863413f 100644 --- a/skills/executor-discovery/SKILL.md +++ b/skills/executor-discovery/SKILL.md @@ -5,6 +5,10 @@ description: Use when `executor next` emits `PHASE-ENTER discovery` — a charte # Executor — Discovery +> **Engine.** `executor <verb>` means +> `python3 <skills-dir>/executor/scripts/executor <verb>`; the engine ships +> inside the router skill, so nothing is on `PATH`. + Discovery answers exactly two questions: **what is actually being asked for**, and **which approach wins**. Its outputs are the `options` artifact (the approaches and the pick) and the `brainstorm` artifact diff --git a/skills/executor-execution/SKILL.md b/skills/executor-execution/SKILL.md index 8d35139..bd84d56 100644 --- a/skills/executor-execution/SKILL.md +++ b/skills/executor-execution/SKILL.md @@ -5,6 +5,10 @@ description: Use when a plan has passed its planning gate and the engine's `exec # Executor — Execution +> **Engine.** `executor <verb>` means +> `python3 <skills-dir>/executor/scripts/executor <verb>`; the engine ships +> inside the router skill, so nothing is on `PATH`. + Execute one plan by following `executor next`: the engine mints a dispatch (`impl`, `review`, `fix`), you spawn the worker and ingest its payload. You are the **controller**: you pump, you dispatch, you never implement. diff --git a/skills/executor-handoff/SKILL.md b/skills/executor-handoff/SKILL.md index 86a8b0c..597ca12 100644 --- a/skills/executor-handoff/SKILL.md +++ b/skills/executor-handoff/SKILL.md @@ -5,6 +5,10 @@ description: Use when `executor next` emits `PHASE-ENTER handoff` — an initiat # Executor Handoff +> **Engine.** `executor <verb>` means +> `python3 <skills-dir>/executor/scripts/executor <verb>`; the engine ships +> inside the router skill, so nothing is on `PATH`. + Close-out is the phase where the human learns what you decided for them, where a leaked credential is caught before it becomes permanent, and where the journal stops being a working log and becomes the diff --git a/skills/executor-plan-regression/SKILL.md b/skills/executor-plan-regression/SKILL.md index b7561cc..f585341 100644 --- a/skills/executor-plan-regression/SKILL.md +++ b/skills/executor-plan-regression/SKILL.md @@ -5,6 +5,10 @@ description: Use when plans are all drafted and `executor next` enters `plan_reg # Executor — Plan Regression +> **Engine.** `executor <verb>` means +> `python3 <skills-dir>/executor/scripts/executor <verb>`; the engine ships +> inside the router skill, so nothing is on `PATH`. + The phase between planning and execution that the plan set earns by surviving one adversarial read as a *set*. Every per-plan check that already exists — the planning self-review — reads ONE plan. This phase diff --git a/skills/executor-planning/SKILL.md b/skills/executor-planning/SKILL.md index 2a3370b..7ba0e13 100644 --- a/skills/executor-planning/SKILL.md +++ b/skills/executor-planning/SKILL.md @@ -5,6 +5,10 @@ description: Use when `executor next` enters `planning` — a spec has passed it # Planning +> **Engine.** `executor <verb>` means +> `python3 <skills-dir>/executor/scripts/executor <verb>`; the engine ships +> inside the router skill, so nothing is on `PATH`. + Turn the `spec` artifact into `plan` payloads: each carries `plan_id`, `objective`, `tasks[]` with exact file paths, verbatim test expectations, and `depends_on` edges, and `gates[]` naming what must diff --git a/skills/executor-review/SKILL.md b/skills/executor-review/SKILL.md index d33f5d8..51acf77 100644 --- a/skills/executor-review/SKILL.md +++ b/skills/executor-review/SKILL.md @@ -5,6 +5,10 @@ description: Use when the engine emits a `DISPATCH` with `role: "review"` — a # Executor Review +> **Engine.** `executor <verb>` means +> `python3 <skills-dir>/executor/scripts/executor <verb>`; the engine ships +> inside the router skill, so nothing is on `PATH`. + A review is not a conversation. It is a **round**: the engine mints a `reviews/R<NN>` slot, packages the diff, and the reviewer's `verdict` payload — validated against the schema — is the judgment of record. The diff --git a/skills/executor-spec/SKILL.md b/skills/executor-spec/SKILL.md index 41c8e8a..a391e37 100644 --- a/skills/executor-spec/SKILL.md +++ b/skills/executor-spec/SKILL.md @@ -5,6 +5,10 @@ description: Use when `executor next` enters `specification` — architecture an # Specification +> **Engine.** `executor <verb>` means +> `python3 <skills-dir>/executor/scripts/executor <verb>`; the engine ships +> inside the router skill, so nothing is on `PATH`. + This phase produces the artifacts every later phase is measured against. diff --git a/skills/executor/SKILL.md b/skills/executor/SKILL.md index ccbb451..40972de 100644 --- a/skills/executor/SKILL.md +++ b/skills/executor/SKILL.md @@ -30,6 +30,31 @@ becomes the work. **The gate:** if you cannot name a deliverable that outlives this session, there is no initiative. Answer the question and stop. +## The `executor` command + +Every skill in this library writes `executor <verb>` as shorthand. The +engine ships **inside this skill**, at `scripts/lib/executor/`, so nothing +is installed on `PATH` and no `PYTHONPATH` is set. Spell the command from +the skill's own directory — the directory containing this `SKILL.md`: + +```bash +python3 <skill-base-dir>/scripts/executor next +``` + +`<skill-base-dir>` is that directory, not the project you are working in: +the launcher resolves its engine relative to itself, so it runs correctly +from any working directory. Where the filesystem kept the exec bit, the +bare `<skill-base-dir>/scripts/executor next` works too; `python3` is the +portable spelling and the one to use when a shell is unsure. Requires +Python 3.11+; the engine is standard library only, so there is nothing to +install, no virtualenv, and no dependency to resolve. + +If the launcher reports the bundled engine missing, the skill was copied +incompletely — reinstall it rather than editing its contents. Do not fall +back to `python3 -m executor` from a clone: a clone's engine and the +skill's engine are different versions as soon as either moves, and the +store records which one wrote it. + ## Session Opening Ritual — run before ANY work, every session Before your first substantive action in any session touching an Executor @@ -270,6 +295,11 @@ that support it. Normal requests also route by the frontmatter description; say "start an initiative" for intake or "execute plan INIT-0004-P01" for a plan already approved. +The engine is a command, not a skill. It ships inside this skill's +`scripts/` directory; the `executor <verb>` spelling throughout this +library means `python3 <skill-base-dir>/scripts/executor <verb>` as +described under [The `executor` command](#the-executor-command). + ## The Two Stores ```mermaid @@ -339,7 +369,7 @@ R2 review round 2 (an integer, paired with its task) (seq-derived), review rounds as an integer `round` field paired with the task ID. The kind segments are `CHTR`, `OPTS`, `BRN`, `ARCH`, `ADR`, `IFCE`, `DSGN`, `SPEC`, `RISK`, `VRFY` — the closed set -`ARTIFACT_SEGMENTS` in `engine/executor/paths.py` defines them, and an ID +`ARTIFACT_SEGMENTS` in `scripts/lib/executor/paths.py` defines them, and an ID carrying any other segment is a `pattern` rejection. Sequence within a kind is per-initiative and starts at `01`. diff --git a/skills/executor/references/frontmatter.md b/skills/executor/references/frontmatter.md index 8c2b10d..2707a50 100644 --- a/skills/executor/references/frontmatter.md +++ b/skills/executor/references/frontmatter.md @@ -2,7 +2,7 @@ Every Executor document is a typed JSON payload, not a markdown file with frontmatter: the payload's fields carry the ID graph, the journal carries -the history, and `engine/executor/schemas.py` validates every field the +the history, and `scripts/lib/executor/schemas.py` validates every field the moment `executor ingest` accepts it. The rendered `.md` beside it is a derived view — a projection of the payload, never the authority. diff --git a/skills/executor/references/layout.md b/skills/executor/references/layout.md index d82924b..f7700cd 100644 --- a/skills/executor/references/layout.md +++ b/skills/executor/references/layout.md @@ -1,7 +1,7 @@ # Directory Layout The exact structure of both Executor stores. The engine — not this document -— enforces every path here: `engine/executor/paths.py` is the one path +— enforces every path here: `scripts/lib/executor/paths.py` is the one path authority, and `executor check` classifies every file in both stores against its grammar. Nothing invents a location. @@ -91,7 +91,7 @@ by the planning AUTHOR. ## Payload kinds A payload is the only unit a worker, a human, or the engine can append to -the journal, and every kind has a schema in `engine/executor/schemas.py`: +the journal, and every kind has a schema in `scripts/lib/executor/schemas.py`: | Kind | Actor | Closes a dispatch? | |---|---|---| diff --git a/skills/executor/references/rejections.md b/skills/executor/references/rejections.md index 1e4ddeb..a11c4f9 100644 --- a/skills/executor/references/rejections.md +++ b/skills/executor/references/rejections.md @@ -3,7 +3,7 @@ Every refusal `executor ingest`, `executor decide`, and `executor check` can emit, with the field it points at and the action that clears it. This is the authoritative list: the codes are raised in -`engine/executor/` (`engine.py` for the semantic pass, `schemas.py` for +`scripts/lib/executor/` (`engine.py` for the semantic pass, `schemas.py` for the structural one, `store.py` for the journal), and a code that appears in neither is not a code. diff --git a/skills/executor/scripts/executor b/skills/executor/scripts/executor new file mode 100755 index 0000000..288f75b --- /dev/null +++ b/skills/executor/scripts/executor @@ -0,0 +1,33 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: MIT +# Copyright (c) 2026 Atri10 +"""The Executor launcher — runs the engine that ships inside this skill. + +An installed skill is a copied directory, so the engine travels with the +skill instead of being resolved from a clone on `PYTHONPATH`. Resolve it +relative to this file, never from the caller's working directory: the +launcher runs inside the user's project, where `lib/` does not exist. + + python3 <skill-base-dir>/scripts/executor next + +`<skill-base-dir>` is the directory containing the router `SKILL.md`. The +exec bit makes the bare form work where the filesystem keeps it; the +`python3 <path>` spelling is the portable one and is what the skills +document. +""" +from __future__ import annotations + +import sys +from pathlib import Path + +LIB = Path(__file__).resolve().parent / "lib" +if not (LIB / "executor" / "cli.py").is_file(): + print(f"executor: the bundled engine is missing at {LIB / 'executor'}.\n" + f"Reinstall the skill; do not edit its contents.", file=sys.stderr) + raise SystemExit(127) +sys.path.insert(0, str(LIB)) + +from executor.cli import main # noqa: E402 + +if __name__ == "__main__": + sys.exit(main(["executor", *sys.argv[1:]])) diff --git a/skills/executor/scripts/lib/executor/__init__.py b/skills/executor/scripts/lib/executor/__init__.py new file mode 100644 index 0000000..10b8802 --- /dev/null +++ b/skills/executor/scripts/lib/executor/__init__.py @@ -0,0 +1,6 @@ +# Executor v2 engine — single-writer, typed-payload, event-sourced. +# +# Public surface is the CLI in executor.cli; this package is the kernel. +__version__ = "2.0.2" +SCHEMA_VERSION = "v1" +STORE_VERSION = "v1" diff --git a/skills/executor/scripts/lib/executor/__main__.py b/skills/executor/scripts/lib/executor/__main__.py new file mode 100755 index 0000000..c86b755 --- /dev/null +++ b/skills/executor/scripts/lib/executor/__main__.py @@ -0,0 +1,16 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: MIT +# Copyright (c) 2026 Atri10 +"""`python -m executor` — the same CLI as `python engine/executor/cli.py`. + +Exists so a launch needs no shell, no shebang bit, and no path arithmetic: +PYTHONPATH=engine python3 -m executor next +""" +from __future__ import annotations + +import sys + +from executor.cli import main + +if __name__ == "__main__": + sys.exit(main(sys.argv)) diff --git a/skills/executor/scripts/lib/executor/cli.py b/skills/executor/scripts/lib/executor/cli.py new file mode 100755 index 0000000..e8ff727 --- /dev/null +++ b/skills/executor/scripts/lib/executor/cli.py @@ -0,0 +1,255 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: MIT +# Copyright (c) 2026 Atri10 +"""executor — the v2 CLI. The pump loop is next → ingest. + + executor new "<title>" scaffold INIT-NNNN + executor next [INIT] one typed action + its prompt + executor ingest <path|-> [INIT] a worker payload: validate → fold → render + executor decide <path|-> [INIT] a human decision: gate_decision, ruling, resume + executor status [INIT] gate card + executor check [INIT] [--secrets] chain, edges, liveness, layout; or scan for secrets + executor doctor [INIT] check + open dispatches + policy in force + executor graph [INIT] [--format json|mermaid] + executor migrate [INIT] [--dry-run] reports the store version verdict; never edits + executor autonomy [INIT] [<phase> <allow|gate|deny>] per-phase autonomy; deny by default + +Exit codes: 0 ok · 1 check found problems · 2 usage, a refusal, or an engine error. +Every write goes through engine.ingest, engine.emit_next or engine.create_initiative. +Human decisions are only accepted through `decide`; a worker payload cannot name +itself human, so it cannot approve its own gate or rule on its own concern. +""" +from __future__ import annotations + +import json +import sys +from pathlib import Path + +sys.path.insert(0, str(Path(__file__).resolve().parent.parent)) +from executor import __version__ # noqa: E402 +from executor.engine import (check, create_initiative, emit_next, # noqa: E402 + fold, ingest, open_dispatches, scan_secrets) +from executor.paths import autonomy_file, docs_root # noqa: E402 +from executor.policy import (AUTONOMY_MODES, effective_policy, # noqa: E402 + normalize_autonomy) +from executor.store import (PHASES, ExecError, Initiative, # noqa: E402 + Rejection, find_initiative, meta_file, read_json, + repo_root, store_version_verdict, write_json) +from executor.views import status_card # noqa: E402 + +HUMAN_COMMANDS = frozenset({"gate_decision", "ruling", "resume"}) + + +def _emit(obj) -> None: + print(json.dumps(obj, indent=2, ensure_ascii=False)) + + +def _err(e: ExecError | Rejection) -> int: + if isinstance(e, Rejection): + print(json.dumps({"rejected": e.to_dict()}, indent=2), file=sys.stderr) + else: + print(json.dumps({"error": e.msg, "code": e.code}, indent=2), file=sys.stderr) + return 2 + + +def _read_payload(path: str) -> dict: + """UTF-8 on every platform: a Windows console or a legacy locale must not + decide how a payload decodes.""" + if path == "-": + raw = sys.stdin.buffer.read().decode("utf-8") + else: + raw = Path(path).read_bytes().decode("utf-8") + try: + return json.loads(raw) + except json.JSONDecodeError as e: + raise Rejection("not_json", "$", "valid JSON", + f"parse error at {e.lineno}:{e.colno}") from e + + +def _target(args: list[str], gate: bool = True) -> tuple[Initiative, list[str]]: + """The initiative a command acts on: an explicit INIT-id as the first argument, + or the one in flight. Returns the remaining arguments. `gate=False` opens a + store whatever its engine version; only `migrate` asks for that.""" + if args and args[0].upper().startswith("INIT-"): + return find_initiative(repo_root(), args[0].upper(), gate=gate), args[1:] + return find_initiative(repo_root(), gate=gate), args + + +def cmd_new(args: list[str]) -> int: + title = " ".join(args).strip('"').strip() + if not title: + raise ExecError('usage: executor new "<title>"', "usage") + init = create_initiative(repo_root(), title) + _emit({"created": init.id, "title": title, + "store": str(init.idir), "docs": str(docs_root(init.root) / init.id)}) + return 0 + + +def cmd_next(args: list[str]) -> int: + init, _ = _target(args) + _emit(emit_next(init)) + return 0 + + +def cmd_ingest(args: list[str]) -> int: + if not args: + raise ExecError("usage: executor ingest <path.json|-> [INIT-ID]", "usage") + payload = _read_payload(args[0]) + if payload.get("kind") in HUMAN_COMMANDS: + raise Rejection("unauthorized", "$.kind", "a worker payload", + payload["kind"], "use `executor decide` for human decisions") + init, _ = _target(args[1:]) + ev = ingest(init, payload, actor="worker") + _emit(ev if ev.get("deduplicated") else + {"accepted": ev["kind"], "seq": ev["seq"], "entity": ev["entity"]}) + return 0 + + +def cmd_decide(args: list[str]) -> int: + if not args: + raise ExecError("usage: executor decide <path.json|-> [INIT-ID]", "usage") + payload = _read_payload(args[0]) + kind = payload.get("kind") + if kind not in HUMAN_COMMANDS: + raise Rejection("unauthorized", "$.kind", + "gate_decision, ruling or resume", str(kind), + "worker payloads go through `executor ingest`") + init, _ = _target(args[1:]) + ev = ingest(init, payload, actor="human") + _emit({"accepted": ev["kind"], "seq": ev["seq"], "entity": ev["entity"]}) + return 0 + + +def cmd_status(args: list[str]) -> int: + init, _ = _target(args) + print(status_card(init, fold(init.events))) + return 0 + + +def cmd_check(args: list[str]) -> int: + rest = [a for a in args if a != "--secrets"] + secrets = len(rest) != len(args) + init, extra = _target(rest) + if extra: + raise ExecError("usage: executor check [--secrets] [INIT-ID]", "usage") + if secrets: + res = scan_secrets(init) + _emit(res) + return 0 if not res["findings"] else 1 + res = check(init) + _emit(res) + return 0 if res["chain"] == "ok" and not res["problems"] else 1 + + +def cmd_doctor(args: list[str]) -> int: + init, _ = _target(args) + res = check(init) + values, sources, _sha = effective_policy(init.root, init.id, init.idir) + res.update({ + "open_dispatch_ids": [d["dispatch_id"] for d in open_dispatches(init)], + "policy": {"values": values, "sources": sources}, + "last_seq": len(init.events), + }) + _emit(res) + return 0 if res["chain"] == "ok" and not res["problems"] else 1 + + +def cmd_autonomy(args: list[str]) -> int: + """executor autonomy [INIT] [<phase> <allow|gate|deny>]. With no phase, prints + the policy in force. With a phase and mode, sets it. An unknown phase or mode is + refused, so a typo can never widen a phase: the engine fails closed on anything + it does not recognise, and so does this command.""" + init, rest = _target(args) + path = autonomy_file(init.idir) + current = normalize_autonomy(read_json(path), PHASES) + if not rest: + _emit({"initiative": init.id, "autonomy": current}) + return 0 + if len(rest) != 2: + raise ExecError("usage: executor autonomy [INIT] <phase> <allow|gate|deny>", + "usage") + phase, mode = rest + if phase not in PHASES: + raise ExecError(f"unknown phase {phase!r}; phases are {', '.join(PHASES)}", + "unknown_phase") + if mode not in AUTONOMY_MODES: + raise ExecError(f"mode must be one of {', '.join(AUTONOMY_MODES)}; got {mode!r}", + "unknown_mode") + write_json(path, {**current, phase: mode}) + _emit({"initiative": init.id, "set": {phase: mode}, + "autonomy": normalize_autonomy(read_json(path), PHASES)}) + return 0 + + +def cmd_graph(args: list[str]) -> int: + fmt = "json" + if "--format" in args: + i = args.index("--format") + if i + 1 >= len(args): + raise ExecError("usage: --format json|mermaid", "usage") + fmt = args[i + 1] + args = args[:i] + args[i + 2:] + if fmt not in ("json", "mermaid"): + raise ExecError(f"unknown graph format {fmt!r}", "usage") + init, _ = _target(args) + s = fold(init.events) + if fmt == "mermaid": + lines = ["flowchart LR"] + for e in s["edges"]: + a = e["from"].replace("-", "_") + b = e["to"].replace("-", "_") + lines.append(f" {a} -->|{e['kind']}| {b}") + for nid, n in s["entities"].items(): + lines.append(f" {nid.replace('-', '_')}[\"{nid}\\n{n['type']}\"]") + print("\n".join(lines)) + else: + _emit({"nodes": s["entities"], "edges": s["edges"], "initiative": init.id}) + return 0 + + +def cmd_migrate(args: list[str]) -> int: + """Reports the store's version verdict, the same one the engine enforces when + it opens a store. It opens the store ungated, because a skewed store is exactly + what it must explain. No upgrade path exists yet, so it never edits anything.""" + init, rest = _target(args, gate=False) + meta = read_json(meta_file(init.idir)) or {} + verdict = store_version_verdict(meta.get("engine_version", "0")) + _emit({"initiative": init.id, + "store_engine_version": meta.get("engine_version"), + "engine": __version__, "dry_run": "--dry-run" in rest, + "verdict": verdict, + "action": "none" if verdict == "current" + else "refused: no migration is defined for this engine version"}) + return 0 if verdict == "current" else 1 + + +COMMANDS = {"new": cmd_new, "next": cmd_next, "ingest": cmd_ingest, + "decide": cmd_decide, "status": cmd_status, "check": cmd_check, + "doctor": cmd_doctor, "graph": cmd_graph, "migrate": cmd_migrate, + "autonomy": cmd_autonomy} + + +def main(argv: list[str]) -> int: + if len(argv) < 2 or argv[1] in ("-h", "--help", "help"): + print(__doc__) + return 0 + cmd = argv[1] + if cmd in ("-V", "--version"): + print(__version__) + return 0 + fn = COMMANDS.get(cmd) + if not fn: + print(f"unknown command {cmd!r}\n{__doc__}", file=sys.stderr) + return 2 + try: + return fn(argv[2:]) + except (Rejection, ExecError) as e: + return _err(e) + except FileNotFoundError as e: + return _err(ExecError(str(e), "missing_file")) + except KeyboardInterrupt: + return 130 + + +if __name__ == "__main__": + sys.exit(main(sys.argv)) diff --git a/skills/executor/scripts/lib/executor/engine.py b/skills/executor/scripts/lib/executor/engine.py new file mode 100644 index 0000000..b842dc2 --- /dev/null +++ b/skills/executor/scripts/lib/executor/engine.py @@ -0,0 +1,1478 @@ +# SPDX-License-Identifier: MIT +# Copyright (c) 2026 Atri10 +"""The kernel: fold the journal, decide the next action, ingest payloads. + +fold pure: journal -> state. The only interpretation of events. +emit_next decides exactly one action and writes only when the run moves: a + phase is entered, a gate opens, a worker is dispatched, a dispatch + is abandoned, a preflight verdict is recorded, or the run escalates. + A repeated poll returns the same instruction and writes nothing. +ingest validates one payload against the schema, the state, the open + dispatch it answers and git, then commits exactly one event. A + rejection writes nothing. +check read-only audit of the chain, edges, liveness, dispatches and layout. + +Every write holds the store lock from the first read of the journal to the +last write, so the state a payload is validated against is the state it is +committed against. +""" +from __future__ import annotations + +import calendar +import contextlib +import re +import subprocess +import threading +import time +from pathlib import Path + +from .paths import (artifact_file, audit_file, classify, dispatch_id, + dispatches_dir, docs_artifact_file, docs_artifact_md, + docs_export_journal, docs_index_file, docs_index_md, + docs_init_dir, docs_plan_file, docs_plan_md, docs_report_file, + docs_root, docs_verdict_file, fix_package_file, + fix_report_file, is_dispatch_id, journal_file, payload_file, + plan_audit_file, plan_file, plan_repair_file, preflight_file, + prompt_file, repair_file, review_package_file, run_root, + state_file, task_impl_report, verdict_file, autonomy_file) +from .policy import default_state, effective_policy, normalize_autonomy, policy_sha +from .schemas import ARTIFACT_KINDS, schema_for, validate +from .store import (PHASES, ExecError, Initiative, Rejection, StoreLock, + append_event, atomic_write, init_store, make_event, + next_seq, read_events, read_json, scan_journal, sha256, + verify_chain, write_json) +from .views import (render_all, render_handoff_index, render_handoff_md, + render_report_md, render_verdict_md) + + +# A human sends these: a worker cannot approve its own gate or rule on its own concern. +HUMAN_KINDS = frozenset({"gate_decision", "ruling", "resume"}) +# While the run is halted only these may land: a human ending the halt, or the +# ruling the halt may be waiting on. +HALT_OPEN_KINDS = frozenset({"ruling", "resume"}) +# Kinds that answer no dispatch: human decisions, halts and the merge record. +SLOT_FREE_KINDS = HUMAN_KINDS | {"halt", "merge"} +# Kinds the engine writes itself; a worker can never produce these. +ENGINE_KINDS = frozenset({"created", "phase_entered", "gate_opened", + "task_dispatched", "abandon", "preflight", "policy"}) +WORKER_KINDS = (frozenset({"report", "heartbeat", "verdict", "spawn_error", + "needs_context", "evidence", "audit"}) + | frozenset(ARTIFACT_KINDS)) +KNOWN_KINDS = ENGINE_KINDS | SLOT_FREE_KINDS | WORKER_KINDS +# Events that carry a dispatch id but do not close that dispatch. +NON_ANSWERING = frozenset({"heartbeat", "task_dispatched"}) +# Schemas whose payload must echo the engine-minted round. +ROUND_SCHEMAS = frozenset({"verdict", "audit"}) + +PHASE_ARTIFACTS = { + "intake": ["charter"], "discovery": ["options", "brainstorm"], + "architecture": ["arch", "adr", "ifce"], + "design": ["design"], "specification": ["spec", "risk", "vrfy"], + "planning": ["plan"], "execution": [], "review": [], + "plan_regression": [], "verification": [], "handoff": []} + +# Pick-class phases: the gate is a choice a human makes between options, so no +# automatic pass may clear it. Mirrors v1 exec-gate's is_pick_phase, kept explicit so +# the engine never infers it. +PICK_PHASES = frozenset({"design", "specification"}) +# Phases whose gate the engine must never clear unattended: the pick-class +# phases, where a human chooses between options, and handoff, where a human +# signs off on the finished run. Every other gate is structural. +NEVER_AUTO = PICK_PHASES | {"handoff"} + + +_AKIND = {"charter": "CHTR-01", "options": "OPTS-01", "brainstorm": "BRN-01", + "arch": "ARCH-01", "adr": "ADR-01", "ifce": "IFCE-01", + "design": "DSGN-01", "spec": "SPEC-01", "risk": "RISK-01", + "vrfy": "VRFY-01"} + +_held = threading.local() + + +# ------------------------------------------------------------ locking + +@contextlib.contextmanager +def _exclusive(idir: Path): + """The store lock, re-entrant within a thread so helpers that write may run + inside an outer locked section. Other threads and processes wait for the + whole outer section.""" + key = str(idir) + if getattr(_held, "key", None) == key: + yield + return + with StoreLock(idir): + _held.key = key + try: + yield + finally: + _held.key = None + + +# ------------------------------------------------------------ git + +def _git(root: Path, *args: str) -> str: + r = subprocess.run(["git", "-C", str(root), *args], capture_output=True, + text=True, encoding="utf-8", errors="replace") + if r.returncode != 0: + raise ExecError(f"git {' '.join(args)} failed: {r.stderr.strip()}", + "git_error") + return r.stdout + + +def _safe_rev(rev) -> bool: + """Agent-supplied revisions reach git as arguments: a leading '-' would be + read as an option, and anything outside a plain rev charset is refused.""" + return (isinstance(rev, str) and not rev.startswith("-") + and re.fullmatch(r"[A-Za-z0-9._/~^@{}-]+", rev) is not None) + + +def rev_exists(root: Path, rev: str) -> bool: + return _safe_rev(rev) and subprocess.run( + ["git", "-C", str(root), "cat-file", "-e", f"{rev}^{{commit}}"], + capture_output=True).returncode == 0 + + +def path_at_rev(root: Path, rev: str, path: str) -> bool: + return (_safe_rev(rev) and not path.startswith("-") + and subprocess.run(["git", "-C", str(root), "cat-file", "-e", + f"{rev}:{path}"], + capture_output=True).returncode == 0) + + +def _head(root: Path) -> str: + return _git(root, "rev-parse", "HEAD").strip() + + +def _resolve(root: Path, rev: str) -> str: + return _git(root, "rev-parse", "--verify", f"{rev}^{{commit}}").strip() + + +def _is_ancestor(root: Path, a: str, b: str) -> bool: + return subprocess.run(["git", "-C", str(root), "merge-base", + "--is-ancestor", a, b], + capture_output=True).returncode == 0 + + +# ------------------------------------------------------------ fold + +def fold(events: list[dict]) -> dict: + """Pure: journal -> folded state. The single source of truth. + + `answered` maps each dispatch id to the digest of the payload that closed + it (None when the engine closed it without an answer). Openness, base and + context of a dispatch live in the journal too, so a lost file costs nothing.""" + s: dict = { + "phase": "intake", "phase_state": {}, + "artifacts": {}, "critiques": {}, + "plans": {}, "plan_order": [], + "tasks": {}, "verdicts": {}, "reports": {}, + "rulings": [], "evidence": {}, + "dispatches": {}, "answered": {}, "lost": {}, + "needs_ruling": [], "questions": [], + "halt": None, "done": False, "entities": {}, "edges": [], + "policy": default_state(), + "seq": len(events), + } + for ev in events: + _apply(s, ev) + return s + + +def _crit_key(s: dict, target: str) -> str: + """Critiques belong to the phase they happened in: plan_regression re-audits + what planning already cleared, and must not inherit that verdict.""" + return f"{s['phase']}:{target}" + + +def _apply(s: dict, ev: dict) -> None: + k, d, e = ev["kind"], ev.get("data") or {}, ev["entity"] + did = ev.get("dispatch_id") + if did and k not in NON_ANSWERING: + s["answered"][did] = ev.get("payload_sha") + if k == "created": + _node(s, e, "initiative") + elif k == "phase_entered": + s["phase"] = d["phase"] + s["phase_state"][d["phase"]] = "in_progress" + elif k == "gate_opened": + s["phase_state"][d["phase"]] = "gate_pending" + elif k == "gate_decision": + _apply_gate(s, d) + elif k == "halt": + s["halt"] = d.get("reason", "halted") + elif k == "resume": + s["halt"] = None + elif k in ARTIFACT_KINDS: + _apply_artifact(s, k, e, d) + elif k == "audit": + _apply_audit(s, d) + elif k == "task_dispatched": + _apply_dispatch(s, ev, d) + elif k == "abandon": + _apply_lost(s, did, "abandoned", d.get("reason", "abandoned")) + elif k == "spawn_error": + _apply_lost(s, did, "spawn_error", d["error_class"]) + elif k == "report": + _apply_report(s, e, d) + elif k == "heartbeat": + if did in s["dispatches"]: + s["dispatches"][did]["last_beat"] = ev["ts"] + elif k == "verdict": + _apply_verdict(s, e, d) + elif k == "needs_context": + t = s["tasks"].get(e) + if t is not None: + t.update(state="needs_context", question=d["question"]) + s["questions"].append({"task": e, "question": d["question"], + "ruled": False}) + elif k == "ruling": + _apply_ruling(s, d) + elif k == "preflight": + _apply_preflight(s, d) + elif k == "evidence": + s["evidence"].setdefault(d["criterion"], []).append(d) + elif k == "policy": + s["policy"] = {**d, "recorded": True} + elif k == "merge": + s["plans"].setdefault(d["plan"], {"status": "draft"}).update( + status="merged", merge_sha=d["merge_sha"]) + + +def _apply_gate(s: dict, d: dict) -> None: + ph = d["phase"] + if d["decision"] == "rejected": + s["halt"] = f"gate {ph} rejected: {d.get('note') or 'no note'}" + return + s["phase_state"][ph] = "passed" # approved or waived + if ph == "handoff": + s["done"] = True + + +def _apply_artifact(s: dict, kind: str, aid: str, d: dict) -> None: + a = s["artifacts"].setdefault(aid, {"kind": kind, "status": "drafted", + "round": 0, "data": d}) + a.update(status="drafted", round=a["round"] + 1, data=d) + _node(s, aid, "artifact") + for c in d.get("cites", []): + _edge(s, aid, c, "cites") + crit = s["critiques"].get(_crit_key(s, aid)) + if crit is not None and crit["status"] == "fail": + crit["status"] = "repaired" # a re-drafted artifact is a repair + if kind == "plan": + s["plans"].setdefault(aid, {"status": "draft"}) + if aid not in s["plan_order"]: + s["plan_order"].append(aid) + _apply_plan_tasks(s, aid, d.get("tasks", [])) + + +def _apply_plan_tasks(s: dict, pid: str, rows: list[dict]) -> None: + """A redrafted plan updates the tasks that have not started and drops the + ones it no longer lists. A task already under way keeps its contract.""" + wanted = {f"{pid}-{t['id']}": t for t in rows} + for tid, t in list(s["tasks"].items()): + if t["plan"] == pid and tid not in wanted and t["state"] == "pending": + del s["tasks"][tid] + for tid, row in wanted.items(): + fields = {"title": row["title"], "goal": row["goal"], + "files": row["files"], "accepts": row["accepts"], + "depends_on": row.get("depends_on", [])} + cur = s["tasks"].get(tid) + if cur is None: + s["tasks"][tid] = {"state": "pending", "round": 0, "fix_rounds": 0, + "plan": pid, "base": None, **fields} + _node(s, tid, "task") + _edge(s, pid, tid, "contains") + elif cur["state"] == "pending": + cur.update(fields) + + +def _apply_audit(s: dict, d: dict) -> None: + tgt = d["target"] + c = s["critiques"].setdefault(_crit_key(s, tgt), + {"round": 0, "status": None, "open": []}) + c["round"] = d["round"] + art = s["artifacts"].get(tgt) + if d["verdict"] == "PASS": + c.update(status="clean", open=[]) + if art is not None: + art["status"] = "cleared" + else: + c.update(status="fail", + open=[f for f in d.get("findings", []) + if f.get("status", "open") == "open"]) + if art is not None: + art["status"] = "under_audit" + + +def _apply_dispatch(s: dict, ev: dict, d: dict) -> None: + did, e = ev["dispatch_id"], ev["entity"] + s["dispatches"][did] = {"entity": e, "role": d["role"], + "schema": d["schema"], + "respond_to": d["respond_to"], + "base": d.get("base"), + "context": d.get("context") or {}, "at": ev["ts"]} + if d["schema"] in ARTIFACT_KINDS: + _node(s, e, "artifact") # the artifact this dispatch authors + t = s["tasks"].get(e) + if t is not None: + t.update(prior_state=t["state"], state="dispatched", role=d["role"], + schema=d["schema"], dispatch_id=did, base=d.get("base")) + _edge(s, did, e, "dispatched") + + +def _apply_lost(s: dict, did: str | None, key: str, value: str) -> None: + """A dispatch closed without an answer: the worker never started (spawn + error) or went silent past its deadline (abandon). The task returns to the + state it was dispatched from, and the loss counts against the retry cap.""" + dsp = s["dispatches"].get(did) + if dsp is None: + return + dsp[key] = value + lk = f"{dsp['entity']}:{dsp['schema']}" + s["lost"][lk] = s["lost"].get(lk, 0) + 1 + t = s["tasks"].get(dsp["entity"]) + if t is not None: + t["state"] = t.get("prior_state", "pending") + + +def _apply_report(s: dict, tid: str, d: dict) -> None: + t = s["tasks"].get(tid) + s["reports"][tid] = d + if t is not None: + t["state"] = "blocked" if d["result"] == "BLOCKED" else "reported" + if d["result"] == "BLOCKED": + t["question"] = f"BLOCKED: {d['summary']}" + for concern in d.get("concerns", []): + s["needs_ruling"].append({"task": tid, "concern": concern, + "ruled": False}) + if d["result"] == "BLOCKED": + s["needs_ruling"].append({"task": tid, "ruled": False, + "concern": f"BLOCKED: {d['summary']}"}) + + +def _apply_verdict(s: dict, tid: str, d: dict) -> None: + s["verdicts"][f"{tid}-R{d['round']:02d}"] = d + t = s["tasks"].get(tid) + if t is None: + return + t["round"] = d["round"] + clean = (d["spec_verdict"] == "PASS" + and d["quality_verdict"] in s["policy"]["values"]["clean_quality"]) + t["state"] = "complete" if clean else "fix_needed" + if not clean: + t["fix_rounds"] += 1 + + +def _apply_ruling(s: dict, d: dict) -> None: + """A ruling clears the concerns it names and frees the task it is about. + A freed task resumes the state it was in before the question, so a question + raised during review resumes review, not implementation.""" + s["rulings"].append(d) + if d.get("stop"): + s["halt"] = d["decision"] + tgt, quoted = d.get("for_task"), d.get("answered") + for n in s["needs_ruling"]: + if tgt and n["task"] == tgt: + n["ruled"] = True + freed = {tgt} if tgt else set() + for q in s["questions"]: + if (tgt and q["task"] == tgt) or (quoted and quoted in q["question"]): + q["ruled"] = True + freed.add(q["task"]) + for tid in freed: + t = s["tasks"].get(tid) + if t is not None and t["state"] in ("blocked", "needs_context"): + t["state"] = t.get("prior_state", "pending") + + +def _apply_preflight(s: dict, d: dict) -> None: + pid = d["plan"] + s["plans"].setdefault(pid, {"status": "draft"})["preflight"] = d["verdict"] + for c in d.get("conflicts", []): + s["needs_ruling"].append({"task": pid, "ruled": False, + "concern": f"file overlap: {c['tasks']} " + f"share {c['files']}"}) + + +def _node(s: dict, nid: str, ntype: str) -> None: + s["entities"].setdefault(nid, {"type": ntype}) + + +def _edge(s: dict, a: str, b: str, kind: str) -> None: + edge = {"from": a, "to": b, "kind": kind} + if edge not in s["edges"]: + s["edges"].append(edge) + + +# ------------------------------------------------------------ small helpers + +def _clock(now: float | None) -> float: + return time.time() if now is None else now + + +def _iso2epoch(ts) -> float: + """UTC ISO timestamp to epoch seconds. timegm reads it as UTC; mktime would + read it as local time and drift on every non-UTC host. An unreadable stamp + raises: read as epoch zero it would make every such dispatch look a billion + seconds silent and get abandoned on the next poll.""" + try: + return float(calendar.timegm(time.strptime(str(ts), "%Y-%m-%dT%H:%M:%SZ"))) + except (TypeError, ValueError) as exc: + raise ExecError(f"unreadable timestamp {ts!r}", "bad_timestamp") from exc + + +def _silent_for(dsp: dict, now: float) -> float: + """Seconds since the dispatch last showed life. A stamp that cannot be + read — malformed, or absent entirely — counts as no silence: a dispatch + is judged dead on evidence, never on bad data.""" + stamp = dsp.get("last_beat") or dsp.get("at") + if not stamp: + return 0.0 + try: + return now - _iso2epoch(stamp) + except ExecError: + return 0.0 + + +def _next_phase(ph: str) -> str | None: + i = PHASES.index(ph) + 1 + return PHASES[i] if i < len(PHASES) else None + + +def _criteria_defs(s: dict) -> list[dict]: + out: list[dict] = [] + for a in s["artifacts"].values(): + if a["kind"] == "vrfy": + out.extend(a["data"].get("criteria", [])) + return out + + +def _last_findings(s: dict, tid: str) -> list[dict]: + mine = [v for v in s["verdicts"].values() if v["task"] == tid] + return mine[-1].get("findings", []) if mine else [] + + +def _action(word: str, init_id: str, **kw) -> dict: + return {"action": word, "initiative": init_id, **kw} + + +def _known_ids(s: dict) -> set[str]: + """Ids a citation may name: an authored artifact, a task, a plan, a + criterion, or a requirement or constraint inside an authored artifact. A + dispatch that has not produced its artifact yet is not a citable id.""" + known = set(s["artifacts"]) | set(s["tasks"]) | set(s["plans"]) + for a in s["artifacts"].values(): + for key in ("requirements", "constraints", "criteria"): + known |= {x["id"] for x in a["data"].get(key, [])} + return known + + +def _kind_of(s: dict, aid: str) -> str: + return "plan" if aid in s["plan_order"] else s["artifacts"][aid]["kind"] + + +def _phase_artifacts(s: dict, ph: str) -> list[str]: + kinds = set(PHASE_ARTIFACTS.get(ph, [])) + return [aid for aid, a in s["artifacts"].items() if a["kind"] in kinds] + + +def _more_plans_wanted(s: dict) -> bool: + """The planner says whether another plan is needed. No plan yet means one is.""" + if not s["plan_order"]: + return True + last = s["artifacts"][s["plan_order"][-1]]["data"] + return bool(last.get("more_plans")) + + +def _write_text(path: Path, text: str) -> None: + atomic_write(path, text.encode("utf-8")) + + +# ------------------------------------------------------------ journal writes + +def _event(init: Initiative, actor: str, kind: str, entity: str, data: dict, + dispatch_id_: str | None = None, + payload_sha: str | None = None) -> dict: + """The next chained event, not yet appended. Callers hold the lock.""" + return make_event(init.idir, actor, kind, entity, data, + dispatch_id=dispatch_id_, payload_sha=payload_sha) + + +def _append(init: Initiative, ev: dict) -> dict: + append_event(init.idir, ev) + init.events.append(ev) + return ev + + +def _record(init: Initiative, actor: str, kind: str, entity: str, data: dict, + dispatch_id_: str | None = None) -> dict: + """An engine write: the caller holds the lock.""" + return _append(init, _event(init, actor, kind, entity, data, dispatch_id_)) + + +def _sync_policy(init: Initiative) -> dict: + """Journal the effective policy when it differs from the one in force. The + caller holds the lock. Ingest calls this only after every check has passed, + so a rejected payload journals no policy change.""" + values, sources, sha = effective_policy(init.root, init.id, init.idir) + state = fold(init.events)["policy"] + if not state["recorded"] or state["sha"] != sha: + _record(init, "engine", "policy", init.id, + {"values": values, "sources": sources, "sha": sha}) + return values + + +def _project(init: Initiative) -> None: + """Refresh the fold cache and every projection after a journal change. Once + the handoff gate is approved, the committed handoff files follow.""" + s = fold(init.events) + write_json(state_file(init.idir), s | {"last_seq": len(init.events)}) + render_all(init) + if s["done"]: + _export_handoff(init, s) + + +def _export_handoff(init: Initiative, s: dict) -> None: + """The committed handoff: an index of the run and a byte copy of its journal. + Both are pure functions of the journal, so a re-export rewrites identical + bytes.""" + write_json(docs_index_file(init.root, init.id), + render_handoff_index(init.id, s)) + _write_text(docs_index_md(init.root, init.id), + render_handoff_md(init.id, s)) + atomic_write(docs_export_journal(init.root, init.id), + journal_file(init.idir).read_bytes()) + + +# ------------------------------------------------------------ dispatches + +def _open_slots(s: dict) -> list[dict]: + """Dispatches the journal records and nothing has answered, in id order. + Openness, base and context come from the journal alone.""" + return [{"dispatch_id": did, "entity": d["entity"], "schema": d["schema"], + "role": d["role"], "respond_to": d["respond_to"], + "base": d["base"], "context": d["context"]} + for did, d in sorted(s["dispatches"].items()) + if did not in s["answered"]] + + +def _open_for(s: dict, entity: str, schema: str | None = None) -> dict | None: + for sl in _open_slots(s): + if sl["entity"] == entity and (schema is None or sl["schema"] == schema): + return sl + return None + + +def open_dispatches(init: Initiative) -> list[dict]: + """What a worker may still answer, in id order. Reads the journal and + writes nothing, so it is safe at any time.""" + return _open_slots(fold(read_events(init.idir))) + + +def _dispatch_action(init: Initiative, sl: dict) -> dict: + return _action("DISPATCH", init.id, entity=sl["entity"], role=sl["role"], + schema=sl["schema"], dispatch_id=sl["dispatch_id"], + respond_to=sl["respond_to"], cwd=str(init.root), + prompt=str(prompt_file(init.idir, sl["dispatch_id"])), + base=sl["base"], context=sl["context"]) + + +# ------------------------------------------------------------ emit next + +def emit_next(init: Initiative, now: float | None = None) -> dict: + """Decide exactly one action, plus a resume manifest. Idempotent: while a + dispatch is open, polling returns the same instruction and writes nothing.""" + with _exclusive(init.idir): + init.reload() + before = len(init.events) + _sync_policy(init) + act = _decide(init, fold(init.events), _clock(now)) + if len(init.events) != before: + _project(init) + act["resume"] = _manifest(init, fold(init.events)) + return act + + +def _manifest(init: Initiative, s: dict) -> dict: + """What a cold pump needs to resume with no history.""" + return { + "initiative": init.id, + "phase": s["phase"], + "phase_state": s["phase_state"].get(s["phase"], "-"), + "last_event": init.events[-1]["kind"] if init.events else None, + "last_seq": len(init.events), + "open_concerns": sum(1 for n in s["needs_ruling"] if not n["ruled"]), + "open_slots": len(_open_slots(s)), + "tasks_done": sum(1 for t in s["tasks"].values() + if t["state"] == "complete"), + "tasks_total": len(s["tasks"]), + } + + +def _decide(init: Initiative, s: dict, now: float) -> dict: + if s["halt"]: + return _action("HALT", init.id, reason=s["halt"]) + if s["done"]: + return _action("DONE", init.id) + unruled = [n for n in s["needs_ruling"] if not n["ruled"]] + if unruled: + return _action("ASK", init.id, topic=unruled[0]["concern"], + task=unruled[0]["task"]) + ph = s["phase"] + pstate = s["phase_state"].get(ph) + if pstate == "passed": + nxt = _next_phase(ph) + return _enter(init, nxt) if nxt else _action("DONE", init.id) + if pstate is None: + return _enter(init, ph) + if pstate == "gate_pending": + return _action("GATE", init.id, phase=ph) + work = _phase_work(init, s, ph, now) + return work if work is not None else _open_gate(init, s, ph, now) + + +def _enter(init: Initiative, phase: str) -> dict: + _record(init, "engine", "phase_entered", init.id, {"phase": phase}) + return _action("PHASE-ENTER", init.id, phase=phase) + + +def _open_gate(init: Initiative, s: dict, ph: str, now: float) -> dict: + """Open the gate for a phase that has no work left. A structural phase whose + journaled autonomy mode is gate or allow clears itself here, recorded as an + automatic decision so the record never reads as a human's. A phase in + NEVER_AUTO never clears itself: a pick needs a human choice, and handoff is + the human's sign-off on the finished run.""" + _record(init, "engine", "gate_opened", init.id, {"phase": ph}) + mode = normalize_autonomy(s["policy"]["values"].get("autonomy"), (ph,)).get(ph, "deny") + if mode in ("gate", "allow") and ph not in NEVER_AUTO: + _record(init, "engine", "gate_decision", init.id, + {"phase": ph, "decision": "approved", "by": "auto", + "note": f"autonomy {mode}"}) + return _decide(init, fold(init.events), now) + return _action("GATE", init.id, phase=ph) + + +def _escalate(init: Initiative, reason: str) -> dict: + """Escalation latches: the halt is a journal event, so every later poll + returns HALT until a human sends a resume. The engine never retries past a + cap by itself.""" + _record(init, "engine", "halt", init.id, {"reason": reason, + "source": "engine"}) + return _action("ESCALATE", init.id, reason=reason) + + +def _phase_work(init: Initiative, s: dict, ph: str, now: float): + """The next dispatch, ask or escalation for this phase; None when the phase + has nothing left to do and its gate may open.""" + if ph == "execution": + return _execution(init, s, now) + if ph == "verification": + return _verification(init, s, now) + if ph == "planning" and _more_plans_wanted(s): + cap = s["policy"]["values"]["max_plans"] + if len(s["plan_order"]) >= cap: + return _escalate(init, f"the planner asked for more than " + f"{cap} plans") + return _author(init, s, "plan", now) + for kind in PHASE_ARTIFACTS.get(ph, []): + if not any(a["kind"] == kind for a in s["artifacts"].values()): + return _author(init, s, kind, now) + targets = (list(s["plan_order"]) if ph == "plan_regression" + else _phase_artifacts(s, ph)) + for tgt in targets: + c = s["critiques"].get(_crit_key(s, tgt)) + if c is None or c["status"] == "repaired": + rnd = _audit_rounds(s, tgt) + cap = s["policy"]["values"]["max_audit_rounds"] + if rnd >= cap: + return _escalate(init, f"{tgt} not cleared after " + f"{cap} audit rounds") + return _dispatch(init, s, "audit", tgt, "audit", now=now, + context={"round": rnd + 1}) + if c["status"] == "fail": + return _dispatch(init, s, "repair", tgt, _kind_of(s, tgt), now=now, + context={"round": c["round"], "findings": c["open"]}) + return None + + +def _audit_rounds(s: dict, tgt: str) -> int: + """Audit rounds are numbered per target across phases, so a plan audited in + planning and again in plan_regression gets rounds 1 and 2, and each round + keeps its own canonical file.""" + return max((c["round"] for key, c in s["critiques"].items() + if key.split(":", 1)[1] == tgt), default=0) + + +def _author(init: Initiative, s: dict, kind: str, now: float) -> dict: + eid = (f"{init.id}-P{len(s['plan_order']) + 1:02d}" if kind == "plan" + else f"{init.id}-{_AKIND[kind]}") + return _dispatch(init, s, "author", eid, kind, now=now) + + +def _verification(init: Initiative, s: dict, now: float): + for crit in _criteria_defs(s): + runs = s["evidence"].get(crit["id"], []) + if runs and runs[-1]["verdict"] == "proven": + continue + cap = s["policy"]["values"]["max_evidence_tries"] + if len(runs) >= cap: + return _escalate(init, f"{crit['id']} not proven after " + f"{cap} attempts") + return _dispatch(init, s, "evidence", crit["id"], "evidence", now=now, + context={"criterion": crit["criterion"], + "procedure": crit["procedure"]}) + return None + + +def _execution(init: Initiative, s: dict, now: float): + pending = [pid for pid in s["plan_order"] + if s["plans"][pid]["status"] != "merged"] + if not pending: + return None + for pid in pending: + act = _plan_step(init, s, pid, now) + if act is not None: + return act + return _escalate(init, "no dispatchable work: every pending task is blocked " + "or its dependencies can never complete") + + +def _plan_step(init: Initiative, s: dict, pid: str, now: float): + tids = sorted(tid for tid, t in s["tasks"].items() if t["plan"] == pid) + for tid in tids: + t = s["tasks"][tid] + st = t["state"] + if st == "dispatched": + sl = _open_for(s, tid) + if sl is None: + return _escalate(init, f"{tid} is dispatched with no open " + f"dispatch on record") + return _dispatch(init, s, sl["role"], tid, sl["schema"], now=now, + base=sl["base"], context=sl["context"]) + if st == "pending": + if not all(s["tasks"].get(f"{pid}-{dep}", {}).get("state") + == "complete" for dep in t["depends_on"]): + continue + pre = _preflight(init, s, pid) + if pre is not None: + return pre + return _dispatch(init, s, "impl", tid, "report", now=now, + base=_head(init.root)) + if st in ("needs_context", "blocked"): + return _action("ASK", init.id, topic=t.get("question", tid), + task=tid) + if st == "reported": + return _review(init, s, tid, now) + if st == "fix_needed": + cap = s["policy"]["values"]["max_fix_rounds"] + if t["fix_rounds"] >= cap: + return _escalate(init, f"{tid} hit the fix-round cap " + f"({cap})") + return _dispatch(init, s, "fix", tid, "report", now=now, + base=t["base"], + context={"round": t["fix_rounds"], + "findings": _last_findings(s, tid)}) + if tids and all(s["tasks"][tid]["state"] == "complete" for tid in tids): + return _merge(init, s, pid) + return None + + +def _review(init: Initiative, s: dict, tid: str, now: float) -> dict: + t = s["tasks"][tid] + return _dispatch(init, s, "review", tid, "verdict", now=now, + base=t["base"], + context={"round": t["round"] + 1, + "findings": _last_findings(s, tid)}) + + +def _merge(init: Initiative, s: dict, pid: str) -> dict: + """The pump performs the merge and ingests the merge record. Nothing is + journaled here: a repeated poll returns the same MERGE instruction.""" + heads = {} + for tid in sorted(tid for tid, t in s["tasks"].items() if t["plan"] == pid): + commits = s["reports"].get(tid, {}).get("commits") or [] + heads[tid] = commits[-1] if commits else None + return _action("MERGE", init.id, plan=pid, heads=heads) + + +def _preflight(init: Initiative, s: dict, pid: str): + """File-ownership scan, once per plan before its first dispatch. Two tasks + that share a file and have no dependency path between them are a plan + defect: the verdict is recorded and each overlap becomes a ruling to make.""" + path = preflight_file(init.idir, pid) + if path.exists(): + return None + tasks = {tid: t for tid, t in s["tasks"].items() if t["plan"] == pid} + conflicts = [] + ids = sorted(tasks) + for i, a in enumerate(ids): + for b in ids[i + 1:]: + if _ordered(tasks, a, b): + continue + shared = sorted(set(tasks[a]["files"]) & set(tasks[b]["files"])) + if shared: + conflicts.append({"tasks": [a, b], "files": shared}) + verdict = "conflict" if conflicts else "clear" + write_json(path, {"plan": pid, "verdict": verdict, + "conflicts": conflicts}) + _record(init, "engine", "preflight", pid, + {"plan": pid, "verdict": verdict, "conflicts": conflicts}) + if conflicts: + return _action("ASK", init.id, task=pid, + topic=f"{pid}: file ownership overlaps between " + f"unordered tasks: {conflicts}") + return None + + +def _ordered(tasks: dict, a: str, b: str) -> bool: + """True when a depends on b or b on a, directly or through the plan.""" + return _reaches(tasks, a, b) or _reaches(tasks, b, a) + + +def _reaches(tasks: dict, src: str, dst: str) -> bool: + seen, todo = set(), [src] + while todo: + cur = todo.pop() + for dep in tasks.get(cur, {}).get("depends_on", []): + nxt = f"{tasks[cur]['plan']}-{dep}" + if nxt == dst: + return True + if nxt not in seen: + seen.add(nxt) + todo.append(nxt) + return False + + +def _review_package(init: Initiative, s: dict, tid: str, rnd: int, + base: str) -> dict: + """What the reviewer must see: the range from the task's base to what the + worker reported, the changed files, the diff itself and the prior findings. + The package sha is what the verdict must echo back.""" + head = _resolve(init.root, s["reports"][tid]["commits"][-1]) + diff = _git(init.root, "diff", "--no-color", base, head) + names = _git(init.root, "diff", "--name-only", base, head).splitlines() + core = {"task": tid, "round": rnd, "base": base, "head": head, + "changed_files": names, "diff_sha256": sha256(diff), + "prior_findings": _last_findings(s, tid)} + return {**core, "diff": diff, "package_sha": sha256(core)} + + +def _dispatch(init: Initiative, s: dict, role: str, entity: str, schema: str, + *, now: float, base: str | None = None, + context: dict | None = None) -> dict: + """Journal a dispatch and write what the worker needs. An open dispatch for + the same entity and schema is re-emitted, never duplicated; one silent past + the deadline is abandoned first. The dispatch id is the seq of the event + that records it, so the id and the journal cannot disagree.""" + pol = s["policy"]["values"] + open_sl = _open_for(s, entity, schema) + if open_sl is not None: + dsp = s["dispatches"][open_sl["dispatch_id"]] + try: + _iso2epoch(dsp.get("last_beat") or dsp["at"]) + except ExecError: + return _escalate(init, f"{entity}: dispatch {open_sl['dispatch_id']} has " + f"an unreadable timestamp; liveness cannot be judged") + if _silent_for(dsp, now) <= pol["deadline_s"]: + return _dispatch_action(init, open_sl) + _record(init, "engine", "abandon", entity, + {"reason": f"silent past {pol['deadline_s']}s"}, + dispatch_id_=open_sl["dispatch_id"]) + s = fold(init.events) + lost = s["lost"].get(f"{entity}:{schema}", 0) + if lost > pol["spawn_retry_cap"]: + return _escalate(init, f"{entity}: {schema} dispatch lost {lost} times") + ctx = dict(context or {}) + package = None + if role == "review": + assert base is not None, "a review is measured from its task's dispatch base" + package = _review_package(init, s, entity, ctx["round"], base) + ctx.update(package_sha=package["package_sha"], base=package["base"], + head=package["head"]) + did = dispatch_id(next_seq(init.events)) + sl = {"dispatch_id": did, "entity": entity, "role": role, + "schema": schema, + "respond_to": payload_file(init.idir, did).relative_to( + init.root).as_posix(), + "base": base, "context": ctx} + if package is not None: + write_json(review_package_file(init.idir, entity, ctx["round"]), package) + if role == "fix": + write_json(fix_package_file(init.idir, entity, ctx["round"]), + {"task": entity, "findings": ctx.get("findings", []), + "base": base}) + _write_text(prompt_file(init.idir, did), _render_prompt(init, s, sl)) + _record(init, "engine", "task_dispatched", entity, + {"role": role, "schema": schema, "respond_to": sl["respond_to"], + "base": base, "context": ctx}, dispatch_id_=did) + return _dispatch_action(init, sl) + + +def _render_prompt(init: Initiative, s: dict, sl: dict) -> str: + """Everything a cold worker needs: where to write, what kind to emit, the + task contract, the findings to answer and, for review, the package.""" + ctx = sl["context"] + e = sl["entity"] + lines = [f"# {sl['role'].upper()} - {e}", "", + f"Dispatch id: `{sl['dispatch_id']}`", + f"Write your JSON payload to: `{sl['respond_to']}`", + f"Payload kind: `{sl['schema']}` (emit exactly this kind)", + f"Working directory: `{init.root}` (cd here; paths are " + f"repo-relative)", ""] + if "round" in ctx: + echo = (" (echo it in the `round` field)" + if sl["schema"] in ROUND_SCHEMAS else "") + lines += [f"Round: `{ctx['round']}`{echo}", ""] + t = s["tasks"].get(e) + if t is not None: + lines += ["## Task", f"- id: `{e}`", f"- {t['title']}", f"- {t['goal']}", + "", "## Files you may touch", + *[f"- `{f}`" for f in t["files"]], "", + "## Accept when", *[f"- {a}" for a in t["accepts"]], ""] + if "criterion" in ctx: + lines += ["## Criterion", f"- {ctx['criterion']}", + f"- procedure: {ctx['procedure']}", ""] + if sl["role"] == "review": + pkg = review_package_file(init.idir, e, ctx["round"]) + lines += ["## Review package", + f"Read `{pkg}` first. It holds the diff from `{ctx['base']}` " + f"to `{ctx['head']}`, the changed files and the prior " + f"findings. Confirm or refute each prior finding before " + f"hunting new ones.", + f"Set `reviewed_package_sha` to `{ctx['package_sha']}`, " + f"`commit_base` to `{ctx['base']}` and `commit_head` to " + f"`{ctx['head']}`.", ""] + if ctx.get("findings"): + lines += ["## Findings to address", + *[f"- {f.get('id', '?')} ({f.get('severity', '?')}): " + f"{f.get('claim', '')}" for f in ctx["findings"]], ""] + req = schema_for(sl["schema"]).get("required", []) + lines += ["## Output", + f"Emit only JSON for `kind: {sl['schema']}`. Required keys: " + + ", ".join(f"`{k}`" for k in req) + + ". Prose goes in string fields; structure is yours to fill, " + "not to invent."] + return "\n".join(lines) + "\n" + + +# ------------------------------------------------------------ ingest + +def ingest(init: Initiative, payload: dict, actor: str = "worker") -> dict: + """Validate one payload against the schema, the state, the open dispatch + it answers and git, then commit exactly one event. Returns the event, or + {"deduplicated": True} when the payload is a redelivery of an answer already + accepted. Raises Rejection and writes nothing otherwise. Human-only kinds + need actor "human".""" + kind = _validated_kind(payload) + with _exclusive(init.idir): + init.reload() + _authorize(kind, actor) + s = fold(init.events) + if s["halt"] and kind not in HALT_OPEN_KINDS: + raise Rejection("halted", "$.kind", "ruling or resume while halted", + kind, f"run is halted: {s['halt']}") + digest = sha256(payload) + if kind in SLOT_FREE_KINDS: + entity = _check_free(init, s, payload) + _sync_policy(init) + ev = _event(init, actor, kind, entity, _data_for(payload), + payload_sha=digest) + else: + try: + sl = _bind(s, payload) + except Rejection: + if _duplicate(init, digest): + return {"deduplicated": True} + raise + entity = _check(init, s, payload, sl) + _sync_policy(init) + ev = _event(init, actor, kind, entity, _data_for(payload), + dispatch_id_=sl["dispatch_id"], payload_sha=digest) + _effects(init, s, payload, sl) + _append(init, ev) + _project(init) + return ev + + +def _validated_kind(payload) -> str: + if not isinstance(payload, dict): + raise Rejection("type", "$", "object", type(payload).__name__) + if "kind" not in payload: + raise Rejection("required", "$.kind", "present", "missing") + if not isinstance(payload["kind"], str): + raise Rejection("type", "$.kind", "string", + type(payload["kind"]).__name__) + validate(payload, schema_for(payload["kind"])) + return payload["kind"] + + +def _authorize(kind: str, actor: str) -> None: + if kind in HUMAN_KINDS and actor != "human": + raise Rejection("unauthorized", "$.kind", "actor human", + f"actor {actor}", + f"{kind} is human-only; pass --actor human") + + +def _duplicate(init: Initiative, digest: str) -> bool: + return any(e.get("payload_sha") == digest for e in init.events) + + +def _data_for(p: dict) -> dict: + return {k: v for k, v in p.items() + if k not in ("kind", "v", "engine_version", "dispatch_id")} + + +def _entity_for(p: dict) -> str: + """The entity a slot-bearing payload speaks for, read from the payload.""" + k = p["kind"] + if k in ARTIFACT_KINDS: + return p["id"] + if k in ("report", "verdict", "heartbeat", "needs_context"): + return p["task"] + if k == "evidence": + return p["criterion"] + if k == "audit": + return p["target"] + return p.get("dispatch_id", "-") + + +def _bind(s: dict, p: dict) -> dict: + """The open dispatch a slot-bearing payload answers. A payload that answers + none is unsolicited and is refused: the engine decides what is asked.""" + kind = p["kind"] + open_ = _open_slots(s) + if kind == "spawn_error": + cands = [x for x in open_ if x["dispatch_id"] == p.get("dispatch_id")] + elif kind in ("heartbeat", "needs_context"): + cands = [x for x in open_ if x["entity"] == p["task"]] + else: + entity = _entity_for(p) + cands = [x for x in open_ if x["entity"] == entity + and x["schema"] == kind] + did = p.get("dispatch_id") + if did is not None and kind != "spawn_error": + cands = [x for x in cands if x["dispatch_id"] == did] + if not cands: + expected = "; ".join(sorted({f"{x['schema']} for {x['entity']}" + for x in open_})) or "none" + raise Rejection("no_open_slot", "$", + f"an open dispatch answered by {kind}", + f"{kind} for {did or _entity_for(p)}", + f"open: {expected}") + return cands[0] + + +def _check(init: Initiative, s: dict, p: dict, sl: dict) -> str: + """Semantic checks for slot-bearing kinds over live state and git. Returns + the entity the event is recorded against.""" + k = p["kind"] + if k in ARTIFACT_KINDS: + _check_artifact(s, p) + return p["id"] + if k == "report": + for c in p.get("commits", []): + if not rev_exists(init.root, c): + raise Rejection("unknown_rev", "$.commits", + "resolvable commit(s)", c) + if p["result"] != "BLOCKED": + _check_advances(init, s, p, sl) + return p["task"] + if k == "verdict": + _check_verdict(init, p, sl) + return p["task"] + if k == "evidence": + _check_evidence(init, p) + return p["criterion"] + if k == "audit": + _check_audit(p, sl) + return p["target"] + if k == "spawn_error": + return sl["entity"] + return p["task"] # heartbeat, needs_context + + +def _check_free(init: Initiative, s: dict, p: dict) -> str: + """Checks for kinds that answer no dispatch.""" + k = p["kind"] + if k == "gate_decision": + if p["phase"] != s["phase"] or \ + s["phase_state"].get(p["phase"]) != "gate_pending": + raise Rejection("no_open_gate", "$.phase", + f"{s['phase']} with its gate pending", p["phase"]) + return p["phase"] + if k == "resume": + if not s["halt"]: + raise Rejection("not_halted", "$.kind", "a halted run", "running") + return init.id + if k == "ruling": + tgt = p.get("for_task") + if tgt and tgt not in s["tasks"] and tgt not in s["plans"]: + raise Rejection("unknown_entity", "$.for_task", + "a known task or plan", tgt) + return tgt or init.id + if k == "merge": + _check_merge(init, s, p) + return p["plan"] + return init.id # halt + + +def _check_artifact(s: dict, p: dict) -> None: + known = _known_ids(s) + for c in p.get("cites", []): + if c == p["id"]: + raise Rejection("dangling_ref", "$.cites", + "another artifact, task, or criterion", c, + "a payload cannot cite itself: the reference " + "would add nothing a reader can check") + if c not in known: + raise Rejection("dangling_ref", "$.cites", "an authored id", c, + "cite only artifacts, tasks or criteria that exist") + if p["kind"] == "plan": + if p.get("plan_id") != p["id"]: + raise Rejection("mismatch", "$.plan_id", p["id"], + str(p.get("plan_id"))) + ids = [t["id"] for t in p["tasks"]] + if len(set(ids)) != len(ids): + raise Rejection("duplicate", "$.tasks", "unique task ids", + "duplicate id") + for t in p["tasks"]: + for dep in t.get("depends_on", []): + if dep not in ids: + raise Rejection("dangling_ref", + f"$.tasks.{t['id']}.depends_on", + "a task id in this plan", dep) + if p["kind"] == "vrfy": + ids = [c["id"] for c in p["criteria"]] + if len(set(ids)) != len(ids): + raise Rejection("duplicate", "$.criteria", "unique criterion ids", + "duplicate id") + + +def _check_advances(init: Initiative, s: dict, p: dict, sl: dict) -> None: + """A worker that reports work must have added something. An implementation + is measured from the base it was dispatched on; a fix is also measured from + the head of the report it answers. A head equal to, or an ancestor of, either + adds nothing.""" + refs = [sl["base"]] + if sl["role"] == "fix": + prior = (s["reports"].get(p["task"]) or {}).get("commits") or [] + refs += prior[-1:] + commits = p.get("commits") or [] + if not commits: + raise Rejection("empty_range", "$.commits", "at least one commit", + "none", "commit the change before reporting it") + head = _resolve(init.root, commits[-1]) + for ref in refs: + base = _resolve(init.root, ref) + if head == base or _is_ancestor(init.root, head, base): + raise Rejection("empty_range", "$.commits", + f"a commit after {base[:12]}", head[:12], + "the change is not in the repository yet") + + +def _check_verdict(init: Initiative, p: dict, sl: dict) -> None: + ctx = sl["context"] + if p["round"] != ctx.get("round"): + raise Rejection("round_mismatch", "$.round", str(ctx.get("round")), + str(p["round"]), "the engine mints rounds") + if p["reviewed_package_sha"] != ctx.get("package_sha"): + raise Rejection("package_mismatch", "$.reviewed_package_sha", + str(ctx.get("package_sha")), p["reviewed_package_sha"], + "review the package the engine wrote for this round") + if (p["commit_base"], p["commit_head"]) != (ctx.get("base"), ctx.get("head")): + raise Rejection("range_mismatch", "$.commit_base", + f"{ctx.get('base')}..{ctx.get('head')}", + f"{p['commit_base']}..{p['commit_head']}", + "the range is the package's, not yours to choose") + for f in p.get("findings", []): + for path in re.findall(r"[\w./-]+\.\w+", f.get("evidence", "")): + if "/" in path and not path_at_rev(init.root, p["commit_head"], path): + raise Rejection("missing_evidence", "$.findings", + f"path exists at {p['commit_head']}", + f"{path} not found") + + +def _check_evidence(init: Initiative, p: dict) -> None: + if not rev_exists(init.root, p["state_commit"]): + raise Rejection("unknown_rev", "$.state_commit", + "a resolvable commit", p["state_commit"]) + for a in p.get("artifacts", []): + if not path_at_rev(init.root, p["state_commit"], a): + raise Rejection("missing_evidence", "$.artifacts", + f"path exists at {p['state_commit']}", a) + + +def _check_audit(p: dict, sl: dict) -> None: + if p["round"] != sl["context"].get("round"): + raise Rejection("round_mismatch", "$.round", + str(sl["context"].get("round")), str(p["round"]), + "the engine mints audit rounds") + + +def _check_merge(init: Initiative, s: dict, p: dict) -> None: + pl = s["plans"].get(p["plan"]) + if pl is None: + raise Rejection("unknown_entity", "$.plan", "a known plan", p["plan"]) + if pl["status"] == "merged": + raise Rejection("already_merged", "$.plan", "an unmerged plan", p["plan"]) + open_tasks = sorted(tid for tid, t in s["tasks"].items() + if t["plan"] == p["plan"] and t["state"] != "complete") + if open_tasks: + raise Rejection("incomplete", "$.plan", "every task complete", + ", ".join(open_tasks)) + if not rev_exists(init.root, p["merge_sha"]): + raise Rejection("unknown_rev", "$.merge_sha", + "a resolvable merge commit", p["merge_sha"]) + + +def _effects(init: Initiative, s: dict, p: dict, sl: dict) -> None: + """Canonical files for a payload that is about to be committed. Runs before + the event is appended, so a payload that is rejected leaves no files, and a + file written before a crash is overwritten identically on retry.""" + k = p["kind"] + if k in ARTIFACT_KINDS: + _write_artifact(init, p) + if sl["role"] == "repair": + _write_repair_record(init, p, sl) + elif k == "audit": + write_json(plan_audit_file(init.idir, p["target"], p["round"]) + if p["target"] in s["plans"] + else audit_file(init.idir, p["target"], p["round"]), p) + elif k == "report": + if sl["role"] == "fix": + write_json(fix_report_file(init.idir, p["task"], + sl["context"]["round"]), p) + else: + write_json(task_impl_report(init.idir, p["task"], + sl["dispatch_id"]), p) + _write_text(docs_report_file(init.root, init.id, p["task"], + sl["dispatch_id"]), + render_report_md(p, sl["dispatch_id"])) + elif k == "verdict": + write_json(verdict_file(init.idir, p["task"], p["round"]), p) + _write_text(docs_verdict_file(init.root, init.id, p["task"], p["round"]), + render_verdict_md(p)) + + +def _write_repair_record(init: Initiative, p: dict, sl: dict) -> None: + """The engine writes the repair: which open findings the re-drafted artifact + answers, and the digest of the artifact it produced. A worker never sends a + repair payload; a critique is cleared only by a re-drafted artifact.""" + rnd = sl["context"]["round"] + record = {"target": p["id"], "round": rnd, + "addressed": sl["context"]["findings"], + "artifact_sha256": sha256(p)} + write_json(plan_repair_file(init.idir, p["id"], rnd) + if p["kind"] == "plan" + else repair_file(init.idir, p["id"], rnd), record) + + +def _write_artifact(init: Initiative, p: dict) -> None: + """Run-store copy of the latest payload, plus the committed thinking store: + canonical JSON and rendered markdown, both deterministic.""" + aid = p["id"] + if p["kind"] == "plan": + write_json(plan_file(init.idir, aid), p) + jf = docs_plan_file(init.root, init.id, aid) + mf = docs_plan_md(init.root, init.id, aid) + else: + write_json(artifact_file(init.idir, aid), p) + jf = docs_artifact_file(init.root, init.id, aid) + mf = docs_artifact_md(init.root, init.id, aid) + write_json(jf, p) + _write_text(mf, _render_doc(p)) + + +def _render_doc(p: dict) -> str: + """Deterministic markdown from the payload's data. The payload never + carries formatting — every table, list, and fence below is built here + from typed fields, so an agent that wants a table emits rows and the + reader always gets the same one.""" + out = [f"# {p['id']} — {p.get('title', '')}", "", f"*{p.get('summary', '')}*", ""] + for r in p.get("requirements", []): + out += [f"### {r['id']} — {r['requirement']}", + f"*observable:* {r.get('observable', '')}", ""] + for c in p.get("constraints", []): + out += [f"**{c['id']}** {c['constraint']} ", + f"*observable:* {c.get('observable', '')} ", ""] + for sec in p.get("sections", []): + out += _render_section(sec) + for c in p.get("criteria", []): + out += [f"### {c['id']}", f"{c['criterion']} ", + f"*procedure:* {c['procedure']} ", ""] + for t in p.get("tasks", []): + out += [f"## {t['id']} — {t['title']}", t.get("goal", ""), "", + "**files:** " + ", ".join(f"`{f}`" for f in t["files"]), "", + "**accepts:**", *[f"- {a}" for a in t["accepts"]], ""] + return "\n".join(out) + "\n" + + +def _render_section(sec: dict) -> list[str]: + out = [f"## {sec['title']}"] + if sec.get("prose"): + out += [sec["prose"], ""] + else: + out.append("") + out += [f"- {b}" for b in sec.get("bullets", [])] + if sec.get("bullets"): + out.append("") + for t in sec.get("tables", []): + if t.get("caption"): + out += [f"*{t['caption']}*", ""] + cols = t["columns"] + out += ["| " + " | ".join(cols) + " |", + "| " + " | ".join(["---"] * len(cols)) + " |"] + out += ["| " + " | ".join(row) + " |" for row in t["rows"]] + out.append("") + for c in sec.get("code", []): + out += [f"```{c.get('lang', '')}", c["source"], "```", ""] + return out + + +# ------------------------------------------------------------ initiatives + +def _next_init_id(root: Path) -> str: + nums = [int(d.name.split("-")[1]) for d in run_root(root).glob("INIT-*") + if d.is_dir() and d.name.split("-")[1].isdigit()] + return f"INIT-{max(nums, default=0) + 1:04d}" + + +def create_initiative(root: Path, title: str) -> Initiative: + """Scaffold a new initiative and journal its creation under the lock.""" + iid = _next_init_id(root) + idir = init_store(root, iid, title) + init = Initiative(iid, root, idir) + with _exclusive(idir): + init.reload() + _record(init, "engine", "created", iid, {"title": title}) + _sync_policy(init) + _project(init) + return init + + +# ------------------------------------------------------------ check + +def check(init: Initiative, now: float | None = None) -> dict: + """Read-only audit. Writes nothing, so it is safe at any time. A stale fold + cache is reported; the next write refreshes it.""" + with _exclusive(init.idir): + events, torn = scan_journal(init.idir) + chain = verify_chain(events) + problems = list(chain) + if torn: + problems.append(f"{torn} unparseable journal line(s) skipped") + unknown = sorted({str(e.get("kind")) for e in events} - KNOWN_KINDS) + if unknown: + problems.append(f"unknown event kind(s): {', '.join(unknown)}") + try: + s = fold(events) + except (KeyError, TypeError, ValueError, IndexError, AttributeError) as exc: + problems.append(f"fold failed: {exc}") + return _report(init, events, chain, problems, []) + known = _known_ids(s) | set(s["entities"]) | {init.id} + for ed in s["edges"]: + for end in (ed["from"], ed["to"]): + if end not in known and not is_dispatch_id(end): + problems.append(f"dangling edge {ed['kind']}: {end}") + cache = read_json(state_file(init.idir)) or {} + if cache.get("last_seq") != len(events): + problems.append(f"state cache stale: last_seq " + f"{cache.get('last_seq')} != journal {len(events)} " + f"(the next write refreshes it)") + pol = s["policy"]["values"] + try: + _values, _sources, files_sha = effective_policy(init.root, init.id, init.idir) + if files_sha != s["policy"]["sha"]: + problems.append("policy drift: the policy files differ from the " + "journal's last policy event (the next poll or " + "ingest records them)") + except ExecError as exc: + problems.append(f"policy invalid: {exc}") + clock = _clock(now) + open_ = _open_slots(s) + for sl in open_: + dsp = s["dispatches"][sl["dispatch_id"]] + try: + _iso2epoch(dsp.get("last_beat") or dsp["at"]) + except ExecError: + problems.append(f"unreadable timestamp on dispatch {sl['dispatch_id']}: " + f"liveness cannot be judged until it is repaired") + continue + silent = _silent_for(dsp, clock) + if silent > pol["deadline_s"]: + problems.append(f"dead dispatch {sl['dispatch_id']}: silent " + f"{int(silent)}s (the next poll abandons it)") + elif silent > pol["suspect_s"]: + problems.append(f"suspect dispatch {sl['dispatch_id']}: silent " + f"{int(silent)}s") + ddir = dispatches_dir(init.idir) + if ddir.exists(): + for d in sorted(ddir.iterdir()): + if d.name not in s["dispatches"]: + problems.append(f"orphan dispatch directory {d.name}: " + f"never journaled") + problems += _layout_problems(init) + return _report(init, events, chain, problems, + [sl["dispatch_id"] for sl in open_]) + + +def _layout_problems(init: Initiative) -> list[str]: + out = [] + run = run_root(init.root) + for f in sorted(init.idir.rglob("*")): + if f.is_file() and classify(f.relative_to(run), "run") is None: + out.append(f"non-canonical file: {f.relative_to(run).as_posix()}") + docs = docs_init_dir(init.root, init.id) + if docs.exists(): + for f in sorted(docs.rglob("*")): + if f.is_file() and classify(f.relative_to(docs_root(init.root)), + "docs") is None: + out.append(f"non-canonical committed file: " + f"{f.relative_to(docs_root(init.root)).as_posix()}") + return out + + +SECRET_RULES = ( + ("private_key", re.compile(r"-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----")), + ("aws_access_key", re.compile(r"\bAKIA[0-9A-Z]{16}\b")), + ("github_token", re.compile(r"\b(?:gh[pousr]|github_pat)_[A-Za-z0-9_]{20,}\b")), + ("slack_token", re.compile(r"\bxox[baprs]-[A-Za-z0-9-]{10,}\b")), + ("generic_secret", re.compile( + r"(?i)\b(?:api[_-]?key|secret|token|password|passwd)\b" + r"\s*[:=]\s*[\"']?[A-Za-z0-9+/=._~|-]{16,}")), +) + + +def scan_secrets(init: Initiative) -> dict: + """Every secret-looking string in both stores, reported without the + bytes: a finding is the rule, the file and line, and a short digest of + the match so a human can correlate it without ever reading it back. + A binary file cannot contain a pattern we know, so it is skipped, and a + false positive is a lead for the human — not a verdict.""" + findings, scanned = [], 0 + for base in (run_root(init.root), docs_root(init.root)): + if not base.exists(): + continue + for path in sorted(base.rglob("*")): + if not path.is_file(): + continue + scanned += 1 + try: + text = path.read_text(encoding="utf-8") + except (OSError, UnicodeDecodeError): + continue + for lineno, line in enumerate(text.splitlines(), 1): + for name, rx in SECRET_RULES: + for m in rx.finditer(line): + findings.append({ + "rule": name, "line": lineno, + "file": str(path.relative_to(init.root)), + "digest": sha256(m.group(0))[:8]}) + return {"initiative": init.id, "scanned": scanned, "findings": findings} + +def _report(init: Initiative, events: list[dict], chain: list[str], + problems: list[str], open_ids: list[str]) -> dict: + return {"initiative": init.id, "events": len(events), + "chain": "broken" if chain else "ok", "problems": problems, + "open_slots": len(open_ids), "open_dispatch_ids": open_ids, + "dangling": [p for p in problems if p.startswith("dangling")]} diff --git a/skills/executor/scripts/lib/executor/paths.py b/skills/executor/scripts/lib/executor/paths.py new file mode 100644 index 0000000..e4e9967 --- /dev/null +++ b/skills/executor/scripts/lib/executor/paths.py @@ -0,0 +1,421 @@ +# SPDX-License-Identifier: MIT +# Copyright (c) 2026 Atri10 +"""The one path authority for the executor store. + +Every file the engine reads or writes is located by a function here, and +every name it can take is defined by the grammar at the bottom of this +module: nothing else in the codebase constructs a path, and `classify` +refuses any file that does not fit. Naming is uniform: ``<ID>.<role>.<ext>`` +nested under the owning entity's directory, so a store is browsable +top-down from initiative to artifact to task to round. + +Identifiers +----------- + INIT-NNNN initiative + INIT-NNNN-<KIND>-NN artifact (CHTR OPTS BRN ARCH ADR IFCE DSGN SPEC + RISK VRFY) + INIT-NNNN-PNN plan + INIT-NNNN-PNN-TNN task, always inside its plan + D<NNNNN> dispatch: the seq of the journal event minting it + R<NN> round (audit, repair, review, fix) + +Layout +------ + <repo>/.executor/ + meta.json engine/schema/store versions + INIT-NNNN/ + journal/ + events.v<N>.jsonl append-only hash-chained truth + state.json derived fold cache + .lock single-writer lock + meta/ + meta.json initiative meta + autonomy.json per-phase deny|gate|allow + artifacts/<ARTIFACT-ID>/ + artifact.json latest validated payload + audits/R<NN>.audit.json + repairs/R<NN>.repair.json + plans/<PLAN-ID>/ + plan.json latest validated plan payload + preflight.json conflict-scan verdict + audits/R<NN>.audit.json + repairs/R<NN>.repair.json + tasks/<TASK-ID>/ + impl/D<NNNNN>.report.json + reviews/R<NN>.package.json review package (what reviewer saw) + reviews/R<NN>.verdict.json + fixes/R<NN>.fix-package.json + fixes/R<NN>.report.json + dispatches/D<NNNNN>/ + slot.json minted single-use slot + prompt.md rendered worker prompt + payload.json the respond_to target + views/ + progress.md dispatches.md summary.md graph.json + <TASK-ID>-R<NN>-verdict.md + <repo>/docs/executor/INIT-NNNN/ committed thinking store + meta/index.json + index.md + artifacts/<ARTIFACT-ID>/artifact.json + artifact.md + plans/<PLAN-ID>/plan.json + plan.md + plans/<PLAN-ID>/tasks/<TASK-ID>/impl/D<NNNNN>.report.md + plans/<PLAN-ID>/tasks/<TASK-ID>/reviews/R<NN>.verdict.md + export/events.jsonl durable journal snapshot (handoff) +""" +from __future__ import annotations + +import re +from dataclasses import dataclass +from pathlib import PurePath +from typing import TypeVar + +# Helpers are pure path arithmetic: they return the same flavour of path +# they are given (a Path in, a Path out), and never touch the filesystem. +_P = TypeVar("_P", bound=PurePath) + +RUN_STORE = ".executor" +DOCS_STORE = "docs/executor" + + +# ---------------------------------------------------------------- id grammar +# One definition per identifier shape. schemas.py, the engine and the layout +# grammar below all import these; a second copy anywhere is a bug. + +INIT_ID = r"INIT-\d{4}" +# kind -> the segment its ids carry. A plan is not here: its id is a plan id. +ARTIFACT_SEGMENTS = { + "charter": "CHTR", "options": "OPTS", "brainstorm": "BRN", + "arch": "ARCH", "adr": "ADR", "ifce": "IFCE", "design": "DSGN", + "spec": "SPEC", "risk": "RISK", "vrfy": "VRFY", +} +_SEGMENT_ALT = "|".join(sorted(ARTIFACT_SEGMENTS.values())) +ARTIFACT_ID = INIT_ID + r"-(?:" + _SEGMENT_ALT + r")-\d{2}" +PLAN_ID = INIT_ID + r"-P\d{2}" +TASK_ID = PLAN_ID + r"-T\d{2}" +DISPATCH_ID = r"D\d{5,}" +ROUND_ID = r"R\d{2}" + + +def dispatch_id(seq: int) -> str: + """The id of the dispatch recorded by journal event `seq`.""" + return f"D{seq:05d}" + + +def is_dispatch_id(text: str) -> bool: + return re.fullmatch(DISPATCH_ID, text) is not None + + +def artifact_pattern(kind: str) -> str: + """The id pattern a payload of this kind must carry: its own segment (a + charter is CHTR, never SPEC), or a plan id for a plan.""" + if kind == "plan": + return PLAN_ID + return INIT_ID + "-" + ARTIFACT_SEGMENTS[kind] + r"-\d{2}" + + +# ---------------------------------------------------------------- roots + +def run_root(root: _P) -> _P: + return root / RUN_STORE + + +def docs_root(root: _P) -> _P: + return root / DOCS_STORE + + +def init_dir(root: _P, init_id: str) -> _P: + return run_root(root) / init_id + + +# ---------------------------------------------------------------- journal + +def journal_dir(idir: _P) -> _P: + return idir / "journal" + + +def journal_file(idir: _P, version: int = 1) -> _P: + return journal_dir(idir) / f"events.v{version}.jsonl" + + +def state_file(idir: _P) -> _P: + return journal_dir(idir) / "state.json" + + +def lock_file(idir: _P) -> _P: + return journal_dir(idir) / ".lock" + + +# ---------------------------------------------------------------- meta + +def meta_dir(idir: _P) -> _P: + return idir / "meta" + + +def meta_file(idir: _P) -> _P: + return meta_dir(idir) / "meta.json" + + +def autonomy_file(idir: _P) -> _P: + return meta_dir(idir) / "autonomy.json" + + +def run_meta_file(root: _P) -> _P: + return run_root(root) / "meta.json" + + +# ---------------------------------------------------------------- artifacts + +def artifact_dir(idir: _P, aid: str) -> _P: + return idir / "artifacts" / aid + + +def artifact_file(idir: _P, aid: str) -> _P: + return artifact_dir(idir, aid) / "artifact.json" + + +def audit_file(idir: _P, aid: str, rnd: int) -> _P: + return artifact_dir(idir, aid) / "audits" / f"R{rnd:02d}.audit.json" + + +def repair_file(idir: _P, aid: str, rnd: int) -> _P: + return artifact_dir(idir, aid) / "repairs" / f"R{rnd:02d}.repair.json" + + +# ---------------------------------------------------------------- plans + +def plan_dir(idir: _P, pid: str) -> _P: + return idir / "plans" / pid + + +def plan_file(idir: _P, pid: str) -> _P: + return plan_dir(idir, pid) / "plan.json" + + +def preflight_file(idir: _P, pid: str) -> _P: + return plan_dir(idir, pid) / "preflight.json" + + +def plan_audit_file(idir: _P, pid: str, rnd: int) -> _P: + return plan_dir(idir, pid) / "audits" / f"R{rnd:02d}.audit.json" + + +def plan_repair_file(idir: _P, pid: str, rnd: int) -> _P: + return plan_dir(idir, pid) / "repairs" / f"R{rnd:02d}.repair.json" + + +# ---------------------------------------------------------------- tasks + +def task_dir(idir: _P, tid: str) -> _P: + pid = tid.rsplit("-", 1)[0] + return plan_dir(idir, pid) / "tasks" / tid + + +def task_impl_report(idir: _P, tid: str, did: str) -> _P: + return task_dir(idir, tid) / "impl" / f"{did}.report.json" + + +def review_package_file(idir: _P, tid: str, rnd: int) -> _P: + return task_dir(idir, tid) / "reviews" / f"R{rnd:02d}.package.json" + + +def verdict_file(idir: _P, tid: str, rnd: int) -> _P: + return task_dir(idir, tid) / "reviews" / f"R{rnd:02d}.verdict.json" + + +def fix_package_file(idir: _P, tid: str, rnd: int) -> _P: + return task_dir(idir, tid) / "fixes" / f"R{rnd:02d}.fix-package.json" + + +def fix_report_file(idir: _P, tid: str, rnd: int) -> _P: + return task_dir(idir, tid) / "fixes" / f"R{rnd:02d}.report.json" + + +# ---------------------------------------------------------------- dispatches + +def dispatches_dir(idir: _P) -> _P: + return idir / "dispatches" + + +def dispatch_dir(idir: _P, did: str) -> _P: + return dispatches_dir(idir) / did + + +def slot_file(idir: _P, did: str) -> _P: + return dispatch_dir(idir, did) / "slot.json" + + +def prompt_file(idir: _P, did: str) -> _P: + return dispatch_dir(idir, did) / "prompt.md" + + +def payload_file(idir: _P, did: str) -> _P: + """The respond_to target the worker writes.""" + return dispatch_dir(idir, did) / "payload.json" + + +# ---------------------------------------------------------------- views + +def views_dir(idir: _P) -> _P: + return idir / "views" + + +def view_file(idir: _P, name: str) -> _P: + return views_dir(idir) / name + + +def verdict_view_file(idir: _P, tid: str, rnd: int) -> _P: + return views_dir(idir) / f"{tid}-R{rnd:02d}-verdict.md" + + +# ---------------------------------------------------------------- committed + +def docs_init_dir(root: _P, init_id: str) -> _P: + return docs_root(root) / init_id + + +def docs_index_file(root: _P, init_id: str) -> _P: + return docs_init_dir(root, init_id) / "meta" / "index.json" + + +def docs_index_md(root: _P, init_id: str) -> _P: + return docs_init_dir(root, init_id) / "meta" / "index.md" + + +def docs_artifact_dir(root: _P, init_id: str, aid: str) -> _P: + return docs_init_dir(root, init_id) / "artifacts" / aid + + +def docs_artifact_file(root: _P, init_id: str, aid: str) -> _P: + return docs_artifact_dir(root, init_id, aid) / "artifact.json" + + +def docs_artifact_md(root: _P, init_id: str, aid: str) -> _P: + return docs_artifact_dir(root, init_id, aid) / "artifact.md" + + +def docs_plan_dir(root: _P, init_id: str, pid: str) -> _P: + return docs_init_dir(root, init_id) / "plans" / pid + + +def docs_plan_file(root: _P, init_id: str, pid: str) -> _P: + return docs_plan_dir(root, init_id, pid) / "plan.json" + + +def docs_plan_md(root: _P, init_id: str, pid: str) -> _P: + return docs_plan_dir(root, init_id, pid) / "plan.md" + + +def docs_task_dir(root: _P, init_id: str, tid: str) -> _P: + pid = tid.rsplit("-", 1)[0] + return docs_plan_dir(root, init_id, pid) / "tasks" / tid + + +def docs_report_file(root: _P, init_id: str, tid: str, did: str) -> _P: + return docs_task_dir(root, init_id, tid) / "impl" / f"{did}.report.md" + + +def docs_verdict_file(root: _P, init_id: str, tid: str, rnd: int) -> _P: + return (docs_task_dir(root, init_id, tid) / "reviews" + / f"R{rnd:02d}.verdict.md") + + +def docs_export_journal(root: _P, init_id: str) -> _P: + return docs_init_dir(root, init_id) / "export" / "events.jsonl" + + +def project_policy_file(root: _P) -> _P: + """The committed project policy: engine tunables every initiative inherits.""" + return docs_root(root) / "config.json" + + +def initiative_policy_file(root: _P, init_id: str) -> _P: + """An initiative's committed policy; its keys override the project file.""" + return docs_init_dir(root, init_id) / "meta" / "policy.json" + + +# ---------------------------------------------------------------- grammar +# Each row is (kind, pattern). A pattern describes a file path relative to its +# store root. Back-references tie every nested id to its owner, so an artifact +# of INIT-0008 inside INIT-0007's directory, or a task outside its plan, fits +# no row and is refused. + +@dataclass(frozen=True) +class Entry: + """What a canonical file is: its store, its kind and the ids in its path.""" + store: str + kind: str + ids: dict[str, str] + + +_I = r"(?P<init>" + INIT_ID + r")" +_ART = r"(?P<art>(?P=init)-(?:" + _SEGMENT_ALT + r")-\d{2})" +_PLAN = r"(?P<plan>(?P=init)-P\d{2})" +_TASK = r"(?P<task>(?P=plan)-T\d{2})" +_DISP = r"(?P<disp>" + DISPATCH_ID + r")" +_RND = r"(?P<rnd>" + ROUND_ID + r")" +_TASK_DIR = _I + r"/plans/" + _PLAN + r"/tasks/" + _TASK + +_RUN_ROWS = ( + ("run_meta", r"meta\.json"), + ("journal", _I + r"/journal/events\.v(?P<ver>\d+)\.jsonl"), + ("state", _I + r"/journal/state\.json"), + ("lock", _I + r"/journal/\.lock"), + ("init_meta", _I + r"/meta/meta\.json"), + ("autonomy", _I + r"/meta/autonomy\.json"), + ("artifact", _I + r"/artifacts/" + _ART + r"/artifact\.json"), + ("artifact_audit", + _I + r"/artifacts/" + _ART + r"/audits/" + _RND + r"\.audit\.json"), + ("artifact_repair", + _I + r"/artifacts/" + _ART + r"/repairs/" + _RND + r"\.repair\.json"), + ("plan", _I + r"/plans/" + _PLAN + r"/plan\.json"), + ("preflight", _I + r"/plans/" + _PLAN + r"/preflight\.json"), + ("plan_audit", + _I + r"/plans/" + _PLAN + r"/audits/" + _RND + r"\.audit\.json"), + ("plan_repair", + _I + r"/plans/" + _PLAN + r"/repairs/" + _RND + r"\.repair\.json"), + ("task_report", _TASK_DIR + r"/impl/" + _DISP + r"\.report\.json"), + ("review_package", _TASK_DIR + r"/reviews/" + _RND + r"\.package\.json"), + ("verdict", _TASK_DIR + r"/reviews/" + _RND + r"\.verdict\.json"), + ("fix_package", _TASK_DIR + r"/fixes/" + _RND + r"\.fix-package\.json"), + ("fix_report", _TASK_DIR + r"/fixes/" + _RND + r"\.report\.json"), + ("dispatch_slot", _I + r"/dispatches/" + _DISP + r"/slot\.json"), + ("dispatch_prompt", _I + r"/dispatches/" + _DISP + r"/prompt\.md"), + ("dispatch_payload", _I + r"/dispatches/" + _DISP + r"/payload\.json"), + ("view", _I + r"/views/(?P<name>progress\.md|dispatches\.md|summary\.md" + r"|graph\.json)"), + ("view_verdict", + _I + r"/views/(?P<task>(?P=init)-P\d{2}-T\d{2})-" + _RND + + r"-verdict\.md"), +) + +_DOCS_ROWS = ( + ("docs_project_policy", r"config\.json"), + ("docs_initiative_policy", _I + r"/meta/policy\.json"), + ("docs_index_json", _I + r"/meta/index\.json"), + ("docs_index_md", _I + r"/meta/index\.md"), + ("docs_artifact_json", _I + r"/artifacts/" + _ART + r"/artifact\.json"), + ("docs_artifact_md", _I + r"/artifacts/" + _ART + r"/artifact\.md"), + ("docs_plan_json", _I + r"/plans/" + _PLAN + r"/plan\.json"), + ("docs_plan_md", _I + r"/plans/" + _PLAN + r"/plan\.md"), + ("docs_task_report", _TASK_DIR + r"/impl/" + _DISP + r"\.report\.md"), + ("docs_task_verdict", + _TASK_DIR + r"/reviews/" + _RND + r"\.verdict\.md"), + ("docs_export", _I + r"/export/events\.jsonl"), +) + +GRAMMAR = {"run": _RUN_ROWS, "docs": _DOCS_ROWS} +_COMPILED = {store: tuple((kind, re.compile(rx)) for kind, rx in rows) + for store, rows in GRAMMAR.items()} + + +def classify(rel: str | PurePath, store: str) -> Entry | None: + """The grammar entry for a file path relative to its store root (the + `.executor/` dir for store "run", `docs/executor/` for "docs"), or None + when the path is not canonical. Directories are never entries.""" + if store not in _COMPILED: + raise ValueError(f"unknown store {store!r}: expected run or docs") + text = rel.as_posix() if isinstance(rel, PurePath) else rel + for kind, rx in _COMPILED[store]: + m = rx.fullmatch(text) + if m: + return Entry(store, kind, m.groupdict()) + return None diff --git a/skills/executor/scripts/lib/executor/policy.py b/skills/executor/scripts/lib/executor/policy.py new file mode 100644 index 0000000..1668c20 --- /dev/null +++ b/skills/executor/scripts/lib/executor/policy.py @@ -0,0 +1,123 @@ +# SPDX-License-Identifier: MIT +# Copyright (c) 2026 Atri10 +"""Engine tunables, and the files that set them per project and per initiative. + +Precedence, lowest first: DEFAULTS, the project file docs/executor/config.json, +the initiative file docs/executor/<INIT>/meta/policy.json. Both files are +committed with the docs, so a change to a threshold is reviewed like any other +change. Each file carries a version key `v`, so an unknown version is refused +rather than misread. + +The engine never decides from a file. It journals the effective values as a +`policy` event at creation and again whenever they differ from the ones in +force, and every decision folds from that event. A decision can then be traced +to the policy in force when it was made, and a re-fold from the journal gives +the same answer on any machine. +""" +from __future__ import annotations + +import copy +from pathlib import Path +from .paths import autonomy_file, initiative_policy_file, project_policy_file +from .schemas import POLICY, validate +from .store import PHASES, ExecError, Rejection, read_json, sha256 + +DEFAULTS: dict = { + "max_fix_rounds": 5, # fix dispatches per task before the run escalates + "max_audit_rounds": 5, # audit rounds per artifact or plan before escalation + "max_evidence_tries": 5, # evidence attempts per criterion before escalation + "max_plans": 9, # plans per initiative + "spawn_retry_cap": 2, # lost dispatches per entity and schema + "suspect_s": 1800, # silence before check warns about a dispatch + "deadline_s": 3600, # silence after which the next poll abandons it + "clean_quality": ["APPROVED", "APPROVED_WITH_ROUTED_RESIDUALS"], +} + +# Inclusive bounds for the integer tunables. max_plans stops at 99 because plan +# ids carry two digits (P01..P99). +BOUNDS: dict[str, tuple[int, int]] = { + "max_fix_rounds": (1, 50), + "max_audit_rounds": (1, 50), + "max_evidence_tries": (1, 50), + "max_plans": (1, 99), + "spawn_retry_cap": (0, 20), + "suspect_s": (60, 604800), + "deadline_s": (60, 604800), +} + + +def policy_sha(values: dict) -> str: + return sha256(values) + + +def default_state() -> dict: + """The policy a journal is folded under before its first policy event. Autonomy + is fail-closed: every phase denied until a recorded policy says otherwise.""" + values = copy.deepcopy(DEFAULTS) + values["autonomy"] = normalize_autonomy({}, PHASES) + return {"values": values, "sources": {key: "default" for key in DEFAULTS}, + "sha": policy_sha(values), "recorded": False} + + +# Autonomy modes per phase. Fail closed: only the exact words allow or gate permit an +# unattended pass. Anything else, including a misspelling, a non-string and a missing +# phase, is deny. A pick-class phase is handled by the engine, never by this table. +AUTONOMY_MODES = ("deny", "gate", "allow") + + +def normalize_autonomy(raw, phases) -> dict[str, str]: + """Every phase mapped to deny unless the file names it with an exact allowed mode. + Pure and total, so an unreadable or partial file degrades to deny, never to allow.""" + source = raw if isinstance(raw, dict) else {} + return {p: (source[p] if isinstance(source.get(p), str) and source[p] in AUTONOMY_MODES + else "deny") + for p in phases} + + +def load_policy(root: Path, init_id: str) -> tuple[dict, dict]: + """The effective policy, and per key the layer its value came from. + + A missing file contributes nothing. Anything else that is unreadable, + malformed, out of range or self-contradictory raises ExecError with code + policy_invalid: the engine stops rather than deciding from a half-read file.""" + values = copy.deepcopy(DEFAULTS) + sources = {key: "default" for key in DEFAULTS} + layers = (("project", project_policy_file(root)), + ("initiative", initiative_policy_file(root, init_id))) + for layer, path in layers: + if not path.exists(): + continue + doc = read_json(path) + if not isinstance(doc, dict): + raise ExecError(f"{layer} policy {path.name} is unreadable or not a " + f"JSON object", "policy_invalid") + try: + validate(doc, POLICY) + except Rejection as exc: + raise ExecError(f"{layer} policy {path.name}: {exc}", "policy_invalid") from exc + for key, value in doc.items(): + if key == "v": + continue + if key in BOUNDS: + low, high = BOUNDS[key] + if not low <= value <= high: + raise ExecError(f"{layer} policy {path.name}: {key} must be " + f"between {low} and {high}, got {value}", + "policy_invalid") + values[key] = value + sources[key] = layer + if values["suspect_s"] >= values["deadline_s"]: + raise ExecError("suspect_s must be below deadline_s", "policy_invalid") + return values, sources + + +def effective_policy(root: Path, init_id: str, init_idir: Path) -> tuple[dict, dict, str]: + """The one policy the engine decides by: the layered tunables plus the normalized + per-phase autonomy map, with the layer each value came from and the digest the + journal records. Every reader (the policy event, check and doctor) calls this, so + they cannot disagree about what the policy is.""" + values, sources = load_policy(root, init_id) + values = {**values, "autonomy": normalize_autonomy(read_json(autonomy_file(init_idir)), PHASES)} + sources = {**sources, "autonomy": "initiative" if autonomy_file(init_idir).exists() + else "default"} + return values, sources, policy_sha(values) diff --git a/skills/executor/scripts/lib/executor/schemas.py b/skills/executor/scripts/lib/executor/schemas.py new file mode 100644 index 0000000..418e008 --- /dev/null +++ b/skills/executor/scripts/lib/executor/schemas.py @@ -0,0 +1,535 @@ +# SPDX-License-Identifier: MIT +# Copyright (c) 2026 Atri10 +"""Payload schemas and a minimal strict validator. + +Zero third-party dependencies: this is a deliberately small JSON-Schema +subset (type/properties/required/enum/items/additionalProperties/ +minItems/minLength/maxLength/pattern/minimum/oneOf). A pattern must match the +WHOLE string, so an id with junk around it is not an id. Every object in +every schema is closed, and every payload the engine accepts is validated +against one of the schemas below: structural first, then the semantic pass +in engine.fold. +""" +from __future__ import annotations + +import re + +from .paths import (ARTIFACT_ID, DISPATCH_ID, PLAN_ID, TASK_ID, + artifact_pattern) +from .store import PHASES, Rejection + +TYPES = {"object": dict, "array": list, "string": str, + "integer": int, "number": (int, float), "boolean": bool, + "null": type(None)} + + +def json_type(obj) -> str: + """The JSON name of a value's type, so a rejection speaks the schema's + vocabulary ("expected string, got integer") instead of Python's ("got + int", "got NoneType"). bool is tested before int: in Python it is an + int, in JSON it is not.""" + if obj is None: + return "null" + if isinstance(obj, bool): + return "boolean" + for name, py in (("integer", int), ("number", float), ("string", str), + ("array", list), ("object", dict)): + if isinstance(obj, py): + return name + return type(obj).__name__ + + +def validate(obj, schema: dict, field: str = "$") -> None: + """Raise Rejection on the first violation. Strict by default: an + object rejects unknown keys unless additionalProperties is set.""" + if not isinstance(schema, dict): + return + stype = schema.get("type") + if stype: + expected = TYPES[stype] + # bool is a subclass of int in Python; keep them distinct. + if stype in ("integer", "number") and isinstance(obj, bool): + raise Rejection("type", field, stype, json_type(obj)) + if not isinstance(obj, expected): + # A nullable field accepts None for a real absent state, so a + # document never has to write a string that means "no value". + if not (schema.get("nullable") and obj is None): + raise Rejection("type", field, stype, json_type(obj)) + # The value constraints below (length, pattern) describe a string; + # on a nullable None there is nothing to measure. + if stype == "string" and obj is None: + return + if "enum" in schema and obj not in schema["enum"]: + raise Rejection("enum", field, "|".join(map(str, schema["enum"])), + repr(obj)) + if stype == "string": + if "minLength" in schema and len(obj) < schema["minLength"]: + raise Rejection("minLength", field, + f"len>={schema['minLength']}", f"len={len(obj)}") + if "maxLength" in schema and len(obj) > schema["maxLength"]: + raise Rejection("maxLength", field, + f"len<={schema['maxLength']}", f"len={len(obj)}") + if "pattern" in schema and not re.fullmatch(schema["pattern"], obj): + raise Rejection("pattern", field, schema["pattern"], obj[:60]) + if "notMatch" in schema: + for rule in schema["notMatch"]: + if re.search(rule, obj): + raise Rejection("notMatch", field, + f"no match for {rule}", obj[:60]) + if schema.get("nonBlank") and not obj.strip(): + # Whitespace is not content: it passes minLength and renders + # an empty paragraph, a list item with no text, or a blank + # table cell — a payload that looks answered and is not. + raise Rejection("nonBlank", field, "non-whitespace text", + repr(obj[:20])) + if stype == "integer": + if "minimum" in schema and obj < schema["minimum"]: + raise Rejection("minimum", field, f">={schema['minimum']}", + str(obj)) + if stype == "object": + req = schema.get("required", []) + for k in req: + if k not in obj: + raise Rejection("required", f"{field}.{k}", "present", + "missing") + props = schema.get("properties", {}) + ap = schema.get("additionalProperties", True) + if ap is False: + for k in obj: + if k not in props: + raise Rejection("additionalProperties", f"{field}.{k}", + "closed object", "extra key") + elif isinstance(ap, dict): + for k, v in obj.items(): + if k not in props: + validate(v, ap, f"{field}.{k}") + for k, sub in props.items(): + if k in obj: + validate(obj[k], sub, f"{field}.{k}") + # An object-level invariant no per-property check can express: the + # named function reads several fields at once and rejects with the + # field path of the offending member. + shape = schema.get("shape") + if shape: + SHAPES[shape](obj, field) + if stype == "array": + if "minItems" in schema and len(obj) < schema["minItems"]: + raise Rejection("minItems", field, + f">={schema['minItems']} items", + f"{len(obj)} items") + if "items" in schema: + for i, item in enumerate(obj): + validate(item, schema["items"], f"{field}[{i}]") + if "oneOf" in schema: + for sub in schema["oneOf"]: + try: + validate(obj, sub, field) + return + except Rejection: + continue + raise Rejection("oneOf", field, "any of the variants", + "no variant matched") + + +# ------------------------------------------------------------ base + +BASE = { + "kind": {"type": "string", "minLength": 1}, + "v": {"type": "string", "minLength": 1}, + "engine_version": {"type": "string"}, + # Optional echo of the slot a payload answers. The engine binds by it when + # present and by entity otherwise; a worker that cannot echo is still valid. + "dispatch_id": {"type": "string", "pattern": DISPATCH_ID}, +} + + +def _obj(props, req=None, extra=False, shape=None): + d = {"type": "object", "properties": props, + "required": req or [], "additionalProperties": extra} + if shape: + d["shape"] = shape + return d + + +def _arr(items, **kw): + d = {"type": "array", "items": items} + d.update(kw) + return d + + +def _enum(*vals): + return {"enum": list(vals)} + + +def _str(**kw): + d = {"type": "string"} + d.update(kw) + return d + + +def _int(**kw): + d = {"type": "integer"} + d.update(kw) + return d + + +def _base(kind: str) -> dict: + """The keys every payload carries, with `kind` pinned to this schema's.""" + return {**BASE, "kind": _enum(kind)} + + +# ------------------------------------------------------------ artifacts + +# A payload carries DATA; the engine renders markdown. These patterns exist +# so a payload cannot become a second renderer: a pipe table, a fence, or a +# heading inside a string is formatting the caller was supposed to leave to +# views._render_doc, and two renderers drift. +MD_TABLE = r"(?m)^\s*\|" +MD_FENCE = r"```" +MD_HEAD = r"(?m)^#{1,6}\s" +MD_BULLET = r"(?m)^\s*[-*+]\s" +MD_RULE = r"(?m)^\s*(?:-{3,}|\*{3,}|_{3,})\s*$" +# What any prose-ish string may not contain: the three markdown constructs +# that have a structured home in the payload. +NO_MD = [MD_TABLE, MD_FENCE, MD_HEAD] +# A table cell becomes one rendered cell: a pipe would end the row early and +# a newline would end the table, so neither is data. +NO_CELL_MD = [r"\|", r"[\r\n]"] + + +def _table_rows_match_columns(obj: dict, field: str) -> None: + """Every row carries one cell per column: a short row renders a table + whose cells shift under a reader's eye, and a long one is silently + truncated by the renderer. Neither is acceptable in the thinking store.""" + width = len(obj["columns"]) + for i, row in enumerate(obj.get("rows", [])): + if len(row) != width: + raise Rejection( + "row_width", f"{field}.rows[{i}]", + f"{width} cells (one per column)", f"{len(row)} cells") + + +def _section_has_content(obj: dict, field: str) -> None: + """A section with no shape is a heading promising text that is not + there: prose, bullets, tables, or code — at least one, or it is a + title with nothing under it.""" + if not any(obj.get(k) for k in ("prose", "bullets", "tables", "code")): + raise Rejection("empty_section", field, + "prose, bullets, tables, or code", "none present") + + +def _section_ids_unique(obj: dict, field: str) -> None: + """A reviewer cites `§<section id>`, so an id must name one section. + Two sections sharing an id make the citation ambiguous — and the + prompt promises the citation.""" + seen: set[str] = set() + for i, sec in enumerate(obj.get("sections", [])): + sid = sec.get("id") + if sid in seen: + raise Rejection("duplicate", f"{field}.sections[{i}].id", + "a section id used once", sid) + seen.add(sid) + + +SHAPES = {"table": _table_rows_match_columns, + "section": _section_has_content, + "artifact": _section_ids_unique} + + +def _prose(**kw): + """Paragraph text: content, not formatting.""" + return _str(nonBlank=True, notMatch=NO_MD, **kw) + + +def _cell(**kw): + """One rendered table cell.""" + return _str(nonBlank=True, notMatch=NO_CELL_MD, **kw) + + +def _bullet_list(**kw): + return _arr(_str(nonBlank=True, notMatch=NO_MD + [MD_BULLET], **kw)) + + +TABLE = _obj({ + "caption": _str(maxLength=200), + "columns": _arr(_cell(minLength=1), minItems=1), + "rows": _arr(_arr(_cell(minLength=1), minItems=1), minItems=1), +}, req=["columns", "rows"], shape="table") + +CODE = _obj({ + "lang": _str(), + "source": _str(minLength=1), +}, req=["source"]) + +# A section is structured content: prose paragraphs, bullet items, tables, +# and code blocks are four shapes, each with a typed home, so the renderer +# never guesses. At least one shape must be present — an empty section is a +# heading in the store promising text that is not there. +SECTION = _obj({ + "id": _str(minLength=1), + "title": _str(minLength=1), + "prose": _prose(minLength=1, maxLength=12000), + "bullets": _bullet_list(minLength=1), + "tables": _arr(TABLE, minItems=1), + "code": _arr(CODE, minItems=1), +}, req=["id", "title"], shape="section") + +REQUIREMENT = _obj({ + "id": _str(pattern=r"R\d+"), + "requirement": _prose(minLength=1), + "observable": _prose(), + "cites": _arr(_str()), +}, req=["id", "requirement", "observable"]) + +CONSTRAINT = _obj({ + "id": _str(pattern=r"C\d+"), + "constraint": _prose(minLength=1), + "observable": _prose(), +}, req=["id", "constraint", "observable"]) + +CRITERION = _obj({ + "id": _str(pattern=r"V\d+"), + "criterion": _prose(minLength=1), + "procedure": _prose(minLength=1), + "cites": _arr(_str()), +}, req=["id", "criterion", "procedure"]) + +# A task id inside its plan is T plus exactly two digits: it becomes a +# directory name, and the layout grammar admits no other shape. +TASK_LOCAL = r"T\d{2}" + +TASK = _obj({ + "id": _str(pattern=TASK_LOCAL), + "title": _str(minLength=1), + "goal": _prose(minLength=1), + "files": _arr(_str(minLength=1), minItems=1), + "accepts": _arr(_str(minLength=1), minItems=1), + "provides": _arr(_str()), + "consumes": _arr(_str()), + "depends_on": _arr(_str(pattern=TASK_LOCAL)), +}, req=["id", "title", "goal", "files", "accepts"]) + +FINDING = _obj({ + "id": _str(minLength=1), + "severity": _enum("critical", "important", "minor", "info"), + "claim": _prose(minLength=1), + "evidence": _prose(), + "fix_scope": _enum("instance", "class"), + "class_hint": _str(), + "status": _enum("open", "fixed", "waived", "routed"), +}, req=["id", "severity", "claim"]) + + +def artifact_schema(artifact_kind: str) -> dict: + """Per-artifact body schema. Shared skeleton: id/title/summary/sections; + heavier kinds add their typed collections. The id's segment is tied to the + kind (a charter is CHTR, never SPEC), and a plan is a plan id.""" + props = { + "id": _str(pattern=artifact_pattern(artifact_kind)), + "title": _str(minLength=1), + "summary": _prose(minLength=1), + "sections": _arr(SECTION), + "cites": _arr(_str()), + } + req = ["id", "title", "summary", "sections"] + if artifact_kind in ("spec", "charter"): + props.update({ + "requirements": _arr(REQUIREMENT), + "constraints": _arr(CONSTRAINT), + "risks": _arr(_str()), + }) + if artifact_kind == "vrfy": + # Verification is driven by these rows: a VRFY without any would make + # the verification gate pass with nothing proven. + props["criteria"] = _arr(CRITERION, minItems=1) + req.append("criteria") + if artifact_kind == "plan": + props.update({ + "plan_id": _str(pattern=PLAN_ID), + "objective": _str(minLength=1), + "tasks": _arr(TASK, minItems=1), + "gates": _arr(_str()), + "more_plans": {"type": "boolean"}, + }) + req += ["plan_id", "objective", "tasks", "more_plans"] + if artifact_kind in ("arch", "design"): + props.update({ + "adrs": _arr(_obj({ + "id": _str(minLength=1), "title": _str(minLength=1), + "decision": _str(minLength=1), "why": _str(minLength=1), + "cost_if_wrong": _str(), + "alternatives": _arr(_str()), + }, req=["id", "title", "decision", "why"])), + "ifces": _arr(_obj({ + "id": _str(minLength=1), "title": _str(minLength=1), + "provides": _arr(_str()), "consumes": _arr(_str()), + }, req=["id", "title"])), + }) + if artifact_kind == "risk": + # `mitigation` is nullable because "accepted without mitigation" + # is a real disposition the human must be able to overrule; forcing + # the string "none" would hide it. + props["risks"] = _arr(_obj({ + "id": _str(minLength=1), "risk": _str(minLength=1), + "likelihood": _enum("high", "medium", "low"), + "impact": _enum("high", "medium", "low"), + "mitigation": _prose(nullable=True), + }, req=["id", "risk", "likelihood", "impact", "mitigation"])) + return _obj({**_base(artifact_kind), **props}, + req=["kind", "v", *req], shape="artifact") + + +ARTIFACT_KINDS = ["charter", "options", "brainstorm", "arch", "adr", "ifce", + "design", "spec", "risk", "vrfy", "plan"] + +# The target of an audit or repair: any artifact, or a plan. +ARTIFACT_OR_PLAN = ARTIFACT_ID + "|" + PLAN_ID + + +# ------------------------------------------------------------ runtime + +REPORT = _obj({ + **_base("report"), + "task": _str(pattern=TASK_ID), + "result": _enum("DONE", "DONE_WITH_CONCERNS", "BLOCKED", "PARTIAL"), + "summary": _str(minLength=1), + "commits": _arr(_str(minLength=1)), + "concerns": _arr(_str()), + "tests": _arr(_obj({ + "name": _str(minLength=1), "ran": {"type": "boolean"}, + "passed": {"type": "boolean"}, "detail": _str(), + }, req=["name", "ran", "passed"])), + "model_actual": _str(), +}, req=["kind", "v", "task", "result", "summary", "commits"]) + +QUALITY_VERDICTS = ("APPROVED", "NEEDS_FIXES", "APPROVED_WITH_ROUTED_RESIDUALS") + + +VERDICT = _obj({ + **_base("verdict"), + "task": _str(pattern=TASK_ID), + "round": _int(minimum=1), + "spec_verdict": _enum("PASS", "FAIL"), + "quality_verdict": _enum(*QUALITY_VERDICTS), + "findings": _arr(FINDING), + "model_actual": _str(), + "commit_base": _str(minLength=4), + "commit_head": _str(minLength=4), + "reviewed_package_sha": _str(minLength=4), +}, req=["kind", "v", "task", "round", "spec_verdict", + "quality_verdict", "commit_base", "commit_head", + "reviewed_package_sha"]) + +HEARTBEAT = _obj({ + **_base("heartbeat"), + "task": _str(pattern=TASK_ID), + "note": _str(maxLength=400), +}, req=["kind", "v", "task"]) + +EVIDENCE = _obj({ + **_base("evidence"), + "criterion": _str(pattern=r"V\d+"), + "command": _str(minLength=1), + "observed": _str(minLength=1), + "verdict": _enum("proven", "unavailable", "failed"), + "state_commit": _str(minLength=4), + "artifacts": _arr(_str()), +}, req=["kind", "v", "criterion", "command", "observed", + "verdict", "state_commit"]) + +GATE_DECISION = _obj({ + **_base("gate_decision"), + "phase": _enum(*PHASES), + "decision": _enum("approved", "rejected", "waived"), + "by": _enum("human", "auto"), + "note": _str(), +}, req=["kind", "v", "phase", "decision", "by"]) + +RULING = _obj({ + **_base("ruling"), + "decision": _str(minLength=1), + "why": _str(minLength=1), + "cost_if_wrong": _str(), + "answered": _str(), + "unsolicited": _str(), + "stop": {"type": "boolean"}, + "for_task": _str(pattern=f"(?:{TASK_ID}|{PLAN_ID})"), +}, req=["kind", "v", "decision", "why"]) + +AUDIT = _obj({ + **_base("audit"), + "target": _str(pattern=ARTIFACT_OR_PLAN), + "round": _int(minimum=1), + "verdict": _enum("PASS", "FAIL"), + "findings": _arr(FINDING), +}, req=["kind", "v", "target", "round", "verdict", "findings"]) + + +HALT = _obj({ + **_base("halt"), + "reason": _str(minLength=1), +}, req=["kind", "v", "reason"]) + +SPAWN_ERROR = _obj({ + **_base("spawn_error"), + "error_class": _enum("rate_limit", "auth", "network", "session", + "other"), + "detail": _str(), +}, req=["kind", "v", "dispatch_id", "error_class"]) + +NEEDS_CONTEXT = _obj({ + **_base("needs_context"), + "task": _str(pattern=TASK_ID), + "question": _str(minLength=1), + "for_role": _str(), +}, req=["kind", "v", "task", "question"]) + +MERGE = _obj({ + **_base("merge"), + "plan": _str(pattern=PLAN_ID), + "merge_sha": _str(minLength=4), + "branch": _str(), +}, req=["kind", "v", "plan", "merge_sha"]) + +RESUME = _obj({ + **_base("resume"), + "reason": _str(minLength=1), +}, req=["kind", "v", "reason"]) + + +POLICY = _obj({ + "v": _enum("v1"), + "max_fix_rounds": _int(), + "max_audit_rounds": _int(), + "max_evidence_tries": _int(), + "max_plans": _int(), + "spawn_retry_cap": _int(), + "suspect_s": _int(), + "deadline_s": _int(), + "clean_quality": _arr(_enum(*QUALITY_VERDICTS), minItems=1), +}, req=["v"]) + + +SCHEMAS = { + "report": REPORT, + "verdict": VERDICT, + "heartbeat": HEARTBEAT, + "evidence": EVIDENCE, + "gate_decision": GATE_DECISION, + "ruling": RULING, + "halt": HALT, + "spawn_error": SPAWN_ERROR, + "needs_context": NEEDS_CONTEXT, + "audit": AUDIT, + "merge": MERGE, + "resume": RESUME, +} + + +def schema_for(kind: str) -> dict: + if kind in ARTIFACT_KINDS: + return artifact_schema(kind) + if kind in SCHEMAS: + return SCHEMAS[kind] + raise Rejection("unknown_kind", "$.kind", + "|".join(sorted(SCHEMAS) + ARTIFACT_KINDS), repr(kind)) diff --git a/skills/executor/scripts/lib/executor/store.py b/skills/executor/scripts/lib/executor/store.py new file mode 100644 index 0000000..0bc4f3d --- /dev/null +++ b/skills/executor/scripts/lib/executor/store.py @@ -0,0 +1,455 @@ +# SPDX-License-Identifier: MIT +# Copyright (c) 2026 Atri10 +"""Durable store mechanics for the executor engine. + +The only mutation surface. Everything a run ever records lives here: + +- ``events.vN.jsonl`` — append-only, hash-chained journal. The truth. +- ``state.json`` — a rebuildable fold cache, never authoritative. +- ``meta.json`` — engine/schema/store version stamps. +- ``slots/`` — minted, single-use payload slots. +- ``in/`` ``out/`` ``views/`` — payloads, prompts/packages, projections. + +No other module writes to ``.executor/``; all writes funnel through these +helpers so atomicity and the hash chain hold in one place. +""" +from __future__ import annotations + +import hashlib +import json +import os +import time +from dataclasses import dataclass, field +from pathlib import Path + +from . import SCHEMA_VERSION, STORE_VERSION, __version__ + +RUN_STORE = ".executor" +DOCS_STORE = "docs/executor" +JOURNAL_FMT = "events.v{}.jsonl" +GENESIS_SHA = "0" * 64 + + +# ---------------------------------------------------------------- paths + +def repo_root(start: Path | None = None) -> Path: + """Locate the git worktree root, like exec_root().""" + start = (start or Path.cwd()).resolve() + for d in [start, *start.parents]: + if (d / ".git").exists(): + return d + raise ExecError("not inside a git repository", "exec_root") + + +# Path helpers live in paths.py — the single naming authority. Re-export +# the ones this module uses so call sites read naturally. +from .paths import (autonomy_file, dispatch_dir, dispatches_dir, + docs_root, init_dir, journal_dir, journal_file, + lock_file, meta_dir, meta_file, payload_file, prompt_file, + run_meta_file, run_root, state_file, + task_dir, views_dir, artifact_dir, artifact_file, + plan_dir, plan_file, audit_file, repair_file, + task_impl_report, review_package_file, verdict_file, + fix_package_file, fix_report_file, preflight_file, + plan_audit_file, plan_repair_file, docs_init_dir, + docs_index_file, docs_index_md, docs_artifact_dir, + docs_artifact_file, docs_artifact_md, docs_plan_dir, + docs_plan_file, docs_plan_md, docs_task_dir, + docs_report_file, docs_verdict_file, + docs_export_journal, view_file) + + +# ---------------------------------------------------------------- errors + +class ExecError(Exception): + """A typed, user-facing engine error. The CLI prints it and exits 2.""" + + def __init__(self, msg: str, code: str = "engine_error"): + super().__init__(msg) + self.code = code + self.msg = msg + + +class Rejection(Exception): + """A payload validation failure. Carries the structured error the pump + relays back to the worker — never a stack trace.""" + def __init__(self, code: str, field: str, expected: str, got: str, + hint: str = ""): + super().__init__(f"{code} at {field}: expected {expected}, got {got}") + self.code, self.field = code, field + self.expected, self.got, self.hint = expected, got, hint + + def to_dict(self) -> dict: + return {"code": self.code, "field": self.field, + "expected": self.expected, "got": self.got, + "hint": self.hint} + + +# ---------------------------------------------------------------- json/io + +def canonical(obj) -> bytes: + """Deterministic bytes for hashing/signing a payload.""" + return json.dumps(obj, sort_keys=True, separators=(",", ":"), + ensure_ascii=False).encode("utf-8") + + +def sha256(obj) -> str: + return hashlib.sha256(canonical(obj)).hexdigest() + + +def now_iso() -> str: + return time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()) + + +def atomic_write(path: Path, data: bytes) -> None: + """Write via tmp+rename so a crash never leaves a torn file. A write that + fails part-way removes its temp file and leaves the target untouched.""" + path.parent.mkdir(parents=True, exist_ok=True) + tmp = path.with_suffix(path.suffix + ".tmp") + try: + with open(tmp, "wb") as f: + f.write(data) + f.flush() + os.fsync(f.fileno()) + os.replace(tmp, path) + except BaseException: + tmp.unlink(missing_ok=True) + raise + + +def write_json(path: Path, obj) -> None: + atomic_write(path, json.dumps(obj, indent=2, ensure_ascii=False, + sort_keys=False).encode("utf-8") + b"\n") + + +def read_json(path: Path, default=None): + try: + return json.loads(path.read_text(encoding="utf-8")) + except (OSError, json.JSONDecodeError): + return default + + +# ---------------------------------------------------------------- locking + +_WINDOWS = os.name == "nt" + +# How long a writer waits for the store lock before reporting `store_locked`. +LOCK_WAIT_S = 10.0 + + +def _lock_retry(fd: int, unlock: bool = False) -> None: + """Take (or release) the Windows byte-range lock. `LK_NBLCK` fails at once + instead of blocking inside the C runtime for its own timeout, so a writer + that cannot get the lock reports `store_locked` after LOCK_WAIT_S rather + than hanging the process. A poll interval of 5ms keeps a contended acquire + under a millisecond of added latency while leaving no descriptor held for + the OS's own retry window.""" + import msvcrt + import time + os.lseek(fd, 0, os.SEEK_SET) + if unlock: + msvcrt.locking(fd, msvcrt.LK_UNLCK, 1) + return + deadline = time.monotonic() + LOCK_WAIT_S + while True: + try: + msvcrt.locking(fd, msvcrt.LK_NBLCK, 1) + return + except OSError: + if time.monotonic() >= deadline: + raise + time.sleep(0.005) + + +class StoreLock: + """Single-writer advisory lock on the initiative dir. Context manager. + flock on POSIX; msvcrt byte-range locking on Windows, which locks from the + descriptor's current offset, so it is rewound first. Every entry opens its + own descriptor, which is why the lock excludes threads as well as + processes. The platform is a module constant so tests can drive both + branches on any OS.""" + + def __init__(self, idir: Path): + self.path = lock_file(idir) + self.fd: int = -1 + + def __enter__(self): + self.path.parent.mkdir(parents=True, exist_ok=True) + self.fd = os.open(self.path, os.O_CREAT | os.O_RDWR) + try: + if _WINDOWS: + _lock_retry(self.fd) + else: + import fcntl + fcntl.flock(self.fd, fcntl.LOCK_EX) + except OSError as e: + os.close(self.fd) + self.fd = -1 + raise ExecError(f"could not lock {self.path}: {e}", + "store_locked") from e + return self + + def __exit__(self, *exc): + if self.fd < 0: + return + try: + if _WINDOWS: + _lock_retry(self.fd, unlock=True) + else: + import fcntl + fcntl.flock(self.fd, fcntl.LOCK_UN) + finally: + os.close(self.fd) + self.fd = -1 + + +# ---------------------------------------------------------------- journal + +def sha_line(line: bytes) -> str: + return hashlib.sha256(line.rstrip(b"\n")).hexdigest() + + +def parse_journal(raw: bytes) -> tuple[list[dict], int]: + """Parse journal bytes line by line. Returns (events, torn): a non-empty + line that is not a JSON event object is counted and skipped. It neither + stops the scan nor is trusted, so a crash mid-append (even one that cut a + multibyte character in half) can never hide the events written after it. + `verify_chain` is what notices a gap. Pure, so corruption can be tested + exhaustively without touching the filesystem.""" + events: list[dict] = [] + torn = 0 + for chunk in raw.split(b"\n"): + line = chunk.rstrip(b"\r") + if not line.strip(): + continue + try: + ev = json.loads(line) + except ValueError: # JSONDecodeError and UnicodeDecodeError + torn += 1 + continue + if isinstance(ev, dict) and isinstance(ev.get("seq"), int): + events.append(ev) + else: + torn += 1 + return events, torn + + +def scan_journal(idir: Path) -> tuple[list[dict], int]: + """The journal file's (events, torn); a missing file is empty.""" + path = journal_file(idir) + if not path.exists(): + return [], 0 + return parse_journal(path.read_bytes()) + + +def read_events(idir: Path) -> list[dict]: + return scan_journal(idir)[0] + + +def verify_chain(events: list[dict]) -> list[str]: + """Return the integrity violations (empty = clean chain). Every line_sha is + recomputed from its event body, so an edit to any committed event is + caught, including the last one, which nothing links to.""" + problems: list[str] = [] + prev = GENESIS_SHA + for i, ev in enumerate(events): + if ev.get("seq") != i + 1: + problems.append(f"event {i+1}: seq {ev.get('seq')} != {i+1}") + if ev.get("prev_sha") != prev: + problems.append(f"event seq {ev.get('seq')}: prev_sha mismatch") + body = {k: v for k, v in ev.items() if k != "line_sha"} + if sha256(body) != ev.get("line_sha"): + problems.append(f"event seq {ev.get('seq')}: line_sha mismatch " + f"(event edited after commit)") + prev = ev.get("line_sha") or prev + return problems + + +def next_seq(events: list[dict]) -> int: + return (events[-1]["seq"] + 1) if events else 1 + + +def chain_tip(events: list[dict]) -> str: + return events[-1]["line_sha"] if events else GENESIS_SHA + + +def make_event(idir: Path, actor: str, kind: str, entity: str, + data: dict, dispatch_id: str | None = None, + payload_sha: str | None = None) -> dict: + """Build the next chained event (not yet appended).""" + events = read_events(idir) + ev = { + "seq": next_seq(events), + "ts": now_iso(), + "v": SCHEMA_VERSION, + "engine_version": __version__, + "actor": actor, + "kind": kind, + "entity": entity, + "dispatch_id": dispatch_id, + "payload_sha": payload_sha, + "prev_sha": chain_tip(events), + "data": data, + } + ev["line_sha"] = sha256({k: ev[k] for k in ev if k != "line_sha"}) + return ev + + +def _tail_is_clean(path: Path) -> bool: + """True when the journal is empty or ends on a newline.""" + if not path.exists() or path.stat().st_size == 0: + return True + with open(path, "rb") as f: + f.seek(-1, os.SEEK_END) + return f.read(1) == b"\n" + + +def append_event(idir: Path, ev: dict) -> dict: + """Append one event to the journal (fsync'd). Caller holds the lock. A + torn fragment left by a crash is closed off with a newline first, so the + new event is never glued onto it.""" + path = journal_file(idir) + path.parent.mkdir(parents=True, exist_ok=True) + lead = b"" if _tail_is_clean(path) else b"\n" + line = json.dumps(ev, sort_keys=False, ensure_ascii=False) + "\n" + with open(path, "ab") as f: + f.write(lead + line.encode("utf-8")) + f.flush() + os.fsync(f.fileno()) + return ev + + +# ---------------------------------------------------------------- meta + +def init_store(root: Path, init_id: str, title: str) -> Path: + """Scaffold a new initiative store + committed docs dir. Refuses an + existing initiative: re-scaffolding would reset its meta and autonomy.""" + idir = init_dir(root, init_id) + if idir.exists(): + raise ExecError(f"{init_id} already exists at {idir}", "exists") + for d in (idir, journal_dir(idir), meta_dir(idir), dispatches_dir(idir), + views_dir(idir), docs_init_dir(root, init_id)): + d.mkdir(parents=True, exist_ok=True) + write_json(meta_file(idir), { + "initiative": init_id, "title": title, + "engine_version": __version__, + "schema_version": SCHEMA_VERSION, + "store_version": STORE_VERSION, + "created_at": now_iso(), + }) + write_json(run_root(root) / "meta.json", { + "engine_version": __version__, + "schema_version": SCHEMA_VERSION, + "store_version": STORE_VERSION, + }) + write_json(autonomy_file(idir), {p: "deny" for p in PHASES}) + return idir + + +def store_version_verdict(engine_version) -> str: + """Compare a store's engine version with this engine's major version. Pure, so + the CLI reports the same verdict the engine enforces. The result is one of + 'current', 'store_outdated' (the store is older) or 'engine_too_old' (the store + is newer than this engine).""" + ev = str(engine_version) + if _major(ev) > _major(__version__): + return "engine_too_old" + if _major(ev) < _major(__version__): + return "store_outdated" + return "current" + + +def check_store_version(idir: Path) -> None: + """Refuse clearly on version skew rather than misreading a store.""" + meta = read_json(meta_file(idir)) + if meta is None: + raise ExecError(f"no meta.json in {idir}: not an executor store " + f"(or one from before v2). Use `executor new`.", + "no_meta") + ev = str(meta.get("engine_version", "0")) + verdict = store_version_verdict(ev) + if verdict == "engine_too_old": + raise ExecError( + f"store written by engine v{ev}; you have v{__version__}. " + f"Install executor ≥ {_major(ev)}.x or run `executor migrate`.", + "engine_too_old") + if verdict == "store_outdated": + raise ExecError( + f"store written by engine v{ev}; you have v{__version__}. " + f"Run `executor migrate --dry-run` then `executor migrate`.", + "store_outdated") + + +def _major(v: str) -> int: + try: + return int(str(v).split(".")[0]) + except (ValueError, IndexError): + return 0 + + +# Phase order — single source for both the machine and meta init. +PHASES = ["intake", "discovery", "architecture", "design", "specification", + "planning", "plan_regression", "execution", "review", + "verification", "handoff"] + + +@dataclass +class Initiative: + id: str + root: Path + idir: Path + events: list[dict] = field(default_factory=list) + + @property + def meta(self) -> dict: + return read_json(meta_file(self.idir)) or {} + + @property + def state(self) -> dict: + return read_json(state_file(self.idir)) or {} + + def reload(self) -> "Initiative": + self.events = read_events(self.idir) + return self + + +def _finished(idir: Path) -> bool: + """A run is finished once its handoff gate was approved. The cached phase + alone does not say so: an initiative parked at handoff with the gate still + open is in flight. A missing or unreadable cache means not finished.""" + state = read_json(state_file(idir)) + phases = state.get("phase_state") if isinstance(state, dict) else None + return isinstance(phases, dict) and phases.get("handoff") == "passed" + + +def find_initiative(root: Path, init_id: str | None = None, + gate: bool = True) -> Initiative: + """Resolve an initiative by id, or the one in flight. Two in flight is an + error, never a silent pick: acting on the wrong initiative is worse than + asking. When every initiative is finished the newest is returned, so + status and check still work on a completed run. + + `gate=False` skips the version check. Only `migrate` uses it: it must open a + skewed store to tell the user what is wrong. Every other command is gated.""" + store = run_root(root) + if init_id: + idir = init_dir(root, init_id) + if not idir.exists(): + raise ExecError(f"no initiative {init_id} at {idir}", + "no_initiative") + if gate: + check_store_version(idir) + return Initiative(init_id, root, idir).reload() + cands = [d for d in sorted(store.glob("INIT-*")) if d.is_dir()] + if not cands: + raise ExecError("no initiatives in .executor/ — run `executor new`", + "no_initiative") + actives = [d for d in cands if not _finished(d)] + if len(actives) > 1: + names = ", ".join(d.name for d in actives) + raise ExecError(f"{len(actives)} active initiatives ({names}); " + f"pass INIT-ID", "ambiguous") + pick = actives[0] if actives else cands[-1] + if gate: + check_store_version(pick) + return Initiative(pick.name, root, pick).reload() diff --git a/skills/executor/scripts/lib/executor/views.py b/skills/executor/scripts/lib/executor/views.py new file mode 100644 index 0000000..0e38b56 --- /dev/null +++ b/skills/executor/scripts/lib/executor/views.py @@ -0,0 +1,201 @@ +# SPDX-License-Identifier: MIT +# Copyright (c) 2026 Atri10 +"""Projections — every human-readable file regenerated from state. + +These are views, never sources of truth. `render_all` runs after every +accepted ingest and on `executor check` / `status`, so a stale view is a +render lag, not a stored lie. +""" +from __future__ import annotations + +from .store import Initiative, now_iso, views_dir, write_json +from . import __version__ + +SEV = {"critical": 0, "important": 1, "minor": 2, "info": 3} + + +def render_all(init: Initiative) -> None: + """Regenerate every projection into views/ + the committed index.""" + from .engine import fold + s = fold(init.events) + vdir = views_dir(init.idir) + vdir.mkdir(parents=True, exist_ok=True) + _progress(init, s, vdir) + _dispatches(init, s, vdir) + _verdicts(init, s, vdir) + _summary(init, s, vdir) + _graph_json(init, s, vdir) + + +def _progress(init, s, vdir) -> None: + lines = [f"# {init.id} — progress", "", + f"*phase:* `{s['phase']}` · *generated:* {now_iso()} · " + f"*engine:* {__version__}", "", + "| Task | State | Round | Fix-rounds | Files |", "|---|---|---|---|---|"] + for tid in sorted(s["tasks"]): + t = s["tasks"][tid] + lines.append( + f"| {tid} | {t['state']} | R{t.get('round',0):02d} | " + f"{t.get('fix_rounds',0)} | {len(t.get('files',[]))} |") + (vdir / "progress.md").write_text("\n".join(lines) + "\n", + encoding="utf-8") + + +def _dispatches(init, s, vdir) -> None: + lines = [f"# {init.id} — dispatches", "", + "| Dispatch | Entity | Role | Schema | At | Outcome |", + "|---|---|---|---|---|---|"] + for did, d in sorted(s["dispatches"].items()): + if d.get("spawn_error"): + out = f"spawn_error: {d['spawn_error']}" + elif did in s["answered"]: + out = "answered" + else: + out = "open" + lines.append(f"| {did} | {d['entity']} | {d['role']} | {d['schema']} | " + f"{d['at']} | {out} |") + (vdir / "dispatches.md").write_text("\n".join(lines) + "\n", + encoding="utf-8") + + +def _verdicts(init, s, vdir) -> None: + for vid, v in s["verdicts"].items(): + lines = [f"# {vid}", "", + f"spec: **{v['spec_verdict']}** · " + f"quality: **{v['quality_verdict']}**", ""] + if v.get("findings"): + lines += ["| ID | Sev | Finding |", "|---|---|---|"] + for f in sorted(v["findings"], + key=lambda x: SEV.get(x["severity"], 9)): + lines.append(f"| {f['id']} | {f['severity']} | " + f"{f['claim']} |") + (vdir / f"{vid}-verdict.md").write_text("\n".join(lines) + "\n", + encoding="utf-8") + + +def _summary(init, s, vdir) -> None: + lines = [f"# {init.id} — gate summary", "", + "| Phase | State |", "|---|---|"] + for ph, st in s["phase_state"].items(): + lines.append(f"| {ph} | {st} |") + open_c = sum(len(c.get("open", [])) for c in s["critiques"].values()) + done = sum(1 for t in s["tasks"].values() if t["state"] == "complete") + lines += ["", f"open critique findings: **{open_c}**", + f"tasks complete: **{done} / {len(s['tasks'])}**", + f"rulings: {len(s['rulings'])}"] + (vdir / "summary.md").write_text("\n".join(lines) + "\n", + encoding="utf-8") + + +def _graph_json(init, s, vdir) -> None: + write_json(vdir / "graph.json", + {"nodes": s["entities"], "edges": s["edges"], + "generated": now_iso(), "engine": __version__}) + + +def evidence_counts(s: dict) -> dict[str, int]: + """Verification counts, unanswered included. A criterion with no + evidence event is unproven however obviously it 'must' work, so it is + counted rather than absorbed into a sentence about the others.""" + counts = {"proven": 0, "failed": 0, "unavailable": 0} + answered = set() + for cid, runs in s["evidence"].items(): + verdict = runs[-1]["verdict"] + if verdict in counts: + counts[verdict] += 1 + answered.add(cid) + from executor.engine import _criteria_defs + total = {c["id"] for c in _criteria_defs(s)} + # Computed, not seeded: a criterion with no evidence event is exactly + # the difference between the declared criteria and the answered ones. + counts["unanswered"] = len(total - answered) + return counts + + +def status_card(init: Initiative, s: dict) -> str: + """The gate card `executor status` prints. Never artifact bytes, and plain + ASCII: Windows consoles on legacy code pages cannot draw the glyphs that + make a card pretty, and a crash on the status command is worse.""" + lines = [f"INITIATIVE {init.id} - {init.meta.get('title', '')}", + f"phase: {s['phase']} ({s['phase_state'].get(s['phase'], '-')})", + f"events: {s['seq']} | artifacts: {len(s['artifacts'])} | " + f"tasks: {len(s['tasks'])}"] + if any(a["kind"] == "vrfy" for a in s["artifacts"].values()): + c = evidence_counts(s) + lines.append(f"evidence: {c['proven']} proven | {c['failed']} failed " + f"| {c['unavailable']} unavailable " + f"| {c['unanswered']} unanswered") + open_c = sum(len(c["open"]) for c in s["critiques"].values()) + if open_c: + lines.append(f"open critique findings: {open_c}") + unruled = [n for n in s["needs_ruling"] if not n["ruled"]] + if unruled: + lines.append(f"! {len(unruled)} concern(s) awaiting rulings") + if s["halt"]: + lines.append(f"HALTED: {s['halt']}") + if s["phase_state"].get(s["phase"]) == "gate_pending": + lines.append(f"-> GATE {s['phase']}: awaiting a human decision " + f"(ingest a gate_decision payload)") + return "\n".join(lines) + + +def render_report_md(p: dict, did: str) -> str: + """The committed record of one worker report. No timestamp, so re-rendering + the same payload writes the same bytes.""" + lines = [f"# {p['task']} — report {did}", "", + f"**result:** {p['result']}", "", p["summary"], "", "**commits:**"] + lines += [f"- `{c}`" for c in p.get("commits", [])] or ["- none"] + if p.get("concerns"): + lines += ["", "**concerns:**", *[f"- {c}" for c in p["concerns"]]] + return "\n".join(lines) + "\n" + + +def render_verdict_md(p: dict) -> str: + """The committed record of one review round. Findings are sorted by + severity so the same verdict always renders the same bytes.""" + lines = [f"# {p['task']} — verdict R{p['round']:02d}", "", + f"- spec: **{p['spec_verdict']}**", + f"- quality: **{p['quality_verdict']}**", + f"- range: `{p['commit_base']}..{p['commit_head']}`", + f"- package: `{p['reviewed_package_sha']}`", "", "## Findings"] + found = sorted(p.get("findings", []), key=lambda f: SEV.get(f["severity"], 9)) + lines += [f"- **{f['id']}** ({f['severity']}): {f['claim']}" for f in found] or ["- none"] + return "\n".join(lines) + "\n" + + +def render_handoff_index(init_id: str, s: dict) -> dict: + """The machine-readable index of a finished run: every artifact, plan, task, + verdict and final evidence state. A pure function of the folded state.""" + return { + "initiative": init_id, + "phase": s["phase"], + "artifacts": [{"id": aid, "kind": a["kind"], "status": a["status"], + "rounds": a["round"]} + for aid, a in sorted(s["artifacts"].items())], + "plans": [{"id": pid, "status": s["plans"][pid]["status"], + "tasks": sorted(t for t in s["tasks"] + if t.startswith(pid + "-"))} + for pid in s["plan_order"]], + "tasks": {tid: t["state"] for tid, t in sorted(s["tasks"].items())}, + "verdicts": sorted(s["verdicts"]), + "evidence": {cid: runs[-1]["verdict"] + for cid, runs in sorted(s["evidence"].items())}, + } + + +def render_handoff_md(init_id: str, s: dict) -> str: + """The human-readable handoff: the same facts as the index, as tables.""" + idx = render_handoff_index(init_id, s) + lines = [f"# {init_id} — handoff", "", + f"Phase at handoff: `{idx['phase']}`", "", + "## Artifacts", "", "| Id | Kind | Status | Rounds |", "|---|---|---|---|"] + lines += [f"| {a['id']} | {a['kind']} | {a['status']} | {a['rounds']} |" + for a in idx["artifacts"]] + lines += ["", "## Plans", ""] + lines += [f"- `{p['id']}` ({p['status']}): {len(p['tasks'])} task(s)" + for p in idx["plans"]] or ["- none"] + lines += ["", "## Tasks", "", "| Task | State |", "|---|---|"] + lines += [f"| {tid} | {state} |" for tid, state in idx["tasks"].items()] + lines += ["", "## Evidence", ""] + lines += [f"- {cid}: {v}" for cid, v in idx["evidence"].items()] or ["- none"] + return "\n".join(lines) + "\n"