@tenkara/afm-linux-arm64 4.0.0-alpha.7 → 4.0.0-alpha.9

package/content/skills/restructure.md

@@ -8,9 +8,7 @@ description: |
 
 # AFM — Restructure (context architecture health)
 
-This is a mechanism skill of AFM. The canonical procedure is the op file that `afm path ops/restructure.md` prints.
-
-> **Carve-out (does not overlap existing ops):** `diagnose` A1 finds a **dead reference** (the path does not exist). `restructure` staleness finds a path that **exists but changed** while the doc did not. `reconcile` adds **missing** information. `restructure` relocates information that **exists but sits in the wrong place**. `reflect` targets **clarity**. `restructure` targets **location and freshness**. `evolve` is the **orchestrator** that composes this skill when `diagnose` flags staleness or bloat.
+> **Carve-out (does not overlap existing ops):** `afm diagnose` A1 finds a **dead reference** (the path does not exist). `restructure` staleness finds a path that **exists but changed** while the doc did not. `afm reconcile` adds **missing** information. `restructure` relocates information that **exists but sits in the wrong place**. `afm reflect` targets **clarity**. `restructure` targets **location and freshness**. `afm evolve` is the **orchestrator** that composes this skill when `afm diagnose` flags staleness or bloat.
 >
 > **Maturity (honest YAGNI):** the actionable core today is **staleness** (from git) plus **findability**. **Temperature tiering** (always-hot vs on-demand) is an **opt-in** ADR proposal, only for a doc that has actually outgrown its size. Small docs do not need it.
 
