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

package/content/core/prd.md

@@ -0,0 +1,141 @@
+---
+type: core
+description: 'The product: the job it does, the pain it removes and who it is for.'
+load: warm
+materializes_to: 'docs/prd.md'
+---
+
+# PRD — {{nome do produto}}
+
+> Product Requirements Document. This is a living document. Edit it in place.
+> Scope changes must pass through the product owner before merge.
+
+
+## 1. Summary
+
+{{The product in 1 paragraph. What it does, who uses it, what the concrete gain is. No marketing jargon. Explain it the way you would explain it to the CTO of another team, in 30 seconds.}}
+
+Value proposition in one sentence: *"{{single sentence that captures why this exists}}"*
+
+## 2. Problem & Opportunity
+
+- **Observed pain:** {{who feels it, in what context, what they do today to work around it}}.
+- **Why now:** {{technology/market/regulation that unlocked this now. Existing alternatives do not solve it, or got worse}}.
+- **Size of the gain:** {{eliminate X class of problem, reduce Y latency, gain Z compliance}}.
+
+## 3. Target User & Jobs-to-be-done
+
+**Primary persona:** {{specific role at a specific type of company}}.
+
+**Typical companies:**
+- {{type A with symptom}}.
+- {{type B with symptom}}.
+
+**Jobs-to-be-done:**
+- When {{context}}, I want {{result}} so that {{outcome}}.
+
+**Typical scenarios:**
+- "{{1-sentence description of the trigger}}"
+
+## 4. Functional Requirements (RF)
+
+| ID | Requirement | Priority |
+| --- | --- | --- |
+| RF-01 | {{1-sentence description}} | P0 |
+| RF-02 | {{description}} | P0 |
+
+*[TBD — fill in as features are built.]*
+
+## 5. Non-Functional Requirements (RNF)
+
+| ID | Type | Criterion |
+| --- | --- | --- |
+| RNF-01 | Availability | {{e.g. 99.5% monthly for the dashboard}} |
+| RNF-02 | Latency | {{e.g. p95 < 500ms on operation X}} |
+| RNF-03 | Security | {{e.g. tokens encrypted at rest}} |
+
+*[TBD.]*
+
+## 6. Goals by Stage
+
+### 6.1 MVP — *"hello world end-to-end"* [PROPOSAL — confirm]
+
+**Objective:** {{1 paragraph on what must work to reach MVP}}.
+
+**Minimum scope:** {{list of RFs included}}.
+
+**Out of the MVP:** {{list of what comes later}}.
+
+**Acceptance criteria:** {{reproducible steps}}.
+
+**Success metric:** {{numeric and measurable}}.
+
+### 6.2 GTM — *"design partners"* [PROPOSAL — confirm]
+
+**Objective:** {{N design partners in production with regular feedback}}.
+
+**Positioning:** *"{{tagline}}"*. Focus on {{specific segment}}.
+
+**Additional scope:** {{new RFs in GTM}}.
+
+**Success metric:** {{NPS, retention, or another indicator}}.
+
+### 6.3 First N — *"operational sustainability"* [PROPOSAL — confirm]
+
+**Objective:** {{scale that runs without human heroics}}.
+
+**Additional scope:** {{billing, multi-tenant isolation, SLA, etc.}}.
+
+**Guardrails:** {{churn, NPS, uptime}}.
+
+## 7. Metrics & North Stars [PROPOSAL — confirm]
+
+**North Star:** **{{single metric}}** — {{why this one, not another}}.
+
+**Input metrics (the team moves these directly):**
+- {{metric A}}.
+- {{metric B}}.
+
+**Guardrails (must not get worse):**
+- {{metric X with threshold}}.
+
+## 8. Risks & Mitigations [PROPOSAL — confirm]
+
+| Risk | Impact | Probability | Mitigation |
+| --- | --- | --- | --- |
+| {{risk}} | High/Medium/Low | High/Medium/Low | {{how we mitigate it}} |
+
+## 9. Out of Scope (v1)
+
+- **{{item explicitly out of scope}}.** {{Reason.}}
+
+## 10. Glossary
+
+- **{{term}}** — {{1-sentence definition}}.
+
+## 11. Naming — product vs technical identifiers
+
+- **User-facing product name:** "{{canonical name}}" — use it in UI, emails, titles, and external copy.
+- **Technical identifiers do NOT change.** They are URL-safe and part of the infra:
+  - {{e.g. cookies, buckets, localStorage keys, folder paths — list which ones stay stable, and why}}.
+
+### 11.1 App-facing string language
+
+- **The language this product shows its own users:** {{language, or `[TBD]`}}.
+
+This is a **product** decision and it lives here, not in `afm.md`. It is declared, never enforced.
+
+The methodology writes every artifact in English — the docs, the code, the comments, the tests,
+the rule text. This field exists because the strings your users read are the one exception. Without
+this field, the exception is only prose. A language migration then has no way to tell an artifact
+from a product string. It would translate your UI.
+
+**Who reads it.** `afm path ops/update.md` reads it before a language migration and excludes those strings
+by construction. `reconcile` reads it before it signals an artifact written in another language.
+
+**`[TBD]` is a valid answer** and it is the default. It makes the migration stop and ask through
+`afm ask init`. It never lets the migration choose a language for you.
+
+---
+
+*Current state and living history are in `/docs/ust.md` (backlog) and `/docs/ach.md` (architecture). Process decisions are in `/docs/afm.md`.*

