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

package/plugin/claude-code/skills/reflect/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: reflect
+description: |
+  Finds where the local docs failed AS A HARNESS in the live session and the project's sessions since the last cycle. Examples are an ambiguous rule applied wrong, a doc that misled, and a user correction against the doc. The evidence is the session trajectory, never a static scan. It proposes edits that make the docs more assertive.
+  Activates: `/afm:reflect`, "this rule is ambiguous", "the doc sent me the wrong way", "why do I keep getting this wrong when the doc covers it?".
+---
+
+
+# AFM — Reflect (behavioral self-reflection on the docs)
+
+> **Questions in this host.** `afm ask <op>` prompts only in a terminal, and the Bash tool has none: it exits 2. Run `afm ask <op> --json` instead and put each pending question to the operator with `AskUserQuestion`: its `header`, `prompt` and `options` as they come, the recommended option first, `multiSelect` as given. 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.
+
+> **Procedure.** Run `afm read ops/reflect.md` and follow it; read an on-demand section when its condition holds.
+
+> **Carve-out (does not overlap existing ops):** `/afm:reconcile` works **code to docs, and is additive**. It learns a new fact and proposes adding it. `reflect` works **docs to docs, and refines**. An existing doc guided the agent wrong, so `reflect` proposes a clearer version. `/afm:diagnose` runs a **static** scan. `reflect` uses **behavioral** evidence from the session trajectory. Only the agent sees its own stumble. `/afm:evolve` is the **orchestrator**. It composes `reflect` and `/afm:diagnose` into one cycle with a single gate.
+
+## When not to activate
+
+This is a disambiguation criterion for a skill already active, not an activation criterion. That is why it lives in the body, not in the resident listing.
+
+Learning a new fact, gotcha, or decision belongs to passive mode (`/afm:reconcile`). Route it to `/afm:gotcha`, `/afm:rule`, or `/afm:adr`. A static mechanical scan belongs to `/afm:diagnose`. Merging N gotchas belongs to `/afm:generalize`. A failure with an external signal belongs to `/afm:remediate`. The full cycle belongs to `/afm:evolve`.
+
+## Pre-check
+
+1. **Does `<consumer>/docs/.afm-version` exist?** If not, stop. Suggest `/afm:init` (greenfield) or `/afm:refactor` (brownfield) first.
+2. **Does `afm preflight` exit 0?** A non-zero exit says why (docs not bootstrapped, content unresolved, pin mismatch). Report it to the user. Do not fall back silently.
+3. **Did the live session or the project's sessions since the last cycle hit a doc-friction event** (or an articulated symptom)? Read the window with `afm sessions --since reflect --json` and `afm sessions signals --since reflect --json`. If the whole window has no signal, report "no doc friction observed" and stop. Reflection without behavioral evidence is forbidden (#5).
+
+## Procedure
+
+The steps are:
+
+**1. Collection.** Build the behavioral signature φ_b = `(symptom-lived, doc-causal-status, mechanism)`. Cite both the doc passage **and** the session event (`session:<id>@<ts>`). Weight: one signal in the live session suffices; a past-session signal needs 2 or more sessions, an explicit correction, or `regressed`, and `regressed` comes first. A repeated prompt is a finding: propose the artifact that stops the retyping.
+
+**2. Self-critique.** Consider a rival hypothesis: it was me, not the doc. Apply the guardrail: a violated rule is not a wrong rule. Apply an addressability filter.
+
+**3. Proposal.** Refine instructiveness: rewrite the ambiguous part, add an executable trigger, and remove ambiguity. Add suggestions for the human. This step follows the **shared proposal discipline** in `evolve.md` (`afm path ops/evolve.md`) and does not duplicate it.
+
+**4. Own gate.** Ask item by item, earned, with `afm ask reflect --scope <item-slug>`. `/afm:evolve` suppresses this gate.
+
+**5. Record.** Write to `docs/evolution/NNN-<date>.md`. Add an `/afm:promote` suggestion when the finding generalizes. Hand off to passive mode (`/afm:reconcile`).
+
+## Invariant principles
+
+Rule #1 applies: refine the doc's instructiveness, not the agent's memory. Rule #5 applies: no lived event, no finding. Rule #6 applies: self-verify, then report. The gate is a load-bearing residue. Bright lines #7 for plugin, deletion, and push apply.
+
+Rule #8 applies: a suggestion or question must be earned, recommendation-first. **No new principle here.** `reflect` is a composed materialization. The doctrine lives in the op file.
+
+**Principles and version.** `afm path PRINCIPLES.md` (universals §1-8 apply). `afm version` prints the version; history: `afm path CHANGELOG.md`.

