@sabaiway/agent-workflow-engine 1.15.0 → 1.17.0

package/CHANGELOG.md

@@ -4,6 +4,41 @@ 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 `2.0.0`).
 
+## 1.17.0 — Prompt-economy canon gains a writer-batch clause + two sandbox-lane sentences (REPORT-FACTS train D5/D6, AD-054)
+
+A **feature** release (ships with kit 1.47.0 / memory 2.3.0 / bridges 2.7.0+2.6.0). The cost-lanes
+canon (`references/orchestration.md` §5) and the agent-rules lens gain:
+- **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. Rendered on all three prompt-economy surfaces (orchestration §5, the lens
+  fragment, the kit cost-lanes advisor), the lens re-rendered into both templates, and the outgoing
+  lens body appended to the append-only prior store.
+- **Sandbox lanes** — two sentences under the sandbox-lanes block: (i) a **pre-dispatch host-diff**
+  (before the first dispatch of each bridge, diff its manifest `networkHosts` against the live sandbox
+  allow-list — a missing host is surfaced to the maintainer, never fired into a known prompt); (ii)
+  **nested-sandbox honesty** (a backend CLI shipping its own OS sandbox cannot run nested inside a
+  harness sandbox — route it outside on the OBSERVED failure, never a preemptive blanket).
+
+## 1.16.0 — Prompt-economy canon: the cost lanes learn autonomy-preserving dispatch (REC-UX-REWORK D7, AD-053)
+
+A **feature** release (ships with kit 1.46.0 / memory 2.2.0). The cost-lanes canon
+(`references/orchestration.md` §5) gains the **prompt-economy clause**: (a) 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 (an invisible prompt-flood plus blast radius, not just
+tokens), and a subagent is never instructed to shell out for facts obtainable read-only; (b) the
+orchestrator's own shell form is ONE plain pipeline per call (a `;`/`&&` chain or env-prefixed
+invocation never matches a prefix allow rule); (c) a fan-out LAUNCHER that gates per call yields to
+the agent-spawn lane — **capability-gated**: without restricted-tool vehicles (a host offering only
+full-tool agents included), read-only research stays in the orchestrator's own context, never a
+vehicle mandate a host cannot satisfy.
+The quality/speed guard rides in canon (the clause narrows TOOLS for read-only work only —
+judgment, code, synthesis stay at the frontier lane) with the honest limit stated (no deterministic
+gate classifies a dispatch — enforcement is canon at the point of use + placed vehicles + the retro
+loop). The `agent-rules-lens.md` cost-lanes line carries the same clause (the outgoing body is
+appended to the append-only prior store, so unmodified in-the-wild deployments converge on first
+touch); one distinctive token per invariant is drift-guarded on all three surfaces (canon · the kit
+advisor render · the lens).
+
 ## 1.15.0 — Canon autonomy prose + the sandbox cost-lane (AD-044 Plan 4)
 
 A **feature** release (ships with kit 1.45.0 / memory 2.1.0). This publish delivers the Plan-3

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

package/capability.json

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

package/package.json

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

@@ -77,3 +77,36 @@ 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.
+
+<!-- prior: 2026-07-12 (AD-053) → pre-prompt-economy outgoing — the fragment as of the D7 clause landing (provenance intro + cost lanes, no prompt-economy) -->
+### 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.
+
+
+<!-- prior: 2026-07-13 (AD-054) → pre-writer-economy outgoing — the fragment as of the writer-batch clause landing (provenance intro + cost lanes + prompt-economy, no writer-economy) -->
+### 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.

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.
+- **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/orchestration.md

@@ -131,13 +131,39 @@ approval asks (commit / push / publish — cost tiering never touches approval g
 **Asymmetric pairing** is the default composition: the cheap lane drafts, a deterministic tool or
 the frontier verifies and signs — never the reverse.
 
+**Prompt economy (autonomy-preserving dispatch).** Under a zero-prompt autonomy bar the lanes also
+bound the TOOLS a dispatch may carry: **(a)** read-only fan-out — research, sweeps, extraction —
+runs ONLY on **restricted-tool vehicles** (read-only tools, no shell); handing a full-tool
+subagent to read-only work is a **forbidden lane downgrade** — an invisible prompt-flood plus
+blast radius, not just tokens — and a subagent is never instructed to run a shell command for
+facts obtainable read-only. **(b)** The orchestrator's own shell form: ONE plain pipeline per call
+— a `;`/`&&` chain or an env-prefixed invocation never matches a prefix allow rule, so each such
+call is a prompt. **(c)** A fan-out LAUNCHER tool may itself gate per call — under a
+zero-prompt bar prefer the agent-spawn lane with placed vehicles. This clause is
+**capability-gated** (route by what the host HAS): on a harness with restricted-tool subagent
+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
+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);
 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
 command out of the sandbox, never its class**, and **BATCH consecutive unsandboxed calls** — a
-blanket unsandbox after one failure is the canonical over-reaction.
+blanket unsandbox after one failure is the canonical over-reaction. **Pre-dispatch host-diff:**
+before the FIRST dispatch of each bridge, diff its manifest `networkHosts` against the live
+sandbox's allowed hosts — a missing host is surfaced to the maintainer BEFORE dispatching, never
+fired into a known prompt. **Nested-sandbox honesty:** a backend CLI that ships its OWN OS sandbox
+cannot run nested inside a harness sandbox — route it outside (an excluded command / a per-run
+consented bypass) on the OBSERVED failure, never a preemptive blanket.
 
 **Incident repair (your own error) defaults down-lane:** salvage recorded state first (journals,
 transcripts, git), replay it deterministically (L0), hand the leftovers to L1 in one batch —