@sabaiway/agent-workflow-engine 1.12.0 → 1.13.0

package/CHANGELOG.md

@@ -4,6 +4,27 @@ 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.13.0 — The agent-rules lens gets its ONE canonical home here (slot-render, AD-041)
+
+A **feature** release (canon content + its guard; installer unchanged; deployment-lineage head
+stays `1.3.0` — no migration). The planning/review/process-fidelity lens block that used to be
+hand-mirrored across the family's `agent_rules.md` templates now lives HERE, once:
+
+- **`references/agent-rules-lens.md`** — the canonical lens block (number-neutral `### 2.x.`
+  heading). Its intro now carries the provenance clause (rendered from the canon; refreshed on
+  upgrade; a custom edit is preserved verbatim, but flagged). The family kit renders this into a
+  deployed `docs/ai/agent_rules.md` region and refreshes it on bootstrap/upgrade.
+- **`references/agent-rules-lens-priors.md`** — the **append-only store** of every lens body a
+  previous release shipped (all 4 historical vintages harvested from the template git history,
+  including the outgoing pre-1.13.0 body). The frozen delimiter format is documented in-file.
+  A future canon wording change edits the fragment AND appends the outgoing body — both files
+  in THIS package, so it ships as an **engine-only release** (the AD-041 measurement clause).
+- **`test/lens-fragment.test.mjs`** — canon-presence guard: the 22 discipline tokens (the single
+  token list going forward), heading shape, path-neutrality, priors shape + the computed
+  pre-1.13.0 membership, injected non-vacuity; CRLF-tolerant reads.
+- `SKILL.md` / `README.md` payload lists name the two new files (slot-fragment counts went
+  count-free). Tarball 12 → 14 files, pinned by `package-content.test.mjs`.
+
 ## 1.12.0 — Plans carry a home for review-settled decisions (§7 optional `## Decisions (locked)`)
 
 A **feature** release (canon text + its tests; installer unchanged; deployment-lineage head stays

package/README.md

@@ -4,8 +4,9 @@
 methodology *text* — the Plan → Phase → Step vocabulary, the plan-file lifecycle
 (`docs/plans/*.md`, ephemeral, never committed), the `queue.md` series index, the mandatory
 final **Phase: Cleanup**, the **orchestration-recipe** vocabulary (Solo / Reviewed / Council /
-Delegated), and the two bounded slot fragments the family kit injects into a deployed project's
-`AGENTS.md`.
+Delegated), the bounded slot fragments the family kit injects into a deployed project's
+`AGENTS.md`, and the canonical agent-rules lens block the kit renders into a deployed
+`docs/ai/agent_rules.md`.
 
 This is the **methodology engine** of the `agent-workflow` family — the canonical source the
 rest of the family builds on. It is **content**, not a runtime: it reads nothing, writes
@@ -53,11 +54,19 @@ the canonical methodology reference on disk:
 - [`references/procedures.md`](references/procedures.md) — the canonical **activity-procedures** canon:
   the named activities (`plan-authoring`, `plan-execution`) as ordered steps with typed recipe slots,
   read live and rendered by the read-only `/agent-workflow-kit procedures <activity>`.
+- [`references/agent-rules-lens.md`](references/agent-rules-lens.md) — the canonical **agent-rules
+  lens** block (the planning/review/process-fidelity invariants) the kit renders into a deployed
+  `docs/ai/agent_rules.md` region and refreshes on upgrade — a canon wording change ships as an
+  engine-only release.
+- [`references/agent-rules-lens-priors.md`](references/agent-rules-lens-priors.md) — the
+  **append-only store** of previously-shipped lens bodies; the kit refreshes a deployed region only
+  when it matches a known body (a customized region is preserved verbatim).
 
 ## What this package ships
 
 `SKILL.md` (the canon overview + ownership rule), `references/` (the full methodology + the
-orchestration + activity-procedures references + the two bounded slot fragments), `capability.json`
+orchestration + activity-procedures references + the bounded slot fragments + the agent-rules lens
+fragment and its prior store), `capability.json`
 (the family manifest), and this installer. It ships **no** family-wide tooling (the schema/validator/injection live in the
 composition root) and mutates nothing — preserving "knows nobody".
 

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.12.0'
+  version: '1.13.0'
 ---
 
 # agent-workflow-engine