@@ -18,7 +16,7 @@ This is a mechanism skill of AFM. The canonical procedure is the op file that `a
 
 This is a disambiguation guide for a skill that has already activated. It does not gate activation, so it stays in the body, not in the resident listing.
 
-A path that does not exist belongs to `afm diagnose` (A1). Staleness means the path exists but changed. Information never documented belongs to `reconcile` → `afm gotcha` or `afm rule`. An ambiguous doc belongs to `afm reflect`. Merging gotchas belongs to `afm generalize`. The full cycle belongs to `afm evolve`.
+A path that does not exist belongs to `afm diagnose` (A1). Staleness means the path exists but changed. Information never documented belongs to passive mode (`afm reconcile`) → `afm gotcha` or `afm rule`. An ambiguous doc belongs to `afm reflect`. Merging gotchas belongs to `afm generalize`. The full cycle belongs to `afm evolve`.
 
 ## Pre-check
 
@@ -28,25 +26,21 @@ A path that does not exist belongs to `afm diagnose` (A1). Staleness means the p
 
 ## Procedure
 
-Read the op (`afm path ops/restructure.md`) end to end. Follow it literally. Use these five steps.
+Use these five steps.
 
 1. **Staleness scan.** `afm doctor --json` runs it (findings with axis `staleness` and `dead-gotcha`); read them. The git trigger fires in two cases. First case: a path cited in the doc has a later last commit than the doc. Second case: the doc has been stale for more than N commits. A hit is a candidate, not a verdict. The scan never rewrites the doc on its own.
-2. **Findability.** Relocate or cross-reference information that exists but sits buried or in the wrong doc. Cite both locations. Route information that is genuinely missing to `reconcile`.
+2. **Findability.** Relocate or cross-reference information that exists but sits buried or in the wrong doc. Cite both locations. Route information that is genuinely missing to passive mode (`afm reconcile`).
 3. **Temperature partition.** Propose a hot/on-demand loading strategy as an opt-in ADR. Do this only when a doc has outgrown its size. Preserve 100% of the content.
-4. **Its own gate.** This gate is load-bearing and earned, one `afm ask restructure --scope <item-slug>` per finding. It follows the **shared-proposal discipline** in `evolve.md` (`afm path ops/evolve.md`), instead of a duplicate copy of that discipline. `evolve` suppresses this gate when it runs.
-5. **Record.** Write the result to `docs/evolution/NNN-<date>.md`. Suggest `promote` if the finding generalizes.
+4. **Its own gate.** This gate is load-bearing and earned, one `afm ask restructure --scope <item-slug>` per finding. It follows the **shared-proposal discipline** in `evolve.md` (`afm path ops/evolve.md`), instead of a duplicate copy of that discipline. `afm evolve` suppresses this gate when it runs.
+5. **Record.** Write the result to `docs/evolution/NNN-<date>.md`. Suggest `afm promote` if the finding generalizes.
 
 ## Invariant principles
 
-The single canonical source is `PRINCIPLES.md` (`afm path PRINCIPLES.md`). Universal principles §1-8 apply here. Four principles matter most for this skill.
+Most relevant here:
 
 - #2: get git evidence before you propose a change.
 - #3: staleness needs an executable git trigger.
-- #4/#5: missing product content becomes `[TBD]` or goes to `reconcile`. Never invent it.
+- #4/#5: missing product content becomes `[TBD]` or goes to passive mode (`afm reconcile`). Never invent it.
 - #6/#8: self-check the work, then pass an earned gate.
 
 **No new principle here.** `restructure` is a composed materialization. The doctrine lives in the op file.
-
-## Version
-
-Content version: `afm version` prints it.

package/content/skills/rule.md

@@ -7,9 +7,8 @@ description: |
 
 # AFM — Rule
 
-Atomic skill of `afm`. The canonical procedure is the op `afm path ops/rule`. The CLI owns the number, the
-rule file, the index line and the runner skeleton, and refuses a rule with no honest trigger form. This
-skill keeps only the judgment.
+The CLI owns the number, the rule file, the index line and the runner skeleton, and refuses a rule with no
+honest trigger form. This skill keeps only the judgment.
 
 ## When NOT to activate
 
@@ -36,7 +35,7 @@ that already exist.
 
 ## Invariant principles
 
-Single canonical source: `afm path PRINCIPLES`. Universals §1-8 apply. Note especially #3 (a hard rule needs
+Most relevant here: #3 (a hard rule needs
 a mechanical trigger, or it is a principle instead) and #6 (autonomy-first: materialize the change and
 report it).
 

package/content/skills/specify.md

@@ -7,11 +7,9 @@ description: |
 
 # AFM — Specify
 
-An atomic skill. The procedure lives in the op: read it with `afm path ops/specify.md`, end to end, and follow it literally.
-
 ## When NOT to activate
 
-A trivial change (no feature folder needed) goes straight to the `afm.md § 2` loop. A full end-to-end delivery is `deliver`, which composes this op.
+A trivial change (no feature folder needed) goes straight to the `afm.md § 2` loop. A full end-to-end delivery is `afm deliver`, which composes this op.
 
 ## Pre-check
 
@@ -23,12 +21,8 @@ The number comes from `afm next-id feature`, never by hand. What is left to you
 
 ## Invariant principles
 
-Single canonical source: `afm path PRINCIPLES.md`. Universals §1-8 apply. In particular #2 (discover-first: compute the heuristic and the US from the scan), #5 (never invent a success criterion) and #6 (autonomy-first).
+Most relevant here: #2 (discover-first: compute the heuristic and the US from the scan), #5 (never invent a success criterion) and #6 (autonomy-first).
 
 ## Continuous doctrine
 
-Passive mode is the always-on `reconcile` skill. This skill covers only the opening of the feature.
-
-## Version
-
-`afm version`. History: `afm path CHANGELOG.md`.
+Passive mode (`afm reconcile`) is always on. This skill covers only the opening of the feature.

package/content/skills/tasks.md

@@ -1,34 +1,24 @@
 ---
 name: tasks
 description: |
-  Generates `tasks.md` in TDD order, and marks the parallel tasks with `[P]`. Every task references a user story or a requirement. It hard-blocks on an open `[NEEDS CLARIFICATION:]` in the plan.
+  Generates the `tasks:` list of `tasks.md` in TDD order with `afm task add`. Every task references a user story or a requirement. It hard-blocks on an open `[NEEDS CLARIFICATION:]` in the plan.
   Activates: `afm tasks [<feature>]`, "generate the tasks", "break the feature into tasks".
 ---
 
 # AFM — Tasks
 
-An atomic skill. The procedure lives in the op: read it with `afm path ops/tasks.md`, end to end, and follow it literally.
-
 ## When NOT to activate
 
-There is no `plan.md` yet: run `afm plan` first. An end-to-end delivery is `deliver`, which composes this op.
+There is no `plan.md` yet: run `afm plan` first. An end-to-end delivery is `afm deliver`, which composes this op.
 
 ## Pre-check
 
 Run `afm preflight` (exit 3: stop and suggest `afm init` or `afm refactor`). Run `afm feature status <NNN> --json`: a non-empty `blockers` is an open `[NEEDS CLARIFICATION:]` in the plan. That is a hard refusal with no override, not a question.
 
-## Procedure
-
-Break the plan into four phases (Setup, Foundation RED/GREEN, Boundary, Reconciliation) from the generator (`afm new feature-tasks --feature NNN-slug`). Mark `[P]` only where a task does not depend on the one before it; a GREEN never is. Give every task a `US-NNN` or `RF-NN`. Then run `afm feature lint <NNN>` and fix what it reports until it exits 0. The last task closes the `status:` keys. Autonomy-first: write and report.
-
-## Invariant principles
+## Principles
 
-Single canonical source: `afm path PRINCIPLES.md`. Universals §1-8 apply. In particular #5 (every task traces to a US or RF) and rule 1 (TDD: no GREEN without the RED before it).
+Most relevant here: #5 (every task traces to a US or RF) and rule 1 (TDD: no green task without the red task it closes).
 
 ## Continuous doctrine
 
-Passive mode is the always-on `reconcile` skill. This skill covers only the task list.
-
-## Version
-
-`afm version`. History: `afm path CHANGELOG.md`.
+Passive mode (`afm reconcile`) is always on. This skill covers only the task list.

package/content/skills/update.md

@@ -7,8 +7,7 @@ description: |
 
 # AFM — Update (sync instance-plugin)
 
-This is the sync skill of `afm`. The canonical procedure is the op `afm path ops/update`. The CLI runs the
-codemod registry, proves each op and moves the pin. This skill keeps the judgment.
+The CLI runs the codemod registry, proves each op and moves the pin. This skill keeps the judgment.
 
 > **Carve-out (does not overlap existing ops):** `afm init` and `afm refactor` **create** the instance
 > (bootstrap). `update` brings an **existing** instance forward, the path that `afm refactor` refuses.
@@ -42,13 +41,16 @@ the run. A pin **ahead** of the binary is an anomaly: report it, never roll it b
 4. **Language migration** (when the instance is not English): read `prd.md` § 11.1 FIRST and derive the
    excluded scope from it, and only then read a file. `[TBD]` there stops the step and asks
    `afm ask update-strings`. It never picks a language. The artifacts question is
-   `afm ask update-artifacts`.
+   `afm ask update-artifacts`. On migrate, run the rewrite as one orchestrated batch through
+   {{host:workflow}}, with a light model per agent ({{host:light-model}}) for the rewrite and the loss
+   check. Escalate only a flagged file to a capable model. The session model keeps the excluded scope and
+   the final gate.
 5. Post-conditions: `afm index --check` returns 0 and the plugin boundary stays clean. Report in chat what
    migrated and what stayed pending. Under `afm evolve`, feed it to `docs/evolution/`.
 
 ## Invariant principles
 
-Single canonical source: `afm path PRINCIPLES`. Universals §1-8 apply. Follow #2 (discover-first): the proof of
+Most relevant here: #2 (discover-first): the proof of
 need is the grep that shows what is missing. Follow #4/#5: materialize only what the plugin already provides
 ready-made, and never invent missing product content. Follow #6 (autonomy-first with a gate). Bright line
 #7 applies: only **read** the plugin, and write only to the instance.

package/content/skills/verify.md

@@ -7,8 +7,6 @@ description: |
 
 # AFM — Verify (stamp a human review)
 
-Atomic skill of `afm`. The canonical procedure is the op `afm path ops/verify`.
-
 ## When not to activate
 
 Never on ordinary work, and never on your own output. This skill records that a PERSON read a document. An
@@ -28,4 +26,4 @@ agent actor. Report the tier that resulted and what it means.
 
 ## Invariant principles
 
-Single canonical source: `afm path PRINCIPLES`. Universals §1-8 apply. #5 is load-bearing here.
+Most relevant here: #5 is load-bearing.

package/content/templates/adr.template.md

@@ -10,7 +10,7 @@ frontmatter_for_output: |
   status: proposed           # proposed | accepted | superseded | deprecated. Set from step 2's
                               # `afm ask adr` answer; `afm adr --supersedes` sets superseded.
   date: YYYY-MM-DD           # The day the decision was written down.
-  decided_by: '<who>'        # '[TBD]' when nobody said.
+  decided_by: '<who>'        # `[TBD]` when nobody said.
   supersedes: ADR-NNNN       # ONLY when this decision replaces an earlier one. Omit otherwise.
   superseded_by: ADR-NNNN    # ONLY when status is superseded by a later decision. Omit otherwise.
   relates_to: [ADR-NNNN]     # ONLY when it depends on or refines other ADRs. Omit otherwise.

package/content/templates/evolution-report.template.md

@@ -11,6 +11,7 @@ frontmatter_for_output: |
   date: 'YYYY-MM-DD'
   cycle_trigger: '<explicit invocation or the symptom stated by the user: cite it>'
   new_signal: '<which Class A delta or symptom released the cooldown>'
+  resolves: []   # optional: fingerprints (from `afm sessions signals`) of the friction this cycle fixed
 ---
 
 # Evolution cycle {{NNN}} — {{date YYYY-MM-DD}}
@@ -20,13 +21,15 @@ frontmatter_for_output: |
 > sorting these names, and an ordinal-first name sorts by ordinal before date — a low ordinal on
 > a recent date rewinds the window in silence. `NNN` is now only a same-day tiebreak.
 >
+> **`resolves:` (frontmatter, optional)** lists the signal fingerprints this cycle fixed. `afm sessions signals`
+> marks a signal with one of them `resolved` when it happened before this report's date, and `regressed` when
+> it happens again after it (the fix did not hold).
+>
 > **`mechanism:` (frontmatter) is mandatory and it is not decoration.** `reflect`, `evolve` and `restructure`
 > all write into this one directory, and each one's cadence window is "since MY last report".
 > Without the field the windows collapse into one, and the cheap mechanism starves the expensive
 > one: measured on 2026-08-30, five reports, all five `reflect`, and `evolve` had never run.
 
-> **In this file:** Vital signs · Findings (φ signature) · Evolution package · ADRs created in this cycle · Attempt memory (anti-oscillation) · Mechanical post-conditions · Suggested promotion
-
 > This is a report of one `afm evolve` cycle (auto-evolution of **this project's local documentation** — the materialized instance of the methodology in `docs/`, never the plugin). It is the **auditable lineage** and the **memory of past attempts** for future cycles. It is not the evolved artifact itself (the edits live in the touched local docs). It is the record of the diagnosis and the gate decisions.
 <!-- /guidance -->
 

package/content/templates/feature-plan.template.md

@@ -17,8 +17,6 @@ frontmatter_for_output: |
 
 # Feature {{NNN}} — Plan
 
-> **Inferred stack:** {{read from /docs/ach.md § 1, do not reopen the discussion}}
-
 ## 1. Approach in 3 sentences
 
 {{What to build, in which layer, linked to which component-types from `ach.md` § 3.}}

package/content/templates/feature-research.template.md

@@ -9,12 +9,11 @@ frontmatter_for_output: |
   load: cold
   status: open              # open | closed — `closed` once the findings were applied to spec.md or plan.md
   consumed_by: '<the artifact that cites this research; omit until one does>'
+  context: '<the marker from spec.md or plan.md this answers, or "free investigation: <topic>">'
 ---
 
 # Research — Feature {{NNN}} — {{title}}
 
-> **Triggered by:** {{original marker from spec/plan OR "free investigation: <topic>"}}
-
 <!-- guidance -->
 {{For each topic investigated, repeat the block below. Put multiple topics in the same file if they went to the subagent in the same round.}}
 <!-- /guidance -->

package/content/templates/feature-spec.template.md

@@ -21,7 +21,7 @@ frontmatter_for_output: |
 # Feature {{NNN}} — {{objective title}}
 
 <!-- guidance -->
-> **Spec:** the what and the why. No technology decision.
+> A spec holds the what and the why. No technology decision.
 > The linked US and the lifecycle `status` live in the frontmatter, never in the body.
 <!-- /guidance -->
 

package/content/templates/feature-tasks.induced.template.md

@@ -3,6 +3,7 @@ type: template
 description: 'Template rendered during materialization: Induced tasks — parameterized template.'
 load: cold
 renders_to: 'docs/templates/feature-tasks.induced.md'
+ancestors: 'Agent Workflow Memory (arXiv:2409.07429): induce a reusable workflow from a successful trajectory, and parameterize the concrete values. Voyager (arXiv:2305.16291): composing from the library beats regenerating from scratch.'
 frontmatter_for_output: |
   type: feature-tasks
   description: '<one sentence: what this task list delivers>'
@@ -12,14 +13,64 @@ frontmatter_for_output: |
     - '{{glob}}'
   us: US-{{NNN}}            # Omit when no US is linked.
   rf: RF-{{NN}}             # Omit when no RF is linked.
+  tasks:                    # replay each item with `afm task add`, the variables filled; never by hand
+    - id: T001
+      kind: setup
+      files: ['{{src-path}}/domain/{domain}.ts']
+      refs: ['US-{{NNN}}']
+      parallel: true
+      text: 'Create the file `{{src-path}}/domain/{domain}.ts` with exported signature `domain_{domain}`.'
+      done: false
+    - id: T002
+      kind: setup
+      files: ['{{src-path}}/domain/{domain}.fixtures.ts']
+      refs: ['US-{{NNN}}']
+      parallel: true
+      text: 'Create the test fixture in `{{src-path}}/domain/{domain}.fixtures.ts`.'
+      done: false
+    - id: T003
+      kind: red
+      scenario: 1
+      files: ['{{src-path}}/domain/{domain}.test.ts']
+      refs: ['US-{{NNN}}']
+      text: 'Write test `domain_{domain} returns <result> given <input>`.'
+      done: false
+    - id: T004
+      kind: green
+      closes: T003
+      files: ['{{src-path}}/domain/{domain}.ts']
+      refs: ['US-{{NNN}}']
+      text: 'Add the minimal implementation of `domain_{domain}`.'
+      done: false
+    - id: T005
+      kind: refactor
+      refs: ['US-{{NNN}}']
+      text: 'Extract a helper if DRY reaches 3 callers (rule 8).'
+      done: false
+    - id: T006
+      kind: red
+      scenario: 2
+      refs: ['US-{{NNN}}']
+      text: 'Write a test for the error path of an invalid `{entity}` at `{boundary-procedure}`.'
+      done: false
+    - id: T007
+      kind: green
+      closes: T006
+      validates: '{boundary-procedure}'
+      refs: ['US-{{NNN}}']
+      text: 'Add the procedure `{boundary-procedure}` with Zod validation at the boundary (rule 16).'
+      done: false
+    - id: T008
+      kind: reconcile
+      text: 'Update `ach.md § 3` if a new component (`{domain}`/`{entity}`) was added, add an ADR if an architectural decision was made, set the US status in `ust.md` to `done`, and move the `status` frontmatter key of `spec.md`, `plan.md` and `tasks.md` to `done`.'
+      done: false
 ---
 
 # Induced tasks — parameterized template
 
 <!-- guidance -->
-> **Source:** induced by `afm export-template` from a feature that is **delivered and 100% green** (`tasks.md` with all tasks `- [X]` — gate `L_eval=1` of AWM). The concrete values of the original feature are parameterized as `{variables}`.
-> **Ancestor:** Agent Workflow Memory (arXiv:2409.07429) — induce a reusable workflow from a successful trajectory, and parameterize the concrete values. Voyager (arXiv:2305.16291) — composing from the library beats regenerating from scratch.
-> **Use:** the next consumer of this template starts here (fills in the variables) instead of generating tasks from scratch. It keeps the TDD convention of `feature-tasks.template.md`. Each task is a cycle of `core/afm.md § 2`.
+> Induced by `afm export-template` from a feature that is **delivered and 100% green** (every task of its `tasks:` list `done: true` — gate `L_eval=1` of AWM). The concrete values of the original feature are parameterized as `{variables}`.
+> The next consumer of this template starts here instead of generating tasks from scratch: fill in the variables and replay each item of the `tasks:` list above with `afm task add`, then close each one with `afm task done`. It keeps the TDD convention of `feature-tasks.template.md`: a red task, the green task that closes it, an optional refactor (`core/afm.md § 2`), and one reconcile task, last.
 <!-- /guidance -->
 
 ## Variables
@@ -29,39 +80,12 @@ frontmatter_for_output: |
 | `{product-name}` | product/project name | — |
 | `{domain}` | module/domain of the feature | `billing`, `auth` |
 | `{entity}` | central entity touched | `Subscription`, `Session` |
-| `{boundary-procedure}` | boundary procedure/handler | `subscriptionCreate` |
-
-## Phase 1 — Setup
-
-- [ ] T001 [P] Create the file `{{src-path}}/domain/{domain}.ts` with exported signature `domain_{domain}`.
-- [ ] T002 [P] Create the test fixture in `{{src-path}}/domain/{domain}.fixtures.ts`.
-
-## Phase 2 — Foundation (write failing tests first)
-
-- [ ] T003 — RED: write test `domain_{domain} returns <result> given <input>` in `{{src-path}}/domain/{domain}.test.ts` (US-NNN scenario 1).
-- [ ] T004 — GREEN: add the minimal implementation of `domain_{domain}` that passes T003.
-- [ ] T005 — REFACTOR: extract a helper if DRY reaches 3 callers (rule 8).
-
-## Phase 3 — Boundary
-
-- [ ] T006 — RED: write a test for procedure `{boundary-procedure}` that calls `domain_{domain}` (US-NNN scenario 1).
-- [ ] T007 — GREEN: add the minimal procedure.
-- [ ] T008 [P] — RED: write a test for the error path of an invalid `{entity}` (US-NNN scenario 2).
-- [ ] T009 — GREEN: add Zod validation at the boundary (rule 16).
-
-## Phase 4 — Reconciliation (8.5)
-
-<!-- guidance -->
-> **Version bump.** In a delivery of more than one commit, the version bump is a **precondition of every commit that touches the installable surface**. It is not a task of this phase: a final-phase bump leaves the earlier commits failing the gate.
-<!-- /guidance -->
-
-- [ ] T010 — Update `ach.md § 3` if a new component (`{domain}`/`{entity}`) was added.
-- [ ] T011 — Add an ADR if an architectural decision was made (see `ops/adr.md`).
-- [ ] T012 — Update the US status in `ust.md` to `done`.
-- [ ] T013 — Move the spec status to `done` (the `status` frontmatter key of `spec.md`, `plan.md` and `tasks.md`).
+| `{boundary-procedure}` | boundary procedure/handler, named as its `### Boundary` of plan § 5 | `subscriptionCreate` |
 
 ---
 
 <!-- guidance -->
