@multileaf/ai-workflow 0.8.0 → 0.10.0

package/docs/opportunities/README.md

@@ -0,0 +1,33 @@
+# Workflow Proportionality Opportunities
+
+Improvement opportunities derived from the analysis of Gentle-AI's ODD/RDD methodology (Organic Driven Development and Receipt-Driven Development), recorded in [ADR-001](../../.context/adrs/ADR-001-odd-rdd-proportionality-scope.md). Each document is self-contained: problem, source concept with references, proposal, affected areas, acceptance criteria, non-goals, and open questions — so any single opportunity can be picked up without reconstructing the original analysis.
+
+The guiding principle: **ceremony should scale with the consequence of the change, not be constant.**
+
+| ID                                                                                              | Opportunity                                                                         | Priority | Depends on                            |
+| ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | -------- | ------------------------------------- |
+| [OPP-001](OPP-001-proportional-ceremony-light-lane.md)                                          | Proportional ceremony — light lane for small, understood work                       | P2       | OPP-002 (advisory signal, optional)   |
+| [OPP-002](OPP-002-risk-assess-command.md)                                                       | `aiw risk assess` — content-based risk classification with exact next command       | P2       | —                                     |
+| [OPP-003](OPP-003-adversarial-review-package.md)                                                | Adversarial review package — blind judges and proof-carrying findings               | P3       | —                                     |
+| [OPP-004](OPP-004-exact-continuation-commands.md)                                               | Exact continuation commands — every block names a runnable way out                  | P1       | —                                     |
+| [OPP-005](OPP-005-friction-benchmark.md)                                                        | Friction benchmark — measure how users get stuck (in-band / out-of-band / dead-end) | P3       | OPP-004                               |
+| [OPP-006](OPP-006-emission-usability-test-policy.md)                                            | Emission ≠ usability — test that named commands actually work                       | P2       | OPP-004 (shared contract)             |
+| [007-decision-findings-triage-scope-watch](OPP-007-decision-findings-triage-scope-watch.md)     | Decision model — findings-evidence triage and lane scope-watch (advisory-only)      | P3       | OPP-001, OPP-003 (integration points) |
+| [008-embedding-covering-tests-judge-context](OPP-008-embedding-covering-tests-judge-context.md) | Embedding retrieval — covering-test detection and judge context scoping             | P3       | OPP-002, OPP-003 (integration points) |
+
+Suggested starting order: **OPP-004 → OPP-002 → OPP-006 → OPP-001 → OPP-005 → OPP-003** (smallest/least invasive first; OPP-004's reason codes feed OPP-005 and OPP-006).
+
+OPP-007 and OPP-008 are **model-integration addenda**: deliberately left for after field exposure — their priority should be set by real usage pain, not speculation. All model features respect the spec's NFR contracts: deterministic floor first, models advisory-only, unconfigured = byte-identical offline behavior.
+
+## Planning
+
+The implementation is planned as six waves in the project's own SDD format:
+
+- Specification: [`.aiw/generated/specs/odd-rdd-proportionality.md`](../../.aiw/generated/specs/odd-rdd-proportionality.md) (requirements REQ-OPP-001…006 with Given/When/Then criteria)
+- Implementation plan: [`.aiw/generated/plans/odd-rdd-proportionality.md`](../../.aiw/generated/plans/odd-rdd-proportionality.md) (TASK-001…010 with code, tests, validation, and evidence per task)
+
+## Source material
+
+- Gentle-AI repository: `Gentleman-Programming/gentle-ai` (v4, ODD mandatory protocol)
+- Key upstream docs: `docs/usage.md` (ODD protocol), `docs/review-integration.md` (RDD contract, `review assess`, stop reason codes, refuter probe), `docs/architecture/organic-rdd.md` (atomic review lifecycle), `docs/architecture/the-organic-rdd-story.md` (audit lessons, benchmark), `docs/review-authority-threat-model.md`
+- What was deliberately **not** adopted and why: see ADR-001, Decision B

package/docs/product-requirements.md

@@ -31,6 +31,9 @@
 - The product must support brainstorming, specification, design, planning, implementation, and verification stages.
 - Requirements, decisions, tasks, code changes, tests, and evidence must be traceable.
 - A task must not be considered complete without configured validation evidence.
+- Ceremony must scale with the consequence of the change: `aiw risk assess` classifies changes by content (read-only, deterministic); small, understood work may run in a human-chosen light lane that records evidence and rationale instead of durable artifacts, and escalates explicitly on scope growth.
+- Every blocking CLI exit must name a stable reason code and an exact runnable continuation, or state explicitly that no automatic continuation exists.
+- When the adversarial review skills are installed, review findings must carry proof: severe findings without a reproducing command or self-proving citations degrade to advisory, and only corroborated severe findings may block.
 
 ### Portability
 

package/docs/product-vision.md

@@ -17,6 +17,7 @@ AI coding tools often depend on implicit prompts, fragmented configuration, repe
 5. Project artifacts are English by default.
 6. Context is loaded just in time to control token cost.
 7. Unsafe capabilities require explicit permission.
+8. Ceremony scales with the consequence of the change — a documentation edit gets zero ceremony; two lines of authentication code get full review.
 
 ## Product outcomes
 

package/docs/quality.md

@@ -19,6 +19,16 @@ Red → Green → Refactor → Verify
 
 No feature is complete without tests for its happy path, invalid input, conflicts, and safe failure behavior.
 
+## Emission is not usability
+
+A test that verifies a message was emitted does not verify it is usable. Any user-facing message, gate output, skill instruction, or generated prompt that names an `aiw` command must be covered by a test that executes that command in the state the message describes and asserts it resolves or advances that state. Emission-only assertions are insufficient for messages that name commands.
+
+`src/command-evidence.ts` extracts command mentions from shipped artifacts; a ratchet test in `src/command-evidence.test.ts` executes every command named by the generated skills and the READMEs and fails when a named command is not real. Blocking continuations follow the stronger rule from [OPP-004](opportunities/OPP-004-exact-continuation-commands.md): a message may name a command only when running that command resolves the block it was printed for — verified by executing the printed continuation.
+
+## Friction budget
+
+`scripts/friction-bench.mjs` drives packaged-CLI journeys (happy paths and adversarial states) and classifies every non-success exit as in-band (the printed continuation, executed, resolves or advances the block), out-of-band (guidance without the typed reason contract), or dead end (the printed continuation fails and names no way out). The budget is **zero dead ends**; CI fails on any. Out-of-band is the honest baseline to shrink over time. Runs are deterministic; the release gate re-verifies the budget and determinism via `scripts/friction-bench.node-test.mjs`.
+
 ## Completion validation
 
 A feature is complete only when all affected layers are validated: domain, module integration, CLI or adapter integration, generated artifacts, end-to-end behavior, documentation, traceability, and security. Domain tests alone are insufficient for changes that affect external behavior or generated project state.

package/docs/release-process.md

@@ -2,6 +2,14 @@
 
 AI Workflow releases are reproducible, evidence-backed, and published only from a clean protected branch.
 
+## How a release ships
+
+1. A contributor opens a pull request with the changes, the version bump in `package.json`, and the dated `CHANGELOG.md` entry, and requests review.
+2. A maintainer reviews and merges the pull request into `main`.
+3. The `Auto-tag releases` workflow notices that the merged version has no `v<version>` tag yet, creates the tag on the merge commit, and the `Release` workflow takes over: it validates the tagged source and publishes with npm trusted publishing and provenance.
+
+No manual tagging and no environment approvals: merging an reviewed pull request with a version bump is the entire release action. Merges that do not bump the version are ignored by the auto-tag workflow.
+
 ## Preconditions
 
 - The release version follows Semantic Versioning and matches the intended Git tag.
@@ -24,7 +32,7 @@ Install the exact candidate tarball in a new temporary project and exercise at l
 
 ## Publication
 
-After human review of the package contents and legal license, create and push a signed version tag. The release workflow validates the exact tagged source and publishes with npm trusted publishing and provenance:
+After human review of the pull request, the auto-tag workflow creates the version tag on the merge commit (the manual equivalent, if ever needed, is `git tag v<version> && git push origin v<version>`). The release workflow validates the exact tagged source and publishes with npm trusted publishing and provenance:
 
 ```bash
 git tag -s v0.1.0 -m "AI Workflow v0.1.0"

package/docs/semantic-mapping.md

@@ -66,3 +66,7 @@ When semantic mapping is enabled and a valid index built with the active model e
 3. Everything else is excluded, so measured token usage decreases while inferred-fact evidence still points at real scoped files.
 
 Without semantic mapping (or when the index is missing, built with another model, or the embedding model is unavailable), the interpreter keeps the previous deterministic alphabetical scoping and scans make no network request for scoping purposes.
+
+## Planned integration (OPP-008)
+
+The next planned retrieval consumers follow the same contracts: covering-test detection for `aiw risk assess` (a semantic hit prevents a false `untested_regression` flag; absence fails safe toward `high`) and judge context scoping for the adversarial review skills (bounded retrieved chunks labeled as context aids). Deterministic fallbacks are unchanged; unconfigured behavior is byte-identical. See [OPP-008](opportunities/OPP-008-embedding-covering-tests-judge-context.md).

package/docs/token-efficiency.md

@@ -83,6 +83,59 @@ Every entry carries `measured` or `estimated`, and aggregates propagate the labe
 
 `aiw scan` auto-records sidecar entries for interpreter and embedding usage with their real measurement label, so the ledger fills without manual effort.
 
+### Importing harness session logs
+
+`aiw usage-sidecar import` turns local harness session logs into measured entries — the same lifecycle coverage as the manual `record`, without friction. Formats were validated against real logs:
+
+```bash
+aiw usage-sidecar import --from=claude-code   # ~/.claude/projects/<this-project>
+aiw usage-sidecar import --from=codex         # ~/.codex/sessions (sessions scoped by cwd)
+aiw usage-sidecar import --from=gemini        # ~/.gemini/antigravity-cli/brain transcripts
+```
+
+- **Claude Code**: per-message usage with all four tiers (including cache), model and CLI version, deduplicated by message id.
+- **Codex**: `token_usage_record` entries; cached input is separated from fresh; sessions are scoped to this project via `session_meta.cwd`.
+- **Gemini**: planner responses with input/cache-read/output. Transcripts do not record a working directory, so Gemini imports cannot be scoped per project (the command says so).
+
+Import is idempotent: every event derives a stable identity (`import.<source>.<hash>`) and already-present events are skipped, so reruns never double-count. Entries land with label `measured` and full harness attribution. Cursor and GitHub Copilot remain outside this coverage: they do not expose per-request usage to the user, so for them the estimate stays the ceiling.
+
+## Session heartbeat (cache-TTL management)
+
+Provider prompt caches expire on a TTL (typically 5 minutes); the cost lands when a session is resumed after expiry, because the next request rebuilds the whole prefix at full input price. Keeping a cache alive with provider pings has its own economics and AIW is not in the call path — but the gap can be measured for free on every event:
+
+```bash
+aiw hooks install --target=claude-code   # wires Stop + UserPromptSubmit to `aiw heartbeat`
+aiw heartbeat --session=<id>              # what the hooks call; also accepts hook JSON on stdin
+```
+
+Each beat measures the gap since the previous one and decides:
+
+- gap < warn (default 4 min): active session, nothing to do;
+- warn ≤ gap < TTL: the cache is still warm (this request just read it at cache price) — a compact checkpoint is saved now, so an idle past the TTL resumes cheap;
+- gap ≥ TTL: the cache expired and this request paid the rebuild — a compact checkpoint is saved so the _next_ gap hurts an order of magnitude less.
+
+No timers and no keep-alive pings: the decision always happens on the next beat, which costs nothing locally. The guarantee is that a session never pays the full-price prefix rebuild twice in a row on the same context. Thresholds are configurable (`--warn=seconds --ttl=seconds`), state lives in `.aiw/heartbeats.yml`, and every action writes an inspectable checkpoint under `.aiw/checkpoints/`. Hook installers are project-scoped, merge without touching foreign hook entries, and are idempotent; Codex (`notify`) and Gemini (`hooks.json`) adapters follow the same command.
+
+## Harness support matrix
+
+AI Workflow's core — the SDD workflow, quality and cost gates, token ledger, cost attribution, task-lifecycle usage, and routing — is harness-agnostic and behaves identically everywhere. What varies per harness is the edge: measured log import and live beats. The matrix declares exactly what is and is not available, because silent degradation is worse than an explicit limitation.
+
+| Capability                                      | Pi                                                               | Claude Code                          | Codex                                | Gemini                              | Cursor                     | Copilot CLI                |
+| ----------------------------------------------- | ---------------------------------------------------------------- | ------------------------------------ | ------------------------------------ | ----------------------------------- | -------------------------- | -------------------------- |
+| Neutral core (gates, ledger, reports, routing)  | ✅                                                               | ✅                                   | ✅                                   | ✅                                  | ✅                         | ✅                         |
+| Manual usage recording (`usage-sidecar record`) | ✅                                                               | ✅                                   | ✅                                   | ✅                                  | ✅                         | ✅                         |
+| Measured log import                             | ✅ all four tiers + provider per message, project-scoped         | ✅ all four tiers + model            | ✅ four tiers, project-scoped by cwd | ✅ three tiers, no project scoping  | ⚠️ local database, fragile | ❌ estimate is the ceiling |
+| Live beats (heartbeat)                          | ✅✅ extensions run in-process (event handlers, commands, tools) | ✅ hooks (Stop, UserPromptSubmit, …) | ⚠️ `notify` per turn                 | ✅ hooks (Pre/PostInvocation, Stop) | ⚠️ limited                 | ❌                         |
+| Multi-provider sessions                         | ✅ provider recorded per message                                 | —                                    | —                                    | —                                   | —                          | —                          |
+
+**Recommendation: use [Pi](https://pi.dev) for the best experience.** It is the only harness where every capability is native: per-message usage with all four billing tiers _and_ the provider, sessions grouped by project, compaction recorded with token counts, and an in-process extension API rich enough that AI Workflow can eventually run inside the harness itself. Claude Code is the strongest alternative; Codex and Gemini cover measurement fully with partial beat granularity. Where a capability is missing, AI Workflow degrades honestly: manual recording with `estimated` labels, and explicit errors instead of silent gaps.
+
+Notes:
+
+- Codex beats fire per turn (`notify`), not per event — enough for gap detection, coarser than Claude Code or Pi.
+- Gemini transcripts do not record a working directory, so their imports cover all sessions on the machine.
+- Cursor and Copilot do not expose per-request usage to the user; for them the estimate stays the ceiling, and every number derived from their sessions carries the `estimated` label.
+
 ## Cost per verified requirement
 
 `aiw cost-report` joins the usage sidecar with the traceability graph to produce the outcome-denominated cost metric — tokens per verified requirement, where verified means the graph links the requirement to evidence:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@multileaf/ai-workflow",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Portable spec-driven development workflow for AI coding agents",
   "license": "MIT",
   "repository": {

package/resources/package.yaml

@@ -32,6 +32,9 @@ resources:
     - { id: prisma-data-access, version: 0.1.0, path: skills/prisma-data-access.md }
     - { id: vite-frontend, version: 0.1.0, path: skills/vite-frontend.md }
     - { id: ticket, version: 0.1.0, path: skills/ticket.md }
+    - { id: review-judge-a, version: 0.1.0, path: skills/review-judge-a.md }
+    - { id: review-judge-b, version: 0.1.0, path: skills/review-judge-b.md }
+    - { id: review-refuter, version: 0.1.0, path: skills/review-refuter.md }
   rules:
     - { id: language-policy, version: 0.1.0, path: rules/language-policy.md }
     - { id: tdd-policy, version: 0.1.0, path: rules/tdd-policy.md }

package/resources/skills/code-review.md

@@ -9,4 +9,6 @@ For every approval, rejection, or optional skip, use the host's native blocking
 
 Review behavior, boundaries, cohesion, naming, types, error handling, duplication, complexity, tests, and documentation. Prioritize actionable findings with severity and evidence.
 
+When the adversarial review skills are installed, run the stronger protocol: two blind judges (`review-judge-a`, `review-judge-b`) review the same diff independently, then `review-refuter` attempts to refute every severe finding — only corroborated severe findings may block, unevidenced ones degrade to advisory, and verdicts carry proof references. Attribute each judge's findings separately in the report.
+
 Write `.aiw/generated/reports/code-review.md` with the scope, findings (including an explicit `None` when clear), checks, residual risks, and decision. Run `aiw gate review`, present the exact report, and ask whether to address findings or accept the residual risk. Stop and wait for an explicit decision. Only after approval, record it with `aiw approve review`; do not start traceability before it succeeds. If changes are requested, first record `aiw reject review --reason=<feedback>`, return to implementation, and require verification and review again. Review completeness is an automated gate; it does not replace human approval. Invoke commands through `npx --yes --package=@multileaf/ai-workflow -- aiw <command>` when no global binary exists.

package/resources/skills/review-judge-a.md

@@ -0,0 +1,24 @@
+---
+name: review-judge-a
+description: First blind reviewer of an adversarial review — inspect the diff independently and report findings with required evidence.
+---
+
+# Review Judge A (blind)
+
+You are one of two independent reviewers. Review the change **without consulting any other review, judge output, or conversation summary about this change**: your value is independence. If another review's findings reach you, ignore them.
+
+## Procedure
+
+1. Read the exact change you are given (diff or files with line numbers). Do not assume intent beyond what the change and its cited request context state.
+2. Inspect the code paths the change touches, including callers of changed exports where visible in the repository.
+3. Report every finding with: severity (`BLOCKER`, `CRITICAL`, `MAJOR`, `MINOR`), `file:line` evidence, and a one-line reproducible statement of impact.
+
+## Finding rules
+
+- A `BLOCKER` or `CRITICAL` finding MUST include either a reproducing command (with its expected observed output) or exact `file:line` citations that prove the claim by themselves.
+- Findings you cannot evidence are `MINOR` questions, never `BLOCKER`.
+- State what you verified and what you did not check. A silent gap reads like coverage.
+
+## Output
+
+Emit a numbered findings list (severity, evidence, impact) and a final line: `Inspection complete: <files/paths examined>`.

package/resources/skills/review-judge-b.md

@@ -0,0 +1,24 @@
+---
+name: review-judge-b
+description: Second blind reviewer of an adversarial review — a fresh, independent pass over the same diff with separately attributable findings.
+---
+
+# Review Judge B (blind)
+
+You are the second independent reviewer. Your pass must be fresh: **do not read, request, or rely on the first judge's findings** or any summary that mixes them. Disagreement between blind reviewers is signal, not noise.
+
+## Procedure
+
+1. Re-derive the review from the change itself (diff or files with line numbers) and the cited request context.
+2. Deliberately vary your reading order from the obvious one (entry points last, or tests first) so the two passes do not share a blind spot.
+3. Report every finding with: severity (`BLOCKER`, `CRITICAL`, `MAJOR`, `MINOR`), `file:line` evidence, and a one-line reproducible statement of impact.
+
+## Finding rules
+
+- A `BLOCKER` or `CRITICAL` finding MUST include either a reproducing command (with its expected observed output) or exact `file:line` citations that prove the claim by themselves.
+- Findings you cannot evidence are `MINOR` questions, never `BLOCKER`.
+- State what you verified and what you did not check.
+
+## Output
+
+Emit a numbered findings list (severity, evidence, impact) and a final line: `Inspection complete: <files/paths examined>`.

package/resources/skills/review-refuter.md

@@ -0,0 +1,28 @@
+---
+name: review-refuter
+description: Adversarial refuter for severe review findings — confirm or drop each claim with proof, degrading unevidenced severe findings to advisory.
+---
+
+# Review Refuter
+
+Your job is to **try to destroy severe findings**, not to defend them. For every `BLOCKER` or `CRITICAL` finding you receive, output one of three verdicts with proof references (`proof_refs`):
+
+- `corroborated` — the claim survives your refutation attempt;
+- `refuted` — you found concrete evidence the claim is wrong or cannot happen;
+- `inconclusive` — evidence is insufficient either way.
+
+## Command execution is a granted capability, never a default
+
+You may run a reproducing command **only when the user or host has explicitly granted command execution for this review**. In that case: run at most one reproducing command per claim, in an isolated disposable directory when the runtime provides one, with no network access, and cite the command and its observed output in `proof_refs`.
+
+When execution is **not** granted — the default — you work in evidence-reading mode: verify claims against the cited `file:line` content and repository state alone, and **append `no command executed` to every `proof_refs`** so the record never implies verification that did not happen.
+
+## Degradation rule
+
+A severe finding with neither a reproducing command nor self-proving `file:line` evidence degrades to `advisory` with the reason recorded. Only `corroborated` severe findings may block; `refuted` findings become advisories; `inconclusive` findings go to the bounded correction discussion.
+
+## Bounds
+
+- Never refute a claim you were not given; one verdict per issued claim.
+- Pre-existing, base-only, or unknown-causality findings are not yours to drop: mark them `inconclusive` and pass them on.
+- A human still accepts the final review outcome; your verdicts are evidence, not approval.

package/resources/skills/ticket.md

@@ -9,6 +9,8 @@ For every approval or optional skip, use the host's native blocking question wid
 
 Use this skill when the user provides a ticket ID (for example `PROJ-142`) or an already-clear requirement and wants to start work immediately.
 
+Lane decision (light lane): before starting, apply the resume test — the work is small when it is understood, risk is contained, and it could be resumed from the request plus `git diff`. If it is, offer the light lane with the blocking widget ("Light lane" / "Full lane"). Only after an explicit human choice, start with `--lane=light --lane-reason=<the resume-test call, one line>`; never choose the light lane yourself. Light-lane work records validation evidence with `aiw task evidence --validation="<command and result>"` and completes with `aiw workflow complete`; if scope grows, escalate with `aiw task escalate --reason=<why>` instead of authoring stage artifacts.
+
 1. Extract the ticket ID and a short title from the user's request. Start the task with `npx --yes --package=@multileaf/ai-workflow -- aiw task start --ticket=<TICKET> --title="<short title>"` (add `--id=<uuid>` only if the user provides one). If a session is already active, report it with `aiw task status` and stop.
 2. Brainstorming decision: the ticket already provides the requirement, but skipping is still a human decision. Ask with the blocking widget whether to skip brainstorming ("Accept skip" / "Do not skip"). Only after an explicit acceptance, record it with `npx --yes --package=@multileaf/ai-workflow -- aiw skip brainstorming --reason="Requirement provided by ticket <TICKET>"`. If the user prefers to brainstorm after all, run the brainstorming skill instead.
 3. Create the specification linked to the ticket with `npx --yes --package=@multileaf/ai-workflow -- aiw spec --ticket=<TICKET> --title="<title>"`, fill in requirements with stable IDs and Given/When/Then acceptance criteria derived from the ticket, then pass `aiw gate specification`, present the artifact, wait, and record the human reply with `aiw approve specification` (or `aiw reject specification --reason=<feedback>` and revise).