@@ -39,6 +39,14 @@ slot fill is needed but the engine is absent, the kit's reconcile **fails loudly
   slots** that bind to the orchestration recipes, composing with `planning.md` without restating it. It
   stays generic (no project-specific stages baked in). The kit reads it live and renders the steps +
   the resolved effective recipe per slot via the read-only `/agent-workflow-kit procedures <activity>`.
+- [`references/agent-rules-lens.md`](references/agent-rules-lens.md) — the canonical **agent-rules
+  lens** block (the planning/review/process-fidelity invariants). The kit renders it into a deployed
+  `docs/ai/agent_rules.md` `### 2.x.` region (heading-anchored, no markers) and refreshes that region
+  on bootstrap/upgrade — a canon wording change edits this file (plus the prior store below) and ships
+  as an engine-only release.
+- [`references/agent-rules-lens-priors.md`](references/agent-rules-lens-priors.md) — the **append-only
+  store** of every lens body a previous release shipped. The kit refreshes a deployed region only when
+  its body matches the fragment or one of these entries; a customized region is preserved verbatim.
 
 ## Ownership rule (the engine knows nobody)
 

package/capability.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-engine",
-  "version": "1.12.0",
+  "version": "1.13.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/agent-rules-lens-priors.md

@@ -0,0 +1,79 @@
+# agent-rules-lens — known-prior canonical bodies (append-only)
+
+Every lens-block body a PREVIOUS release ever shipped in an `agent_rules.md` template. The family
+composition root refreshes a deployed `### 2.x. Planning, review & process-fidelity invariants`
+region to the current `references/agent-rules-lens.md` ONLY when the deployed body
+normalize-matches (heading number → `2.x`, trim, CRLF→LF) one of these entries — so every
+unmodified in-the-wild deployment converges on first touch, while a customized region is
+preserved verbatim. A canon wording change edits `agent-rules-lens.md` AND appends the outgoing
+body here — both engine files, an engine-only release.
+
+FROZEN FORMAT (an old reader must keep parsing a newer file — append entries, never reshape):
+
+- Everything above the first delimiter line is this header; parsers ignore it.
+- A delimiter is a line that starts with `<!-- prior` and ends with `-->`; text between is a
+  free-form provenance label (never parsed).
+- An entry body is everything after its delimiter up to the next delimiter or end of file,
+  with leading/trailing blank lines trimmed.
+- APPEND-ONLY: new entries go at the end of the file; never edit or remove an existing entry
+  (a deployment seeded from any past release must keep matching forever).
+
+<!-- prior: 2026-06-30 (AD-029) — the seven process-fidelity invariants land -->
+### 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.)
+- **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); the ceiling is on *fold-bred* detail — a review fold must not push fine code-mechanics (`cd`, an env default, a flag) into prose. A fold that needs a mechanic 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.
+- **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.
+- **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.
+- **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.
+
+<!-- prior: 2026-07-01 (AD-031) — review-loop economics: fold-minimally, per-round emission, divergence crossover -->
+### 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.)
+- **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); the ceiling is on *fold-bred* detail — a review fold must not push fine code-mechanics (`cd`, an env default, a flag) into prose. A fold that needs a mechanic 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.
+
+<!-- prior: 2026-07-02 (AD-035) — the cost-lanes bullet lands -->
+### 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.)
+- **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); the ceiling is on *fold-bred* detail — a review fold must not push fine code-mechanics (`cd`, an env default, a flag) into prose. A fold that needs a mechanic 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.
+
+<!-- prior: 2026-07-02 (AD-036) → pre-E4 outgoing — the checked-syntax B5 sharpening -->
+### 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.)
+- **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.

package/references/agent-rules-lens.md

@@ -0,0 +1,14 @@
+### 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.