-*Fill in the variables for this feature. The rest of the TDD structure came from a validated delivery. Every task must reference US-NNN/RF-NN in its commit and must run as a cycle of `core/afm.md § 2`. Do not skip RED (rule 1).*
+*Fill in the variables for this feature. The rest of the TDD structure came from a validated delivery. Every task must reference US-NNN/RF-NN in its commit. Do not skip the red task (rule 1).*
+
+> **Version bump.** In a delivery of more than one commit, the version bump is a **precondition of every commit that touches the installable surface**. It is not a task: a bump in the reconcile task leaves the earlier commits failing the gate.
 <!-- /guidance -->

package/content/templates/feature-tasks.template.md

@@ -9,52 +9,74 @@ frontmatter_for_output: |
   load: cold
   status: planned           # draft | clarified | planned | in_progress | done | cancelled — the folder's
                               # ONE lifecycle value: `in_progress` with the first task, `done` in the
-                              # same last task (Phase 4, T013) that moves spec.md and plan.md
+                              # reconcile task that moves spec.md and plan.md
   for_paths:                 # carried from plan.md § 2, unchanged
     - '{{glob}}'
   us: US-{{NNN}}             # carried from spec.md. Omit when spec.md omits it.
   rf: RF-{{NN}}              # carried from spec.md. Omit when spec.md omits it.
