@tacuchi/agent-workflow-cli 25.6.1 → 25.8.0

package/skills/w/loops/CODE-POLICIES.md

@@ -1,9 +1,8 @@
 # CODE-POLICIES — policies for code-editing loops
 
 They apply to **`plan-exec-loop`** (per effective batch) and **`quick-loop`** (the single task;
-**proportional** gate): each reads this doc with the chassis, and no document loop loads it. These
-policies own the DB scripts-only, safe Git and closing-review invariants; code loops keep only a
-short inline floor for advisory hosts.
+**proportional** gate), read with the chassis. They own the DB scripts-only, safe Git and
+closing-review invariants.
 
 ## Safe git — verified branch + proposed commits
 
@@ -17,7 +16,7 @@ its internal phases in one reviewed commit, and no batch may co-mingle with anot
 
 Concurrent flows never share a working tree: a run declares its sources and takes an **isolation
 unit** in each before writing — a worktree on its own branch
-(`aw worktree ensure | list | release`), where branch and commits are read. An edit outside is
+(`aw worktree ensure | list | release`). An edit outside is
 blocked naming the command that gets one, and at close `aw worktree integrate` merges each into
 the source's work branch; a conflict is reported, routed to `aw fix-git --path`, never alone.
 
@@ -29,16 +28,22 @@ After validation and before commits, the whole execution-unit diff passes a **cl
 gate**: an effective batch in plan-exec, or the proportional task in quick. Early `Cerrar` uses the
 same gate before any pending commit.
 
