@sabaiway/agent-workflow-engine 1.14.1 → 1.16.0

package/CHANGELOG.md

@@ -4,6 +4,40 @@ 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.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
+`autonomy-slot.md` fragment to the install base — the third AGENTS.md `workflow:autonomy` slot
+finally fills everywhere, so the kit's `ENGINE_FRAGMENT_CAVEATS` soft-skip residual retires on
+refresh. Canon additions, appended without renumbering: orchestration.md trailing **§7
+Checkpoint-bounded autonomy** (sandbox-as-floor, red-lines always-ask, informational for delegated
+backends — enforcement stays the OS sandbox + the orchestrator); planning.md trailing **§10**
+(autonomy at plan/execution checkpoints); procedures.md gains the read-at-start clause beside its
+preamble. orchestration.md §5 gains the sandbox cost-lane token (sandbox-safe L0 surfaces ·
+genuinely-unsandboxed bridge wrappers · command-shape-dependent npm-cache commands; move only the
+failing command out of the sandbox, batch consecutive unsandboxed calls) — parity-pinned on both
+the engine and kit sides.
+
 ## 1.14.1 — npm 12 tarball-guard compat + the lineage-head preamble correction
 
 A **patch** release (no canon content change; co-released with memory 2.0.0 + kit 1.42.0 — the

package/README.md

@@ -51,6 +51,10 @@ the canonical methodology reference on disk:
 - [`references/orchestration-slot.md`](references/orchestration-slot.md) — the **bounded** one-line
   orchestration fragment the composition root injects into a deployed `AGENTS.md`, routing to the
   in-project recipes surface.
+- [`references/autonomy-slot.md`](references/autonomy-slot.md) — the **bounded** one-line autonomy
+  fragment the composition root injects into a deployed `AGENTS.md`: the cross-agent read contract
+  for `docs/ai/autonomy.json` (read at session start; the canonical default floor when absent; STOP
+  on malformed), routing to the in-project `set-autonomy` / `autonomy-doctor` surfaces.
 - [`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>`.

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.14.1'
+  version: '1.16.0'
 ---
 
 # agent-workflow-engine
@@ -34,6 +34,14 @@ slot fill is needed but the engine is absent, the kit's reconcile **fails loudly
   orchestration fragment the composition root injects into a deployed `AGENTS.md`, between the
   `<!-- workflow:orchestration:start -->` / `<!-- workflow:orchestration:end -->` markers. It names the
   four recipes and routes to `/agent-workflow-kit recipes`, never to this engine-internal reference.
+- [`references/autonomy-slot.md`](references/autonomy-slot.md) — the **bounded** one-line autonomy
+  fragment the composition root injects into a deployed `AGENTS.md`, between the
+  `<!-- workflow:autonomy:start -->` / `<!-- workflow:autonomy:end -->` markers. It carries the
+  cross-agent READ CONTRACT for the per-project autonomy policy (`docs/ai/autonomy.json`): read at
+  session start, the canonical default floor when the file is absent, STOP on malformed — plus the
+  honesty note that the policy is informational for delegated backends (enforcement stays the OS
+  sandbox + the orchestrator). It routes to the kit's `set-autonomy` / `autonomy-doctor` surfaces,
+  never to any engine-internal reference.
 - [`references/procedures.md`](references/procedures.md) — the canonical **activity-procedures** canon:
   the ordered steps of the named activities (`plan-authoring`, `plan-execution`) with **typed recipe
   slots** that bind to the orchestration recipes, composing with `planning.md` without restating it. It

package/capability.json

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

package/package.json

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

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.

package/references/autonomy-slot.md

@@ -0,0 +1 @@
+> **Autonomy policy** — checkpoint-bounded autonomy, declared per project in `docs/ai/autonomy.json` (red-lines + a per-activity level: `sandbox` or `prompt`). Read it at session start. File absent → the computed defaults ARE the policy: commit/push/publish `ask`; network/credentials/fs-outside-repo `deny`; an absent activity floors at `prompt`. Malformed → STOP loudly, never guess. Set it with `/agent-workflow-kit set-autonomy` (previews first; hand-edit stays supported); provision the OS sandbox with `/agent-workflow-kit autonomy-doctor` (consent-gated). For delegated backends this policy is informational — enforcement stays the OS sandbox + the orchestrator process.

package/references/orchestration.md

@@ -131,6 +131,32 @@ 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. 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.
+
 **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 —
 frontier re-derivation of recoverable state is the expensive failure mode, and the maintainer
@@ -156,3 +182,20 @@ default; it **never executes** a recipe and **never runs a subscription CLI**. T
 executes the chosen recipe through the bridge skills, accepts or rejects every edit, runs the
 verification gate, and makes the **one** commit — exactly as the plan lifecycle (`planning.md`)
 requires.
+
+## 7. Checkpoint-bounded autonomy (the policy every recipe runs under)
+
+Autonomy is **checkpoint-bounded**: between human checkpoints the orchestrator runs as autonomously
+as the project declares, and the checkpoints themselves never move. The policy is declared per
+project in `docs/ai/autonomy.json` — **red-lines** (always in force: `commit`/`push`/`publish` ask;
+`network`/`credentials`/`fs_outside_repo` deny) plus a **per-activity autonomy level**: `sandbox`
+(the OS sandbox confines and auto-allows confined commands — work runs to the next checkpoint
+without per-command prompts) or `prompt` (every non-allowlisted command prompts; the sandbox, where
+enabled, still confines). **Read it at session start.** An **absent** file means the computed
+defaults ARE the policy (every activity floors at `prompt`); a **malformed** file is a loud STOP —
+never guess around it. The **sandbox is the floor, not the permission**: red-line commands keep
+their asks at every level, and cost tiering (§5) never touches an approval gate. For **delegated
+backends the policy is informational** — enforcement stays the OS sandbox plus the orchestrator
+process (a backend never gains autonomy the orchestrator itself does not have). Declare and edit
+the policy with `/agent-workflow-kit set-autonomy` (previews first; hand-editing stays supported);
+render it into the harness settings with the kit's velocity `--autonomy` mode.

package/references/planning.md

@@ -134,3 +134,18 @@ 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.
+
+## 10. Autonomy at the plan checkpoints
+
+The plan lifecycle's human checkpoints — plan **approval** (plan-authoring ends there), each
+**gated commit** (plan-execution commits per Step), and any push/publish ask — are **fixed points
+the autonomy policy never moves** (`orchestration.md` §7). What the per-activity level changes is
+the texture *between* them: under `sandbox` autonomy the executor runs a whole working stretch —
+edits, tests, gates, review dispatches — to the next checkpoint without per-command prompts (the
+OS sandbox confines the blast radius); under `prompt` it asks along the way. **Read the policy at
+session start** (`docs/ai/autonomy.json`; absent → the computed defaults ARE the policy; malformed
+→ STOP loudly) alongside the standing recipe preference, and state the effective level in the
+session's opening summary so the human knows which texture to expect. A plan itself never needs to
+restate the policy — it is per-project configuration, not plan content; a plan names an autonomy
+requirement only when a Step genuinely departs from the declared level (e.g. a consent-gated
+privileged install), and that departure is always an explicit ask, never a silent widening.

package/references/procedures.md

@@ -28,6 +28,11 @@ single project's stages.
 project's standing recipe preference in `docs/ai/orchestration.json` (set it in plain language with
 `/agent-workflow-kit set-recipe` — it previews then writes; hand-editing the file stays supported); the
 kit resolves it against backend readiness. Do not re-ask each session what is already configured there.
+Read the **autonomy policy** the same way and at the same moment: `docs/ai/autonomy.json` declares the
+red-lines and the per-activity autonomy level (absent → the computed defaults ARE the policy; malformed
+→ STOP loudly, never guess; set it with `/agent-workflow-kit set-autonomy`) — the per-activity
+procedures below run UNDER that policy (`orchestration.md` §7), and the kit's `procedures` advisor
+prints the resolved level beside each activity's recipes.
 
 **Communication contract.** Every user-facing message delivers the artifact **inline** — the plan, the
 next-session prompt, the diff, the value asked for — never a bare pointer ("see §X / open the file") as a