+  tasks:                     # written by `afm task add`, corrected by `afm task set`, closed by `afm task done`; never by hand
+    - id: T001
+      kind: setup
+      files: ['{{src-path}}/domain/x.ts']
+      refs: ['US-{{NNN}}']
+      parallel: true
+      text: '{{ex: create the empty file with an exported signature}}'
+      done: false
+    - id: T002
+      kind: red
+      scenario: 1
+      files: ['{{src-path}}/domain/x.test.ts']
+      refs: ['US-{{NNN}}']
+      text: '{{ex: test domain_x returns Y given Z}}'
+      done: false
+    - id: T003
+      kind: green
+      closes: T002
+      files: ['{{src-path}}/domain/x.ts']
+      refs: ['US-{{NNN}}']
+      text: '{{ex: minimal implementation of domain_x}}'
+      done: false
+    - id: T004
+      kind: refactor
+      refs: ['US-{{NNN}}']
+      text: '{{ex: extract parseInput if DRY has 3+ callers (rule 8)}}'
+      done: false
+    - id: T005
+      kind: red
+      scenario: 2
+      files: ['{{src-path}}/procedures/x-create.test.ts']
+      refs: ['US-{{NNN}}']
+      text: '{{ex: test the INVALID_INPUT error path of the xCreate boundary}}'
+      done: false
+    - id: T006
+      kind: green
+      closes: T005
+      validates: '{{boundary name of plan § 5, ex: xCreate}}'
+      files: ['{{src-path}}/procedures/x-create.ts']
+      refs: ['US-{{NNN}}']
+      text: '{{ex: Zod validation at the boundary (rule 16)}}'
+      done: false
+    - id: T007
+      kind: reconcile
+      text: 'ach.md § 3 if a new component landed, an ADR if a decision materialized, the US status in ust.md, and the status key of spec.md, plan.md and tasks.md set to done'
+      done: false
 ---
 
 # Feature {{NNN}} — Tasks
 
 <!-- guidance -->
