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"