-- **Independent re-read** of the diff (subagent or clean re-read — the engine's *independent verification*: it does not assume the implementation is correct; *only command output counts*).
+- **Independent re-read** of the diff — the engine's *independent verification*: it does not assume the implementation is correct; *only command output counts*. In `quick` a subagent reviewer is optional; `plan-exec` requires a distinct one (its Delta 5).
 - **Apply the installed ambient conventions** relevant to the touched stack (code/stack standards, security, diff review, the workspace's own families) — the host **auto-discovers them by `description`**. Workline **names and binds no** concrete conventions skill: **it creates the moment; the installed skills fill it** (that is why review is **not a role** — see [`../roles/README.md`](../roles/README.md)). With no convention skills installed → minimal generic checklist: SOLID/early-return, clear names, DRY, no silenced errors, no secrets/PII, parametrized SQL, no dead code, + the plan's `Validations` (if any).
 - **Minimality lens** (floor — holds with **no external skill**; chassis § *Minimality*): re-read the diff for over-building. Flag `delete` (dead/speculative code), `stdlib` (reinvented standard library), `native` (a dep or code doing what the platform already does), `yagni` (one-implementation abstraction, config nobody sets, one-caller layer), `shrink` (same behavior, fewer lines). An installed ambient review skill *raises* this; it never lowers it.
 - **Test-value lens** (floor, next to minimality): every test the diff adds must demonstrate an observable behavior, protect a business rule, verify a contract, exercise a real integration or prevent a known regression. Flag `overtest` for the ones that only mirror structure — a test per class or method, mocked call chains, the same happy path re-asserted at every layer, trivial getters/setters/mappers, cases written for coverage, broad snapshots where a functional assertion is clearer. Bounded by *Gate integrity*: `overtest` prunes redundancy, **never** a check that guards behavior, a trust boundary, security or accessibility.
 - **Temporary simulation check** (only when the change carries one): stubs, fakes and in-memory adapters are **explicit and named as such** (`Stub…` / `Fake…`), they sit at the boundary the plan declares, and no configuration can select them in a production runtime. A simulation still active on the main path with no declared removal is a finding, not a detail.
-- **Tooling check** (`docs/tools`): did the run create **reusable auxiliary tooling** (support scripts/CLIs/generators/reusable configs — not product code, not session probes)? → the host applies the **ambient `creating-tools` skill** (auto-discovered by its `description`; Workline does not bind it) so the tool gets its home under `docs/tools/<slug>/` (README + run/output structure per that skill's contract + its index row). Host without such a skill → the loop still **never writes `docs/tools` itself**: **declare the gap** — the homeless tool goes to the plan's `Open questions` + `BACKLOG` (in quick, `BACKLOG`) — never silent.
+- **Tooling check** (`docs/tools`): did the run create **reusable auxiliary tooling** (support scripts/CLIs/generators/reusable configs — not product code, not session probes)? → the host applies the **ambient `creating-tools` skill** (auto-discovered; Workline does not bind it), which homes it under `docs/tools/<slug>/` per its contract. Host without such a skill → the loop still **never writes `docs/tools` itself**: **declare the gap** — the homeless tool goes to the plan's `Open questions` + `BACKLOG` (in quick, `BACKLOG`) — never silent.
 - **Findings**: **fix** them in the working tree and **re-run validation** (the gate does not replace the tests: it re-verifies after fixing), or **defer them justified** (→ the plan's `Open questions` + `BACKLOG`; in quick, `BACKLOG`); the non-obvious → `DECISION`. Gate integrity (see [`CHASSIS.md`](CHASSIS.md) § *Verification-first*): never weaken a check or lower a convention to pass.
 - **Artifact-first + verification-first**: seed `CHECKPOINT.Next = "review <batch/task>"`; Success
   criteria require the whole diff to pass before commits.
 
+**Close first, follow up on demand.** Before the commit only the validations and this review run;
+nothing waits on exploration. After commit and integration the report offers a parallel follow-up
+that probes what was delivered, in one line. It runs only if the user asks; its agents never modify
+the delivered work nor commit. Each finding comes back as a ready `/w:quick`, without reopening the
+closed document or session. A host without subagents runs it inline.
+
 ## Conditional modules
 
 - `db` — the DB scripts-only rule → `../modules/DB-SCRIPTS-ONLY.md`

package/skills/w/loops/plan-exec-loop/LOOP.md

@@ -46,13 +46,9 @@ inference, the deferred-validation cycle and conditional Git authorization.
 
 `git` (safe branch + proposed commits). `plan-exec` does **not** load `external-data`: its proof comes from the acquired checkout only. SQL fixture/ephemeral tests are ordinary local commands; remote MCP reads belong to earlier research, never this loop.
 
-> **Ambient conventions (not roles):** code/testing/writing standards and `creating-tools` are standalone skills the host auto-discovers by `description` — Workline neither binds nor depends on them. Full doctrine: [../../roles/README.md](../../roles/README.md).
-
 ## Internal sessions (managed)
 
-- **plan-exec session** descriptor `<slug>-plan-exec` → `NNN-<slug>-plan-exec` (the `<slug>` comes from the input plan-doc `docs/plans/PPP-plan-<slug>.md`): **a single session per run** (Type = `exec`). Owns the run; holds `SESSION` + `CHECKPOINT` + `DECISION` + `SCRIPTS.sql` (+ `BACKLOG` only if something is deferred). Research is **inline** inside this session: it produces `ANALYSIS-FILE`/`CONCLUSIONS` (+ read-only `SCRIPTS.sql` if it queries DB) in its own folder.
-
-> **Numbering**: the caller passes only the descriptor; the CLI prepends the global sequential `NNN` over `.workflow/sessions/` (see chassis). It never restarts per type.
+- **plan-exec session** descriptor `<slug>-plan-exec` → `NNN-<slug>-plan-exec` (the `<slug>` comes from the input plan-doc `docs/plans/PPP-plan-<slug>.md`): **a single session per run** (Type = `exec`). Owns the run; holds `SESSION` + `CHECKPOINT` + `DECISION` + `SCRIPTS.sql` (+ `BACKLOG` only if something is deferred). Research runs inside this session and produces `ANALYSIS-FILE`/`CONCLUSIONS` (+ read-only `SCRIPTS.sql` if it queries DB) in its own folder.
 
 > **Compat (legacy):** old workspaces may hold `plan-exec-phase-*` sessions (one per phase) and `*-research-*` ones — historical, left as-is; new runs use a single session.
 
@@ -243,10 +239,14 @@ adds nothing of its own beyond running on a verified branch and never
 
 ## Delta 5 — Closing review gate (conventions, pre-commit)
 
-Full gate in [`../CODE-POLICIES.md`](../CODE-POLICIES.md): independent re-read, ambient
-conventions and the floor lenses. It covers the execution unit's **whole** diff after every phase
-proof/check and before states or Git advance. Findings are fixed and the affected checks rerun, or
-deferred with justification when they are not blockers.
+Full gate in [`../CODE-POLICIES.md`](../CODE-POLICIES.md). It covers the execution unit's **whole**
+diff after every phase proof/check and before states or Git advance. Findings are fixed and the
+affected checks rerun, or deferred with justification when they are not blockers.
+
+**Distinct reviewer (hard rule).** Every batch close is reviewed by a reviewer other than its
+author: neither whoever wrote the diff nor any of its implementers. The round that fixes its
+findings goes back, before the commit, to a reviewer who wrote neither the diff nor the fix. A host
+without subagents runs a clean re-read instead, and the closing report declares it.
 
 ## Delta 6 — Completion / close
 

package/skills/w/modules/COMPACTION.md

@@ -4,6 +4,6 @@ Loaded when the run is long enough that context pressure governs its pacing (sig
 
 `Compactar` is not only reactive: the loop **watches its own context pressure** and raises compaction itself. Recognizing that pressure is judgment — the host's signal where it exists (*compaction* capability in [`../harness/HARNESS.md`](../harness/HARNESS.md)), otherwise the **qualitative** question *"would a fresh reader need the CHECKPOINT to continue?"* at a boundary of an already-long run. Doctrine fixes **no numeric thresholds**: a number that means anything is a number about one host.
 
-> **Whether the host can honour it is not this document's call:** `aw checkpoint-write` writes the CHECKPOINT and **never holds the compaction back** — there is no configurable mode; an ambiguity degrades and parks a refuge checkpoint to adopt later. **CHECKPOINT before compacting** is the invariant. What this document keeps is why: consent lives in the `Compactar` control a person ratifies, and a compaction that fires before the checkpoint loses the thread it was meant to protect.
+> **Whether the host can honour it is not this document's call:** `aw checkpoint-write` with `--code <NNN>` writes the CHECKPOINT and **never holds the compaction back** — no configurable mode; unresolved, it parks a refuge checkpoint to adopt later. **CHECKPOINT before compacting** is the invariant. What this document keeps is why: consent lives in the `Compactar` control a person ratifies, and a compaction that fires before the checkpoint loses the thread it was meant to protect.
 
 > **`Compactar`** (the `flow` control) → write `CHECKPOINT.md` in the session (in-flight progress, remaining gaps, Q&A, `attempts`) → trigger the harness **compaction** (Claude Code: `/compact`; see [`../harness/HARNESS.md`](../harness/HARNESS.md)) → resume by reading the checkpoint.

package/skills/w/roles/design/CONTRACT.md

@@ -12,11 +12,18 @@ This file is what a person or a loop reads.
 
 ```
 aw capability prepare  --capability design --operation <op> [--input k=v ...]
-aw capability continue                                       # stdin: {"parent": <request>}
-aw capability validate                                       # stdin: {"request": …, "answer": …}
-aw capability apply --approval <digest>                      # stdin: {"request": …, "plan": …}
+aw capability continue --capability design --operation <op> [--input k=v ...] # stdin: {"parent": <request>}
+aw capability validate --capability design --operation <op> [--input k=v ...] # stdin: {"request": …, "answer": …}
+aw capability apply --capability design --operation <op> [--input k=v ...] --approval <plan.proposal.digest> # stdin: {"request": …, "plan": …, "pin": …}
 ```
 
+Repeat the same `--capability`, `--operation`, every `--input` and
+`--consumer-document` (if used) at each stage. Carry the response as one JSON
+object on stdin; `prepare` reads no stdin and `pin` is optional. Approval is the
+digest of `plan.proposal.digest`. Read `aw capability --help` for the full envelope.
+Shared wrappers have no host binding: if `aw harness` returns `unknown`, pass
+`--host <id>` at every stage.
+
 The verbs are **stages**, never operations: the operation travels in the
 envelope. Every attempt returns `outcome`, `output` and `receipt`. A
 `needs_input` is answered with `continue`, which builds the NEXT attempt of the