-> **Convention:** Tasks follow TDD order. `[P]` marks a task you can run in parallel, with no dependency on the task right before it. Each task is one cycle of `core/afm.md` § 2 (RED → GREEN → REFACTOR → COMMIT).
-> **Prerequisite:** `plan.md` has no open `[NEEDS CLARIFICATION:]` marker.
+> The tasks live in the frontmatter `tasks:` list, never as a checklist in this body. Add each one with `afm task add {{NNN}} --kind <setup|red|green|refactor|reconcile> --text "..." [--scenario N] [--closes Txxx] [--validates <boundary>] [--files a,b] [--refs US-NNN,RF-NN] [--parallel]`: the CLI assigns the id, refuses an item that breaks a rule `afm feature lint` grades, and keeps the reconcile task last (reopening it when it was done). Correct a field with `afm task set {{NNN}} Txxx --<field> <value>`. Close each one with `afm task done {{NNN}} Txxx`: a green waits for its red, a refactor for the task before it. Never edit the list by hand.
+> A TDD cycle of `core/afm.md` § 2 is a red task (`scenario: N` of spec § 3), then a green task that closes it (`closes:` the red), then an optional refactor. `parallel: true` marks a task with no dependency on the task right before it; a green or a refactor never is.
+> Each new component of plan § 2 is in the `files:` of one task, with the exact path of the plan cell. Each boundary of plan § 5 needs a task whose `validates:` is its name (`### Boundary <name>`): the task that validates its input (rule 16).
+> One reconcile task, the last: `afm task done` refuses it while another task is open. Run `afm feature lint {{NNN}}` until it exits 0.
+> Before you start, `plan.md` has no open `[NEEDS CLARIFICATION:]` marker.
 <!-- /guidance -->
 