package/plugin/claude-code/skills/remediate/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: remediate
+description: |
+  Reads the open failures of the state store (`afm failures promotable`) and proposes the durable artifact: a procedure when the fix is mechanical, a learning when it is conceptual. A failure enters by external signal, never by self-judgment.
+  Activates: `/afm:remediate`, "this failed again, fix it for real", "create a runbook for this", "record this lesson for the next agent sessions".
+---
+
+
+# AFM — Remediate (CRITIC loop)
+
+> **Questions in this host.** `afm ask <op>` prompts only in a terminal, and the Bash tool has none: it exits 2. Run `afm ask <op> --json` instead and put each pending question to the operator with `AskUserQuestion`: its `header`, `prompt` and `options` as they come, the recommended option first, `multiSelect` as given. 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.
+
+> **Procedure.** Run `afm read ops/remediate.md` and follow it; read an on-demand section when its condition holds.
+
+## When NOT to activate
+
+This is a disambiguation for a skill that already activated. It is not an activation trigger. That is why it lives in the body and not in the resident listing.
+
+Use `afm.md § 5.1` for an in-task retry at the moment of the error. Use `/afm:gotcha` for an SDK surprise with no failure of its own. Do not invent a failure. Only act on a recorded failure that `afm failures promotable` lists, or on an explicit user correction.
+
+## Pre-check
+
+1. **Does `<consumer>/docs/.afm-version` exist?** If not, stop. Suggest `/afm:init` for a greenfield project or `/afm:refactor` for a brownfield project.
+2. **Is there an open failure?** Run `afm failures promotable`. With `no failure is promotable` and no explicit user correction, report "nothing to remediate" and stop. An empty diagnosis is a valid result.
+3. **Does `afm preflight` exit 0?** A non-zero exit says why (docs not bootstrapped, content unresolved, pin mismatch). Report it to the user. Do not fall back silently.
+
+## Procedure
+
+The op includes the promotion gate (#5): 1 user correction OR at least 2 mechanical occurrences promote a failure. A transient failure does not promote. It also includes classification through the rubric `rubrics/failure-classification.md` (`afm path rubrics/failure-classification.md`). For each delta, propose the artifact (procedure or learning) and cite the source `sig=` (hard rule 19). Ask the artifact question with `afm ask remediate --scope <sig>`, materialize the result, close the signature with `afm failures close --sig <sig> --as remediated`, and report it (#6).
+
+## Invariant principles
+
+Most relevant here: #3 (CRITIC corollary — recognition by tool, not self-judgment). See also #5 (do not promote a failure without recurrence or an oracle) and #6 (propose only, the human approves).
+
+## Continuous doctrine
+
+Passive mode (`/afm:reconcile`) is always on. It reads `afm failures promotable` at the end of the turn and can propose remediation with no explicit command. The `/afm:evolve` cycle uses the failure events as evidence for `/afm:reflect`, toward a final remediation. This skill is the active record of the loop.
+
+**Principles and version.** `afm path PRINCIPLES.md` (universals §1-8 apply). `afm version` prints the version; history: `afm path CHANGELOG.md`.

package/plugin/claude-code/skills/restructure/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: restructure
+description: |
+  Checks the context architecture of the local docs. It looks at staleness against the code, findability across layers, and the hot versus on-demand partition. It relocates content that already exists and writes no new content.
+  Activates: `/afm:restructure`, "the doc is stale versus the code", "this should load only on demand", "the guidance exists but I cannot find it in the doc".
+---
+
+
+# AFM — Restructure (context architecture health)
+
+> **Questions in this host.** `afm ask <op>` prompts only in a terminal, and the Bash tool has none: it exits 2. Run `afm ask <op> --json` instead and put each pending question to the operator with `AskUserQuestion`: its `header`, `prompt` and `options` as they come, the recommended option first, `multiSelect` as given. 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.
+
+> **Procedure.** Run `afm read ops/restructure.md` and follow it; read an on-demand section when its condition holds.
+
+> **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.
+
+## When NOT to activate
+
+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 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
+
+1. **Does `<consumer>/docs/.afm-version` exist?** If not, stop. Suggest `/afm:init` (greenfield) or `/afm:refactor` (brownfield) first.
+2. **Does `afm preflight` exit 0?** A non-zero exit says why (docs not bootstrapped, content unresolved, pin mismatch). Report it to the user. Do not fall back silently.
+3. **Is git available?** The staleness scan needs the git history. Without git, `afm doctor` marks this axis "not covered: no git". Never omit it.
+
+## Procedure
+
+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 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. `/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
+
+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 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.
+
+**Principles and version.** `afm path PRINCIPLES.md` (universals §1-8 apply). `afm version` prints the version; history: `afm path CHANGELOG.md`.

package/plugin/claude-code/skills/rule/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: rule
+description: |
+  Adds a hard rule to `<consumer>/docs/afm.md § 3`. A mechanical trigger is mandatory and must return 0 or 1, such as `grep`, `wc -l`, `git diff` or `tsc`. A code review or a PR template is not a trigger. Without a trigger the entry becomes a principle in § 1.3.
+  Activates: `/afm:rule`, "new hard rule", "this should be a rule".
+---
+
+# AFM — Rule
+
+> **Questions in this host.** `afm ask <op>` prompts only in a terminal, and the Bash tool has none: it exits 2. Run `afm ask <op> --json` instead and put each pending question to the operator with `AskUserQuestion`: its `header`, `prompt` and `options` as they come, the recommended option first, `multiSelect` as given. 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.
+
+> **Procedure.** Run `afm read ops/rule.md` and follow it; read an on-demand section when its condition holds.
+
+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
+
+This is a disambiguation for a skill that already activated. Use `/afm:adr` for a one-off architectural
+decision. Use `/afm:gotcha` for a counterintuitive surprise. Use `/afm:generalize` to merge rules or gotchas
+that already exist.
+
+## Pre-check
+
+`afm preflight`. Exit 3 means there is no instance: stop and suggest `/afm:init` or `/afm:refactor` first.
+
+## Procedure (judgment only)
+
+1. Confirm the mechanical trigger as free text, and push back hard: no trigger means a principle in § 1.3.
+   Run the anti-Goodhart test: can a diff pass the trigger while it breaks the rule's intent? If yes, rewrite
+   or downgrade it.
+2. Measure the repo for any constant and propose the value with the measurement. An unanswered constant is
+   `[TBD]`. Check for an existing versioned script and cite it.
+3. Choose the surface: `afm ask rule`. Run `afm rule new <slug> --trigger '<command>' --surface <surface>` and
+   report the paths (#6). For `pre-commit` or `ci`, follow "Install the gate" in the op: `afm gate --baseline`
+   before the gate goes on.
+4. In a refactored project only, ask where the rule enters: `afm ask rule-scope` (universal § 3 or
+   forward-only § 3.1). The scope decision reflects intent, so it stays fixed once made.
+
+## Invariant principles
+
+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).
+
+Passive mode (`/afm:reconcile`) is always on and can propose `/afm:rule` when it detects the signal "the user
+corrected an approach with a reusable rule".
+
+**Principles and version.** `afm path PRINCIPLES.md` (universals §1-8 apply). `afm version` prints the version; history: `afm path CHANGELOG.md`.

package/plugin/claude-code/skills/specify/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: specify
+description: |
+  Opens a feature folder at `docs/features/NNN-slug/spec.md`, linked to a user story. A mechanical heuristic decides first, because a feature folder for a trivial change is overhead.
+  Activates: `/afm:specify <slug>`, "open a feature", "start a new feature", "create a feature folder".
+---
+
+# AFM — Specify
+
+> **Questions in this host.** `afm ask <op>` prompts only in a terminal, and the Bash tool has none: it exits 2. Run `afm ask <op> --json` instead and put each pending question to the operator with `AskUserQuestion`: its `header`, `prompt` and `options` as they come, the recommended option first, `multiSelect` as given. 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.
+
+> **Procedure.** Run `afm read ops/specify.md` and follow it; read an on-demand section when its condition holds.
+
+## 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 `/afm:deliver`, which composes this op.
+
+## Pre-check
+
+Run `afm preflight`. Exit 3 means no `docs/.afm-version`: stop and suggest `/afm:init` or `/afm:refactor`. Exit 4 or 5: report the line it printed.
+
+## Procedure
+
+The number comes from `afm next-id feature`, never by hand. What is left to you is judgment: compute the trigger heuristic from the scan (ask the `heuristic` question only when borderline), find the linked US in `docs/ust.md` before asking (`afm ask specify`), create the spec with `afm new feature-spec <slug>` (the generator writes the frontmatter the template names) and fill its body, update the `Spec:` line of the US, and report the open `[NEEDS CLARIFICATION:]` items. Autonomy-first: write and report, review through `git diff`.
+
+## Invariant principles
+
+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 (`/afm:reconcile`) is always on. This skill covers only the opening of the feature.
+
+**Principles and version.** `afm path PRINCIPLES.md` (universals §1-8 apply). `afm version` prints the version; history: `afm path CHANGELOG.md`.

package/plugin/claude-code/skills/tasks/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: tasks
+description: |
+  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
+
+> **Procedure.** Run `afm read ops/tasks.md` and follow it; read an on-demand section when its condition holds.
+
+## When NOT to activate
+
+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.
+
+## Principles
+
+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 (`/afm:reconcile`) is always on. This skill covers only the task list.
+
+**Principles and version.** `afm path PRINCIPLES.md` (universals §1-8 apply). `afm version` prints the version; history: `afm path CHANGELOG.md`.

package/plugin/claude-code/skills/update/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: update
+description: |
+  Syncs `<consumer>/docs/` with the current plugin version. It materializes the consumer-facing deltas between the pinned version and the shipped version, then moves the pin. It reads the plugin and never edits it.
+  Activates: `/afm:update`, "bump the methodology version", "sync docs with the new plugin", "my `.afm-version` is behind".
+---
+
+# AFM — Update (sync instance-plugin)
+
+> **Questions in this host.** `afm ask <op>` prompts only in a terminal, and the Bash tool has none: it exits 2. Run `afm ask <op> --json` instead and put each pending question to the operator with `AskUserQuestion`: its `header`, `prompt` and `options` as they come, the recommended option first, `multiSelect` as given. 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.
+
+> **Procedure.** Run `afm read ops/update.md` and follow it; read an on-demand section when its condition holds.
+
+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.
+> `/afm:diagnose` only **detects** drift on axis A3 (read-only). `update` **resolves** it. `/afm:promote`
+> **records** a finding meant for the plugin. `update` reads the plugin and materializes it into the
+> instance, and neither touches the shipped content: an absolute boundary (#7). `/afm:evolve` is the
+> **cycle** that composes `update` on axis A3.
+
+## When NOT to activate
+
+This is a disambiguation for a skill that already activated. Use `/afm:init` or `/afm:refactor` if no instance
+is bootstrapped yet. Skip `update` if the pinned version already equals the shipped version (no drift). Use
+`/afm:promote` to carry a learning from the instance TO the plugin (the opposite direction). Use
+`/afm:diagnose` to only CHECK for drift. Use `/afm:evolve` for the full cycle.
+
+## Pre-check
+
+`afm update --dry-run` does it: exit 3 means no instance (suggest `/afm:init` or `/afm:refactor`), exit 4 means
+the shipped content does not resolve (report it, do not fall back silently), and "already up to date" ends
+the run. A pin **ahead** of the binary is an anomaly: report it, never roll it back.
+
+## Procedure (judgment only)
+
+1. Read the dry run as one package and show it as evidence. Ask `afm ask update`. Under `/afm:evolve` this gate
+   is suppressed.
+2. Run `afm update`. It moves the pin only at the end, and keeps it where it was when a codemod fails.
+3. Exit 6 means agent tasks are pending: do each one inside its scope (`afm lint --fix <path>` fixes the
+   frontmatter findings), then run `/afm:update` again. `afm update --accept <path>` closes a sync on a file
+   you merged by hand. An opt-in delta is reported and never applied. Exit 5 (a major crossing) is
+   `afm migrate`.
+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`. On migrate, run the rewrite as one orchestrated batch through
+   the `Workflow` tool (an ultracode run), with a light model per agent (`haiku` as the `model` of each agent call) 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
+
+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.
+
+**No new principle here.** `update` is composed materialization. The doctrine lives in the op file.
+
+**Principles and version.** `afm path PRINCIPLES.md` (universals §1-8 apply). `afm version` prints the version; history: `afm path CHANGELOG.md`.

package/plugin/claude-code/skills/verify/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: verify
+description: |
+  Stamps a human verification on one doc under `docs/`. It writes the OKF `verified` field and is the only writer of that field. Use it when a person states they reviewed a document.
+  Activates: `/afm:verify <path>`, "I reviewed this rule", "mark this gotcha as verified", "sign off on this ADR".
+---
+
+# AFM — Verify (stamp a human review)
+
+> **Questions in this host.** `afm ask <op>` prompts only in a terminal, and the Bash tool has none: it exits 2. Run `afm ask <op> --json` instead and put each pending question to the operator with `AskUserQuestion`: its `header`, `prompt` and `options` as they come, the recommended option first, `multiSelect` as given. 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.
+
+> **Procedure.** Run `afm read ops/verify.md` and follow it; read an on-demand section when its condition holds.
+
+## When not to activate
+
+Never on ordinary work, and never on your own output. This skill records that a PERSON read a document. An
+agent stamping its own writing produces a lie the trust tier cannot detect.
+
+## Pre-check
+
+1. `afm preflight`. Exit 3 means there is no instance: stop.
+2. **Did a person state they reviewed the file?** If not, stop and ask: `afm ask verify`. Inference is not
+   review.
+3. The file must carry a frontmatter block, or there is no contract to stamp.
+
+## Procedure (judgment only)
+
+Run `afm verify <path under docs/>` (add `--as <id>` when no git user name is set). The command refuses an
+agent actor. Report the tier that resulted and what it means.
+
+## Invariant principles
+
+Most relevant here: #5 is load-bearing.
+
+**Principles and version.** `afm path PRINCIPLES.md` (universals §1-8 apply). `afm version` prints the version; history: `afm path CHANGELOG.md`.

package/plugin/opencode/afm/index.js

@@ -0,0 +1,245 @@
+// AFM for opencode 2, server side: forwards what the hooks decide on to `afm hook <Event>` with the
+// native tool name, the harness marker and the session, and carries the answer back: a deny throws,
+// injected context rides in the tool's result or the system prompt, and a notice for the operator
+// goes to the terminal client (tui.js) as the `notice` event of the afm RPC. A hook that cannot
+// answer never blocks the tool. All decisions live in the afm CLI; this file only translates
+// opencode's plugin API.
+import { spawn } from "node:child_process";
+
+const MARKER = "opencode";
+const TIMEOUT_MS = 20000;
+const LOOKUP_TIMEOUT_MS = 2000;
+// The tools whose calls AFM decides on or records; every other call is not worth a process.
+const FORWARDED = new Set(["write", "edit", "shell", "skill"]);
+// The events that end a turn: opencode cannot hold a session open, so each one only records the handoff.
+const ENDED = new Set([
+	"session.execution.succeeded",
+	"session.execution.failed",
+	"session.execution.interrupted",
+]);
+
+function afmHook(event, payload) {
+	return new Promise((resolve) => {
+		let out = "";
+		const child = spawn("afm", ["hook", event], {
+			stdio: ["pipe", "pipe", "ignore"],
+		});
+		const timer = setTimeout(() => {
+			child.kill();
+			resolve("");
+		}, TIMEOUT_MS);
+		child.stdout.on("data", (chunk) => {
+			out += chunk;
+		});
+		child.on("error", () => {
+			clearTimeout(timer);
+			resolve("");
+		});
+		child.on("close", () => {
+			clearTimeout(timer);
+			resolve(out);
+		});
+		child.stdin.on("error", () => {});
+		child.stdin.end(JSON.stringify(payload));
+	});
+}
+
+/** The `hookSpecificOutput` of an `afm hook` answer; empty when there is none or it is not JSON. */
+function decisionOf(out) {
+	try {
+		return JSON.parse(out).hookSpecificOutput ?? {};
+	} catch {
+		return {};
+	}
+}
+
+/** The `systemMessage` of an `afm hook` answer: what the operator must read, not the model; undefined when there is none. */
+function noticeOf(out) {
+	try {
+		const notice = JSON.parse(out).systemMessage;
+		return typeof notice === "string" && notice !== "" ? notice : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+/** The afm RPC: one event, the notice the terminal client shows as a toast. Plain JSON Schema, no Effect. */
+const RPC = {
+	id: "afm",
+	methods: {},
+	events: {
+		notice: {
+			schema: {
+				type: "object",
+				properties: { message: { type: "string" } },
+				required: ["message"],
+			},
+		},
+	},
+};
+
+const bounded = (promise) => {
+	let timer;
+	const limit = new Promise((resolve) => {
+		timer = setTimeout(resolve, LOOKUP_TIMEOUT_MS, undefined);
+	});
+	return Promise.race([promise.catch(() => undefined), limit]).finally(() =>
+		clearTimeout(timer),
+	);
+};
+
+/** A tool result's content as a list of parts: the host may hand a plain string. */
+const partsOf = (content) =>
+	typeof content === "string"
+		? [{ type: "text", text: content }]
+		: Array.isArray(content)
+			? content
+			: [];
+
+/** The text the model reads in a tool result. */
+const textOf = (result) =>
+	partsOf(result?.content)
+		.filter((part) => part?.type === "text")
+		.map((part) => part.text)
+		.join("\n");
+
+/**
+ * Whether a session is a sub-agent's (it has a parent). The lookup is bounded and its failure is not an
+ * error: the call is then treated as the main thread's. Only an answered lookup is remembered, so a failed
+ * one is tried again.
+ */
+async function isChild(session, sessionID, cache) {
+	if (typeof sessionID !== "string") return false;
+	if (cache.has(sessionID)) return cache.get(sessionID);
+	const info = await bounded(
+		Promise.resolve().then(() => session?.get?.({ sessionID })),
+	);
+	if (info === undefined || info === null) return false;
+	const child = typeof info.parentID === "string";
+	cache.set(sessionID, child);
+	return child;
+}
+
+export default {
+	id: "afm",
+	async setup(ctx) {
+		const directory = ctx.location?.directory;
+		// A host whose RPC is missing or refuses the definition still runs the hooks: only the toast is lost.
+		const rpc = await Promise.resolve()
+			.then(() => ctx.rpc?.register?.(RPC, {}))
+			.catch(() => undefined);
+		const notify = async (message) => {
+			try {
+				await rpc?.events?.emit?.("notice", { message });
+			} catch {
+				// nowhere to show it: the next session start tries again
+			}
+		};
+		const children = new Map();
+		const starts = new Map();
+		const pending = new Map();
+		const childOf = (sessionID) => isChild(ctx.session, sessionID, children);
+		const base = (sessionID, child) => ({
+			harness: MARKER,
+			session_id: sessionID,
+			cwd: directory,
+			...(child ? { agent_id: sessionID } : {}),
+		});
+		// The digest a session starts with: the main thread's, or the sub-agent's rules. Asked once.
+		const startOf = (sessionID, agent) => {
+			if (typeof sessionID !== "string") return Promise.resolve(undefined);
+			if (!starts.has(sessionID))
+				starts.set(
+					sessionID,
+					(async () => {
+						const child = await childOf(sessionID);
+						if (!child) {
+							const out = await afmHook("SessionStart", {
+								...base(sessionID, false),
+								source: "startup",
+							});
+							const notice = noticeOf(out);
+							if (notice) await notify(notice);
+							return decisionOf(out).additionalContext;
+						}
+						if (typeof agent !== "string") return undefined;
+						return decisionOf(
+							await afmHook("SubagentStart", {
+								...base(sessionID, true),
+								agent_type: agent,
+							}),
+						).additionalContext;
+					})(),
+				);
+			return starts.get(sessionID);
+		};
+
+		// Runs before every model request: the system prompt is rebuilt each time, so the digest is added each time.
+		await ctx.session.hook("context", async (event) => {
+			const text = await startOf(event.sessionID, event.agent);
+			if (text) event.system.push({ type: "text", text });
+		});
+		await ctx.tool.hook("execute.before", async (event) => {
+			if (!FORWARDED.has(event.tool)) return;
+			const child = await childOf(event.sessionID);
+			const decision = decisionOf(
+				await afmHook("PreToolUse", {
+					...base(event.sessionID, child),
+					tool_name: event.tool,
+					tool_input: event.input ?? {},
+				}),
+			);
+			if (decision.permissionDecision === "deny")
+				throw new Error(decision.permissionDecisionReason);
+			// A PreToolUse cannot speak to the agent before the tool runs: its context joins the result.
+			if (decision.additionalContext && event.id)
+				pending.set(event.id, decision.additionalContext);
+		});
+		await ctx.tool.hook("execute.after", async (event) => {
+			if (!FORWARDED.has(event.tool)) return;
+			const child = await childOf(event.sessionID);
+			const exit =
+				event.status === "completed" ? event.result?.metadata?.exit : undefined;
+			const failed =
+				event.tool === "shell" && typeof exit === "number" && exit !== 0;
+			const decision = decisionOf(
+				await afmHook(failed ? "PostToolUseFailure" : "PostToolUse", {
+					...base(event.sessionID, child),
+					tool_name: event.tool,
+					tool_input: event.input ?? {},
+					...(failed ? { exit, error: textOf(event.result) } : {}),
+				}),
+			);
+			const context = [pending.get(event.id), decision.additionalContext]
+				.filter(Boolean)
+				.join("\n\n");
+			pending.delete(event.id);
+			if (context && event.status === "completed")
+				event.result = {
+					...event.result,
+					content: [
+						...partsOf(event.result?.content),
+						{ type: "text", text: context },
+					],
+				};
+		});
+
+		const controller = new AbortController();
+		(async () => {
+			for await (const event of ctx.event.subscribe({
+				signal: controller.signal,
+			})) {
+				if (!ENDED.has(event?.type)) continue;
+				const sessionID = event.data?.sessionID;
+				if (!(await childOf(sessionID)))
+					await afmHook("Stop", base(sessionID, false));
+			}
+		})().catch(() => {
+			// the stream ends with the plugin: nothing is left to record
+		});
+		return () => {
+			controller.abort();
+			return rpc?.dispose?.();
+		};
+	},
+};

package/plugin/opencode/afm/tui.js

@@ -0,0 +1,21 @@
+// AFM for opencode 2, terminal-client side: shows the notice the server side (index.js) emits on the
+// afm RPC as a toast. opencode loads this file in the terminal client only; a server plugin has no screen.
+
+/** How long a notice stays: long enough to read a sentence about a failed update. */
+const DURATION_MS = 20000;
+
+export default {
+	id: "afm",
+	setup(ctx) {
+		return ctx.data.on("rpc.afm.notice", (event) => {
+			const message = event?.data?.message;
+			if (typeof message !== "string" || message === "") return;
+			ctx.ui.toast.show({
+				title: "AFM",
+				message,
+				variant: "warning",
+				duration: DURATION_MS,
+			});
+		});
+	},
+};