package/content/core/protocol.md

@@ -0,0 +1,158 @@
+---
+type: core
+description: The autonomy posture, declared per job, that parametrizes the loop.
+load: hot
+materializes_to: 'docs/protocols/'
+---
+
+# Protocol — the autonomy posture, declared per job
+
+
+A **protocol** declares how the agent and the human split decisions in a delivery. Before v4, this posture was global and implicit. It was the same for a throwaway POC and for a production refactor, with one on/off switch (`"go"`).
+
+A protocol is **data**, not code. It sets parameters for operations that already exist. It does not create a new execution path.
+
+---
+
+## 1. The fields
+
+| # | Field | What it decides |
+| --- | --- | --- |
+| 1 | `plan` | **planning** posture: `auto` \| `assisted` |
+| 2 | `exec` | **execution** posture: `auto` \| `assisted` |
+| 3 | `policy` | the **escalation contract** — the mechanical conditions that force a stop |
+| 4 | `cadence` | when `reflect` / `evolve` trigger |
+| 5 | `delegation` | subagent delegation ceiling (§ 5) |
+
+---
+
+## 2. The parameters
+
+Each row is a literal that used to live scattered, and now has a name. **The `default` column reproduces pre-v4 behavior.** No protocol present means no change.
+
+| Parameter | Where it applies | default | P1 | P2 | P3 |
+| --- | --- | --- | --- | --- | --- |
+| `RETRY_CAP` | `core/afm.md § 5.1` — retries before escalation | `2` | `2` | `1` | `2` |
+| `MAX_DISCOVERY_ROUNDS` | `afm path ops/deliver.md` Phase 0 | `2` | `2` | `3` | `3` |
+| `QUESTION_CAP` | `PRINCIPLES.md` #8 — questions per call | `4` | `4` | `4` | `4` |
+| `ROUND_CAP` | `PRINCIPLES.md` #8 — rounds in the flow | `2` | `0` | `4` | `2` |
+| `HALT_PER_PHASE` | `afm path ops/deliver.md` Phase 3 | chosen at the gate | `off` | `on` | `off` |
+| `SUPPRESS_SUBGATES` | `deliver` suppression contract | `on` under orchestration | `on` | `off` | `on` |
+| `PLAN_THRESHOLD` | `core/afm.md § 2` step 3 — when to require a plan file | heuristic `§ 2.1` | `§ 2.1` | report before editing | `§ 2.1` |
+| `UNKNOWN_POLICY` | what to do with an irreducible unknown | ask | `[ASSUMIDO:]` | ask | ask in phase 1 |
+| `MAX_PARALLEL_SUBAGENTS` | `afm path ops/deliver.md` 0.C — research topics per round | `4` | `4` | `2` | `6` |
+| `REFLECT_EVERY` | `hooks/afm-session-end.sh` — deliverables closed before `reflect` becomes mandatory | `1` | `1` | `1` | `1` |
+| `EVOLVE_EVERY` | `hooks/afm-session-end.sh` — deliverables closed before `evolve` becomes mandatory; also reported by `hooks/afm-health.sh` | `3` | `3` | `3` | `3` |
+| `REFLECT_TASKS` | `hooks/afm-session-end.sh` — per-task floor, when work does not open a feature folder | `20` | `20` | `20` | `20` |
+
+> **The three cadence parameters are declared on one line**, in `docs/_focus.md`: `cadence: reflect=1 evolve=3 tasks=20`. Every key accepts `off`, which turns off that arm and leaves the other one standing. An absent key keeps the default in this table. `hooks/lib/afm-cadence.sh` is the single reader (hard rule 34).
+>
+> **`20`, not the `4` this table used to carry — measured, not guessed.** `hooks/lib/afm-cadence.sh` hardcoded the default two ways at once: `4` here, `20` there, since 3.9.0-rc.9. The code's number is the one with a measurement behind it: tasks closed per session, read off this repository's own ledger on 2026-08-29, were 8, 17, 18, 29 and 150 — a median of 18, rounded up to 20. At `4`, the threshold came due four times inside a median session, and `Stop`'s cap of one block per session (G2) saturated it by construction — it fired on every session that did any work, which reads as noise and gets ignored. `20` comes due about once per median session, which is what G2 was sized for. This row now matches the code; no runtime behavior changed.
+
+`ROUND_CAP = 0` in P1 makes "no questions" mechanical, not a promise. With zero rounds available, every irreducible unknown falls to `UNKNOWN_POLICY`.
+
+> **`MAX_PARALLEL_SUBAGENTS` is the first of two rows whose `default` does NOT reproduce pre-v4 behavior.** Before, fan-out had no limit. The exception is deliberate. The delegation ceiling in § 5 always governed *what* gets delegated (`none`/`read-only`/`full`), never *how many*. A fan-out with no ceiling multiplies cost and latency without multiplying signal. Each subagent re-establishes context, re-explores, and returns a report the parent must reread. An explicit number costs less than the prose "delegate sparingly," which is not verifiable.
+
+> **`REFLECT_EVERY`/`EVOLVE_EVERY` are the second exception, and it is deliberate.** Before, the threshold (`3-4`) lived **hardcoded in `afm-health.sh`** and produced a nudge at `SessionStart` — the worst possible spot. It sat thousands of tokens before the decision moment, and out of context when the delivery ended. The measured result: `reflect` triggered almost never, with the operator reporting whole protocols with zero reflections.
+>
+> This repo names the cause: *a primitive whose trigger is "remember to do it" has no trigger.* Moving the threshold into the project artifact lets `Stop` evaluate it (§ 6, **hard** category) instead of only reporting it.
+>
+> **The unit is the deliverable**, not the task. It is what the ledger already counts (`afm-capture.sh` appends a `deliverable` event), and it is the granularity the operator stated — *"reflect at the end of each protocol, evolve every N protocols"*. `REFLECT_EVERY = 1` is literally that.
+>
+> **`REFLECT_TASKS` exists because `deliverable` alone would be a dead trigger.** The `deliverable` event fires only when every task of the `tasks:` list of a `docs/features/*/tasks.md` is done. Work that never opens a feature folder — most work, per `§ 2.1` — never emits it. Measured in the plugin's own repo while building this feature: **25 `task` events, zero `deliverable` events**, over two months of real work. A gate anchored only on the first counter would never fire. It would be indistinguishable from a working gate, which is the worst property a gate can have.
+>
+> So the condition is a **disjunction**: `NDEL >= REFLECT_EVERY` **OR** `NTASK >= REFLECT_TASKS`. The first catches work that went through the delivery loop. The second catches the rest.
+
+---
+
+## 3. The three presets
+
+| | P1 — Autonomous | P2 — Assisted | P3 — Planned Autonomous |
+| --- | --- | --- | --- |
+| `plan` | `auto` | `assisted` | `assisted` |
+| `exec` | `auto` | `assisted` | `auto` |
+| For | POC, MVP — speed over depth | pair programming, human as senior dev | plans together, executes alone |
+| Gate | none (bright lines only) | per phase | **one**, at the plan→exec transition |
+| Cadence | `REFLECT_EVERY`/`EVOLVE_EVERY` (§ 2) — default `1`/`3` deliverables | same | same — phase 2 closes with mandatory `reflect` |
+
+**What P1 does NOT relax:** a hard rule with an executable trigger stays 0/1. Security posture is not negotiable (`core/afm.md § 1.3` — hardening does not trade for speed). What relaxes is **depth**: coverage, edge-case exhaustiveness, naming refinement.
+
+**P2 is compositional, not introspective.** P2 does not call `afm ask` merely because it is unsure. Self-reported confidence is not an executable trigger, per principle #3 (CRITIC). P2 is exactly three knobs: `SUPPRESS_SUBGATES=off`, `RETRY_CAP=1`, `HALT_PER_PHASE=on`.
+
+**P2 floor.** Below the feature-folder heuristic (`§ 2.1`), the assisted posture degrades to **"report before commit"**. Calling `afm ask` at every step for a trivial change is noise that makes people turn the protocol off. Above the heuristic, the change stops being a loose task and falls into the runner's path.
+
+**P3 transition gate** — a mechanical criterion, not judgment: `plan.md` and `tasks.md` with no open `[NEEDS CLARIFICATION:]` (`grep`, 0/1).
+
+---
+
+## 4. What the protocol does NOT govern
+
+Invariants that hold in **every** protocol, including P1:
+
+- **Bright lines** (`PRINCIPLES.md` #6): destructive action, editing the canonical plugin, `git push`, hard rule 11.
+- **`reconcile`** — always on, it proposes and never applies. A passive signal is not approved scope.
+- **Self-evolution operations** (`evolve` and its mechanisms) — a **mandatory gate**, a first-class exception alongside the bright lines. (This used to read "`evolve` has no `AUTONOMY=high` path." The flag is now replaced by a protocol. The sentence had to stop denying a flag that no longer exists.)
+- **`RETRY_CAP` minimum of 1** — zero retries would turn every transient failure into an escalation.
+
+---
+
+## 5. Subagent: delegation ceiling, not inheritance
+
+The harness already propagates permission **downward, with no override**. A subagent is at most as loose as its parent, and plugin subagents ignore `permissionMode`. So the protocol **is not inherited**. It declares a **ceiling**.
+
+| `delegation` | Means |
+| --- | --- |
+| `none` | does not delegate writes — the gate stays with the parent (P2 default) |
+| `read-only` | delegates only search/read (`Explore`) |
+| `full` | delegates writes — `SubagentStart` injects the hard rules (default for P1 and P3-exec) |
+
+The escalation contract (field 3) **does not flow down**. A subagent has no useful `afm ask` channel — the question would die in its own transcript.
+
+**Two dimensions, not one.** `delegation` answers *what* can be delegated. `MAX_PARALLEL_SUBAGENTS` (§ 2) answers *how many at once*. The two are independent — `read-only` with no ceiling can still fire N parallel searches. The ceiling applies to the fan-out of a single turn, not to the session total. A sequence of rounds is still governed by `MAX_DISCOVERY_ROUNDS`.
+
+When the desired fan-out exceeds the ceiling: **prioritize, do not split into batches.**
+
+- Running 6 topics under a ceiling of 4 means investigating the 4 that move the decision most.
+- Log the other 2 as `[NEEDS CLARIFICATION:]`.
+- Do not run two rounds of 3. That pays the spawn cost twice for the same signal.
+
+---
+
+## 6. Hard, counted, and soft
+
+| Category | Mechanism | Who enforces |
+| --- | --- | --- |
+| **Hard** | cadence counters derived from the ledger (`afm-capture.sh` appends → `hooks/lib/afm-cadence.sh` derives), 0/1 gates in `test/`, **`REFLECT_EVERY` at `Stop`** (blocks session end until the reflection exists as an artifact) | the harness |
+| **Counted** | `RETRY_CAP` and `QUESTION_CAP` (self-observable by the model within its own context window — a hook here would duplicate information already present: YAGNI) · `MAX_PARALLEL_SUBAGENTS` (reportable only *after the fact* — the fan-out goes out in a single message, before the first `SubagentStart` fires. The v3.5.0 blocking carve-out is **named and singular**: it applies only to `Stop`, not to `SubagentStart` — see `hooks/README.md`) · `ROUND_CAP` (a counter, not a promise — see note below) | no one — it is counted, and overflow is observable, but nothing blocks |
+| **Soft** | the posture described in prose in the protocol file | the model cooperates |
+
+> **Design correction (2026-07-25).** The plan called for denying the ask tool as the hard mechanism for P1, through a per-skill tool denylist. It **does not fit this architecture**. A tool denylist is static, **per-skill** frontmatter that not every harness has, and the protocol is **data** layered on a **shared** runner (`deliver` serves all three presets). A separate skill just for P1 would multiply the listing — the exact problem v4 exists to solve.
+> The real P1 mechanism is **`ROUND_CAP = 0`** — **counted**, in the § 6 category, not hard. With no question round available, every irreducible unknown falls to `UNKNOWN_POLICY` and becomes `[ASSUMIDO:]`. It is a counter, not a promise — and a counter is exactly the form that survives the Claude 5 generation cut.
+
+A declarative artifact in the repo **does not bind the harness**. The official precedent: Claude Code ignores `defaultMode: "auto"` coming from the project's `.claude/settings.json`, *"so a repository cannot grant itself auto mode"*. Two design consequences follow:
+
+1. **Every field declares which category it lives in.** A soft-only field with no matching gate is prescriptive prose. It is exactly what Claude 5 generation guidance says to cut.
+2. **P1 is not granted by the repo.** `docs/protocols/p1.md` can exist and be versioned. But P1 becomes **current** only through an explicit act in the session. A `git pull` never changes the autonomy posture.
+
+> **Note — `permissions.deny`.** It is left out of the table above because it is a harness mechanism class, not something AFM configures (cited once in the repo, with no `settings.json` that configures it).
+
+---
+
+## 7. Current protocol
+
+**`afm protocol` is the skill that reads and writes this layer.** With no argument it reports the current posture. With an argument (`afm protocol p2`) it materializes the preset into `docs/protocols/` and writes the `protocol:` line below. Editing the line by hand does the same thing. The skill exists so the presets stay data instead of prose someone retypes.
+
+A line in `docs/_focus.md`:
+
+```
+protocol: p3
+cadence: reflect=1 evolve=3
+```
+
+The `cadence:` line is optional. It overrides the § 2 defaults — `reflect=off` turns off the entire `Stop` block (guard G3 in `afm-session-end.sh`). When absent, the current preset's defaults apply.
+
+Read by `SessionStart` (marginal cost ~0 — the hook already injects `_focus.md`). Also read by step 1 (READ) of `core/afm.md § 2`, which already lists this file. **A project with no such line runs pre-v4 behavior** — the default for each parameter in the § 2 table.
+
+**The config is the floor of both lines.** `[protocol] preset` and `[cadence]` in the layered config (`afm config get protocol.preset`) are in force where `docs/_focus.md` says nothing: a preset the config sets stands in for a missing `protocol:` line, and a cadence value replaces the default for a key the `cadence:` line omits. A key the organisation locks (`[org] locked`) ignores the focus file: `afm protocol <name>` refuses another preset (exit 1) and the hooks read the locked value. A project config can never grant p1; only a person's `afm protocol p1 --i-mean-it` does.
+
+An already-bootstrapped instance receives `protocol: [TBD]` from `afm update`. Assuming the posture the owner wants would be invention (principle #4).

package/content/core/ust.md

@@ -0,0 +1,65 @@
+---
+type: core
+description: The user stories, which are the oracle for every acceptance criterion.
+load: warm
+materializes_to: 'docs/ust.md'
+---
+
+# UST — User Stories
+
+> Living backlog of stories. Every new feature or change starts as a US.
+> Status flows: `draft` → `ready` → `in_progress` → `done` (or `cancelled` with a reason).
+
+## Conventions
+
+- **ID:** `US-NNN` (3 digits, zero-padded — `US-001` to `US-999`).
+- **Cross-reference:** always by ID (`RF-NN`, `RNF-NN`, `US-NNN`).
+- **Criteria:** Gherkin (`Given/When/Then`). 1 or more scenarios per US.
+- **Status:** update in place, in the commit that changes the real state.
+
+## Summary
+
+| ID | Title | Category | Priority | Status |
+| --- | --- | --- | --- | --- |
+| US-001 | {{Título}} | {{categoria}} | P0 | ready |
+
+---
+
+## Epic {{Nome do Épico}}
+
+### US-001 — {{título objetivo, "[Persona] [verbo] [outcome]"}}
+
+- **Persona:** {{quem do PRD §3}}.
+- **Pain point:** {{1 sentence on the workaround they use today}}.
+- **Story:** As a {{persona}}, I want {{ação}} so that {{outcome mensurável}}.
+
+**Acceptance criteria:**
+
+```gherkin
+Scenario: {{nome do cenário happy path}}
+  Given {{precondição}}
+  And {{precondição adicional se houver}}
+  When {{ação do user}}
+  Then {{resultado esperado observável}}
+  And {{efeito colateral verificável}}
+```
+
+```gherkin
+Scenario: {{cenário de erro mais provável}}
+  Given {{precondição}}
+  When {{ação do user em estado inválido}}
+  Then {{erro esperado, classificação tipada}}
+  And {{nada de side-effect de DB}}
+```
+
+**Metadata:**
+- **Priority:** P0
+- **Status:** ready
+- **RF:** RF-NN
+- **RNF:** RNF-NN (if applicable)
+- **Success metric:** {{how to measure that the user job is done}}
+- **Dependencies:** US-NNN, US-NNN (if any)
+
+---
+
+*To add a new US: copy the block above and place it below the matching epic. If the epic does not exist, create a new H2. Number the ID in sequence after the last one used.*

package/content/guardrails/README.md

@@ -0,0 +1,55 @@
+# Guardrail catalog
+
+> **This is data, not a skill.** Each file here describes a gate that AFM can **suggest** when a
+> signal matches the project. Suggesting is all it does on its own. Installing needs the
+> operator's OK. Writing outside `docs/` is a bright line.
+
+The catalog grows, but the mechanism that reads it does not. `interview/triggers.md` has **one**
+line for the whole catalog. That line says a guardrail whose `signal` matches this project is not
+installed yet. One line per guardrail would repeat the same thing N times.
+
+## The two origins
+
+The catalog in this directory is **gate suggestion by project signal**. The guardrails that the
+consumer materializes in `<consumer>/docs/guardrails/` arrive through two doors. Both produce the
+same artifact.
+
+| `origin:` | Comes from | Procedure |
+| --- | --- | --- |
+| `recurring-failure` | `sig=` recurred 2 or more times (or 1 user correction) in the substrate | [`../rubrics/failure-classification.md`](../rubrics/failure-classification.md) → [`../ops/remediate.md`](../ops/remediate.md) |
+| `hard-rule` | rule in `afm.md § 3` with a 0/1 trigger that no one ran | [`../ops/rule.md` § Install the gate](../ops/rule.md) |
+
+Installation itself is **one procedure**, in `ops/rule.md`. The two doors compose into it.
+
+## Format
+
+YAML frontmatter plus prose. The fields the mechanism reads:
+
+| Field | What it is |
+| --- | --- |
+| `id` | stable and citable. Never reuse a retired id. The historical rationale points to it |
+| `signal` | the command that detects whether **this project** would benefit. Exit 0 means match. It triggers the suggestion |
+| `trigger` | the 0/1 check the gate runs after install. Without this, it is advice, not a guardrail |
+| `surface` | where it **can** run. Where it **will** run is the operator's choice |
+| `params` | what the operator fills in. Never hardcode an operator constant. That was the bug that started this catalog |
+| `cost` | `low`/`medium`/`high`. High does not suggest itself. It runs only when the operator asks |
+
+## The burden of refutation
+
+Every file ends in **`## What would refute this`**, and this field is not decorative.
+
+An installed guardrail becomes permanent friction. Friction without a visible rationale is the
+first thing someone removes on a tight Friday. This section states **what evidence would overturn
+the recommendation**. It is not "when not to use this," which is opinion. It is the observable
+fact that makes the gate wrong for this project. Anyone who removes a guardrail should be able to
+cite the line that refuted it.
+
+## What does NOT go in
+
+- **A guardrail without a 0/1 `trigger`.** Without a command, it is not a gate. If the idea is
+  good but does not mechanize, it belongs in `core/afm.md § 1.3` as a principle, not in this
+  directory.
+- **A guardrail whose constant AFM chooses.** The framework supplies the form. The operator
+  supplies the value. A catalog that hardcodes `300` repeats the bug it exists to fix.
+- **A guardrail that blocks only by heuristic.** A gate that rejects correct work gets bypassed.
+  A bypassed gate protects nothing.

package/content/guardrails/dsl-com-ordem-obrigatoria.md

@@ -0,0 +1,47 @@
+---
+type: guardrail-suggestion
+description: A fluent builder whose call order matters should refuse the wrong order at compile time.
+load: cold
+id: dsl-com-ordem-obrigatoria
+title: A builder whose order matters must refuse the wrong order at compile time
+signal: |
+  grep -rqE 'return this;?$' --include='*.ts' --include='*.tsx' --exclude-dir=node_modules --exclude-dir=dist --exclude-dir=build --exclude-dir=vendor --exclude-dir=target --exclude-dir=.git . 2>/dev/null
+trigger: tsc --noEmit
+surface: [tsconfig-or-lint, script-local]
+params: [tipo-do-builder]
+cost: high
+source: patterns/16-type-state-builder-faseado.md
+---
+
+# Mandatory order in a fluent chain
+
+A builder with mandatory order — `.authorize()` before `.refund()` — is a deferred bug
+**when it only fails at runtime**. It wears the disguise of an elegant API.
+The person who writes the wrong chain finds out in production.
+
+The pattern that closes this gap is **type-state**. Each method returns a type.
+That type exposes only the next legal methods. The wrong order stops compiling.
+No path to runtime remains.
+
+**This guardrail carries `cost: high` on purpose.** The cheap exit is part of the
+recommendation. Type-state often gets expensive in TypeScript. When it does,
+**do not build the builder.** Use one function with all arguments required.
+It solves the same problem without the technique. The rubric
+`rubrics/when-to-create-dsl.md` prefers this exit by default.
+
+**The proof must stay committed.** Add a `@ts-expect-error` above the call that uses
+the illegal order. Place it inside the test file. This turns a one-time audit into
+a gate. If the protection regresses, the `@ts-expect-error` becomes an unused
+directive. Then `tsc` fails the build.
+
+## What would refute this
+
+- **The order is not truly mandatory.** Suppose `.b()` before `.a()` only produces
+  a different result, not an illegal state. Then there is nothing to protect.
+  Type-state here is dead weight.
+- **The chain has two steps.** The cost of the pattern does not pay off. Two
+  arguments in one function solve the same problem.
+- **You measured the ergonomics and they are bad.** Type-state error messages in
+  TypeScript are famously unclear. An error nobody understands can cost more than
+  the bug it prevents. This is legitimate evidence against the pattern.
+  It explains why `cost: high` exists here.

package/content/guardrails/exaustividade-de-union.md

@@ -0,0 +1,48 @@
+---
+type: guardrail-suggestion
+description: A new union case should break every caller that does not handle it.
+load: cold
+id: exaustividade-de-union
+title: A new case in a union must break every caller that does not handle it
+signal: |
+  grep -rqE 'as const' --include='*.ts' --include='*.tsx' --exclude-dir=node_modules --exclude-dir=dist --exclude-dir=build --exclude-dir=vendor --exclude-dir=target --exclude-dir=.git . 2>/dev/null
+trigger: tsc --noEmit
+surface: [tsconfig-or-lint, script-local, ci]
+params: []
+cost: low
+source: patterns/03-exaustividade-com-never.md
+---
+
+# Exhaustiveness with `never`
+
+A `switch` over a union of literals does **not** guarantee coverage in the caller. A new code
+compiles clean in every existing caller. The `switch` falls through in silence, and the
+`if`-chain returns `undefined`. Only a `default` that assigns the rest to `never` gives you that
+guarantee.
+
+```ts
+default: {
+  const _exhaustive: never = result.code;
+  throw new Error(`unhandled code: ${_exhaustive}`);
+}
+```
+
+**Marginal cost is zero.** This does not install a new tool. The gate is the `tsc --noEmit` the
+project already runs. What changes is that the code now produces the error instead of swallowing
+the case.
+
+**What changes with an agent:** it adds the new member to the union because the task asked for it.
+It does not visit the callers, because nothing forced it to. The compiler is the only reviewer
+that never forgets.
+
+## What would refute this
+
+- **The union is open by design** (a third-party error code, a protocol string that grows outside
+  your control). Exhaustiveness is the wrong model here. If you force it, someone silences the
+  `default` with `as never`. That is the same hole, with one more line.
+- **The project has no type-check.** Then there is no gate to install here. Turn the type-check on
+  first.
+
+> AFM already fixed this exact case in itself. `rubrics/error-classification.md` claimed
+> that an exhaustive switch guarantees caller coverage, and the claim was **false**. A test with
+> `tsc --noEmit --strict` proved it false, on a union of three codes with a switch that covered two.

package/content/guardrails/fronteira-de-import.md

@@ -0,0 +1,57 @@
+---
+type: guardrail-suggestion
+description: A layer import boundary should be a command that fails, not a paragraph in the README.
+load: cold
+id: fronteira-de-import
+title: A layer boundary is a command, not a paragraph in the README
+signal: |
+  test -d packages -o -d apps && ! grep -q '"references"' tsconfig.json 2>/dev/null
+trigger: tsc -b
+surface: [tsconfig-or-lint, ci, script-local]
+params: [camadas, quem-pode-importar-quem]
+cost: medium
+source: guardrails/code-quality/05-fronteiras-de-arquitetura-executaveis.md
+---
+
+# Executable import boundary
+
+The rule "`billing` does not import from `ui`" needs a command. The command must
+return a non-zero exit code when someone breaks the rule. While the rule lives in
+the README, a human must enforce it by inspection. Human inspection does not scale.
+It cannot match the volume of PRs a team with agents produces.
+
+The wrong import compiles. It fixes the bug of the day. It passes a forty-second
+review. Months later it is circular coupling, with five modules tangled instead of
+one.
+
+**What changes with an agent:** a senior human has social hesitation. They think
+"this import looks strange, let me ask". An agent is the most literal executor of
+"make the test pass". It imports from whatever module solves the task fastest.
+
+Human review is good at local complexity in a diff. It is bad at fan-in/fan-out
+drift, because that drift does not show in the diff. It shows in the graph.
+
+## How to install
+
+Add `composite: true` and `references` to each package's `tsconfig.json`. A passing
+`tsc -b` (exit 0) then becomes **impossible** with a broken boundary. This is not a
+lint that warns. It is a build that does not close.
+
+Outside TypeScript, use the stack's declarative config equivalent
+(`dependency-cruiser`, `import-linter`, `ArchUnit`). One thing does **not** work:
+`grep` for a forbidden import. `grep` does not track transitivity, so a boundary
+break two hops away passes clean.
+
+## What would refute this
+
+- **The project has only one package.** With no graph, there is no boundary to
+  cross, and `references` is ceremony.
+- **The layers are still forming.** Code that changes shape every week does not
+  support a frozen boundary. A frozen boundary there produces a gate that rejects
+  legitimate work. The team then learns to edit the config instead of respecting
+  the boundary. That outcome is worse than no gate at all.
+- **`tsc -b` ran and missed the violation you have.** Then the problem is not the
+  import boundary. This guardrail is not the fix. (Precedent: a catalog listed
+  `tsc -b --dry` as proof of a boundary check, but it **runs no type-check at all**.
+  Someone built the monorepo with the violation in place, and measured exit 0.
+  Measure before you trust it.)

package/content/hooks/README.md

@@ -0,0 +1,70 @@
+# AFM hooks — shared contract
+
+The hooks of AFM 4.0 are one command, `afm hook <Event>`, not a set of scripts. Each harness adapter
+(claude-code, opencode, agy) wires its own native events to that command and translates the payload
+in and the decision out. The logic is TypeScript in `packages/core/src/features/hook/domain/`, so it is
+tested once for every harness. The git hooks (`afm install git`) run the gate with no AI at all.
+The 3.x bash scripts and their history live in `CHANGELOG-archive.md`.
+
+---
+
+## Contract
+
+- **cwd** = consumer project root (reads `./docs/...`).
+- **Silent no-op** outside an AFM project (no `docs/.afm-version`): the decision is `noop`, exit 0, no stdout.
+- **A bug fails open, a policy decision fails closed.** A crash, a timeout or an unreadable payload exits 0 and the operation goes on. A decision the hook made (a red gate on a commit) refuses. **Exit 2 means "I did not decide"** and never counts as a pass.
+- **A hook never blocks an operation by default.** The one rule has **two named exceptions** (below). The list is nominal: no third hook inherits the permission, and a test fails if one does (see the carve-outs below).
+- **Factual phrasing, never imperative.** The injected text describes the state of the project; what to do with it is judgment. An order triggers the model's anti-injection defenses.
+- **Every handler is a pure function** `payload -> decision`. A decision is one of `inject | deny | block | noop`, and the adapter renders it in the harness's native format.
+- **No secret is ever written.** A captured command is redacted before it reaches the state store.
+
+## Events
+
+The adapters normalize every harness to six events.
+
+| Event | Handler | What it does |
+| --- | --- | --- |
+| `session.start` | digest | Injects the § 3 rule headlines, the doctrine, and a pending handoff or focus. The focus carries its age ("last updated N days ago") and is flagged possibly stale after 7 days; an unset `protocol: [TBD]` points at `afm protocol`. It does not run `afm doctor`. |
+| `tool.pre` on a write | pre-edit | Injects the rule, gotcha or learning whose `Trigger:` matches the file by path segment or by content (`afm detect --for <file>`). |
+| `tool.pre` on a shell command | pre-commit | When the command is a `git commit` (read by a token grammar, never a substring), runs `afm gate --staged` and refuses on red. |
+| `tool.post` | capture | Appends one line to the ledger for an edit to a normative doc, and for the op that ran. It also warns once per file and session when a `docs/*.md` write is over `max-doc-bytes`. |
+| `tool.fail` | failure capture | Records a failure of an oracle (test, typecheck, lint, build) with its `sig=`. The second occurrence of a `sig=` is what `afm failures promotable` lists. |
+| `subagent.start` | headlines | Hands a sub-agent that writes the hard-rule headlines, because it never sees the parent's digest. A read-only role gets nothing. |
+| `session.stop` | handoff | Writes the mechanical handoff of a session with work. The judgment fields are the agent's (`reflect`). |
+
+Matching is **by content for gotchas and rubrics, by path segment for hard rules**. `afm detect`
+evaluates `trigger_path`, `trigger_basename`, `trigger_ext`, `trigger_grep`, `trigger_min_lines`,
+`trigger_max_consumers` and `trigger_new_module`, conjunctive unless `trigger_any: yes`. A gotcha keyed
+on an API call fires only if it declares `fires_on: file-shape` and a `trigger_grep`.
+
+> **The cap starves a narrow trigger.** `MAX_RUBRICS` and `AFM_MAX_GOTCHAS` default to 2, and matches are
+> emitted in filename order, not by specificity. A broad entry with no content condition wins the slot over
+> a precise one that sorts later. The cap is deliberate (an always-loud channel gets ignored); the order is
+> a known limit.
+
+## The Stop carve-out and the pre-commit carve-out
+
+- **`session.stop` may `block` for a cadence.** The reflection arm and the evolve arm are independent: each has its own threshold, its own opt-out key (`cadence: reflect=off`, `cadence: evolve=off` in `docs/_focus.md`) and its own ceiling of one block per threshold crossing. A stop that is already the result of a block never blocks again, which is what prevents an infinite loop. Blocking a stop postpones the end of a turn; it never stops work. The counter is **derived** from the ledger and `docs/evolution/`, never stored, so it resets only when a real cycle is on disk.
+- **`tool.pre` on a shell command may `deny` a `git commit`** when the gate is red and the project has no native pre-commit surface (no husky, lefthook, `pre-commit`, or `core.hooksPath`). Blocking a commit only postpones it: the work stays on disk.
+
+The commit detector is a **nudge for the common path, not a boundary.** It reads `git commit` after a
+separator, inside `(...)` or `{...}`, behind `VAR=value`, behind an enumerated wrapper (`command`, `env`,
+`sudo`, `nohup`, `nice`, `time`, `stdbuf`) or shell (`sh -c`, `bash -c`), quoted, and with the global
+options that take a value. It cannot see `eval`, a variable holding the command, or a script on disk.
+The boundary is `afm install git`, which writes git's own `pre-commit`; git runs it however the command
+is spelled. That is why the nudge goes quiet once a native surface exists.
+
+`block` carries the only imperative prose a hook may emit, because saying what to do is the field's
+meaning: `{ "decision": "block", "reason": "<what to do, with both paths>" }`.
+
+## Where state lives
+
+Nothing a hook records goes into the repository. The ledger, the handoffs, the captured failures and the
+dedup flags live under `AFM_HOME` (`~/.afm/state/<project-hash>/`), with a TTL on the volatile ones. The
+repository keeps only the structure of `docs/` and its markers. `afm gc` deletes the expired keys.
+
+## Changing a hook
+
+- A handler is a pure function under `packages/core/src/features/hook/domain/` named `domain_<name>`, with its test beside it.
+- If you change the `docs/` format a handler parses (the `## 3.` heading, a rule's `*Verification:*` field, a gotcha's `trigger_path` key), change the handler and its fixture in the same commit.
+- A hook that depends on a harness event must go through the adapter. No handler branches on a harness name.