-## Phase 1 — Setup
+## Notes
 
-- [ ] T001 [P] {{ex: create empty file `{{src-path}}/domain/x.ts` with an exported signature}}
-- [ ] T002 [P] {{ex: create test fixture in `{{src-path}}/domain/x.fixtures.ts`}}
-
-## Phase 2 — Foundation (failing tests first)
-
-- [ ] T003 — RED: test `domain_x returns Y given Z` in `{{src-path}}/domain/x.test.ts` (US-NNN scenario 1)
-- [ ] T004 — GREEN: minimal implementation of `domain_x` that passes T003
-- [ ] T005 — REFACTOR: extract `parseInput` if DRY has 3+ callers (rule 8)
-
-## Phase 3 — Boundary
-
-- [ ] T006 — RED: test the `xCreate` procedure that calls `domain_x` (US-NNN scenario 1)
-- [ ] T007 — GREEN: minimal procedure
-- [ ] T008 [P] — RED: test the `INVALID_INPUT` error path (US-NNN scenario 2)
-- [ ] T009 — GREEN: Zod validation at the boundary (rule 16)
-
-## Phase 4 — Reconciliation (8.5)
-
-<!-- guidance -->
-> **Version bump.** In a delivery of more than one commit, the version bump is a **precondition of every commit that touches the installable surface**. It is not a task of this phase: a final-phase bump leaves the earlier commits failing the gate.
-<!-- /guidance -->
-
-- [ ] T010 — Update `ach.md` § 3 if a new component landed
-- [ ] T011 — Add an ADR if an architectural decision materialized (see `ops/adr.md`)
-- [ ] T012 — Update the US status in `ust.md` to `done`
-- [ ] T013 — Move the spec status to `done` (the `status` frontmatter key of `spec.md`, `plan.md` and `tasks.md`)
-
----
+{{ex: what the list does not say: the order of the phases, a dependency between tasks, a risk}}
 
 <!-- guidance -->
