@sabaiway/agent-workflow-engine 1.17.0 → 2.1.0

package/CHANGELOG.md

@@ -2,7 +2,40 @@
 
 All notable changes to the methodology engine. Versions are this **package's** npm versions;
 they are distinct from the **deployment-lineage** stamp written into a project's `docs/ai/`
-(which tracks the shared `agent-workflow` lineage, head `2.0.0`).
+(which tracks the shared `agent-workflow` lineage, head `3.0.0`).
+
+## 2.1.0 — the plan names the layout it is about to create (AD-091)
+
+The authoring canon now asks for the layout while the plan is still text: every Step that creates a
+file names that file and the single responsibility it carries — and where the project declares a
+source-size cap, the planned layout fits it.
+
+- **`procedures.md` plan-authoring, Draft (step 2)** — every Step that CREATES a file names that file
+  and the single responsibility it carries, and **where the project declares a source-size cap**, the
+  planned layout fits it. The conditional is canon, not decoration: a project that declares no
+  practice must never be handed an invented limit.
+- **`planning.md` §8 self-review checklist** — the matching line, so the draft is re-checked against
+  it before the plan is finalized. The line carries the canon's own rationale for asking at plan
+  time: "a gate that refuses an oversized file after it is written only pays for a rewrite".
+- The rung lives in **plan-authoring only** — plan-execution grows no rival copy of it. Both canon
+  pins are enforced by the existing canon suites, including the conditional form.
+
+## 2.0.0 — strip-the-kit: the planning canon teaches the computed loop (AD-059)
+
+> ### ⚠ BREAKING — the §9 "Computed instrument" canon is rewritten
+>
+> The review-ledger/fold-completeness vocabulary is gone from the methodology. The loop the canon
+> now teaches: red-proof BEFORE a fix (`core-evidence red-proof`) · explicit per-backend degrade
+> records · stage → reviews on the STAGED tree → `run-gates --final` (the ONE receipt) →
+> `commit-guard --check` at the commit boundary — **no ledger records it**; the round
+> tally/classification discipline stays dialogue-level.
+
+- `planning.md` §9 rewritten to the D3 loop; `procedures.md` step 5 mirrors it; the
+  `orchestration.md` writer-economy clause reworded (the ledger-triad example died with the
+  machinery).
+- The agent-rules LENS reworded in its canonical home; the OUTGOING pre-strip body is appended to
+  `agent-rules-lens-priors.md` verbatim (the AD-041 vintage contract — priors are append-only
+  history).
 
 ## 1.17.0 — Prompt-economy canon gains a writer-batch clause + two sandbox-lane sentences (REPORT-FACTS train D5/D6, AD-054)
 

package/SKILL.md

@@ -3,7 +3,7 @@ name: agent-workflow-engine
 description: Canonical home of the agent-workflow planning methodology — the Plan→Phase→Step→Substep vocabulary, plan lifecycle, queue.md series index, mandatory Cleanup phase, the bounded methodology slot fragment, the orchestration-recipe vocabulary (Solo / Reviewed / Council / Delegated), and the activity-procedures canon (plan-authoring / plan-execution, with typed recipe slots). A published, installable npm package (available:true) that *provides* the methodology text; it mutates nothing. The composition root (agent-workflow-kit) reads this canon LIVE from the installed engine and injects the bounded slots from it — one source of truth, no bundled mirror; `npx @sabaiway/agent-workflow-kit@latest init` installs the engine.
 disable-model-invocation: true
 metadata:
-  version: '1.17.0'
+  version: '2.1.0'
 ---
 
 # agent-workflow-engine

package/bin/install.mjs

@@ -14,7 +14,7 @@
 // not a project deploy and not a model-invoked skill — there is nothing to "run"
 // inside an agent.
 //
-// No telemetry, no phone-home. Dependency-free, Node >= 18.
+// No telemetry, no phone-home. Dependency-free, Node >= 22.
 
 import { readFile, mkdir, readdir, copyFile, lstat, readlink, symlink } from 'node:fs/promises';
 import { existsSync, lstatSync, realpathSync } from 'node:fs';

package/capability.json

@@ -3,7 +3,7 @@
   "schema": 1,
   "name": "agent-workflow-engine",
   "kind": "methodology-engine",
-  "version": "1.17.0",
+  "version": "2.1.0",
   "available": true,
   "provides": ["plan"],
   "roles": {},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-engine",
