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

package/content/modules/vireya-ui/ach.patch.md

@@ -0,0 +1,85 @@
+---
+type: module
+description: 'Adds Vireya token-first primitive, package, and provider conventions to the materialized ACH. It replaces the shadcn-style module.'
+load: cold
+stack: vireya-ui
+patches: 'docs/ach.md'
+detect: |
+  if command -v jq >/dev/null 2>&1; then jq -e '(.dependencies//{})+(.devDependencies//{})+(.peerDependencies//{})|keys|any(startswith("@vireya/"))' package.json >/dev/null 2>&1; else grep -q '"@vireya/' package.json 2>/dev/null; fi
+---
+
+# Patch — ACH for projects with Vireya Design System
+
+> Applies to `/docs/ach.md`. It adds conventions for UI primitives, tokens, packages, and providers.
+>
+> **Context:** Vireya is a token-first design system in React 19. It ships as a pnpm monorepo. It replaces shadcn-style primitives. It does not use `components.json` or `npx shadcn add`. It uses the private Gitea registry (`@vireya:registry`).
+
+## §3.2 — UI primitives via Vireya
+
+```md
+#### UI primitives — `@vireya/ui` (per-component subpaths)
+
+- **What it is:** 67 React components in `@vireya/ui` plus 26 composed blocks in `@vireya/blocks`. Token-first: all styling uses CSS Modules with `--v-*` tokens.
+- **Responsibility:** presentation and interaction. Forms keep local state. Remote state goes through the transport client (tRPC + React Query, etc).
+- **Stack:** React 19.2.1 (pinned), `@vireya/core` (tokens + `createTheme`), `@vireya/ui` (components), `@vireya/next` (server `ThemeProvider` and client `useTheme`), `@vireya/blocks` (pre-composed sections).
+
+##### Imports — per-component subpath, NEVER the root barrel
+
+```ts
+// ✅
+import { Button } from "@vireya/ui/form/button";
+import { Dialog } from "@vireya/ui/overlay/dialog";
+import { HeroCentered } from "@vireya/blocks/hero/centered";
+import enUS from "@vireya/ui/locales/enUS";
+
+// ❌ root barrel (forbidden for Button, Dialog, etc.)
+import { Button } from "@vireya/ui";
+```
+
+**One exception:** `AppProvider` is exported from the `@vireya/ui` root barrel. It is the only allowed root import.
+
+##### Next.js setup
+
+```tsx
+// app/layout.tsx
+import { ThemeProvider } from "@vireya/next";
+import { AppProvider } from "@vireya/ui";
+import enUS from "@vireya/ui/locales/enUS";
+
+<ThemeProvider>
+  <AppProvider locale={enUS} icons={...}>
+    {children}
+  </AppProvider>
+</ThemeProvider>
+```
+
+##### Tokens — absolute `--v-*` tokens
+
+Every visual CSS property must use a `--v-*` token. A hardcoded `px`, `#hex`, or `rgb()` value is a bug. The only allowed literals are: `0`, `100%`, `9999px` (a true pill), `1px`/`1.4px` for inline-SVG hairlines, `currentColor` in icons, and percentages inside `calc()`.
+
+The full token catalog lives in `@vireya/core` (reference) and in the Vireya skill file `references/tokens.md`.
+
+##### `primary` is not `accent`
+
+- `primary` — neutral-strong (near-black in light mode, near-white in dark mode). Use it for body text and default CTAs.
+- `accent` — brand-vivid (magenta, teal, etc.). It is **optional** and falls back to `primary`. Use it only for promotional or highlight elements (a popular badge, a focus ring, a hero CTA).
+
+Always chain the fallback in CSS:
+
+```css
+background-color: var(--v-accent-fill, var(--v-primary-fill));
+color: var(--v-accent-foreground, var(--v-primary-foreground));
+border-color: var(--v-accent-border, var(--v-primary-border));
+```
+```
+
+## §6 — Add Vireya conventions
+
+```md
+### Vireya Design System
+
+- **Skill:** if you use Claude Code, the `vireya` skill (at `vireya.mapree.dev/skills/vireya/`) has the full catalog of components, blocks, and tokens. It triggers automatically on "vireya", "@vireya/*", or "create a Vireya component".
+- **Per-component prop details:** open the component's `index.tsx` file. The `IProps` interfaces live next to the code and are authoritative. Do not memorize props. Navigate to the source instead.
+- **CSS Modules + forwardRef + asChild:** this pattern is mandatory for Vireya components. Each component needs a CSS Module, a forwarded ref, and `asChild` support for polymorphism through Radix.
+- **New component in the consumer project:** never duplicate a visual that already exists in `@vireya/ui`. Extend it with a wrapper, or open an upstream issue to add it.
+```

package/content/modules/vireya-ui/gotchas.seed.md

@@ -0,0 +1,98 @@
+---
+type: module
+description: 'Seed gotchas for the Vireya Design System, starting with the root barrel import breaking tree-shaking.'
+load: cold
+stack: vireya-ui
+patches: 'docs/gotchas/*.md'
+detect: |
+  if command -v jq >/dev/null 2>&1; then jq -e '(.dependencies//{})+(.devDependencies//{})+(.peerDependencies//{})|keys|any(startswith("@vireya/"))' package.json >/dev/null 2>&1; else grep -q '"@vireya/' package.json 2>/dev/null; fi
+---
+
+# Gotchas seed — Vireya Design System
+
+> Each entry below is a complete gotcha file. Copy one to `docs/gotchas/NNN-slug.md` (the first `---` of the entry as line 1) only when it bites in real use. Re-date `last_bite` on copy.
+
+---
+type: gotcha
+description: 'The root barrel import from @vireya/ui adds every component to the bundle because the bundler cannot tree-shake the eager re-exports.'
+load: warm
+fires_on: event
+fires_when: 'you import a component from @vireya/ui and you consider the root barrel.'
+bites: 1
+last_bite: 2026-10
+---
+
+## Vireya — root barrel import breaks tree-shaking
+
+## Behavior
+
+The root barrel (`import { Button } from "@vireya/ui"`) adds all 67 components to the bundle, even if you use 1. The bundler cannot tree-shake because `index.ts` re-exports everything eagerly.
+
+## Solution
+
+Always use a per-component subpath: `import { Button } from "@vireya/ui/form/button"`. The same rule applies to `@vireya/blocks/<category>/<name>`. One exception: `AppProvider` (exposed at the root on purpose, for ergonomic setup).
+
+---
+type: gotcha
+description: 'CI rewrites package.json versions to 0.0.0-rc.N on push to dev, so the working directory shows a version that is not the published one.'
+load: warm
+fires_on: event
+fires_when: 'you debug an install, or you try to find the @vireya/ui version in use.'
+bites: 1
+last_bite: 2026-10
+---
+
+## Vireya — `package.json` versions show `0.0.0-rc.<N>` in the working directory
+
+## Behavior
+
+The Gitea CI release workflow rewrites the `version` field of every `packages/*/package.json` to `0.0.0-rc.{commitCount}` on push to `dev`. The local working directory shows `0.0.0` or similar. This is not the real published version.
+
+## Solution
+
+Check the real version with `pnpm list @vireya/ui` after install. It matches the registry `rc.{commitCount}`. Do not trust the local `package.json` to track the version.
+
+---
+type: gotcha
+description: 'The @vireya scope is a private Gitea registry; without credentials in .npmrc the install fails silently or pulls the wrong version from the public registry.'
+load: warm
+fires_on: event
+fires_when: 'pnpm install fails with a 401 or 404 error on @vireya/*.'
+bites: 1
+last_bite: 2026-10
+---
+
+## Vireya — the private registry needs a configured `.npmrc`
+
+## Behavior
+
+`@vireya:registry` is a private Gitea registry. Without valid credentials in `.npmrc`, the install fails silently or pulls the wrong version from the public registry.
+
+## Solution
+
+Make sure the project `.npmrc` has the two lines below, with the registry URL and the token of your Gitea instance. Pass the token through an env var in CI.
+
+```
+@vireya:registry=<GITEA_REGISTRY_URL>
+//<GITEA_HOST>/api/packages/vireya/npm/:_authToken=<TOKEN>
+```
+
+---
+type: gotcha
+description: 'Docs and Storybook can lag behind the code; the IProps type exported next to a Vireya component is always current.'
+load: warm
+fires_on: event
+fires_when: 'you check the docs or Storybook for a Vireya component prop and the behavior does not match.'
+bites: 1
+last_bite: 2026-10
+---
+
+## Vireya — `IProps` is the authoritative source, NOT external documentation
+
+## Behavior
+
+The docs and Storybook can lag behind the code. The `IProps` type exported next to the component's `index.tsx` is always current.
+
+## Solution
+
+When in doubt, open `node_modules/@vireya/ui/<category>/<component>/index.d.ts` (or the monorepo source). Do not memorize props from the skill or the docs. Go to the source instead.

package/content/modules/vireya-ui/rules.patch.md

@@ -0,0 +1,36 @@
+---
+type: module
+description: 'Hard rules for projects that use Vireya UI, split between executable triggers and review-only principles.'
+load: cold
+stack: vireya-ui
+patches: 'docs/rules/*.md'
+detect: |
+  if command -v jq >/dev/null 2>&1; then jq -e '(.dependencies//{})+(.devDependencies//{})+(.peerDependencies//{})|keys|any(startswith("@vireya/"))' package.json >/dev/null 2>&1; else grep -q '"@vireya/' package.json 2>/dev/null; fi
+---
+
+# Patch — Hard rules for projects that use Vireya UI
+
+> Hard rules (with an executable trigger) go after the last hard rule in `/docs/afm.md` §3.
+> Principles (checked only by review) go in `/docs/afm.md` §1.3. They do **not** become hard rules. The §3 contract needs an executable trigger.
+
+## Hard rules (executable trigger)
+
+- **Absolute tokens. Zero hardcoded values in visual CSS.** Every visual CSS property must use a `--v-*` token. A hardcoded `px`, `#hex`, `rgb()`, or `rgba()` in a style file is a bug. Allowed literals: `0`, `100%`, `9999px`, `1px` or `1.4px` (inline-SVG hairlines), `currentColor`, and percentages inside `calc()`.
+  *Verification:* `grep -rnE "#[0-9a-fA-F]{3,6}|rgba?\(|[0-9]+px" --include='*.css' {{src-path}}` (this covers `*.module.css`). Review the context and exclude the allowed literals.
+- **Per-component subpath imports. Never the root barrel.** Import `@vireya/ui` and `@vireya/blocks` only through subpaths. The one exception is `AppProvider` from the root barrel.
+  *Verification:* `grep -rnE 'from "@vireya/(ui|blocks)"' {{src-path}}` must return 0 results, except for `AppProvider`.
+- **Use `:focus-visible`, never `:focus`.** Style disabled elements as `opacity: 0.5; cursor: not-allowed;`. Do not use a custom gray color for disabled state.
+  *Verification:* `grep -rnE ":focus([^-]|$)" --include='*.css' {{src-path}}` must return 0 results (`[^-]|$` excludes `:focus-visible` without needing PCRE lookahead). Review `grep -rnE "color.*#[0-9a-fA-F]{3,6}.*disabled" --include='*.css' {{src-path}}` by hand.
+- **`accent` must always fall back to `primary`.** The `--v-accent-*` token is optional. Chain the CSS as `var(--v-accent-fill, var(--v-primary-fill))`.
+  *Verification:* `grep -rnE "var\(--v-accent-[^,)]+\)" --include='*.css' {{src-path}}` flags any accent use without a fallback.
+
+> The React-version pin ("sync the whole monorepo to 19.2.1") used to be a hard rule here. A
+> version pin is an operator decision that goes stale the moment React ships a patch release, not
+> a Vireya fact — Vireya itself only requires React 19. It is not migrated to a
+> `code-style/vireya-ui/` seed: none of the five code-style concerns (naming, test-placement,
+> file-size, error-boundary, imports) fit a version-pinning policy. If a workspace needs one,
+> state it in that project's own `docs/afm.md` §3, with a version the operator owns and updates.
+
+## Principles (insert in §1.3 — review, not a trigger)
+
+- **A custom component must not copy an existing Vireya component's look.** Check `@vireya/ui` for a match first. *(No grep can detect "this copies that" — it needs review. A PR that adds a component must explain why `@vireya/ui` does not already cover the need.)*

package/content/ops/adr.md

@@ -0,0 +1,54 @@
+---
+type: op
+description: Records one load-bearing decision as an ADR, with its context and its consequence.
+load: warm
+writes: ["docs/adr/*.md"]
+composes: []
+---
+# Sub-flow: create an ADR
+
+> **Form** — effect: `docs/adr/NNNN-*.md` · trigger: `afm adr`, composition · precondition: `.afm-version` · used by: `evolve`, `restructure` · **degree of freedom: low**
+
+Triggers: `afm adr`, or natural language ("create ADR", "architecture decision").
+
+The CLI owns the mechanics: the next number, the template, the frontmatter keys the template names
+(`type: adr`, `description`, `load: warm`, `status`, `date`, `decided_by`), the supersede link and the index. This op owns
+what only the operator knows: the decision itself.
+
+## Procedure
+
+1. `afm preflight`. Exit 3 means there is no instance: stop and run `afm init` (greenfield) or
+   `afm refactor` (brownfield).
+2. **Ask the status** with `afm ask adr` (questions in `content/questions/adr.questions.yaml`).
+   Status is intent, not discoverable state.
+3. **Collect the content as free text**, because it describes and does not choose: the **title**
+   (short, names the decision, not the problem), the **context**, the **decision**, the
+   **alternatives** and the **consequence**, and the **refs** (commit, RF, gotcha, when they apply).
+4. **Create the file**: `afm adr new <slug> --title "<title>" --description "<one sentence saying what the reader learns>" --status <proposed|accepted|deprecated> --decided-by "<who>"` (the status answer of step 2; omit `--decided-by` when nobody said and it stays `[TBD]`). Add `--supersedes N` when the decision replaces ADR N. The command
+   retires ADR N in the same step and refreshes the indexes. It prints the path.
+5. **Fill the sections** of the printed file with the free-text answers. Everything the operator did
+   not say stays `[TBD]`; inventing a context or a consequence is worse than leaving it open.
+6. **Adjust the frontmatter only where the answer needs it:**
+   - The metadata lives only in the frontmatter; the body starts at its H1 and carries no
+     `> **Status:**` line.
+   - **Superseded by ADR-NNNN** is set by `--supersedes N` on the new ADR (the old one gets
+     `status: superseded` and `superseded_by`); by hand it is both keys.
+   - Add `trigger_path` only when the decision constrains one path or glob. Most decisions bind
+     none, and a guessed path is worse than an absent key.
+   - After a hand edit of the frontmatter run `afm index --materialize`; hard rule 39 fails on a
+     stale index.
+7. **Report the path.** Writing is autonomy-first (invariant principle #6): the operator reviews with
+   `git diff`.
+
+## Additional step in a refactored project
+
+> Applies only if the project adopted AFM through `afm refactor` (signal: `afm.md` § 3.1
+> forward-only exists, or the README or history shows retroactive adoption). In a greenfield project
+> skip it: a retroactive ADR is forbidden after `afm init`.
+
+A retroactive ADR is allowed here, with a load-bearing guardrail:
+
+- The decision must still be load-bearing today. Swapping or removing it would break something visible.
+- A dead decision (once relevant, not relevant now) does not become an ADR. Record it as a note in
+  `ach.md` instead.
+- See invariant principle #9 in `afm path PRINCIPLES`.

package/content/ops/analyze.md

@@ -0,0 +1,129 @@
+---
+type: op
+description: Validates spec, plan and tasks against each other and reports what disagrees.
+load: warm
+writes: []
+composes: []
+needs: ["feature"]
+---
+# Sub-flow: Cross-Artifact Validation for the Feature (`analyze`)
+
+> **Form** — effect: **read-only** (chat) · trigger: `afm analyze`, composition · precondition: spec+plan+tasks · composed by: `deliver` 1.E · **degree of freedom: medium**
+
+Triggers: `afm analyze [<feature>]`, or natural language ("audit the feature", "check coverage", "validate consistency").
+
+> Suggested (not a hard gate) between `afm tasks` and the start of T001. It writes no file: the output is read-only in chat, with remediation on demand.
+
+The fixed question of this op is data: `questions/analyze.questions.yaml`, asked with `afm ask analyze --scope <slug>`. Choosing among several features is a dynamic list: ask it in plain words.
+
+## The mechanical part is a command
+
+`afm feature lint <NNN>` runs passes **A** (coverage), **C** (inconsistency), **D** (ambiguity), **E** (underspecification) and the structure of `tasks.md` (pass **T**). It applies the severity matrix below, caps the list at 50 findings, groups the rest as an overflow count, and exits 1 on CRITICAL or HIGH. `--json` gives `{findings, overflow}` for machines. **Run it first and start from its findings.** Do not recompute them by reading.
+
+What stays judgment, and is yours: pass **B** (constitution violations), pass **F** (duplication), the semantic side of C and D (terminology drift, a `Then` that is not observable, a plan § 7 rule marked applicable but contradicted by the content), the load-bearing sort of the gating mode, and the coverage table. You add those on top of the command's output.
+
+## Two Modes
+
+`analyze` is the **verification engine** of AFM (the verification corollary of #6 in [`../PRINCIPLES.md`](../PRINCIPLES.md)). It runs in two modes. The detection passes are identical. Only what happens to the findings changes.
+
+- **Advisory mode (default, `afm analyze` à la carte):** the full flow below. Read-only in chat, a suggestion and not a gate, remediation on demand. This is what the operator invokes to audit a feature.
+- **Gating mode (in-loop, called by `deliver` Phase 1.E):** detection is the same. It **sorts** each finding into the three buckets of the verification corollary and writes **no** report in chat. The caller presents the result:
+  - **(a) resolvable by evidence:** the fix comes from code, `docs/` or a page read. It **auto-corrects** the artifact and notes it in the summary. Example: the spec says "saves to the database" without naming the store, and the code already uses Prisma with Postgres.
+  - **(b) load-bearing and not resolvable alone**, by the **structural test of #6**: the wrong choice changes *which components, boundaries or tasks get created* (the structural inventory), not just their content. Example: "the US says 'recurring subscription', I inferred Stripe subscriptions. If it is one-time, the task and webhook inventory changes entirely" is (b). "The spec does not state the button copy" changes only content, so it is **not** (b). It becomes an **earned question** (recommendation-first, with the evidence and "what changes in the structure if this is wrong") and goes back to the caller for the gate. **CRITICAL** changes the inventory of the whole plan (layer, module, contract). **HIGH** changes the inventory of one isolated feature or task.
+  - **(c) not load-bearing and not resolvable** (cosmetic or deferrable): it becomes `[TBD]` or `[NEEDS CLARIFICATION:]` for reconcile.
+  - **Loop until zero.** After auto-correcting (a), **re-run** `afm feature lint` and the judgment passes. Repeat until **CRITICAL and HIGH are 0**, or until nothing new gets auto-corrected. The cap is 3 auto-fix rounds. A stuck CRITICAL or HIGH after 3 rounds goes to (b); a CRITICAL never becomes deferrable. Remaining MEDIUM and LOW findings do not block: they become a note in the gate summary, and a stuck one becomes (c).
+  - **Anti-oscillation history (Self-Refine, arXiv:2303.17651).** Keep the list `finding -> fix applied` across rounds. A finding that reappears after an earlier round "fixed" it is an **oscillation**: the loop undid and redid the same edit. Do not auto-correct it again. Promote it straight to (b) with the note "oscillated: fix X applied and reverted N times".
+  - Questions of bucket (b) follow the holistic cap of #8: at most `QUESTION_CAP` per call, added to the discovery questions inside the flow's `ROUND_CAP` (read both with `afm protocol`).
+
+Procedure (advisory mode; gating mode reuses steps 2 to 5 and replaces 6 to 8 with the sorting above):
+
+1. **Pre-check.** Run `afm preflight` (exit 3: no `docs/.afm-version`, redirect to `afm init` or `afm refactor`). Find the feature: the `<feature>` argument, or the folder with a materialized `docs/features/NNN-*/tasks.md`.
+   - Zero features with tasks: say "Nothing to analyze: run `afm tasks` first." and stop.
+   - Several: ask in plain words with up to 4 candidates.
+
+2. **Progressive load** (token-efficient, read only what is needed):
+   - `docs/features/NNN-feature/spec.md`: § 1, § 2, § 3, § 5, § 6 and, if present, § 7 Clarifications.
+   - `docs/features/NNN-feature/plan.md`: § 1, § 2, § 4, § 5, § 6 and § 7 (validation against the invariants).
+   - `docs/features/NNN-feature/tasks.md`: the full list with US and RF refs, `[P]` markers and phases.
+   - `docs/prd.md`: § 3 persona and § 4 RFs (only the sections relevant to the linked US).
+   - `docs/ust.md`: the US row linked to the feature.
+   - `docs/ach.md`: § 1 stack and § 3.1 component-type mapping.
+   - `docs/afm.md` § 3: the hard rules that apply to the feature's scope.
+   - [`../PRINCIPLES.md`](../PRINCIPLES.md): the universal invariants (the constitution).
+
+3. **Build the semantic models** (in memory, not in a file):
+   - **Requirements inventory:** each Gherkin scenario of spec § 3 gets an id `S1`, `S2`, ...; each success-criterion checkbox of § 2 becomes `C1`, `C2`, ...
+   - **Component inventory:** each row of plan § 2 with its file path.
+   - **Boundary inventory:** each boundary of plan § 5.
+   - **Task coverage map:** each task `T0NN` maps to a scenario (S?), a component (§ 2) or a hard rule (§ 7).
+   - **Constitution rule set:** the universal invariants (`PRINCIPLES.md` § 1 to 8) plus the hard rules (`afm.md` § 3) marked in `plan.md` § 7.
+
+4. **Detection passes** (limit: **50 findings in total**; group the excess in an "overflow summary"). `afm feature lint` already produced A, C, D, E and T. You add B and F, and what is semantic in C and D.
+
+   - **A. Coverage gaps** (HIGH by default): a scenario with no RED+GREEN pair; a new component with no creation task in Phase 1 or 2; an applicable hard rule with no task that adds the check (rule 16 needs a Zod schema at the boundary); a missing Phase 4 reconciliation (ach update, ADR, US status, the `status` frontmatter key of the three files set to `done`); an external boundary with no input-validation task plus a procedure task that consumes it.
+   - **B. Constitution violation** (CRITICAL by default): the plan chose a stack that diverges from `ach.md § 1` (#5, do not invent); the spec invented a § 2 criterion not derivable from the linked US (#5); a task skips RED (rule 1, TDD: any GREEN with no RED immediately before it); a plan § 4 decision with no rejected alternative and reason; a plan § 6 item with no rejected simpler alternative; a #6 bright line crossed with no confirmation (a destructive operation with no diff, an automatic push, a plugin edit with no confirmation). Check the session history when you can infer it. *Applying autonomously inside the scope of an invoked op is NOT a violation: #6 expects it.*
+   - **C. Inconsistency** (HIGH or MEDIUM): terminology drift (an entity with different names across spec, plan and ust); a plan § 2 component type not mapped in `ach.md § 3.1`; tasks citing a `US-NNN` missing from `ust.md`; a plan § 7 rule marked `[x]` applicable but contradicted by the content (rule 16 marked, but § 5 has no Zod); a spec § 3 scenario citing an entity field absent from the `ach.md` mini-ER.
+   - **D. Ambiguity** (LOW or MEDIUM): vague adjectives with no measurable criterion (`fast`, `scalable`, `secure`, `intuitive`, `robust`) in § 2; unresolved placeholders (`TODO`, `TKTK`, `???`, `{{x}}`) in required sections; open `[NEEDS CLARIFICATION:]` markers (a strong signal for `afm clarify`).
+   - **E. Underspecification** (HIGH or MEDIUM): a scenario with no observable `Then` ("Then it works correctly"); a task with no `US-NNN` or `RF-NN`; a § 2 criterion with no testable `[ ]`; a plan § 5 boundary with no `errors` codes.
+   - **F. Duplication** (LOW): near-duplicate Gherkin scenarios; repetitive tasks in the same file or scope; redundant § 2 criteria.
+   - **INVENTION** (HIGH by default): the artifact states something its source does not contain, for example a plan component, a spec criterion or a number that no US, RF, code or page read supports. The fix is to cite the source or mark it `[TBD]` (#4, #5).
+
+   **Verifying a produced artifact.** When you check an artifact against its source (a summary, a port, a migration, a generated doc), check three failures: **loss** (the source holds it, the artifact dropped it), **invention** (the artifact holds it, the source does not), and **inversion** (the artifact says the opposite of the source). A check of loss alone passes an artifact that is wrong in the other two ways.
+
+5. **Severity assignment:**
+
+   | Severity | Criterion |
+   |---|---|
+   | **CRITICAL** | Violates a universal invariant (`PRINCIPLES.md` § 1 to 8) OR an applicable hard rule of `afm.md § 3` fails its mechanical trigger |
+   | **HIGH** | A functional coverage gap (scenario or component with no task), OR blocking underspecification, OR a load-bearing finding that changes the inventory of one isolated feature or task |
+   | **MEDIUM** | A guiding principle (`afm.md § 1.3`) is violated (this includes the downgraded rules: types at boundaries, Rule of Three, saga ordering), terminology drift, incomplete complexity tracking, ambiguity in an optional section |
+   | **LOW** | Style or wording. A placeholder in an optional section. Minor duplication with no effect on execution |
+
+6. **Produce a compact report**, markdown in chat. It does **NOT** write to a file:
+
+   ```markdown
+   ## Analysis of Feature {{NNN}} — {{title}}
+
+   | ID | Category | Severity | Location(s) | Summary | Recommendation |
+   |---|---|---|---|---|---|
+   | F01 | Coverage Gap | HIGH | tasks.md (no T for scenario S2) | Scenario "<name>" has no RED/GREEN | Add T0NN RED + T0NN+1 GREEN before Phase 3 |
+   | F02 | Constitution | CRITICAL | plan.md § 7 + § 5 | Rule 16 marked [x] but Zod missing from § 5 contracts | Add the Zod schema to § 5 boundary <name> |
+   | F03 | Ambiguity | MEDIUM | spec.md § 2 | "Works fast" with no measurable criterion | Replace with "p95 < Xms" or similar |
+
+   ### Coverage Summary
+
+   | Scenario/Component/Rule | Has task? | Task IDs | Notes |
+   |---|---|---|---|
+   | S1 (happy path) | yes | T004 (RED), T005 (GREEN) | |
+   | S2 (error) | no | — | F01 |
+   | Component: `src/features/<feature>/domain/x.ts` (new) | yes | T001, T004, T005 | |
+   | Component: `src/lib/storage/presigned.ts` (new) | partial | T009, T010 | no retry test task |
+   | Hard rule 16 (Zod boundary) | no | — | F02 |
+
+   ### Metrics
+
+   - Total scenarios: X / Total tasks: Y
+   - Scenario-to-task coverage: Z%
+   - Open `[NEEDS CLARIFICATION:]` markers: N
+   - Critical issues: M / High: K / Medium: L / Low: P
+   - Total findings: X (of 50 max, overflow: Y grouped)
+   ```
+
+7. **Next actions:**
+   - A **CRITICAL** exists: "N CRITICAL issue(s). Resolve before you start T001 (use `afm clarify` for ambiguity, or edit manually)."
+   - Only **MEDIUM** or **LOW**: "OK to proceed. Optional suggestions are in the tables above."
+   - A **HIGH** with no CRITICAL: "Consider resolving before T001: coverage gaps tend to surface as production bugs."
+
+8. **Offer remediation:** ask the question `remediation` (`afm ask analyze --scope <slug>`). `top-5` applies the 5 edits in severity order and reports what changed with the paths (#6: "yes" is the approval; review with `git diff`). `top-10` does the same with 10. `report-only` closes with "Report complete. Addressing manually." Edits to `spec.md`, `plan.md` or `tasks.md` invalidate a recorded delivery approval (`afm approve --check <NNN>`); the next gate asks again.
+
+## Anti-patterns
+
+- ❌ **Advisory mode:** applying fixes the operator did NOT ask for. The report is read-only; remediation runs only on `top-5` or `top-10` (then #6 authorizes applying and reporting). *(In gating mode it is the opposite: bucket (a) auto-corrects with no question, because the `deliver` gate is the approval.)*
+- ❌ **Advisory mode:** writing the report to a file. It is chat-only: a visual audit, not a versioned artifact. *(In gating mode there is no chat report: the sorted result goes back to the caller.)*
+- ❌ Recomputing by hand what `afm feature lint` already reported. Start from its findings.
+- ❌ Exceeding 50 findings. Group the overflow at the end of the report.
+- ❌ Inventing a finding with no evidence (#5). List only what is visible in the files read.
+- ❌ **Advisory mode:** blocking T001. Analyze is a suggestion and the operator decides. *(In gating mode the loop until zero CRITICAL and HIGH before proceeding is the point.)*
+- ❌ **Gating mode:** turning a cosmetic finding into a gate question. Only load-bearing bucket (b) findings, with an articulable "what breaks if this is wrong", become a question. The rest auto-corrects or becomes `[TBD]` (#6 corollary and #8 earned).
+- ❌ Marking everything CRITICAL. Apply the severity matrix strictly: CRITICAL is an invariant violation or a hard rule with a failing mechanical trigger.
+- ❌ Skipping the coverage table. It is the most valuable output: an explicit map of gaps.

package/content/ops/clarify.md

@@ -0,0 +1,86 @@
+---
+type: op
+description: Finds the ambiguities in a spec and asks at most five questions to close them.
+load: warm
+writes: ["docs/features/*/spec.md"]
+composes: []
+needs: ["feature"]
+---
+# Sub-flow: clarify feature ambiguities (`clarify`)
+
+> **Form** — effect: `spec.md § 7` · trigger: `afm clarify`, composition · precondition: `spec.md` with marker · composed by: `deliver` 0.E · **degree of freedom: low**
+
+Triggers: `afm clarify [<feature>]`, or natural language ("resolve markers", "clear ambiguity in feature X", "scan for gaps").
+
+> This replaces the "soft inline block" of [`plan.md`](plan.md) step 3: `afm plan` suggests `afm clarify` as the recommended path.
+>
+> **Orchestrated mode:** when [`deliver.md`](deliver.md) calls this op, it batches the irreducible questions (up to `QUESTION_CAP` per call) instead of one question per turn. See its suppression contract.
+
+**Questions.** Every question this op puts to the operator is derived from the spec, so its text cannot live in a question file. Ask each as a dynamic question: a header of at most 12 characters, 2 to 4 options with the recommended one first and its reason, through whatever question facility the host offers, or in plain chat. The fixed decision of this op is data: `questions/clarify.questions.yaml`, asked with `afm ask clarify --scope <slug>`.
+
+Procedure:
+
+1. **Pre-check.** Run `afm preflight` (exit 3: no `docs/.afm-version`, redirect to `afm init` or `afm refactor`). Find the feature. With the `<feature>` argument, use it. Without it, run `afm feature status <NNN> --json` over the folders of `docs/features/` and keep those whose `blockers` name an open `[NEEDS CLARIFICATION:]`.
+   - Zero features with markers: say "No feature has an open [NEEDS CLARIFICATION:]. To run a structured scan anyway, name the feature." and stop.
+   - Several: auto-detect the active feature (discover-first #2): the branch, the most recently touched spec, the hint. Ask in plain words (up to 4 candidates) only when it is genuinely ambiguous.
+
+2. **Structured scan (9-category taxonomy).** Read `spec.md` (and `plan.md`, when it exists) of the feature. Classify each category as `Clear`, `Partial` or `Missing`. Build an internal coverage map and do not write it to a file.
+
+   | # | Category | What it checks |
+   |---|---|---|
+   | 1 | Functional Scope & Behavior | spec § 1 problem, § 2 criteria, explicit out-of-scope |
+   | 2 | Domain & Data Model | entities, attributes, relations, lifecycle (cross-checks `docs/ach.md` when relevant) |
+   | 3 | Interaction & UX Flow | spec § 3 Gherkin scenarios: happy path plus errors |
+   | 4 | Non-Functional Quality | performance, scalability, reliability, observability, security, compliance (spec § 2 or § 5) |
+   | 5 | Integration & External Dependencies | external boundaries in plan § 5 (if it exists) or marked in the assumptions |
+   | 6 | Edge Cases & Failure Handling | the most likely error scenario of spec § 3, plus others |
+   | 7 | Constraints & Tradeoffs | technical constraints, rejected alternatives |
+   | 8 | Terminology & Consistency | canonical terms against synonym drift |
+   | 9 | Completion Signals | the spec § 2 criteria are testable and measurable |
+
+3. **Build a prioritized question queue** (5 questions at most per session). Heuristic: **Impact x Uncertainty**. Rank higher-impact categories first (architecture, data modeling, task decomposition, test design, UX behavior, compliance), then higher uncertainty first (`Missing` before `Partial`).
+   - Skip `Clear` categories.
+   - **Auto-resolve through discovery (principle #2)** before you ask: try to answer each candidate from the code, `docs/` or a nasca research (`nasca-research`). A question with an evidence-backed answer becomes an auto-resolved clarification, logged in § 7 with the note `(inferred from discovery)`. It does not enter the queue. Only irreducible product-intent questions reach the operator.
+   - Filter: a question must materially affect a downstream step. A stylistic question does not count.
+   - Each question needs 2 to 5 options, or an answer of 5 words or fewer.
+   - If more than 5 categories are `Missing` AND more than 5 markers are open, this is severe underspecification: ask the question `underspecified`.
+
+4. **Sequential loop: ask ONE question per turn** (universal principle #8, see [`../PRINCIPLES.md`](../PRINCIPLES.md)). These are the irreducible product-intent questions left after the auto-resolve, and they are the point of this op.
+   - **Recommendation-first.** Weigh the options (best practice, common patterns, risk reduction, alignment with the goals of the spec and the PRD) and pick the strongest. **The first option is always the recommendation**, marked as recommended with a 1 to 2 sentence reason.
+   - List the other options neutrally, with the trade-off of each. The operator can always answer outside the list.
+   - For a question with no natural 2 to 5 options (a field name, say), offer "Accept suggestion: X" as the recommendation and let the operator type another value.
+   - Never reveal future questions of the queue.
+
+5. **After each accepted answer** (principle #6: materialize the integration and continue, with no blocking gate):
+   - Add a line `- Q: <question> → A: <answer>` to the `## Clarifications` section under `### Session YYYY-MM-DD` in `spec.md`. Create the section right after § 6 Dependencies and today's subheading when they do not exist.
+   - Apply the clarification to the section it concerns:
+     - **Functional ambiguity** → § 1 problem or § 2 success criterion (replace the vague statement, do not duplicate it).
+     - **User interaction or actor** → § 3 Gherkin scenarios (update Given/When/Then).
+     - **Domain and data** → § 5 assumptions (field, type, reason).
+     - **Non-functional** → § 2 criterion (turn a vague adjective into a metric: `fast` becomes `p95 < 200ms`).
+     - **Edge case** → a new § 3 error scenario or a § 5 assumption.
+     - **Terminology** → normalize the term across all sections; keep the original once, marked `(previously "X")`, when needed.
+     - **Constraints** → § 4 out of scope or § 5 assumption.
+     - **Completion signals** → a § 2 criterion with a testable checkbox.
+   - If the clarification invalidates an earlier vague statement, replace it and leave no contradiction.
+   - Remove the matching `[NEEDS CLARIFICATION:]` marker from its section.
+   - **Save atomically after each integration.** Do not buffer several answers. Review happens through `git diff`.
+   - Editing the spec invalidates a recorded delivery approval (`afm approve --check <NNN>` exits 1). That is expected: the next gate asks again.
+
+6. **Stop when** any of these is true: all critical ambiguities are resolved (the queue is empty); the operator signals completion ("done", "good", "no more", "proceed", "stop"); the session reached 5 questions asked (a retry of the same question does not count). When no `[NEEDS CLARIFICATION:]` marker remains and the spec frontmatter `status` is `draft`, set it to `clarified` (the frontmatter, never a body line).
+
+7. **Report to the operator:**
+   - The path of the updated spec, the number of questions asked and answered, the sections touched (§ 1, § 3, § 5, ...).
+   - **Coverage summary**, one value per category: `Resolved` (was Partial or Missing, now addressed), `Deferred` (past the quota, or better suited to `plan`), `Clear` (already sufficient), `Outstanding` (still Partial or Missing but low impact).
+   - Re-run `afm feature status <NNN> --json` and report the remaining `blockers`.
+   - **Next step:** if high-priority `Outstanding` or `Deferred` items remain, "run `afm clarify` again after starting the plan" or consider re-running `afm specify`. Otherwise "the spec is ready, run `afm plan`".
+
+## Anti-patterns
+
+- ❌ Asking more than 5 questions in one session. Severe underspecification calls for a re-spec, not an endless clarify.
+- ❌ Skipping principle #8: every question carries a recommendation as its first option.
+- ❌ Asking a question that discovery (#2) already answered. Only irreducible product questions reach the queue.
+- ❌ Inventing an answer when the operator disagrees with the recommendation. The recommendation is a rejectable hypothesis, not a guess (#4: `[TBD]` beats invention).
+- ❌ Buffering several integrations. Save after each answer.
+- ❌ Modifying `plan.md` or `tasks.md`. `afm clarify` touches **only** `spec.md`; everything else comes from re-running `afm plan` and `afm tasks`.
+- ❌ Revealing future questions of the queue before reaching them.