-*Every task references US-NNN or RF-NN in the commit (rule in `core/afm.md` § 2, step 7 COMMIT).*
-*Every task runs as a `core/afm.md` § 2 cycle. Never skip RED (rule 1 — TDD).*
+> **Version bump.** In a delivery of more than one commit, the version bump is a **precondition of every commit that touches the installable surface**. It is not a task: a bump in the reconcile task leaves the earlier commits failing the gate.
+> Every task references US-NNN or RF-NN in the commit (rule in `core/afm.md` § 2, step 7 COMMIT). Never skip the red task (rule 1 — TDD).
 <!-- /guidance -->

package/content/templates/protocols/p1.md

@@ -6,7 +6,7 @@ load: cold
 
 # P1 — Autonomous Delivery
 
-> **For:** POC and MVP work. Speed and no interaction matter more than depth.
+> POC and MVP work. Speed and no interaction matter more than depth.
 > **Granted per session, never by the repo** (`core/protocol.md` § 6).
 
 | Field | Value |

package/content/templates/protocols/p2.md

@@ -6,7 +6,7 @@ load: cold
 
 # P2 — Assisted Delivery
 
-> **For:** pair programming. The human is the senior dev. The agent escalates early instead of continuing on a wrong path.
+> pair programming. The human is the senior dev. The agent escalates early instead of continuing on a wrong path.
 
 | Field | Value |
 | --- | --- |

package/content/templates/protocols/p3.md

@@ -6,7 +6,7 @@ load: cold
 
 # P3 — Planned Autonomous Delivery
 
-> **For:** the middle ground — P2 quality with P1 interaction. You plan together. The agent executes alone.
+> the middle ground — P2 quality with P1 interaction. You plan together. The agent executes alone.
 
 | Field | Phase 1 (planning) | Phase 2 (execution) |
 | --- | --- | --- |

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@tenkara/afm-linux-arm64",
-	"version": "4.0.0-alpha.7",
+	"version": "4.0.0-alpha.9",
 	"description": "The afm binary (CLI and MCP server) for linux-arm64.",
 	"license": "UNLICENSED",
 	"publishConfig": {

package/plugin/agy/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "afm",
-  "version": "4.0.0-alpha.7",
+  "version": "4.0.0-alpha.9",
   "description": "AFM (Agent Flow Methodology): hooks and an MCP server that keep a project's docs and its code in step.",
   "license": "UNLICENSED"
 }