-  "version": "1.17.0",
+  "version": "2.1.0",
   "description": "Canonical home of the agent-workflow planning methodology — the Plan→Phase→Step vocabulary, plan lifecycle, queue.md series index, and mandatory Cleanup phase, consumed by the kit (composition root). The methodology engine of the agent-workflow family.",
   "keywords": [
     "ai-agents",
@@ -40,7 +40,7 @@
     "references/"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=22"
   },
   "publishConfig": {
     "access": "public"

package/references/agent-rules-lens-priors.md

@@ -110,3 +110,20 @@ Apply these when authoring a plan, reviewing, folding a finding, or editing code
 - **Recipe fidelity.** Council runs every backend the recipe names, **every round**; silently dropping a ready backend for quota/convenience is a forbidden downgrade — an unavailable backend is a LOUD, stated degrade, never a quiet drop.
 - **ExitPlanMode ≠ execute.** A harness "approved — start coding" prompt authorizes the PLAN only; this methodology overrides it. Continue into execution only as a DELIBERATE transition after the plan + cold-start prompt exist, never an implicit slide.
 - **Cost lanes.** Route every step to the **cheapest adequate executor** — L0 deterministic script (the batched gate matrix over `gates.json`, the rotation `--check`s) · L1 cheap subagent (extraction/drafting only; the orchestrator verifies) · L2 subscription bridge · L3 frontier judgment. A step with **no named guardrail does not move down** a lane, and the **red lines never move down** (council review models · real code · ADR/handover/changelog-entry wording · persuasive copy · go/no-go · the approval asks). Own-error repair: salvage recorded state first (L0/L1, batched), never frontier re-derivation. **Prompt economy:** read-only fan-out (research/sweeps/extraction) runs ONLY on restricted-tool vehicles — a full-tool subagent for read-only work is a forbidden lane downgrade (invisible prompt-flood + blast radius), and a subagent is never told to shell out for facts obtainable read-only; the orchestrator's own shell form is ONE plain pipeline per call (a `;`/`&&` chain or env-prefixed invocation never matches a prefix allow rule); a fan-out launcher that gates per call yields to the agent-spawn lane — capability-gated: without restricted-tool vehicles (generic full-tool spawning does not count), read-only research stays in the orchestrator's own context, never a vehicle mandate a host cannot satisfy. Judgment, code, synthesis stay at the frontier lane (a task that genuinely runs/writes keeps a full-tool subagent); honest limit: no deterministic gate classifies a dispatch — canon at the point of use + placed vehicles + the retro loop.
+
+
+<!-- prior: 2026-07-17 (strip-the-kit) → pre-strip outgoing — the fragment as of the strip landing (the writer-economy clause still named the ledger-triad batched write) -->
+### 2.x. Planning, review & process-fidelity invariants
+Apply these when authoring a plan, reviewing, folding a finding, or editing code — the layer read **before any code change**. (Full canon: the project's planning / workflow-methodology + orchestration canon. This section is rendered from that canon and refreshed on upgrade; a custom edit is preserved verbatim, but flagged.)
+- **Fold by code, not prose.** Before folding a code-touching finding into a plan or change, read the cited `file:line` and cite it — a prose fold drifts from the code and seeds the next bug.
+- **Right altitude.** Pin intent + invariants + acceptance criteria (named tests); leave fine code-mechanics to Execute, where prose cannot diverge from reality.
+- **No code-mechanics in the plan.** A Step still carries its exact paths + commands (the plan-structure / self-review canon) — checked syntax: the plan's own Verification runs them against an explicit expected outcome or gate; the only other syntax a plan may carry is a literal fixture/schema fragment a named test copies or validates. Un-run, logic-bearing syntax — control-flow, a regex, a glob, a grammar, an algorithm body, a mini-DSL — never lives in plan prose, however plausible or shell-verified it looks: a fold or draft that wants one is the trigger to write the test instead.
+- **Test-as-spec.** Fold a code-touching finding into a red→green TEST, not a prose paragraph — the gate is the only deterministic checker; a paragraph cannot self-check.
+- **Characterize-first.** Before editing UNCOVERED code, pin its current behavior in a green test, then edit — any unintended change goes red. Never edit what has no checker; first give it one. Keep edits atomic/reversible; prefer SUBTRACTIVE folds.
+- **Fold minimally — prose has no checker.** An ephemeral, gitignored plan is prose with no executable checker; fold **minimally, in ONE place** and run a **self-consistency** read across the plan before every re-review — a fold that drifts several prose spots is what turns a 2-round review into churn.
+- **Heavy review at the diff.** Plan-review settles architecture only (≤2 rounds, stop at the pre-existing→fold-induced crossover); the exhaustive per-Step review runs against real compiling code + the full suite, where a regression fails a gate immediately. **Backend divergence** (one backend grounded-ships while another keeps revising mechanics) IS that crossover — resolve at altitude, don't exhaust the strictest backend; route an all-mechanics/CI or prose-only artifact to a **thin plan + diff-review**.
+- **Convergence bar.** A review loop is CLEAN only when one round returns **0 blockers + 0 majors** from EVERY backend the recipe names (nits + a ship verdict is the stop). Folding ≠ convergence — re-review after folding.
+- **Per-round emission.** Every review round emits **{round N · finding-origin tally · per-backend verdict}** so the crossover is a computed, visible signal, not a remembered rule.
+- **Recipe fidelity.** Council runs every backend the recipe names, **every round**; silently dropping a ready backend for quota/convenience is a forbidden downgrade — an unavailable backend is a LOUD, stated degrade, never a quiet drop.
+- **ExitPlanMode ≠ execute.** A harness "approved — start coding" prompt authorizes the PLAN only; this methodology overrides it. Continue into execution only as a DELIBERATE transition after the plan + cold-start prompt exist, never an implicit slide.
+- **Cost lanes.** Route every step to the **cheapest adequate executor** — L0 deterministic script (the batched gate matrix over `gates.json`, the rotation `--check`s) · L1 cheap subagent (extraction/drafting only; the orchestrator verifies) · L2 subscription bridge · L3 frontier judgment. A step with **no named guardrail does not move down** a lane, and the **red lines never move down** (council review models · real code · ADR/handover/changelog-entry wording · persuasive copy · go/no-go · the approval asks). Own-error repair: salvage recorded state first (L0/L1, batched), never frontier re-derivation. **Prompt economy:** read-only fan-out (research/sweeps/extraction) runs ONLY on restricted-tool vehicles — a full-tool subagent for read-only work is a forbidden lane downgrade (invisible prompt-flood + blast radius), and a subagent is never told to shell out for facts obtainable read-only; the orchestrator's own shell form is ONE plain pipeline per call (a `;`/`&&` chain or env-prefixed invocation never matches a prefix allow rule); a fan-out launcher that gates per call yields to the agent-spawn lane — capability-gated: without restricted-tool vehicles (generic full-tool spawning does not count), read-only research stays in the orchestrator's own context, never a vehicle mandate a host cannot satisfy. Judgment, code, synthesis stay at the frontier lane (a task that genuinely runs/writes keeps a full-tool subagent); honest limit: no deterministic gate classifies a dispatch — canon at the point of use + placed vehicles + the retro loop. **Writer economy:** a stage's repeated WRITER commands batch into ONE invocation — the review-ledger triad rides one batched write, other stage writers combine via one launcher per stage; never one writer call at a time (each write is its own prompt).

package/references/agent-rules-lens.md

@@ -11,4 +11,4 @@ Apply these when authoring a plan, reviewing, folding a finding, or editing code
 - **Per-round emission.** Every review round emits **{round N · finding-origin tally · per-backend verdict}** so the crossover is a computed, visible signal, not a remembered rule.
 - **Recipe fidelity.** Council runs every backend the recipe names, **every round**; silently dropping a ready backend for quota/convenience is a forbidden downgrade — an unavailable backend is a LOUD, stated degrade, never a quiet drop.
 - **ExitPlanMode ≠ execute.** A harness "approved — start coding" prompt authorizes the PLAN only; this methodology overrides it. Continue into execution only as a DELIBERATE transition after the plan + cold-start prompt exist, never an implicit slide.
-- **Cost lanes.** Route every step to the **cheapest adequate executor** — L0 deterministic script (the batched gate matrix over `gates.json`, the rotation `--check`s) · L1 cheap subagent (extraction/drafting only; the orchestrator verifies) · L2 subscription bridge · L3 frontier judgment. A step with **no named guardrail does not move down** a lane, and the **red lines never move down** (council review models · real code · ADR/handover/changelog-entry wording · persuasive copy · go/no-go · the approval asks). Own-error repair: salvage recorded state first (L0/L1, batched), never frontier re-derivation. **Prompt economy:** read-only fan-out (research/sweeps/extraction) runs ONLY on restricted-tool vehicles — a full-tool subagent for read-only work is a forbidden lane downgrade (invisible prompt-flood + blast radius), and a subagent is never told to shell out for facts obtainable read-only; the orchestrator's own shell form is ONE plain pipeline per call (a `;`/`&&` chain or env-prefixed invocation never matches a prefix allow rule); a fan-out launcher that gates per call yields to the agent-spawn lane — capability-gated: without restricted-tool vehicles (generic full-tool spawning does not count), read-only research stays in the orchestrator's own context, never a vehicle mandate a host cannot satisfy. Judgment, code, synthesis stay at the frontier lane (a task that genuinely runs/writes keeps a full-tool subagent); honest limit: no deterministic gate classifies a dispatch — canon at the point of use + placed vehicles + the retro loop. **Writer economy:** a stage's repeated WRITER commands batch into ONE invocation — the review-ledger triad rides one batched write, other stage writers combine via one launcher per stage; never one writer call at a time (each write is its own prompt).
+- **Cost lanes.** Route every step to the **cheapest adequate executor** — L0 deterministic script (the batched gate matrix over `gates.json`, the rotation `--check`s) · L1 cheap subagent (extraction/drafting only; the orchestrator verifies) · L2 subscription bridge · L3 frontier judgment. A step with **no named guardrail does not move down** a lane, and the **red lines never move down** (council review models · real code · ADR/handover/changelog-entry wording · persuasive copy · go/no-go · the approval asks). Own-error repair: salvage recorded state first (L0/L1, batched), never frontier re-derivation. **Prompt economy:** read-only fan-out (research/sweeps/extraction) runs ONLY on restricted-tool vehicles — a full-tool subagent for read-only work is a forbidden lane downgrade (invisible prompt-flood + blast radius), and a subagent is never told to shell out for facts obtainable read-only; the orchestrator's own shell form is ONE plain pipeline per call (a `;`/`&&` chain or env-prefixed invocation never matches a prefix allow rule); a fan-out launcher that gates per call yields to the agent-spawn lane — capability-gated: without restricted-tool vehicles (generic full-tool spawning does not count), read-only research stays in the orchestrator's own context, never a vehicle mandate a host cannot satisfy. Judgment, code, synthesis stay at the frontier lane (a task that genuinely runs/writes keeps a full-tool subagent); honest limit: no deterministic gate classifies a dispatch — canon at the point of use + placed vehicles + the retro loop. **Writer economy:** a stage's repeated WRITER commands batch — evidence declarations ride consecutive plain invocations of ONE allow-listed tool, other stage writers combine via one launcher per stage; never an unbatched writer scatter (each gated write is its own prompt).

package/references/orchestration.md

@@ -144,16 +144,16 @@ zero-prompt bar prefer the agent-spawn lane with placed vehicles. This clause is
 vehicles, use them; WITHOUT restricted-tool vehicles — whether or not generic full-tool spawning
 exists — read-only research stays in the orchestrator's own context —
 never a vehicle mandate a host cannot satisfy. **(d)** a stage that fires repeated WRITER commands
-batches them — the review-ledger triad (records / classifications / overrides) rides ONE batched
-write, and the remaining stage writers combine via one launcher per stage; never
-one writer call at a time (each write is its own prompt). The clause narrows
+batches them — a stage's evidence declarations (red-proofs, degrades) ride consecutive plain
+writer invocations of ONE allow-listed tool, and the remaining stage writers combine via one
+launcher per stage; never an unbatched writer scatter (each gated write is its own prompt). The clause narrows
 TOOLS for read-only work only — judgment, code, and synthesis stay at the frontier lane, and a
 task that genuinely needs to run or write keeps a full-tool subagent. **Honest limit:**
 no deterministic gate classifies a dispatch — enforcement is this canon at the point of use,
 the placed vehicles, and the retro loop.
 
 **Sandbox lanes.** Under an OS sandbox the lanes split once more by **surface class**: the L0
-surfaces are **sandbox-safe** (gate/ledger/state/fold checks, git reads, plain no-network tests);
+surfaces are **sandbox-safe** (gate/state/coverage checks, git reads, plain no-network tests);
 the bridge wrappers are **genuinely unsandboxed** (they need network); npm-cache-touching commands
 are **COMMAND-SHAPE dependent** — first try the sandbox-safe shape (cache under `$TMPDIR`,
 offline/notifier off) before moving anything out. Two driving rules: **move ONLY the failing

package/references/planning.md

@@ -104,6 +104,7 @@ A harness "approved — you can now start coding" prompt (e.g. Claude Code's **E
 ## 8. Self-review checklist (before finalizing a Plan)
 
 - Every Step has exact file paths and exact commands.
+- Every Step that CREATES a file names that file and its single responsibility; where the project declares a source-size cap, the planned layout fits it (no declared cap → no invented limit). Deciding the layout here is the cheap lever — a gate that refuses an oversized file after it is written only pays for a rewrite.
 - Every recommendation that used to live outside the Plan is now a Step (§5).
 - Vocabulary is strict (§1); the Plan ends with **Phase N: Cleanup** (§4).
 - If part of a series: `queue.md` is initialised / updated (§3).
@@ -133,7 +134,7 @@ These disciplines keep a plan converging instead of churning, and keep a fold or
 
 **Convergence heuristic.** When a review round keeps finding code-mechanism issues on a stable architecture, STOP refining prose — either raise the spec to invariant + acceptance altitude, or hand the mechanics to Execute. Do not re-litigate code mechanics in the plan.
 
-**Computed instrument (plan-execution).** The **review-ledger** computes the crossover-stop for the plan-execution (code) loop: each round and each triage classification — **fixable-bug** (a fold pinned by a red→green test) / **inherent-layer-residual** (raised to an acceptance criterion) / **escalate** (a maintainer decision) — is recorded, and the stop decision is READ from the ledger, never remembered; its `--check` is the loop's gate (the exit contract lives in the tool's own header — point, don't restate). The same per-round tally + classification discipline governs plan-authoring review; the ledger itself is plan-execution-scoped.
+**Computed instrument (plan-execution).** The plan-execution (code) loop's stop is READ from the four deterministic checks + the ship receipts, never remembered: declare each bugfix red BEFORE the fix (`core-evidence red-proof` — an observed N/N red with content custody); an unavailable review backend gets an explicit `core-evidence degrade` record, never a silent skip; then stage everything, run the configured reviews on the STAGED tree, and mint the ONE receipt with `run-gates --final` (coverage of every changed executable line + red-proof verification ride the final run); `commit-guard --check` gates the commit against that receipt — any later edit re-stales it (the exit contracts live in each tool's own header — point, don't restate); `core-evidence summary` renders the loop state statelessly. The per-round finding-origin tally + triage classification discipline — **fixable-bug** (a fold pinned by a red→green test) / **inherent-layer-residual** (raised to an acceptance criterion) / **escalate** (a maintainer decision) — stays the dialogue-level discipline for BOTH activities; no ledger records it.
 
 ## 10. Autonomy at the plan checkpoints
 

package/references/procedures.md

@@ -50,9 +50,16 @@ Produce a self-contained, cold-readable plan, reviewed to the configured depth b
 
 1. **Research** — gather the exact files, contracts, and constraints the plan will touch.
 2. **Draft** — write the plan to the document structure defined in [`planning.md`](planning.md) §7,
-   with exact paths and commands per Step. Bind to that structure; do not restate it here.
+   with exact paths and commands per Step. Bind to that structure; do not restate it here. Name the
+   LAYOUT as you draft: every Step that CREATES a file names that file and the single responsibility
+   it carries, and — **when the project declares a source-size cap** (the composition root's
+   `procedures` advisor prints the declared practice; a project that declares none carries no limit
+   to invent) — the planned layout fits that cap. Scope fixed before any code exists is what keeps a
+   module small; a size gate is only the backstop.
 3. **Self-review** — run the [`planning.md`](planning.md) §8 checklist (exact paths/commands, strict
-   vocabulary, every out-of-plan recommendation folded into a Step, `queue.md` updated for a series).
+   vocabulary, every created file named with its single responsibility (fitting the declared cap
+   where there is one), every out-of-plan recommendation folded into a Step, `queue.md` updated for a
+   series).
    Apply the [`planning.md`](planning.md) §9 lens — fold by code (read and cite the `file:line`), and
    hold the right altitude.
 4. **review {recipe}** — review the draft at the depth the resolved `review` recipe selects: Solo
@@ -116,9 +123,10 @@ Execute an approved plan Step by Step; each Step is one logical commit.
    **{round N · finding-origin tally · per-backend verdict}**; when backends diverge, that is the
    crossover — resolve at altitude, not by exhausting the strictest backend. Classify survivors at the
    cap the same way (**fixable-bug / inherent-layer-residual / escalate**). This loop's computed
-   instrument is the **review-ledger**: record each round + triage, read the stop from its `--status`
-   render (it replaces the hand-composed tally), and wire `review-ledger --check` as the gate — the
-   exit contract lives in the tool's own header, never restated here.
+   instruments: `core-evidence red-proof` declares each bugfix red BEFORE the fix; `core-evidence
+   degrade` records an unavailable backend explicitly; the reviews run on the STAGED tree and
+   `run-gates --final` mints the ONE receipt `commit-guard --check` gates the commit against — the
+   exit contracts live in each tool's own header, never restated here.
 6. **Gates** — run the project's verification gate (tests + checks) to green before committing.
 7. **Commit boundary** — the orchestrator makes the single commit for the Step; a backend never
    commits. The project's commit-approval policy (e.g. ask first) lives in the project's own rules.