@sabaiway/agent-workflow-engine 1.6.0 → 1.8.0

package/CHANGELOG.md

@@ -4,6 +4,45 @@ All notable changes to the methodology engine. Versions are this **package's** n
 they are distinct from the **deployment-lineage** stamp written into a project's `docs/ai/`
 (which tracks the shared `agent-workflow` lineage, head `1.3.0`).
 
+## 1.8.0 — Mechanize the §9 review-loop discipline (round cap · crossover · finding-origin)
+
+A **feature** release. The methodology canon institutionalizes the review-loop economics so the round
+cap, the crossover stop, and the finding-origin discipline stop being deletable prose:
+
+- **`planning.md` §9** gains a *Fold minimally — a prose plan has no checker* bullet (a self-consistency
+  read; fold minimally in ONE place), and the *Heavy review at the diff* bullet now names
+  **backend divergence** as the crossover and routes an all-mechanics/CI or prose-only artifact to a
+  **thin plan + diff-review**.
+- **`orchestration.md` §4/§5** adds the **backend-divergence stop-signal**, reconciled with recipe
+  fidelity: divergence bounds the *rounds*, never drops a ready backend within one.
+- **`procedures.md`** requires a per-round emission **{round N · finding-origin tally · per-backend
+  verdict}** at the loop point of *both* activities.
+
+Guarded non-vacuously: `planning-`/`procedures-`/`orchestration-canon` gain region-scoped tokens; the
+kit's `lens-mirror` registers the five review-loop tokens (Set-1) + the M6 `finding-origin` token (Set-2).
+Deployment-lineage head stays `1.3.0` (no `docs/ai` migration).
+
+## 1.7.0 — Harden the planning canon: process-fidelity + regression-free editing
+
+A **feature** release. The methodology canon gains **seven invariants** that close recurring
+process-fidelity slips and fold-induced churn — each pinned in its natural home and guarded by the engine
+canon tests (+ the kit's extended cross-package `lens-mirror.test.mjs`):
+
+- **`references/planning.md` §6 — *ExitPlanMode ≠ execute*.** A harness "approved — start coding" prompt
+  authorizes the PLAN only; "continue in-session" is a DELIBERATE transition into `plan-execution` after
+  the plan + cold-start prompt exist, never an implicit slide (disambiguates §6 vs the Definition of Done).
+- **`references/planning.md` §9 — regression-free editing + the convergence bar.** *No code-mechanics in
+  the plan*, *test-as-spec* (fold a code-touching finding into a red→green test, not prose),
+  *characterize-first* (pin uncovered behavior before editing), *heavy review at the diff*, and a CLEAN
+  loop defined as **0 blockers + 0 majors from every named backend** (folding ≠ convergence).
+- **`references/orchestration.md` §4/§5 — *recipe fidelity*.** Council runs every ready backend **every
+  round**; quietly dropping a ready backend is a forbidden silent downgrade (the converse of the
+  unavailable-backend degrade), and the §5 quota guard is explicitly not a licence to drop one.
+- **`references/procedures.md`** — terse pointers weave all of the above into both activity steps.
+
+The deployment-lineage head stays **`1.3.0`** (no `docs/ai` structural change, no migration); the npm
+package version is a separate axis.
+
 ## 1.6.0 — Loosen the agy Issue-001 caveat (grounded review is sound)
 
 A **feature** release. `references/orchestration.md` §5 reframes the `agy` health advisory: the grounded

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.6.0'
+  version: '1.8.0'
 ---
 
 # agent-workflow-engine

package/capability.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-engine",
-  "version": "1.6.0",
+  "version": "1.8.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",

package/references/orchestration.md

@@ -69,12 +69,38 @@ always reported, never silently dropped:
 - **Delegated → Solo.** No backend provides `execute` and is `ready` → Solo, with the reason.
 - **Reviewed → Solo.** No backend provides `review` and is `ready` → Solo, with the reason.
 
+**Recipe fidelity — the converse: every ready backend, every round.** Degradation is the *only*
+licence to run fewer backends than the recipe names. When the resolved recipe is `council` and BOTH
+reviewers are `ready`, EVERY review round runs BOTH — skipping a ready backend for quota, convenience,
+or "the other one already shipped" is a **SILENT downgrade of Council → Reviewed, and is forbidden**.
+The distinction is strict: an *unavailable* backend is a LOUD, stated degrade (the lattice above); a
+*ready* backend you quietly drop is a fidelity breach, not a degrade. The same holds for any recipe
+that names ≥2 backends. Folding a finding and re-reviewing (the convergence bar, [`planning.md`](planning.md)
+§9) re-runs **every named backend each round** — convergence is reached only when one round comes back
+clean from all of them.
+
+**Backend divergence is the crossover stop — it bounds the ROUNDS, never the backends.** Running every
+named backend every round CONVERGES when one round returns **0 blockers + 0 majors** from all of them.
+But when the backends **diverge** — one grounded-**ships** while another keeps line-by-line **revising**
+mechanics round after round — that **backend divergence** IS the crossover the loop must stop at: resolve
+at **altitude** (raise the surviving major to an explicit acceptance invariant Execute must meet, or hand
+the mechanics to the diff), NOT by exhausting the strictest line-by-line backend. This is the exact
+converse of the fidelity rule above: divergence bounds how many ROUNDS the loop runs, and never licenses
+dropping a ready backend within a round — both still run every round.
+
 ## 5. Quota & health guard (advisory)
 
 Backends are **subscription** services with **finite** quota. The orchestrator should: prefer the
 cheapest model that fits the task; not reach for a top-tier model by reflex; and remember that
 **Council spends two backends' quota** for one decision.
 
+This guides *which recipe to choose up front* and *which model to run within a backend* — it is
+**never a licence to drop a ready backend mid-Council** (that is the §4 fidelity breach, not a quota
+saving). Once `council` is the resolved recipe and both backends are `ready`, the two-backend cost is
+already accepted: run both, every round, until a round comes back clean — or until **backend divergence**
+marks the crossover (§4), resolved at altitude rather than by exhausting the strictest backend. Spending
+quota to line-by-line re-review mechanics past that crossover is the over-run the divergence stop prevents.
+
 A **standing health advisory** applies to `agy`: the Antigravity service can **stall on substantive
 prompts** (a long hang that returns nothing — an external service issue, not a setup problem;
 tracked as **Issue-001** in the kit's known issues). It is **invisible to file-presence detection**,

package/references/planning.md

@@ -78,6 +78,10 @@ The volume trigger above (files / LoC / tokens) is necessary but not sufficient.
 - **Continue** in the current session when ALL hold: (1) exploration was *targeted-deep* — you read the exact files to be created/modified/copied, so execution would just re-read them; (2) no new heavy exploration is needed to execute; (3) the context budget is healthy (far from the window limit / Lost-in-the-Middle).
 - When continuing, each Phase's Verification block is a natural checkpoint. If different Phases need different cold context, continue only through the warm Phases, then split.
 
+### ExitPlanMode authorizes the plan, not execution
+
+A harness "approved — you can now start coding" prompt (e.g. Claude Code's **ExitPlanMode**) authorizes the **PLAN only** — this methodology overrides that generic prompt. A planning session is not done until the plan is landed in `docs/plans/` **and** the cold-start execution prompt is emitted (the plan-authoring Definition of Done). So **"Continue in-session" above is a DELIBERATE transition into `plan-execution`, taken *after* both of those exist** — never an implicit slide from plan-approval straight into editing tracked files. Plan-approval is not a licence to execute the plan in the same breath; the boundary holds whether you split or continue.
+
 ## 7. Plan-document structure
 
 ```
@@ -107,10 +111,22 @@ The volume trigger above (files / LoC / tokens) is necessary but not sufficient.
 
 ## 9. Right-altitude & code-grounded folds
 
-Two disciplines keep a plan converging instead of churning. They govern authoring, every review round, and execution.
+These disciplines keep a plan converging instead of churning, and keep a fold or edit from shipping a new bug. They govern authoring, every review round, and execution. The honest premise: prose has no checker, so the only guarantee that a fold/edit ships no regression is a deterministic, non-vacuous, auto-run gate — hence test-as-spec + characterize-first below.
 
 **Right altitude.** A plan pins *intent + architecture + invariants + acceptance criteria* — the named tests that must stay green and the new tests that must pass. It does NOT spell out fine code-mechanics in prose: those are resolved in code at Execute (against the real files + the per-Step review + the gates), where prose cannot diverge from reality. Most "blockers" that resurface across review rounds are code-level details that never belonged in a prose plan.
 
+**No code-mechanics in the plan.** A Step still carries its exact paths + commands (§7, §8); the ceiling is on *fold-bred* detail — a review fold must not push fine code-mechanics (`cd`, an env default, a flag) into prose, where they diverge from reality. A fold that needs a mechanic is the trigger to write the test (test-as-spec) instead.
+
 **Fold by code, not prose.** Before folding any code-touching finding into the plan, READ the cited `file:line`; the fold cites it. A fold grounded in prose alone drifts from the code and seeds the next bug.
 
+**Test-as-spec.** Fold a code-touching review finding into a red→green TEST, not a prose paragraph — the gate is the only deterministic checker, and a paragraph cannot self-check. A bug may still be written, but the test catches a fold-/edit-induced regression before it ships.
+
+**Characterize-first.** Before editing UNCOVERED code, first write a test pinning its current behavior (green), then edit — any unintended change goes red. Never edit what has no checker; first give it one. Keep edits atomic/reversible (one logical change = one gated commit), and prefer SUBTRACTIVE folds.
+
+**Fold minimally — a prose plan has no checker.** An ephemeral, gitignored plan is PROSE with no executable checker, so a single fold that silently drifts one of several prose spots seeds the next churn round (this is what turns a 2-round review into a 6-round one). Fold **minimally, in ONE place**, run a **self-consistency** read across the whole plan before every re-review, and keep the plan SHORT. The only runtime firing an ephemeral plan can carry is the point-of-use advisor's printed review-loop checkpoint — there is no other checker.
+
+**Heavy review at the diff, not the plan.** 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 line-by-line mechanics — IS that crossover: resolve at altitude (raise the surviving major to an acceptance invariant, or hand the mechanics to Execute), do not exhaust the strictest backend. Route an all-mechanics/CI or prose-only artifact to a **thin plan + diff-review**, where the runner and gates settle it, not another prose round. The plan is the wrong place for an exhaustive line-by-line review.
+
+**Convergence bar.** A review loop is CLEAN only when one round returns **0 blockers + 0 majors** from EVERY named backend the recipe runs (nits / non-blocking + a ship verdict is the stop). FOLDING a finding is NOT convergence — re-review after folding. This §9 governs the ALTITUDE at which you reach clean (fix the major, or raise it to an explicit acceptance invariant Execute must meet) — it NEVER lowers the bar to "majors folded".
+
 **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.

package/references/procedures.md

@@ -53,8 +53,25 @@ Produce a self-contained, cold-readable plan, reviewed to the configured depth b
 4. **review {recipe}** — review the draft at the depth the resolved `review` recipe selects: Solo
    (self-review only), Reviewed (one backend reviews), or Council (both backends review, you
    synthesize). The kit resolves the effective recipe from `docs/ai/orchestration.json` + readiness.
-5. **Fold + loop** — fold every finding back into the draft and re-review until the review is clean.
-6. **Present for approval** — surface the finished plan to the user; do not begin execution here.
+5. **Fold + loop** — fold every finding back into the draft and re-review. A loop is CLEAN only at
+   **0 blockers + 0 majors** from every backend the recipe names (the convergence bar,
+   [`planning.md`](planning.md) §9); folding ≠ convergence — re-review after folding. Fold a
+   code-touching finding **test-as-spec** (a named acceptance test, not a prose paragraph); a fold must
+   add **no code-mechanics** to the plan — a Step still carries its own exact paths + commands, but a
+   fold needing a mechanic is the trigger to name the test instead. Council runs every named backend
+   **every round** (recipe fidelity,
+   [`orchestration.md`](orchestration.md) §4) — never quietly drop a ready backend. Cap architecture
+   plan-review at **≤2 rounds**, stopping at the **crossover** where **backend divergence** (one backend
+   grounded-ships while another keeps revising mechanics) IS the stop — the bar is still met by RESOLVING
+   the surviving major at altitude (raise it to an acceptance invariant, or hand it to Execute), never by
+   exhausting the strictest backend. Run a **self-consistency** read before every re-review and route an
+   all-mechanics/CI or prose-only artifact to a **thin plan + diff-review** ([`planning.md`](planning.md)
+   §9). Each round MUST emit **{round N · finding-origin tally (first-draft / fold-induced / mechanics) ·
+   per-backend verdict}** so the crossover is a computed signal, not a remembered rule.
+6. **Present for approval** — surface the finished plan to the user; do not begin execution here. A
+   harness "approved — start coding" prompt (**ExitPlanMode**) authorizes the PLAN only
+   ([`planning.md`](planning.md) §6); continuing into `plan-execution` is a deliberate transition taken
+   after the plan + its cold-start prompt exist, never an implicit slide.
 
 **Required output (Definition of Done):** a planning session produces a self-contained plan in
 `docs/plans/` **and** a cold-start execution prompt to begin the next session — **both produced without
@@ -78,9 +95,16 @@ Execute an approved plan Step by Step; each Step is one logical commit.
    following the project's reuse + clean-code rules.
 4. **Self-review** — run the [`planning.md`](planning.md) §8 self-review on the change, applying the
    [`planning.md`](planning.md) §9 lens — fold by code (read and cite the `file:line`), and hold the
-   right altitude.
+   right altitude. Edit-time corollary: **characterize-first** — before editing uncovered code, pin its
+   current behavior in a green test, then edit (any unintended change goes red); fold each finding
+   **test-as-spec** (red→green), and keep edits atomic/reversible.
 5. **review {recipe}** — review the result at the resolved `review` depth (Solo / Reviewed / Council),
-   exactly as in plan-authoring.
+   exactly as in plan-authoring. This is the **heavy review at the diff** — real compiling code + the
+   full suite, where a regression fails a gate immediately ([`planning.md`](planning.md) §9). Council
+   runs every named backend **every round** (recipe fidelity, [`orchestration.md`](orchestration.md) §4);
+   loop to **0 blockers + 0 majors** from every backend before the gate. Each round MUST emit
+   **{round N · finding-origin tally · per-backend verdict}**; when backends diverge, that is the
+   crossover — resolve at altitude, not by exhausting the strictest backend.
 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.