package/plugin/agy/skills/afm-adr/SKILL.md

@@ -9,8 +9,10 @@ description: |
 
 > **Questions in this host.** `afm ask <op>` prompts only in a terminal, and your shell tool has none: it exits 2. Run `afm ask <op> --json` instead and put each pending question to the operator with the host's question tool when it has one, and otherwise in chat as a numbered list: the `prompt`, then the `options` with their descriptions, the recommended one first and marked. Wait for the answer. Then record each choice with `afm answer <op> <id> <label>` (one label per selected option). Run `afm ask <op>` again: `all questions answered` means the op may go on.
 
-Atomic skill of `afm`. The canonical procedure is the op `afm path ops/adr`. The CLI owns the number, the
-template, the frontmatter, the supersede link and the index. This skill keeps only the judgment.
+> **Procedure.** Run `afm read ops/adr.md` and follow it; read an on-demand section when its condition holds.
+
+The CLI owns the number, the template, the frontmatter, the supersede link and the index. This skill keeps
+only the judgment.
 
 ## When NOT to activate
 
@@ -37,8 +39,10 @@ project (signal: `afm.md` § 3.1 forward-only exists). A greenfield project forb
 
 ## Invariant principles
 
-Single canonical source: `afm path PRINCIPLES`. Universals §1-8 apply. Additional #9 (a retroactive ADR is
+Additional #9 (a retroactive ADR is
 load-bearing-only) applies ONLY in a refactored project.
 
 Passive mode (`afm-reconcile`) is always on and can propose `afm-adr` when it detects a "novel structural
 decision" signal. This skill covers only the active creation.
+
+**Principles and version.** `afm path PRINCIPLES.md` (universals §1-8 apply). `afm version` prints the version; history: `afm path CHANGELOG.md`.

package/plugin/agy/skills/afm-analyze/SKILL.md

@@ -9,7 +9,7 @@ description: |
 
 > **Questions in this host.** `afm ask <op>` prompts only in a terminal, and your shell tool has none: it exits 2. Run `afm ask <op> --json` instead and put each pending question to the operator with the host's question tool when it has one, and otherwise in chat as a numbered list: the `prompt`, then the `options` with their descriptions, the recommended one first and marked. Wait for the answer. Then record each choice with `afm answer <op> <id> <label>` (one label per selected option). Run `afm ask <op>` again: `all questions answered` means the op may go on.
 
-An atomic skill. The procedure lives in the op: read it with `afm path ops/analyze.md`, end to end, and follow it exactly.
+> **Procedure.** Run `afm read ops/analyze.md` and follow it; read an on-demand section when its condition holds.
 
 ## When NOT to activate
 
@@ -21,16 +21,14 @@ Run `afm preflight` (exit 3: no `docs/.afm-version`, stop and suggest `afm-init`
 
 ## Procedure
 
-Start from the mechanical findings: `afm feature lint <NNN> --json` covers the passes A, C, D, E and the structure of `tasks.md`. Add the judgment on top (constitution violations, duplication, the semantic side of inconsistency and ambiguity), build the coverage table, assign severities by the matrix, and report in chat with metrics. Close with the `remediation` question (`afm ask analyze`). Gating mode sorts findings into buckets instead of reporting.
+Start from the mechanical findings: `afm feature lint <NNN> --json` covers the passes A, C, D, E and the structure of `tasks.md`. Add the judgment on top (constitution violations, duplication, the semantic side of inconsistency and ambiguity), build the coverage table, assign severities by the matrix, and report in chat with metrics. Close with the `remediation` question (`afm ask analyze`); a remediation that adds a task runs `afm task add`, never a hand edit of the `tasks:` list, and a task is closed only with `afm task done`. Gating mode sorts findings into buckets instead of reporting.
 
 ## Invariant principles
 
-Single canonical source: `afm path PRINCIPLES.md`. Universals §1-8 apply, especially #2 (detection is an autonomous scan, not a question), #5 (no finding without evidence) and #6 (analyze is read-only: it reports in chat, writes no file, and remediates only on request).
+Most relevant here: #2 (detection is an autonomous scan, not a question), #5 (no finding without evidence) and #6 (analyze is read-only: it reports in chat, writes no file, and remediates only on request).
 
 ## Continuous doctrine
 
-Passive mode is the always-on `reconcile` skill. This skill covers only active auditing.
+Passive mode (`afm-reconcile`) is always on. This skill covers only active auditing.
 
-## Version
-
-`afm version`. History: `afm path CHANGELOG.md`.
+**Principles and version.** `afm path PRINCIPLES.md` (universals §1-8 apply). `afm version` prints the version; history: `afm path CHANGELOG.md`.