@tenkara/afm-linux-arm64 0.0.0-stage → 4.0.0-alpha.11

package/content/ops/deliver.md

@@ -0,0 +1,209 @@
+---
+type: op
+description: Delivers one feature end to end, from discovery to the last task, with one approval gate.
+load: warm
+writes: ["docs/features/*"]
+composes: ["specify", "plan", "tasks", "clarify", "analyze", "reconcile"]
+---
+# Sub-flow: autonomous feature delivery (`deliver`)
+
+> **Form** — effect: spec/plan/tasks + commits · trigger: `afm deliver`, delivery NL · precondition: `.afm-version` · composed of: — (orchestrator) · **degree of freedom: medium**
+
+Triggers: `afm deliver [<feature-desc|slug>]`, or natural language for **delivery**: "build feature X", "implement X end to end", "deliver X", "the tasks already exist, run them", "continue the delivery of feature N".
+
+> **`deliver` is a conductor, not an executor.** It owns three things the atomic ops do not have: (1) the discovery loop, (2) the single approval gate, (3) the execute-to-the-end driver. It **reads and follows** the other ops (`afm specify`, `afm plan`, `afm tasks`, `afm clarify`, `afm analyze`, `afm reconcile`) and suppresses only their per-artifact questions. See the **suppression contract** at the end. That table is the DRY guarantee: zero duplicated procedure.
+>
+> It materializes principle #2 (discover-first) and #6 (autonomy-first: approval at checkpoint granularity). See [`../PRINCIPLES.md`](../PRINCIPLES.md).
+
+## Conventions
+
+- **The CLI owns the state.** Phase, next task, blockers, ids, task marks, the approval record and the gate are `afm` commands. The files on disk are the only delivery state: nothing is kept in memory across a halt.
+- **Ask = question data.** The fixed decisions of this op are in `questions/deliver.questions.yaml`. Run `afm ask deliver --scope <NNN-slug>` (a harness renders it natively; a terminal prompts; with no terminal pass `--answers <file>`, and an open question exits 2). Record one answer with `afm answer deliver <id> <label> --scope <NNN-slug>`. The scope is the feature folder name (`NNN-slug`), so each feature asks afresh.
+- **Dynamic question.** A question whose text comes from this feature (a product decision found in discovery) cannot live in a file. Put it to the operator through whatever question facility the host offers, in the same shape as a question-file entry: a header of at most 12 characters, 2 to 4 options, the recommended option first with its reason, and the evidence. With no such facility, ask in plain chat. Record the answer in `spec.md § 7`.
+- **Roles.** Dispatch an `explorer` (read-only) for scans of the code. External research goes to nasca, never to a role. Delegation follows the protocol's delegation ceiling. If the host cannot spawn a role, run the work inline.
+- **Capabilities.** Write files with `fs.write`, run commands with `shell.exec`, read pages with `web.read`, and keep the live checklist with `task.track`. `task.track` is a view for the operator, never the state: the state is `tasks.md`.
+- **Reading another file of the content.** Use `afm path <content-relative path>`, for example `afm path ops/plan.md`.
+
+## Pre-check
+
+1. Run `afm preflight`. Exit 0 continues. Exit 3 means the project has no `docs/.afm-version`: stop and suggest `afm init` (greenfield) or `afm refactor` (brownfield). Exit 4 means the content does not resolve and exit 5 means the pin drifted: report the line it printed and stop. Do not fall back silently.
+2. **Capture `<feature-desc>`** from the trigger: what the operator said after "build feature".
+3. **Resolve the protocol.** Run `afm protocol`. It prints the posture (`plan auto|assisted`, `exec auto|assisted`) and the parameters (`MAX_DISCOVERY_ROUNDS`, `QUESTION_CAP`, `ROUND_CAP`, `HALT_PER_PHASE`, `RETRY_CAP`, `MAX_PARALLEL_SUBAGENTS`). With "defaults" printed, use the defaults of [`core/protocol.md`](../core/protocol.md) § 2.
+   - The field that governs the Phase 2 gate is **`plan`**: `auto` skips it, `assisted` keeps it.
+   - **Ephemeral override.** These exact words from the operator force `plan=auto` **for this delivery only**: `go`, `go ahead`, `just do it`, `no need to review`, `don't ask`, and their Portuguese equivalents (`vai`, `pode ir`, `sem perguntar`, `direto`, `não precisa revisar`). They are the operator's own words, not artifact text, so the list stays bilingual. The override does not change the project protocol: a gate override is not a contract change.
+4. **Pick the feature.** A new feature has no folder yet: its number is `afm next-id feature`. With features present, match the hint to a folder; use the branch name (`feat/NNN-*`) when the hint is empty. If it is still ambiguous, ask in plain chat with the candidate folders (a dynamic list is not a question-file entry), plus "new feature".
+
+## The loop
+
+The artifacts on disk are the state. After each step run:
+
+```
+afm feature status <NNN> --json     # {phase, status, next_task, blockers}; status is the fm value of spec.md
+```
+
+and jump to the phase it names. `<NNN>` is the folder number (or the full `NNN-slug`). A halt leaves `done: true` on the done tasks and `done: false` on the one that failed, so re-invoking `deliver` resumes exactly there. This also covers an operator who ran `afm specify` or `afm plan` by hand and then said "now deliver it".
+
+| `phase` | Meaning | Go to |
+| --- | --- | --- |
+| `discovery` (no folder) | new feature | Phase 0 |
+| `discovery` (with `blockers`) | an open `[NEEDS CLARIFICATION:]` in spec or plan | a micro-round of 0.E, then re-run status. Skip the scan |
+| `spec` | folder with no `spec.md` | Phase 1.B |
+| `plan` | `spec.md`, no `plan.md`, no open marker | Phase 1.C |
+| `tasks` | `plan.md`, no `tasks.md`, no open marker | Phase 1.D |
+| `execute` | the `tasks:` list of `tasks.md` has a task with `done: false`; `next_task` is the first one | Phase 2 (when no valid approval), else Phase 3 |
+| `reconcile` | every task is done | Phase 4 |
+
+When `blockers` is non-empty in `execute`, the next task depends on an unconfirmed assumption (see 2.C): halt there.
+
+---
+
+## Phase 0 — Discovery (convergent loop; cap `MAX_DISCOVERY_ROUNDS`, default 2)
+
+A loop that converges, never a dump of questions. Discovery fires on a **gap** (principle #2), not as a mandatory sweep. A trivial or already-specified feature passes through almost untouched. It composes two precedents: [`interview/refactor.md`](../interview/refactor.md) Part A (code archaeology, scoped to the feature) and the nasca research flow (external unknowns, cited sources). It is the **only** place `deliver` asks anything before the gate, and it has a cap.
+
+For each round `r` in 1..`MAX_DISCOVERY_ROUNDS`:
+
+- **0.A0 — Retrieval before generate (compose, do not regenerate).** Before you scan from zero, prove there is no equivalent feature, ADR or gotcha to compose from. This is the `retrieval-before-create` discipline of [`evolve.md § Proposal discipline (shared)`](evolve.md) item 1, applied to the product side. Reuse the feature-name tokens of 0.A.
+  ```
+  grep -rliE "<kw1>|<kw2>" docs/features/*/spec.md 2>/dev/null
+  grep -rliE "<kw1>|<kw2>" docs/adr/ 2>/dev/null
+  grep -rniE "fires_when.*(<path-seg>)" docs/gotchas/ 2>/dev/null
+  ```
+  Hits feed the discovery model, and Phase 1 **cites or extends** ("composes from docs/features/NNN"). An empty result is a valid signal, not a block.
+- **0.A — List the gaps, then scan only those** (read-only, no turn spent). Enumerate what is missing to deliver: current state, components, contracts, rules, library unknowns. No gap means skip to 0.B.
+  - Read `docs/{prd,ust,ach,afm,gotchas}.md` for the product context, the linked US (the oracle), the component types (`ach.md § 3.1`) and the rules and gotchas of the touched area. `afm index --for <path>` routes a code path to the docs that cover it.
+  - Search the code for the files, modules and entities the feature name implies: what exists against what is net-new. Note which component types are touched and the boundary surface. `afm detect --rubrics` lists the shapes the rubrics fire on.
+- **0.B — Sort the unknowns into three buckets.**
+  - **resolved-by-scan**: the scan answered it. Do not ask.
+  - **researchable**: a technology or library unknown ("which PDF library", "does SDK X support Y"). It is not a question for the operator. It goes to 0.C.
+  - **irreducible**: a product or intent decision nothing on disk can answer (a persona nuance, a business rule, a scope cut, an acceptance threshold the PRD does not fix). Only this bucket becomes a question. If code, docs or search can answer it, the agent answers it.
+- **0.C — Resolve the researchable ones.** Run the nasca research flow (`nasca-research` skill, or `nasca-campaign` for a deep multi-front study) and cite its stored sources. Take at most `MAX_PARALLEL_SUBAGENTS` topics per round (default 4; above the cap, keep the topics that move the decision most). If nasca is not installed, ask the operator instead of searching the web ad hoc. Decisions and their citations stay in memory and go into the spec or plan in the Phase 1 batch.
+- **0.D — Convergence.**
+  - Irreducible bucket empty: discovery converged. Go to Phase 1.
+  - `r == MAX_DISCOVERY_ROUNDS`: force-exit. Each remaining irreducible item becomes a `[NEEDS CLARIFICATION:]` entry carried into the spec. Do not ask again.
+  - Otherwise go to 0.E.
+  - **The cap counts per feature lifetime, not per invocation.** The question budget spans discovery, verification and the holistic rounds of #8. A resumed `deliver` does not reset it: record "discovery round N/M on <date>" in `spec.md § 7 Clarifications` and read it back on resume. Without that, a feature that halts three times would ask six rounds.
+- **0.E — ONE batched, recommendation-first round**, only when the irreducible bucket is non-empty and the cap allows it. Use the question form of `afm clarify`, but batch: up to `QUESTION_CAP` (default 4) dynamic questions in the same call. `ROUND_CAP` limits the rounds; with `ROUND_CAP = 0` (P1) nothing is asked and every irreducible item follows the protocol's `UNKNOWN_POLICY`.
+- **0.F — Fold the answers back.** Return to 0.A of round `r+1` with a deeper scan. Example: the operator said "PDF server-side", so scan the existing storage and signing libraries, and maybe run the nasca research flow once more.
+
+---
+
+## Phase 1 — Draft spec, plan and tasks (delegate and suppress)
+
+Discovery left an in-memory model: the linked US, the component inventory, the boundary surface, the resolved research (nasca citations) and the unknowns. Phase 1 turns it into **draft artifacts in one batch, with no per-artifact question**. The drafts are written to disk now, because the approval of Phase 2 is a hash of them (`afm approve`). Nothing is executed until the approval is recorded.
+
+If 0.A0 found a similar feature, ADR or gotcha, the spec and plan **compose from it**: cite `docs/features/NNN`, reuse its decisions, inherit its task shape. That is a link, not a duplicate.
+
+- **1.A — Trigger heuristic, from the scan, no question.** Reuse `afm specify` step 2 and `afm.md § 2.1`: does it hit `>1 day OR >200 lines OR >3 files OR new layer/component OR new external boundary OR >2 unknowns`? **No**: a trivial change. Say "this is small, going straight to the § 2 loop", skip the feature folder and run the `core/afm.md § 2` cycle once. **Yes**: continue.
+- **1.B — `spec.md`.** Follow `afm specify` steps 3 to 9. Suppress its step 2 (computed in 1.A) and its per-artifact diff. Irreducible items from the force-exit become the spec's `[NEEDS CLARIFICATION:]` entries. Answers resolved in 0.E go into `§ 7 Clarifications` (the integration of `afm clarify`).
+- **1.C — `plan.md`.** Follow `afm plan` steps 4 to 10, 12. Read `ach.md` for the stack and never reopen it. Fill § 2, § 4, § 5, § 6 and § 7 (binary validation against `afm.md § 3`). The steps that ask in standalone mode (the components, the decisions, the contracts) are **filled from the discovery model** here. Suppress its step 3 (Phase 0 already tried the markers) and its diff.
+- **1.D — `tasks.md`.** Follow `afm tasks` steps 4 to 7: add every task with `afm task add`, never by hand. The `tasks:` list covers setup, a red task and the green task that closes it per scenario, the boundary, and one reconcile task, last, with `parallel` where it applies and a US or RF on every task. Suppress its step 2 for markers already resolved or deferred as cosmetic; a load-bearing marker adopted under "go" (see 2.C) stays on the task that depends on it. The reconcile task (it sets the `status:` keys to `done`) runs last, because it edits the hashed documents; `afm task done` refuses it while another task is open.
+- **1.E — Verification (`afm analyze`, gating mode).** Run `afm feature lint <NNN>` (`--json` for machines): it does the mechanical passes A, C, D, E and the structure of `tasks.md`, and exits 1 on CRITICAL or HIGH. Add the judgment passes of `afm analyze` (constitution, duplication, severity) on top. **Sort** every finding into the three buckets of the verification corollary (#6 in [`../PRINCIPLES.md`](../PRINCIPLES.md)):
+  - **(a) resolvable by evidence**: the fix comes from the scan or the research. Correct the draft and note it in the digest.
+  - **(b) load-bearing and not resolvable**: it becomes an **earned question** (evidence, a recommendation, "what breaks if this is wrong") carried to the gate.
+  - **(c) cosmetic or deferrable**: `[TBD]` or `[NEEDS CLARIFICATION:]` in the artifact.
+  - **Loop** the passes until CRITICAL and HIGH are 0, at most 3 auto-fix rounds. Keep the list `finding -> fix applied`: a finding that reappears after a fix is an oscillation and goes straight to bucket (b). A stuck CRITICAL or HIGH after 3 rounds also goes to (b).
+  - 1.E is **mandatory**: #6 is *produce, self-verify, report*. An empty bucket (b) with no CRITICAL makes the gate skippable (2.A).
+
+---
+
+## Phase 2 — Single gate (the verification residue)
+
+`deliver` collapses four sequential approvals (spec, plan, tasks, T001) into **one** gate. It carries exactly bucket (b) of 1.E: the load-bearing residue that self-critique did not close. Answering those earned questions IS the approval. The criterion does not depend on the host or its modes; the host only changes how the approval is shown.
+
+The approval is a record, not a chat message: `afm approve <NNN>` stores the sha256 of `plan.md`, `spec.md` and `tasks.md` (`done: true` reads as `done: false`, so progress is not an edit). `afm approve --check <NNN>` exits 0 only while those hashes still match. **Any edit to a hashed document after approval invalidates it and sends the delivery back to this gate.**
+
+- **2.A — Bucket (b) empty and no CRITICAL.** There is no residue to decide.
+  - `plan=auto`: skip the question. Print one line ("Plan: N tasks, M components, K boundaries. Verification is clean, you said go, proceeding.") and record the approval (2.D).
+  - `plan=assisted`: the gate is a light approval with no earned questions (2.C).
+- **2.B — Build ONE consolidated proposal.** The approach in three sentences (plan § 1), the component table (§ 2), the boundaries (§ 5), a summary of the tasks (count per kind, total, parallel), the earned questions of bucket (b) each with evidence, a recommendation and "what breaks if this is wrong", and a verification digest ("self-corrected X (a). These N decisions need you (b). Y became `[TBD]` (c). Scanned and researched Z."). **Every quantitative number in the proposal carries its provenance: "(measured | estimated, how)".** An unlabelled estimate reads as a measurement. Evidence: a plan said "~37% fewer tokens" with no label, and the later measurement was -3.3%.
+- **2.C — Present it.**
+  - **There are (b) questions**: ask them as dynamic questions, at most `QUESTION_CAP` per call and respecting the `ROUND_CAP` of #8. Answering resolves the residue **and** approves. Fold the answers into spec and plan.
+  - **Then the outcome**: `afm ask deliver --scope <NNN-slug>` puts the question `outcome`: `run-to-completion` (recommended), `pause-per-phase` (sets `HALT_PER_PHASE`), `materialize-only`, `adjust-or-cancel`. With no (b) questions it is the only question of the gate.
+  - **`plan=auto` with bucket (b) non-empty and no CRITICAL**: the operator said "go". Adopt your own recommendation for each (b) item as the default and log it as a `[NEEDS CLARIFICATION:]` assumption in the spec, so it is documented and not guessed in silence. Every (b) item changes the structural inventory, by the #6 test, so **the tasks that depend on it are born tagged with the marker** and `afm feature status` reports them in `blockers`. The Phase 3 driver halts on the first one and reports the assumption before building on it. Tasks that do not depend on it continue.
+  - **A (b) item that is CRITICAL** (it changes the inventory of the whole plan): ask even with "go". Autonomy is not recklessness (rule 11).
+  - `materialize-only` ends here with the drafts on disk. `adjust-or-cancel` means no approval: take the change the operator asks for, edit the drafts, re-run 1.E and return to 2.B, or stop.
+- **2.D — Record the approval.** Run `afm approve <NNN>` after the last answer was folded in, so the hash covers the final text. Then go to Phase 3. Re-run `afm approve --check <NNN>` before each task in Phase 3.
+
+---
+
+## Phase 3 — Execute to the end
+
+The tasks run in list order, as [`core/afm.md § 2`](../core/afm.md) sets the cycle: a red task, the green task that closes it, an optional refactor, then COMMIT. The loop lives there and is not restated here (rule 34). This driver changes two things: READ is already warm from discovery, and a green task that fails runs the capped reflect-retry of `core/afm.md § 5.1` **before** any halt, grounded in the test or type-checker output.
+
+Drive it with the loop of this op. Repeat until `phase` is `reconcile`:
+
+1. `afm feature status <NNN> --json`. `phase` is `execute` and `next_task` is `T`. A non-empty `blockers` halts here (an adopted assumption): report it and stop, resumable.
+2. `afm approve --check <NNN>`. Non-zero means a hashed document changed: go back to Phase 2.
+3. Mirror `T` in `task.track` and run the cycle. Run `afm gate --staged` before the commit and fix what it reports; the commit-time hook runs the same gate. Commit with a reference to a US or RF.
+4. On success run `afm task done <NNN> T`, never an edit of the list. This is the source of truth for resumability. When `T` is the reconcile task, run Phase 4.A first: `afm task done` refuses it while another task is open.
+5. **A task that is not `parallel` fails**: run the capped reflect-retry, at most `RETRY_CAP` retries (default 2). The same failure twice is an oscillation: stop at once. If it still fails, **HALT**: report which task, what failed, the error, what the retries tried and a suggested fix. Leave the task `done: false`; re-invoking `deliver` resumes from it.
+6. **A `parallel` task fails**: once the retry is exhausted, continue the sibling parallel tasks, collect the failure and report it at the end of the phase.
+7. **Phase boundary** with `HALT_PER_PHASE` on: summarize the phase and ask the fixed question `phase-continue` (`afm ask deliver --scope <NNN-slug>`). Otherwise continue silently.
+
+> **Scope: `tasks.md` is the ceiling, not the floor.** Autonomy (#6) is permission to execute without asking *inside* the approved scope, not to widen it.
+> - A refactor task applies to the code the task touched, not to code that happened to be nearby. Do not invent an abstraction for a hypothetical requirement and do not add a `try/catch` for a scenario that cannot happen (rule 16 puts validation at the boundary).
+> - Not narrowing matters too. "Done" with half the task finished is the mirror failure. If something is stuck, do the rest, say plainly what is left and why. A declared partial is a result; a silent partial is debt.
+> - If you conclude the task is wrong, or a better path exists, say so in one sentence and continue with the task as approved. Resizing the work is the operator's decision. An architectural divergence already falls under rule 11: stop and ask.
+
+**The push boundary.** `deliver` stops at the push boundary and never pushes on its own. `afm.md § 6.1` requires the suite, the type-check and the build before a push: print that reminder and stop.
+
+### Stop table (everything else is autonomous)
+
+| Situation | What `deliver` does |
+| --- | --- |
+| Task (parallel or not) passes | `afm task done`, continue |
+| A task that is not `parallel` fails | Capped reflect-retry; if it still fails, **HALT** with the report. The task stays `done: false`. Resumable |
+| Same failure twice (oscillation) | **HALT** at once |
+| A `parallel` task fails | Retry runs out, continue the siblings, report at the end of the phase |
+| `afm approve --check` fails | Back to the Phase 2 gate: a hashed document changed |
+| Phase boundary + `HALT_PER_PHASE` | Pause, summarize, ask `phase-continue` |
+| Architectural surprise (rule 11: new layer, first-class component, cross-module contract, folder refactor) | **STOP and ask**. Applies even with `plan=auto` |
+| `blockers` names an adopted assumption | **HALT** on the first dependent task and report it |
+| Every task done | Phase 4 and a final summary |
+| Ready to push | **Never push on your own.** Print the § 6.1 reminder and stop |
+
+**Bright line.** Inside an approved plan `deliver` is autonomous. It stops for the operator at five boundaries: (1) the single gate, unless "go" was said, (2) a failure of a task that is not `parallel` that persists after the capped retry, (3) a rule-11 surprise, (4) the push, (5) a task that depends on an unconfirmed adopted assumption.
+
+---
+
+## Phase 4 — Reconcile
+
+- **4.A** The reconcile task runs inside the Phase 3 loop, as the last task: `ach.md § 3` for a new component, an ADR (`afm adr new <slug>`) for an architectural decision, the US status set to done. It also sets the `status:` frontmatter of `spec.md`, `plan.md` and `tasks.md` to `done` (never a body Status line), which makes the approval stale by design: nothing runs after it.
+- **4.B** Hand the closing turn to `afm reconcile` (always-on): a gotcha that bit twice, a rule the operator corrected, a learning that generalizes to the template. It **proposes**; `deliver` does not reimplement it.
+- **4.C — Final output.** The feature path, tasks done over total, the files touched, the commits made, the `[NEEDS CLARIFICATION:]` and `[TBD]` entries that remain, and reconcile's proposals. Add the **§ 6.1 pre-push reminder**: "run the ritual before you push, I did not push on my own".
+- **4.D — Post-delivery self-reflection (composes `afm reflect`).** This step does not decide the cadence. `REFLECT_EVERY` does (`core/protocol.md § 2`), enforced by the session-stop hook. What remains here is the context note: under `plan=auto` the operator reviewed less inline, so a reflection tends to yield more. When the cadence calls for it, run `afm reflect` after 4.C. It keeps its own gate and never self-applies (#6); with no friction observed in the session it reports that and stops. A session that ends before 4.D does not fire it later on its own: re-invoking `deliver` on a feature whose tasks are all done lands in Phase 4 and re-evaluates.
+
+---
+
+## Suppression contract (the DRY guarantee)
+
+`deliver` never copies an op's body. **It reads the op and follows it**, with this documented set of suppressions for orchestrated mode.
+
+> The only *universal* suppression is each op's per-artifact question and diff: it moves up to the single gate. If you only need to know "does this op ask or show a diff on its own here?", the answer is **no, that becomes the gate**. The few suppressions beyond that are listed per op below. Read the row. Do not re-subtract steps from the whole op.
+
+| Op | Steps reused | Suppressed in orchestrated mode | Why it is safe |
+| --- | --- | --- | --- |
+| `afm specify` | 1, 3 to 6, 8, 9 | 2 (heuristic, computed in 1.A), 7 (diff) | the gate replaces the diff, the scan replaces the heuristic question |
+| `afm plan` | 1, 2, 4, 5, 7 to 10, 12 | 3 (marker soft-block, Phase 0 resolved it), 6 (components, filled from the scan), 11 (diff) | discovery filled in what the plan used to ask |
+| `afm tasks` | 1, 3 to 7, 9 | 2 (HARD block, only for a resolved or cosmetic marker; a CRITICAL becomes a gate question, a load-bearing HIGH under "go" blocks the dependent task in Phase 3), 8 (diff) | no load-bearing marker drives the implementation in silence |
+| `afm clarify` | question form (step 4) and § 7 integration (step 5) | one question per turn, batched up to `QUESTION_CAP` (0.E) | #8 allows consolidating independent questions in one call |
+| `afm analyze` | detection passes and the **gating mode** | the chat report (6) and the remediation offer (8) | gating mode sorts into three buckets, self-corrects (a), loops to zero CRITICAL and HIGH; bucket (b) becomes the earned questions of the gate |
+| `afm reconcile` | everything (it proposes, it does not apply) | nothing | runs as designed in Phase 4 |
+| `afm reflect` | everything, **gate kept** | **nothing**: its gate is not suppressed, that is the point | runs only at 4.D, self-gated by evidence |
+
+> If a marker is so load-bearing that the tasks would come out incoherent, verification throws it into bucket (b), or CRITICAL. It becomes an earned gate question, and the gate **is not skippable** with an open CRITICAL (the 2.A condition applies even with "go"). The `tasks.md` HARD block turns into a gate question. It does not disappear.
+
+## Anti-patterns
+
+- ❌ Asking what the scan or the research can answer (#2). Discovery first, ask only the irreducible part.
+- ❌ Inventing a file or an entity during the scan (#5). 0.A is search and read on the real tree. What cannot be anchored becomes `[TBD]` or `[NEEDS CLARIFICATION:]`.
+- ❌ Duplicating procedure from specify, plan, tasks and the rest. Read the op and follow it. Suppress only through the contract above.
+- ❌ More than `MAX_DISCOVERY_ROUNDS` rounds, or more than `QUESTION_CAP` questions per round. The anti-interrogation cap is hard.
+- ❌ Executing a task before `afm approve` recorded the approval, or past a failing `afm approve --check`.
+- ❌ Editing `spec.md`, `plan.md` or `tasks.md` during Phase 3 to make a task pass, or closing a task by editing the `tasks:` list instead of `afm task done`. An edit invalidates the approval; if the plan is wrong, go back to the gate.
+- ❌ Pushing on your own, or crossing the rule-11 boundary without asking. Both apply even with `plan=auto`.
+- ❌ Continuing after the failure of a task that is not `parallel`. Halt, report, stay resumable. The capped retry **precedes** the halt; what is forbidden is going *past* the cap, or halting flat when the signal is cheap to re-run.
+- ❌ Stealing the intent of a standalone step. "Just generate the tasks" or "just open the spec" belongs to the atomic op, not to `deliver`.
+- ❌ Delivering without self-verification. 1.E is mandatory: *produce, self-verify, report*.
+- ❌ Putting into the gate what verification could self-correct (a) or defer (c). The gate carries only bucket (b), each with an articulable "what breaks if this is wrong" (#8 earned).

package/content/ops/diagnose.md

@@ -0,0 +1,143 @@
+---
+type: op
+description: Scans the instance mechanically for weakness and reports what it measured, read only.
+load: warm
+writes: []
+composes: []
+ancestors: the *Weakness Mining* stage of Self-Harness (arXiv 2606.09498).
+---
+# Sub-flow: mechanical weakness-mining of the methodology (`diagnose`)
+
+
+> **Form** — effect: **read-only** (evidence bundle) · trigger: `afm diagnose`, composition · precondition: `.afm-version`, git · composed by: `evolve` 1.1 · **degree of freedom: low**
+
+Triggers: `afm diagnose`. Also natural language for a **health scan**: "diagnose the methodology" or "scan the docs". Or: "what is broken in the docs?" or "list the instance health signals".
+
+> **Target = this project's local docs (`<consumer>/docs/`), never the plugin.** "Health of the methodology" here means health of the **materialized instance** in this repo, not the canonical framework (the bundled content). `diagnose` is read-only. It does not touch anything, not the local docs and not the plugin. See [`evolve.md § The target of evolution`](./evolve.md).
+>
+> **Read-only mechanism, not a conductor.** `diagnose` is the mechanism-skill that runs the **mechanical scan** of the instance's health and returns an **evidence bundle** — no edit proposal, no gate, no mutation. The `evolve` orchestrator composes it (together with `reflect`) to feed the cycle. À la carte, it is a **health report**.
+>
+>     WeaknessMining(traces, verifier):
+>       1. ANALYZER := the role that only finds        # "you are an ANALYZER, not a solver"
+>                       — it proposes no edit and picks no fix
+>       2. for each trace, run verifier                # verifier := the mechanical checks (git/file-system/command)
+>       3. Symptom := the verifier's output, anchored to file:line
+>       4. PhiSignature := (Symptom, causal-status-of-behavior, mechanism)   # the φ signature
+>       5. EvidenceBundle := every PhiSignature, ordered by severity        # severity := support
+>       6. return EvidenceBundle   # ANALYZER stops here; IMPROVER proposes the fix, elsewhere
+>
+> `diagnose` plays ANALYZER over `docs/` as the trace set. It materializes #2 (discover-first:
+> diagnose with evidence before any proposal) and #3 (mechanize-or-demote: the checks themselves
+> must pass the test they audit). See [`../PRINCIPLES.md`](../PRINCIPLES.md).
+
+---
+
+## What `diagnose` is / is not
+
+**Is:** the scan of the **7 axes** of health of the materialized instance (`<consumer>/docs/`). It uses evidence **external to the text** (command + `file:line`), partitioned by severity, and is **read-only**. Role ANALYZER: it produces findings. **Zero edit proposals**.
+
+**Is not:**
+- `analyze` (it audits **one feature** — coverage and consistency across spec, plan, and tasks). `diagnose` audits the **whole instance** of `/docs/`.
+- `reflect` (its evidence is **behavioral** — the agent stumbled on a doc). `diagnose` is **static** (file system, git, command). These are the two sides of the Self-Harness φ: `c` (mechanical cause, here) vs `q/m` (behavioral mechanism, in `reflect`).
+- A proposer or editor. `diagnose` does not touch anything. The proposal (role IMPROVER) and the gate belong to `evolve` (or to `reflect`, on the behavioral axis).
+- "The agent feels the doc looks bloated": every finding is mechanized as a 0/1 command. An impression without `command + file:line` is forbidden (#5).
+
+> **No cooldown** (unlike `evolve`): `diagnose` is read-only and cheap. Running it again has no mutation cost. The cooldown that refuses a **cycle** without a new signal belongs to the orchestrator (the cycle is costly: gate plus record).
+
+---
+
+## Pre-check
+
+1. **Does `<consumer>/docs/.afm-version` exist?** If not, stop. Suggest `afm init` (greenfield) or `afm refactor` (brownfield).
+2. **Does `afm preflight` exit 0?** A non-zero exit says why: the docs are not bootstrapped, the bundled content does not resolve, or the pin does not match. Report it to the user. Do not use a silent fallback.
+3. **Capture the stated symptom** (what the user said after invoking it — "the rules do not fire", "confusion between docs"). This becomes the scan's **directed focus**. If absent, run a uniform scan of all 7 axes.
+4. **Thresholds are the instance's, and `afm doctor` reads them.** The override is one comment line at the end of `docs/.afm-version`: `<!-- evolve: marker-age-days=120 inflation-lines=500 cooldown-days=14 -->`. With no line, the defaults apply (marker age 90 days, inflation 400 lines). The agent never guesses a threshold: it reads the number `afm doctor` reports.
+
+---
+
+## Phase 0 — Scan (≈ Weakness Mining / Execute)
+
+Gap-driven, **not a blind sweep**: it runs `afm doctor --json` (the Class A checks, below) plus reads directed by the pre-check's symptom. If the user said "rules do not fire", it goes deeper into § 3. If the user said "confusion", it cross-checks the core docs against each other (the gap that per-feature `analyze` does not cover).
+
+**Golden rule of the scan:** every piece of evidence is **command + output + `file:line`**. `afm doctor` prints each finding that way (`evidence: <command> @ <file>:<line>`), and it exits 0 healthy, 1 with findings, 2 outside an AFM project. *A finding without evidence external to the text is forbidden.* "This doc looks bloated" is not a finding. `wc -l`, `git log`, or a grep for a duplicate block is a finding. (This blocks the self-reference loop: the agent auditing the text based on the text itself.)
+
+### Class A checks (mechanizable — 0/1 command)
+
+Run **`afm doctor --json`** once. It is read only. It scans A1 through A6, A5b, staleness and dead gotchas in one pass and returns the evidence bundle as data: `status`, `findings[]` (`axis`, `severity`, `symptom`, `evidence[]` as `command` + `file` + `line`, an optional `rival`) and `notCovered[]`. The session-start digest shows the same signs in two or three lines when something is wrong. Here they run live, with no time budget, and the agent reads each finding to the bottom. **A7 is in-cycle-only** (semantic, paired reading — `afm doctor` does NOT run it). Without `--json`, `afm doctor` prints the same bundle as text.
+
+| # | Signal | What `afm doctor` decides (the CLI runs it; read the finding, do not redo the scan) |
+| --- | --- | --- |
+| A1 | **Dead reference** | extracts the paths cited in the normative docs (`afm.md`, `ach.md`, `prd.md`, `ust.md`, `_focus.md`, the ADR index, `rules/`, `gotchas/`, `learnings/`, `guardrails/`, `procedures/`; the same scope as PLUGIN-40, so an ADR body, an immutable record, is out), then checks each one exists (from the repo root, the citing file's directory, or by suffix of a tracked file). Missing = signal. A line that announces a removal is history, not a reference |
+| A2 | **Aged marker** | `git log -S` finds the introduction date of each open `[TBD]`/`[NEEDS CLARIFICATION:]` (a marker inside a code span is the doc talking about the notation, not an open one). Age > threshold (default 90 days) = signal. It measures **age**. It never rewards a zero count |
+| A3 | **Version drift** | the pin in `docs/.afm-version` is behind the shipped version (compared as semver, a prerelease sorts below its release). It never fires when either side is not a version |
+| A4 | **Broken ADR chain** | every `Superseded by ADR-NNNN` (bare, or in the markdown-link form) is checked: does the referenced NNNN exist in `adr/`? Numbers compare as numbers |
+| A5 | **Unparseable trigger (static)** | for each `*Verification:*` command in `afm.md` § 3: does the path or glob it targets exist? Does the command parse and return 0/1? **Static check** — it does NOT execute § 3 (that does not fit a health check and gives an ambiguous exit 0). The real-execution dry run belongs to `evolve` Phase 2 (or `afm gate --audit`). **Severity:** a command that returns **something other than 0/1** (error exit, or a target path that does not exist) = **CRITICAL** (a stillborn guard-rail means zero enforcement), **regardless of an observable violation** — distinct from a trigger that regressed but still runs (HIGH). **Sub-case (HIGH, read by the agent — the CLI cannot see it):** the command rewrites in prose what a versioned repo script already does (a `test/` script, `npm run <x>`, a project hook). Two sources of truth for the same check drift out of sync on their own, and the one the human reads is not the one that runs. Finding: "point the `*Verification:*` field at the script." **Sub-case (CRITICAL, mechanical):** the command ends in `\| head`, `\| wc -l`, or a pipe whose last stage always exits 0. It is **vacuously green**. It passes whether installed or not, and it measures presence instead of activation |
+| A5b | **Missing inalienable rule** | for each rule marked `INALIENABLE` in the shipped `core/afm.md § 3`: does it stand in the instance's `docs/afm.md`, with its marker and no N/A? (An instance from before the `PLUGIN-` namespace that wrote the rule as a plain number is accepted.) **Severity:** missing = **CRITICAL**. This is the only axis that compares the instance against the plugin outside A3, and that is deliberate — A3 measures *version*, this one measures *floor integrity*. Detection, not prevention: the file belongs to the operator |
+| A6 | **Inflation** | the line count of **any `.md` in `docs/`** (not only the 4 core files `afm/ach/prd/ust` — this also catches orphan appendices like `ach-notes.md`) **> 400 lines** (default threshold, override in the instance) **AND/OR** a paragraph repeated verbatim **AND/OR** an orphan doc (no doc references it; `afm index --orphans` lists them too). A high `wc` alone, with none of these extra signals, is **not** a finding (this avoids rewarding or punishing raw size — mechanize-or-demote, #3) |
+
+**A7 — Cross-doc normative contradiction.** This axis runs in-cycle, with paired reading. It runs ALWAYS, not only when the user says "confusion". This is the "mental confusion" axis. The method has 2 steps.
+
+(1) **Surface candidates mechanically.** Grep for opposing normative assertions in `ach.md § 6` (code conventions), `afm.md § 1.3` (principles), and `afm.md § 3` (rules). Use antonym verbs and terms: `only at the boundary` vs `in the domain`, `always` vs `never`, `before` vs `after`.
+
+(2) **Read the matched passages in pairs.** Confirm the real conflict, with `file:line` for both sides.
+
+This is the **only legitimate case where paired reading replaces a pure 0/1 check**. It is distinct from "looks bloated" (forbidden). A7 requires citing **both literal conflicting assertions**, not an impression. No literal conflicting pair means no A7 finding.
+>
+> **Before you mark a contradiction — layer test (anti-false-positive):** check whether the two passages operate at **different layers or scopes** (example: "validation at the boundary" can mean input validation at the edge, while "invariant checked in the domain" can mean a business rule — both correct). Mechanical heuristic: **same decision** = both passages use the same normative term in absolute form, with no layer qualifier. **Different layers** = each passage carries a different scope qualifier (input vs. invariant, request vs. persistence). When the layers differ, log the A7 finding as **"layer ambiguity"** (the fix will be to disambiguate, not to pick a side — but that decision belongs to the proposal Phase of `evolve`/`reflect`, not to `diagnose`). Only when both passages provably govern the *same* decision is there a real contradiction.
+
+> **Watch for the right field and section (disambiguating `## 3.`):** the **hook-parsed § 3 is EXCLUSIVELY the one in `afm.md`** (the `*Verification:*` field, read by the pre-edit hook and by `afm doctor` from the `## 3.` section of `afm.md`), plus the `trigger_path` frontmatter key in **gotchas**. `## 3.` headers in **other** docs (example: `ach.md ## 3. Mapa componente→onde`) are **prose, NOT hook surface** — a dead reference in them has a different nature (see `hooks/README.md`). `diagnose` only **classifies** the surface. The treatment (auto-applicable vs. gate) is a decision for the `evolve` proposal.
+
+> **Where the thresholds live (deterministic override).** The defaults (`A2` marker 90 days, `A6` inflation 400 lines) belong to the op. Override them with one parseable comment line at the end of `docs/.afm-version`: `<!-- evolve: marker-age-days=120 inflation-lines=500 cooldown-days=14 -->` (`afm doctor` reads it; if absent, it uses the defaults).
+
+### Axis coverage is mandatory (anti-miss)
+
+An **empty** diagnosis is a valid result (a healthy instance). A **silent partial** diagnosis is not valid. The 7 axes are A1 reference, A2 marker, A3 drift, A4 ADR, A5 trigger, A6 inflation, and **A7 contradiction**. The scan checks all 7 axes, every time: `afm doctor` covers six, and the agent covers A7.
+
+An axis that could not be scanned (example: no git, no `adr/`) gets a report entry. `afm doctor` lists it in `notCovered` as **"not covered: <reason>"**, and A7 is yours to report the same way when you skip it. Never omit it. Omitting an axis hides a problem the scan exists to find.
+
+---
+
+## Phase 1 — Diagnosis (≈ Reflect ρ) — role ANALYZER, **forbidden to propose edits**
+
+This is a literal role separation (Autogenesis: "You are an ANALYZER, not a solver"). This phase **only** produces findings with evidence. Zero edit proposals — that belongs to `evolve`/`reflect`.
+
+1. **φ signature per finding** = `(symptom, causal-status-of-behavior, mechanism)`:
+   - *symptom* — what the command flagged (with `file:line`). For a mechanical axis this is the `symptom` and `evidence` of the `afm doctor` finding, copied, never paraphrased into something the command did not say.
+   - *causal-status-of-behavior* — was the methodology's behavior causally implicated? (True to the paper: the middle slot is the **causal status of the behavior**, not "the cause".)
+   - *mechanism* — why the methodology produced this. Options: a badly written trigger, an obsolete rule, an orphan doc, or **the agent out of compliance**.
+
+   **Mandatory competing mechanisms (do not assume the rule itself is the defect).** A finding of `afm doctor` may carry a `rival`; keep it, and add the ones below that apply:
+   - For the signal **"rule violated despite being injected"**, always list a rival hypothesis. Say **"the agent is out of compliance"**, not just "the rule is wrong". Otherwise the cycle turns into a self-serving loop. It demotes anything that constrains the agent.
+   - For the signal **"rotten / stillborn trigger" (A5)**, list a rival too. Besides "badly written rule", consider **"the target subsystem was legitimately removed"**. If the code was deliberately removed, the right action is different. **Archive the rule with a tombstone** instead (a downstream step). Distinguishing the two needs git evidence of what happened to the target.
+
+2. **Addressability filter** (Self-Harness: exclude beats forcing a patch). A finding needs a plausible editable surface on the whitelist. Example: "this library is hard to use" is an external limit. Such a finding becomes an **observation in the report**, never a proposal candidate. This stops the cycle from "patching every friction point".
+
+   **Case A2 (aged marker):** an `[TBD]` marker past the threshold is addressable as a **binary posture question** (`is this still deliberate deferral` / `is it time to decide?`). But the marker's **content**, and the user's silence, stay an **observation** (the cycle never invents the answer — #4/#5). `diagnose` only tags the finding as "addressable: posture question". The question itself belongs to the `evolve` gate.
+
+3. **Severity** — self-contained inline matrix:
+   - **CRITICAL** — violates a `PRINCIPLES.md` invariant. OR it breaks or stillbirths an enforcement guard-rail. Examples: a `*Verification:*` trigger that does not return 0/1, or a hook that stops injecting.
+   - **HIGH** — the functional health of a doc or rule. Examples: version drift, a broken ADR chain, or a dead reference on a surface that matters. Also a trigger that regressed but still runs.
+   - **MEDIUM** — guidance/§1.3, terminology drift, addressable inflation.
+   - **LOW** — cosmetic, a posture marker, a minor near-duplicate.
+
+   **Severity is not fix friction.** Severity = the impact of the **symptom** (how bad the problem is). The bucket classification (auto-applicable / gate / defer) is **downstream**, in the `evolve` proposal. It is **orthogonal** to severity (a finding can be HIGH and auto-applicable at the same time). `diagnose` delivers only the severity. It does not pre-decide the bucket.
+
+---
+
+## Output — evidence bundle (read-only)
+
+`diagnose` returns an **evidence bundle**, ordered by severity (CRITICAL to LOW). Each finding carries: axis (A1-A7), φ signature, evidence (`command` + `file:line`), severity, and addressability (yes / observation). It also lists the rival mechanisms when they apply. Axes not covered are listed as "not covered: <reason>".
+
+- **À la carte:** it prints the bundle in the chat as a **health report** (the `afm doctor` findings plus A7). Nothing is written to disk, and there is no gate. (Useful on its own: "how is the methodology's health here?")
+- **Under `evolve`:** the bundle feeds the orchestrator's proposal Phase (role IMPROVER). That Phase sorts it into buckets and takes it to the gate. `diagnose` does not write `docs/evolution/` — that belongs to the cycle.
+
+---
+
+## Anti-patterns
+
+- ❌ **A finding with no evidence external to the text** — "looks bloated" is not a finding. Command + `file:line` is (#5).
+- ❌ **An empty diagnosis treated as a failure** — for a healthy instance, report "100%" and stop. Never fabricate a problem to justify the invocation.
+- ❌ **A silent partial diagnosis** — staying silent on an axis (A1-A7) without saying it was not checked. A7 (contradiction) always runs, not only when the user says "confusion".
+- ❌ **Proposing an edit, demoting a rule, or archiving a doc** — `diagnose` is read-only. That is role IMPROVER, in `evolve`/`reflect`.
+- ❌ **Assuming a violated rule means a wrong rule.** The agent may be out of compliance instead. Always list that as a rival mechanism in the φ.
+- ❌ **Pre-deciding the bucket** — severity is not fix friction. The bucket is decided downstream, in the proposal.