@orkastery/cli 0.5.3 → 0.6.0

package/assets/docs-en/padroes/roadmap-de-produto.md

@@ -0,0 +1,100 @@
+# Software product roadmap standard
+
+> Version 1.1 · Applies to: initiatives, epics, features and changes · Companion document: [Product documentation standard](documentacao-de-produto.md)
+>
+> Version 1.1 keeps 1.0 and adds section 6 (three readers and SDLC facts) and the template frontmatter, which `ork docs verificar` checks.
+
+The frontmatter keys and values, the section titles of the page templates and the `> **Em uma frase:**` line stay in Portuguese in every language, because they are the contract that `ork docs verificar` reads.
+
+## 1. Purpose and tracking unit
+
+This standard records **why to change, what is meant to be delivered, how to validate it and what the real state of execution is**. Use one item per traceable investment/delivery decision. Initiatives can contain epics, and epics can contain features; each item has its own ID and points to its parent item. An implemented feature points to its `FEAT-ID` specification. Do not replicate extensive technical fields of the product in the roadmap: keep links to the canonical documentation.
+
+The roadmap is a planning view subject to revision. Dates, priorities and scope are commitments only when explicitly approved and identified as such. Mark estimates and hypotheses as such.
+
+## 2. Common rules
+
+| Rule | How to apply |
+| --- | --- |
+| ID and links | Use a stable `RM-001`; state the parent, affected features and links to specifications, ADRs, issue, PR, tests and release. |
+| Outcome | Spell out the problem, audience, objective, measurable hypothesis, baseline, target, window and source of the metric. |
+| Prioritization | Record method, criteria, score and date; priority is distinct from urgency and does not replace a rationale. |
+| Scope | Separate what is included, what is excluded, dependencies and assumptions. Scope changes call for a decision record. |
+| Dates | Distinguish target, forecast and actual date; use ISO 8601, time zone and confidence level. Never infer progress from the date. |
+| Evidence | Give the source and date of each status. Merged PR, deploy and availability to users are distinct facts. |
+| Responsibility | Name a human owner for decision, execution and validation. AI agents can draft, verify or execute within recorded autonomy; assign review and the final decision to people. |
+| Gaps | Use `To be defined` with an owner and a deadline; for an irrelevant section, `Not applicable: reason`. Do not make up status or metrics. |
+
+## 3. Roadmap item categories
+
+### 3.1 Identification and positioning
+
+Record `ID`, `outcome-oriented title`, `type` (initiative, epic, feature or improvement; the `categoria` key takes `iniciativa`, `épico`, `feature` or `melhoria`), `parent item`, `platform`, `system`, `module`, `affected features`, `audience`, `requesting area`, `canonical links` and `page version`. The architectural hierarchy describes where the change happens; the roadmap hierarchy describes how it is planned.
+
+### 3.2 Problem, objective and hypothesis
+
+Record `problem/opportunity`, `evidence`, `objective/OKR`, `hypothesis in the form If... then... because...`, `main metric`, `guardrail metrics`, `baseline`, `target`, `observation window`, `analysis segment` and `data source`. Without a known baseline, define how it will be measured before declaring success.
+
+### 3.3 Scope, deliverables and validation
+
+Record `included scope`, `out of scope`, `deliverables`, `affected use cases`, `acceptance criteria`, `experiment/pilot`, `measurement plan`, `criteria to expand/stop`, `operational enablement` and `required documentation`. Point to the IDs of rules, contracts and tests in the product documentation.
+
+### 3.4 Prioritization and planning
+
+Record `priority`, `method/score` (for example RICE, with explicit factors), `rationale`, `urgency`, `horizon` (Now/Next/Later or quarter), `target date`, `forecast`, `confidence`, `milestones`, `estimated capacity/cost` and `trade-offs`. A score without criteria and a date is not reproducible.
+
+### 3.5 Dependencies, risks and decisions
+
+Record `dependencies with IDs and owners`, `blockers`, `assumptions not yet validated`, `risks with probability/impact`, `mitigation/contingency`, `product decisions`, `technical ADR`, `discarded alternatives`, `date/decider` and `review trigger`. An ADR is a decision record that can be superseded by another; preserve the history, without erasing earlier decisions.
+
+### 3.6 Lifecycle and independent states
+
+Do not use a single field to hide differences between plan, code and delivery. Update each dimension separately:
+
+| Dimension | Recommended values | Minimum evidence |
+| --- | --- | --- |
+| Item lifecycle | `Discovery` → `Backlog` → `Refinamento` (refinement) → `Pronto para desenvolvimento` (ready for development) → `Em desenvolvimento` (in development) → `Em validação` (in validation) → `Piloto` (pilot) → `Disponível` (available) → `Concluído` (done); side states: `Bloqueado` (blocked), `Cancelado` (canceled), `Descontinuado` (discontinued) | Decision, milestone or delivery with date and owner. |
+| Documentation | `Rascunho` (draft), `Em revisão` (in review), `Aprovada` (approved), `Desatualizada` (outdated) | Link, version and reviewer. |
+| Code | `Não iniciado` (not started), `Branch criada` (branch created), `PR aberto` (PR open), `Mesclado` (merged) | Repository, branch/PR and commit. |
+| Tests | `Não iniciados` (not started), `Em execução` (running), `Aprovados` (passing), `Falhando` (failing) | Run and date; coverage, if relevant. |
+| Deploy | `Não implantado` (not deployed), `Dev`, `Staging`, `Produção` (production) | Pipeline, release and actual date. |
+| Exposure | `Flag desligada` (flag off), `Piloto/Canary` (pilot/canary), `Parcial` (partial), `Geral` (general) | Configuration per environment/cohort and verification. |
+| Enablement | `Pendente` (pending), `Em andamento` (in progress), `Concluída` (done) | Communication, training or published material. |
+
+`Bloqueado` requires a reason, a dependency, an owner and a next review. `Concluído` requires met acceptance criteria, evidence of availability and a record of the initial measurement or a post-launch evaluation plan. Status must not be updated merely because time has passed.
+
+### 3.7 Owners and collaboration between people and agents
+
+Record `PM/PO accountable`, `technical lead`, `implementing engineer`, `QA/validator`, `sponsor`, `consulted`, `informed`, `channel`, `planning agent`, `execution agent`, `validation agent`, `allowed autonomy`, `human reviewer` and `RACI`. Separate an agent's contribution from the person who approves; document the actions taken and the evidence, without attributing decisions to an agent by default.
+
+## 4. Roadmap item template
+
+Copy [the template](../roadmap/_modelo-item.md) for each item. The frontmatter holds the seven dimensions of section 3.6 with the standard's exact values, and the checker enforces coherence between them:
+
+| Coherence rule | Why |
+| --- | --- |
+| `ciclo: Concluído` requires `codigo: Mesclado` and `testes: Aprovados` | done without code on the base branch is a promise |
+| `deploy: Produção` requires `codigo: Mesclado` | you do not deploy what has not been merged |
+| `codigo: Mesclado` requires `evidencias.codigo.commit` **on the base branch** | a merge is proven by git, not by declaration |
+| `ciclo: Bloqueado` requires the `bloqueio` map (reason, dependency, owner, next review) | a blocker without an owner does not get cleared |
+
+## 5. Cadence and consistency
+
+Revisit active items at the team's cadence and always after a decision, relevant PR, test, deploy, flag change or outcome measurement. At each review, compare roadmap, feature documentation, code, contracts and production evidence; note divergences with an owner and a deadline. Agents can suggest status updates from repository events, but a merged PR updates only the **code** dimension until deploy and exposure are proven. Record the update date and keep a history of decisions and scope changes.
+
+In Orkastery, `ork docs sincronizar` is that agent: it updates `estado.codigo` and `evidencias.codigo.commit` from the ledger (`ship_done`) and git, and the `sdlc` section from the thread. **It never touches lifecycle, documentation, deploy, exposure or enablement**: those dimensions are a person's decision, and the checker only requires them to be coherent with the code. In a thread's worktree, it only touches that thread's item and the indexes, so that one thread's PR does not change another thread's item; `--so RM-NNN` picks the items, and `--todos` (the default at the project root, where the conductor syncs after the merge) goes back to all of them.
+
+## 6. Three readers and SDLC facts (Orkastery adaptation)
+
+The reading rules of the [documentation standard](documentacao-de-produto.md#6-three-readers-and-sdlc-facts-orkastery-adaptation) apply here: answer first, state at a glance, one idea per line, sections with fixed names, frontmatter for agents.
+
+What changes in the roadmap is the `sdlc` block, which ties the item to the Orkastery method **with product facts only**:
+
+| Key | Content | Who fills it in |
+| --- | --- | --- |
+| `sdlc.thread` | ID of the thread that delivers the item | a person, when opening the thread |
+| `sdlc.modo` | `#Classic`, `#Maestro` or `#Auto` | a person |
+| `sdlc.fase`, `sdlc.status` | current phase and status of the thread | `ork docs sincronizar` |
+| `sdlc.check` | latest verdict of the independent CHECK | a person, based on the assessment |
+
+Conduction micro-decisions (re-registered claims, a GO-FIX for a test, a session that dropped) **stay out of the item**: they live in the thread's ledger, which is the method's audit record.

package/assets/docs-en/produto/README.md

@@ -0,0 +1,14 @@
+# Product documentation
+
+> **In one sentence:** what the product is and does today, one page per entity, checked against the code on every PR.
+
+- **Standard:** [product documentation](../padroes/documentacao-de-produto.md) · **Companion:** [roadmap](../roadmap/README.md)
+- **Hierarchy:** platform (`PLAT`) → system (`SYS`) → module (`MOD`) → feature (`FEAT`)
+- **New page:** copy [the template](_modelo-feature.md) and run `ork docs verificar`
+
+## Index
+
+Generated by `ork docs sincronizar` from the frontmatter of each page, with the column labels in Portuguese.
+
+<!-- ork-docs:indice:inicio -->
+<!-- ork-docs:indice:fim -->

package/assets/docs-en/produto/_modelo-feature.md

@@ -0,0 +1,62 @@
+---
+id: FEAT-000
+tipo: feature
+titulo: <Feature name>
+estado: proposto
+pai: MOD-00
+roadmap: [RM-000]
+owner: <name>
+aprovador: <name>
+verificado_em: 2026-01-01T00:00:00-03:00
+versao: main@0000000
+fontes:
+  codigo: []
+  testes: []
+  simbolos: []
+  contratos: []
+  comandos: []
+---
+
+<!-- The feature number comes from `ork roadmap feat --thread <thread>`, reserved across machines; never from the highest number on your branch. -->
+<!-- Keep the frontmatter keys and values, the section titles and the "Em uma frase" line as they are: `ork docs verificar` reads them in Portuguese in every language. -->
+
+# FEAT-000: Feature name
+
+> **Em uma frase:** [what this feature does, for whom, in up to 240 characters]
+
+- **State:** `proposto` · **Verified on:** [YYYY-MM-DD] · **Version:** [branch@commit]
+- **Where it lives:** [PLAT-00 > SYS-00 > MOD-00, with links]
+- **Roadmap:** [RM-000, with a link]
+- **Page owner / approver:** [names]
+
+## Comportamento
+
+- **Use cases and operations:** [UC-ID, action, actor]
+- **Preconditions and trigger:** [what must exist and what starts it]
+- **Main flow:**
+  1. [observable step]
+- **Alternatives, errors and recovery:** [error, cancellation, timeout, resume]
+- **Postconditions:** [what is recorded, emitted or changed outside]
+- **Business rules:** [BR-ID: condition → result; exception]
+- **Acceptance criteria and tests:** [Given/When/Then, with the test that proves it]
+- **Interface and accessibility:** [screens, states, prototype, or Not applicable: reason]
+
+## Dados e contratos
+
+- **Entities and fields:** [links, types, validations, sensitivity]
+- **APIs and endpoints:** [IDs, methods, contracts, errors, versioning]
+- **Events and jobs:** [IDs, schemas, triggers, retries, time zone]
+
+## Operação e controle
+
+- **Configuration and environments:** [parameters, no secrets]
+- **Observability:** [metrics, SLO, logs, alerts, runbook]
+- **Access, privacy and compliance:** [applicable controls]
+- **Dependencies and rollback:** [what it uses and how to roll it back]
+- **Code, PR, tests and release:** [identifiable links]
+
+## Histórico
+
+| Date | Change | Author/reviewer | Evidence or decision |
+| --- | --- | --- | --- |
+| [YYYY-MM-DD] | [description] | [names] | [link] |

package/assets/docs-en/roadmap/README.md

@@ -0,0 +1,14 @@
+# Roadmap
+
+> **In one sentence:** why change, what to deliver and where each item stands, with the state proven by git, not declared.
+
+- **Standard:** [product roadmap](../padroes/roadmap-de-produto.md) · **Companion:** [product documentation](../produto/README.md)
+- **One file per item:** `RM-000-subject.md`, with the state in the frontmatter
+- **New item:** copy [the template](_modelo-item.md) and run `ork docs verificar`
+
+## Items
+
+Generated by `ork docs sincronizar` from the frontmatter of each item, with the column labels in Portuguese.
+
+<!-- ork-docs:indice:inicio -->
+<!-- ork-docs:indice:fim -->

package/assets/docs-en/roadmap/_modelo-item.md

@@ -0,0 +1,75 @@
+---
+id: RM-000
+tipo: roadmap
+titulo: <Intended result>
+categoria: iniciativa
+pai: null
+features: []
+owner: <name>
+atualizado_em: 2026-01-01T00:00:00-03:00
+estado:
+  ciclo: Discovery
+  documentacao: Rascunho
+  codigo: Não iniciado
+  testes: Não iniciados
+  deploy: Não implantado
+  exposicao: Flag desligada
+  habilitacao: Pendente
+evidencias:
+  codigo:
+    commit: null
+    pr: null
+sdlc:
+  thread: null
+  modo: null
+---
+
+<!-- Keep the frontmatter keys and values, the section titles and the "Em uma frase" line as they are: `ork docs verificar` reads them in Portuguese in every language. -->
+
+# RM-000: Intended result
+
+> **Em uma frase:** [what this item delivers, for whom, in up to 240 characters]
+
+<!-- ork-docs:relance:inicio -->
+<!-- ork-docs:relance:fim -->
+
+## Problema e resultado
+
+- **Audience and problem/opportunity:** [who suffers what]
+- **Evidence and source:** [data, conversation, incident, with a link]
+- **Objective/OKR:** [what changes for whom]
+- **Hypothesis:** If [change], then [measurable effect], because [mechanism].
+- **Main metric / baseline / target / window / source:** [values and origin]
+- **Guardrail metrics:** [what must not get worse]
+
+## Escopo e validação
+
+- **Included:** [what is in]
+- **Out of scope:** [what is out]
+- **Deliverables and acceptance criteria:** [deliverable → how it is proven]
+- **Pilot, measurement and expand/stop criteria:** [how and when to decide]
+
+## Plano e decisões
+
+- **Priority / method / score / rationale / date:** [values]
+- **Horizon / target / forecast / confidence / milestones:** [values]
+- **Dependencies and blockers (ID, owner, next review):** [list]
+- **Assumptions / risks / mitigation:** [list]
+- **Decisions, alternatives and ADRs (ID, decider, date, link):** [list]
+
+## Estado com evidências
+
+The state is edited in the frontmatter; this table is generated by `ork docs sincronizar`, with its labels in Portuguese.
+
+<!-- ork-docs:estado:inicio -->
+<!-- ork-docs:estado:fim -->
+
+## Responsabilidades e histórico
+
+- **RACI (R / A / C / I):** [names]
+- **Agents involved, role, autonomy and human reviewer:** [who did what, and who approved]
+- **Next action, owner and deadline:** [one line]
+
+| Date | Change of plan, scope or status | Reason and evidence | Decider |
+| --- | --- | --- | --- |
+| [YYYY-MM-DD] | [description] | [link] | [name] |

package/assets/references-en/README.md

@@ -0,0 +1,25 @@
+# references/
+
+Normative checklists cited **by item number** by the skills, by the adapters and by the
+human, so that whoever writes `DoD 4` or `SEC 5` and whoever reads it resolve the same line.
+
+| File | Cited as | What it establishes |
+|---|---|---|
+| [definition-of-done.md](definition-of-done.md) | `DoD 4` | The conditions a delivery meets, per task, per thread, per merge and per log |
+| [code-review-axes.md](code-review-axes.md) | `REVIEW 7` | The 5 review axes and the rule that categorizes every finding |
+| [security-checklist.md](security-checklist.md) | `SEC 5` | The audit surface and the hard condition of zero blockers |
+| [testing-patterns.md](testing-patterns.md) | `TEST 3` | What a suite must prove and how a green suite is earned honestly |
+| [performance-checklist.md](performance-checklist.md) | `PERF 2` | The conditional audit, its waiver contract and measurement honesty |
+
+Three rules govern the five.
+
+1. **They elevate checks that already exist** in the core (`core/`) and in the thin skills, with the same
+   meaning. A divergence between a checklist and the `ork` command that runs it is a defect, never
+   a second opinion; wherever it shows up, the core wins.
+2. **An item is a gate only when this machine can run it.** Anything that depends on a missing
+   tool goes to the `Recomendacoes` (Recommendations) section, saying so. A checklist that demands evidence that
+   nobody can produce is a lie dressed up as rigor. What cannot be measured is published
+   as `unavailable`, never as zero.
+3. **Numbering is append-only** from the commit that publishes these files, for the life of v1.
+   Renumbering breaks every citation already written and is a change to a versioned public contract: it requires
+   a ratified class 2 decision, the same rule the MASTER log contract adopted when it was frozen.

package/assets/references-en/code-review-axes.md

@@ -0,0 +1,82 @@
+# Code Review Axes
+
+The five axes the CHECK walks through and the rule that categorizes every finding. No axis is optional:
+an axis without findings comes out as an explicit "none", because silence is not evidence that anyone looked.
+Items are numbered only once across the whole file. Cite an item as `REVIEW 7`.
+
+**Sources:** `core/src/verify.ts`, `core/src/gates.ts`, `core/src/claims.ts`,
+[definition-of-done.md](definition-of-done.md), [security-checklist.md](security-checklist.md).
+
+```mermaid
+flowchart TB
+    D["diff da thread contra a base carimbada"] --> A1["REVIEW 1 a 4<br/>correcao"]
+    D --> A2["REVIEW 5 e 6<br/>seguranca"]
+    D --> A3["REVIEW 7 e 8<br/>performance"]
+    D --> A4["REVIEW 9 a 11<br/>manutenibilidade"]
+    D --> A5["REVIEW 12<br/>estilo"]
+    A1 --> C{"categoria de cada achado"}
+    A2 --> C
+    A3 --> C
+    A4 --> C
+    A5 --> C
+    C -->|"bloqueador"| B["veredito BLOQUEADO"]
+    C -->|"aviso aceito com registro"| P["veredito PASSOU"]
+    C -->|"sugestao"| P
+```
+
+## Axis 1, correctness
+
+| # | Check | How it is proven |
+|---|---|---|
+| 1 | The code does what the PLAN said it would do, and what it does not do is stated. A difference between what was delivered and what was planned is a finding, even when what was delivered is better. | Diff against the PLAN tasks. |
+| 2 | Edge cases declared in the PLAN have a test or a line saying why they do not. | Suite rerun by `ork verify <thread>`. |
+| 3 | Errors are not swallowed: every failure path either handles the error, or propagates it with context, or fails loudly. An empty catch is a blocker. | Reading of the diff, backed by the failure-path tests. |
+| 4 | No file or test cited by the runtime is missing from the diff. A citation without backing is a hallucination, categorized as a blocker. | `ork verify <thread>`, which reruns the claims on the real HEAD. |
+
+## Axis 2, security
+
+| # | Check | How it is proven |
+|---|---|---|
+| 5 | The list in [security-checklist.md](security-checklist.md) was walked through over the scope of the diff and of the branch history, and the result is in the report. | The security section of the CHECK report, citing `SEC n` per finding. |
+| 6 | Zero security blockers. This is a hard condition: with one open blocker the verdict is BLOQUEADO (blocked), in any conduction mode, including `#Auto`. | The report's verdict against the blocker count. The mode loosens the pause, never the verification. |
+
+## Axis 3, performance
+
+| # | Check | How it is proven |
+|---|---|---|
+| 7 | The asymptotic cost of the touched structures was examined when the diff changes a loop over a collection that grows with use, and the finding brings the order of magnitude, not an adjective. | Reading of the diff, with the measured number when there is a way to measure. |
+| 8 | A performance regression is only asserted with a measurement. Without a measurement, the item comes out `unavailable` with the reason, never as a guess presented as data. | [performance-checklist.md](performance-checklist.md) and the declared origin of each number. |
+
+## Axis 4, maintainability
+
+| # | Check | How it is proven |
+|---|---|---|
+| 9 | Names say what the thing is, and new code looks like the code around it: same comment density, same human language, same language for names. Code that needs a guided tour to be read is a finding. | Reading of the diff against the neighboring files. |
+| 10 | Introduced duplication was pointed out together with the place it should come from. Pointing out duplication without pointing to its owner is an empty suggestion. | Diff against the module that already solves the problem. |
+| 11 | The diff carries no change outside the thread's scope. An opportunistic improvement without a task is scope creep, and it becomes a proposal, never a hidden commit. | `git show --stat` against the PLAN's `touch_paths`. |
+
+## Axis 5, style
+
+| # | Check | How it is proven |
+|---|---|---|
+| 12 | The project's lint and formatter pass, and what they do not cover follows the convention of the neighboring file. Style never becomes a blocker on its own: it is a suggestion, except when it breaks a project tool, and then it is already a correctness issue. | The manifest's `verify:` commands. |
+
+## The categorization rule
+
+Every finding, on any axis, comes out with exactly one category.
+
+- **Blocker**: prevents the merge. A correctness defect, a hallucination proven with evidence, a security
+  blocker, a public contract break without ratification.
+- **Warning**: passes only with a named record of who accepted it and why. A warning accepted without a record
+  is the same as a hidden warning.
+- **Suggestion**: holds nothing up and needs no record; it becomes a roadmap proposal when it matters.
+
+A finding without a category does not exist: it is opinion. And a category is not negotiated out of haste: a blocker
+downgraded to a warning because the delivery was close is the process defect that this axis exists
+to make visible.
+
+## Recommendations (not a gate on this machine)
+
+- Static analysis beyond lint (cyclomatic complexity, tool-based duplication detection):
+  this repository does not have those tools, so axes 4 and 5 are walked through by reading and the
+  report says so, instead of reporting a number that nobody produced.

package/assets/references-en/definition-of-done.md

@@ -0,0 +1,74 @@
+# Definition of Done
+
+The universal conditions a delivery meets before it is called done. It consolidates the gates
+the `ork` core already runs and invents no doctrine of its own. Items are numbered only once
+across the whole file, so that a reviewer writes a number and every human and every skill resolve to the
+same line. Cite an item as `DoD 4`.
+
+**Sources:** `core/src/phase.ts` (phase contract), `core/src/claims.ts`, `core/src/verify.ts`,
+`core/src/gates.ts`, `core/src/policies.ts`, `core/src/ship.ts`, `core/src/master.ts`,
+`core/src/worktree.ts`, `core/src/leases.ts`, `core/src/retry.ts`, `core/src/fix.ts`,
+`core/src/ratelimit.ts` (block B3: typed retry, GO-FIX/CHECK-REVERIFY and the rate limit queue).
+
+```mermaid
+flowchart LR
+    GOAL["GOAL<br/>DoD 17 e 18<br/>objetivo aprovado"] --> PLAN["PLAN<br/>DoD 19 e 20<br/>tradeoffs decididos"]
+    PLAN --> GO["GO<br/>DoD 1 a 5 por tarefa"]
+    GO --> CHECK["CHECK<br/>DoD 6 a 11<br/>gate da thread"]
+    CHECK --> SHIP["SHIP<br/>DoD 12 a 15<br/>gate do merge"]
+    SHIP --> MASTER["MASTER<br/>DoD 16<br/>gate de fechamento"]
+    CHECK -->|"correcao tipo B"| GO
+```
+
+## Every task, before GO calls it done
+
+| # | Check | How it is proven |
+|---|---|---|
+| 1 | One atomic commit per task, at most five files changed, with the thread and the task in the message (example: `ork-checkout T3: extrai o calculo de frete`). | `git log --oneline` and `git show --stat` on the thread branch. Above five files the task goes back to PLAN to be sliced. |
+| 2 | The task's verify declared in the PLAN was run and passed. | Run the command. A reported pass is not a pass: `ork verify <thread>` reruns it on the real HEAD. |
+| 3 | Anti-hallucination check: every file the runtime cited exists in the diff and every test it cited exists and passes. | Every statement becomes `ork claims add ... --verificar "<comando>"`, and `ork verify <thread>` reruns it. A mismatch comes out as typed reason `claims.failed`. |
+| 4 | Work inside the thread worktree, with the base stamped in `thread.json`, never in the main tree. | `ork worktree audit <thread>` checks against git itself and exits non-zero if they diverge. |
+| 5 | Every relevant delegated decision was recorded in the ledger with who decided, on what evidence and why. The qualifier carries weight: formatting and internal names are delegable too, and demanding an event for each of them is undue escalation, which the audit weighs the same as under-classification. | `ork phase list <thread>` over the thread's `ledger.jsonl`. |
+
+## Every thread, before the CHECK gate passes
+
+| # | Check | How it is proven |
+|---|---|---|
+| 6 | The full suite is green, including the manifest's `verify:` commands, and code health passes: typecheck, lint and coverage with a declared origin. | `ork verify <thread>`. Every number carries `runtime_reported`, `estimated` or `unavailable`; a gap is published as a gap, never as zero. |
+| 7 | The comparison is against the baseline recorded before GO, separating regression from pre-existing debt. | `ork verify <thread> --baseline` before GO and `ork verify <thread>` after it. A command that passed on the baseline and fails now comes out as `verify.regression`; what already failed before comes out as debt, not as the thread's fault. |
+| 8 | The five review axes (correctness, security, performance, maintainability, style) bring findings or an explicit "none", each categorized as blocker, warning or suggestion. | The five-axis table of the CHECK report, per [code-review-axes.md](code-review-axes.md). |
+| 9 | The security audit reports zero blockers, and the web performance audit either ran or states why the target has no web surface. | The report's audit sections, per [security-checklist.md](security-checklist.md) and [performance-checklist.md](performance-checklist.md). |
+| 10 | Fixes classified honestly: type A is one line or equivalent, recorded, with the affected checks rerun; type B sent the task back to GO, and this CHECK round is the full rerun. | `ork fix open <thread>` derives one fix per typed reason, with the exact spec and the command that judges it; `ork fix reverify <thread>` gives the verdict PER fix and REFUSES a partial rerun when there is a type B. The ledger's `go_fix_opened` and `check_reverify` events against the report's counts. These counts measure the quality of the PLAN and of the GO, not that of the reviewer. |
+| 11 | The report is in the thread directory with exactly one verdict (PASSOU = passed, PRECISA DE MUDANCA = needs changes, BLOQUEADO = blocked), every accepted warning has its record, and the gate was resolved through the right path. | The human answer to `ork gate request <thread>`, through the authenticated channel, for a human decision, or the mode's autonomous decision event, which only a PASSOU verdict allows. A verify failure, an anti-hallucination failure, any CHECK with a type B fix, an envelope deviation, a verdict other than PASSOU and an emergency always go up to the human, in any mode. |
+
+## Every merge, before SHIP closes
+
+| # | Check | How it is proven |
+|---|---|---|
+| 12 | Contract guard: nothing in the final diff changes a versioned public contract (telemetry schema, interface contract, state layout, event types) without a ratified class 2 decision. | `git diff <base>...HEAD` over those files and the id of the gate that ratified it, in the ledger. No ratification, no merge. |
+| 13 | The merge went through the serialized queue, updated against the latest base, fully revalidated whenever the update brought changes, with the `DoD 12` guard rerun against the final diff. | `ork ship <thread> --para <base>` takes the `main-tree` lease; the update can bring changes that touch a contract, so a verdict computed before it describes a diff that no longer exists. |
+| 14 | The push was proven by a command, not reported. | `ork ship` compares the local sha with `git ls-remote` on the remote and writes `pushVerificado` to the ledger. A reported push without the remote's sha counts as a push that did not happen. |
+| 15 | An irreversible step only happens with the mode's authorization: push, merge and deletion require the pause the #TAG provided for or a recorded advance authorization. | `ork ship <thread> --para <base> --autorizar-push <quem>`, or the human answer to the mode's pause, visible in `ork phase list <thread>`. |
+
+## Every closure, before the thread dies
+
+| # | Check | How it is proven |
+|---|---|---|
+| 16 | There is a MASTER log valid against the frozen contract `ork.master-log/v1`, with a typed POSTMORTEM, failure classes from the fixed catalog, an integer score from 0 to 5 and a non-empty justification. A delivery without a MASTER log did not happen. | `ork master <thread> --score N --justificativa "<texto>" --por <quem>`. The command refuses a score outside the scale, a score without a justification, a score without human authorship in `--por` and a class outside the catalog, and writes nothing when it refuses. |
+
+## Every thread, at its start
+
+| # | Check | How it is proven |
+|---|---|---|
+| 17 | The goal of the GOAL phase is verifiable: observable criteria (latency, coverage, behavior), never adjectives. In a fix request, reproducing the defect is a mandatory criterion. | The GOAL becomes claims with a verification command; a criterion that does not become a command is not a criterion. |
+| 18 | The assumptions are written down. An implicit assumption is the biggest source of rework and is treated as a process defect, not as cleverness. | The assumptions section of the GOAL and the claims that tie them down. |
+| 19 | The PLAN brings tasks with queryable `touch_paths` and one executable verify per task. | The thread's PLAN and the `path:<glob>` leases it justifies. |
+| 20 | Decisions D1..Dn have a single home and stay locked once decided; reopening is a new decision, with a record, never a silent edit. | The thread's ledger, where the decision appears with who decided and when. |
+
+## Recommendations (not a gate on this machine)
+
+- Test coverage as a number: this repository has no coverage tool installed, so
+  coverage is reported as `unavailable` instead of estimated.
+- Tool-based dependency audit: `npm audit` runs where a dependency is declared; the
+  `ork` core has only development dependencies, and this is stated in the report instead of becoming a
+  convenient zero.

package/assets/references-en/performance-checklist.md

@@ -0,0 +1,53 @@
+# Performance Checklist
+
+The conditional audit: it runs when the target has a surface that suffers from latency, and when it does
+not have one, it is waived by a written contract, never by oversight. Items are numbered only
+once across the whole file. Cite an item as `PERF 2`.
+
+**Sources:** [code-review-axes.md](code-review-axes.md) (axis 3),
+[definition-of-done.md](definition-of-done.md), `core/src/verify.ts`.
+
+```mermaid
+flowchart TB
+    Q{"o alvo tem superficie<br/>sensivel a latencia?"} -->|"nao"| D["dispensa registrada:<br/>PERF 1, com o motivo"]
+    Q -->|"sim"| M["PERF 2 a 6:<br/>medir antes de afirmar"]
+    M --> A["PERF 7 e 8:<br/>custo assintotico e recurso"]
+    A --> H["PERF 9 e 10:<br/>honestidade de medicao"]
+```
+
+## The waiver contract
+
+| # | Check | How it is proven |
+|---|---|---|
+| 1 | When the target has no web surface and no latency-sensitive path, the audit is waived with a line saying what the target is and why it has no such surface. A written waiver is a result; a missing audit with no line at all is a gap. | The performance section of the CHECK report, which always exists, even when its content is the waiver. |
+
+## Measure before asserting
+
+| # | Check | How it is proven |
+|---|---|---|
+| 2 | Every performance statement carries a number, a unit and how the number was obtained. "It got faster" without a measurement is opinion, and opinion does not pass a gate. | The report's measurement table, with the command that produced each number. |
+| 3 | There is a measurement before and after, on the same machine and under the same conditions. Comparing measurements from different machines compares machines, not code. | The two runs, with the machine and the conditions declared. |
+| 4 | The measurement was repeated enough to separate signal from noise, and the variation is stated. A single run becomes `estimated`, never `runtime_reported`. | The number of repetitions in the report. |
+| 5 | The measured path is the user's path, not the convenient microbenchmark. A gain in a function nobody calls on the hot path is a suggestion, not a result. | The stretch of the real flow that the measurement covers. |
+| 6 | A detected performance regression is categorized like any other finding: blocker, recorded warning or suggestion. | [code-review-axes.md](code-review-axes.md), categorization rule. |
+
+## Asymptotic cost and resources
+
+| # | Check | How it is proven |
+|---|---|---|
+| 7 | A loop over a collection that grows with use was examined, and the order of magnitude is stated. A quadratic hidden in small data is a defect with a date already set. | Reading the diff at the points that iterate over accumulated state. |
+| 8 | Repeated work inside a loop (file read, process call, parsing the same data) was pointed out, or it was stated that there is none. In `ork`, reading the whole ledger per event would be exactly this defect. | Reading the diff against the I/O points. |
+
+## Measurement honesty
+
+| # | Check | How it is proven |
+|---|---|---|
+| 9 | Every number carries its source: `runtime_reported`, `estimated` or `unavailable`. It is the same discipline as the `ork` token gate, which would rather say "not measurable" than invent a window occupancy. | The source attached to each number in the report. |
+| 10 | What was not measured shows up as `unavailable` with the reason, never as zero, never as a silent absence. A published gap is a gap; a hidden gap becomes a false number on the next reading. | The metrics section of the report. |
+
+## Recommendations (not a gate on this machine)
+
+- Browser profiling tool (Lighthouse, CPU traces): not installed here. A web performance audit
+  of a target with a web surface comes out `unavailable` with the reason while that is the case.
+- Continuous benchmarking with history: out of reach for this machine; the before-and-after comparison is
+  done in the thread itself, with an explicit `PERF 3`.

package/assets/references-en/security-checklist.md

@@ -0,0 +1,101 @@
+# Security Checklist
+
+The normative list that the CHECK security audit walks through, whose hard pass condition is
+zero blockers in the consolidated report. It elevates checks that already exist in the core and
+invents none. Items are numbered only once across the whole file. Cite an item as `SEC 5`.
+
+**Sources:** `core/src/policies.ts` (secret patterns and blocking policies),
+`core/src/doctor.ts`, `core/src/ship.ts`, `core/src/gates.ts`,
+`core/src/superficie.ts` (deterministic scan of the network attack surface,
+rules SP8..SP12 of the `security-privacy` pack),
+[definition-of-done.md](definition-of-done.md).
+
+```mermaid
+flowchart TB
+    E["escopo declarado:<br/>diff, historico, prompts, artefatos"] --> S1["SEC 1 a 4:<br/>segredo e credencial"]
+    S1 --> S2["SEC 5 a 8:<br/>entrada e superficie"]
+    S2 --> S3["SEC 9 e 10:<br/>dependencia e cadeia"]
+    S3 --> S4["SEC 11 a 14:<br/>artefatos do repositorio"]
+    S4 --> S5["SEC 15 a 17:<br/>conduta da auditoria"]
+    S5 --> S6["SEC 18 a 22:<br/>superficie de ataque de rede"]
+    S6 --> C{"algum bloqueador?"}
+    C -->|"sim"| B["veredito BLOQUEADO"]
+    C -->|"nao"| P["zero bloqueadores:<br/>condicao dura cumprida"]
+```
+
+## Secrets and credentials
+
+| # | Check | How it is proven |
+|---|---|---|
+| 1 | No secret in the working tree: token, API key, password, private key block, connection string and high-entropy string that looks like a credential, including `.env` files, test fixtures and example configs. | Reading of the branch diff plus a scan of the tree. The report names the tool used or says the pass was manual. With `verify.security_scan` declared, the evidence is the `security_scan` (Gitleaks on the tree); the manual pass is only valid with the scan declared `unavailable`. |
+| 2 | No secret in the history behind the branch. A secret committed and later deleted is still leaked. | `git log -p <base>..HEAD` over the whole range, not just the tree. Blocker until the credential is rotated and the history cleaned, with the rotation verified, not promised. With `verify.security_scan` declared, the `security_scan` also scans the commits of `<base>..HEAD`; the manual pass is only valid with the scan declared `unavailable`. |
+| 3 | No real credential in a dispatched prompt. The `phase.dispatch` gate of `ork` evaluates the `segredo_em_prompt` policy BEFORE writing the prompt to disk: a rejected prompt never comes to exist as a file, because writing a prompt with a credential creates a second leak inside the repository itself. | `ork phase run` exits with typed reason `policy.violation`; the ledger records the pattern name and the line, never the matched excerpt. |
+| 4 | No real credential in a thread artifact, the ledger, captured command output or the audit report itself. A leak report that prints the secret is a second leak. | Reading of the artifacts the thread produced. A redacted placeholder passes and is declared as such; a credential is referenced by location and redacted form. |
+
+## Input and surface
+
+| # | Check | How it is proven |
+|---|---|---|
+| 5 | Every input that crosses a trust boundary is validated on the trusting side, not on the calling side. Client-only validation counts as missing. | Reading of the diff at the touched entry points. |
+| 6 | No concatenation of input into SQL, shell, file path or rendered template. The `ork` core runs commands as an argument list, with no interpolated shell, and the same pattern applies to the reviewed code. | Reading of the diff; any command built by concatenation is a blocker. |
+| 7 | Authentication and authorization checked per operation, not per screen: whoever can read cannot always write, and either the test that proves this exists or the finding is a warning with a record. | Authorization tests in the suite, rerun by `ork verify`. |
+| 8 | Deserialization of untrusted data does not instantiate arbitrary types, and every `JSON.parse` of a state file has its error handled with the path in the error text. | Reading of the diff over the points that read state. |
+
+## Dependencies and supply chain
+
+| # | Check | How it is proven |
+|---|---|---|
+| 9 | No new dependency without justification in the PLAN. A dependency that comes in without a task is scope creep with an attack surface. | Diff of the package manifest files against the PLAN tasks. |
+| 10 | Known vulnerabilities in the declared dependencies were looked up, and the result is in the report with the date and the tool. Where there is no tool, the item comes out `unavailable` with the reason. | `npm audit` where a production dependency is declared. With `verify.security_scan` declared, the evidence is the `security_scan` (dependencies and govulncheck `reachable`); the manual pass is only valid with the scan declared `unavailable`. |
+
+## Repository artifacts
+
+| # | Check | How it is proven |
+|---|---|---|
+| 11 | No mass destructive command in a script, hook or documentation that someone will copy: `rm -rf` with an unanchored variable path, `git add -A`, `git checkout -- .`, `git reset --hard` without a target, `push --force`. | Scan of the touched directories. The `PreToolUse` guard of the Claude Code adapter blocks these same commands at run time. |
+| 12 | No direct push to the base branch. The manifest's `push_direto_na_base` policy is blocking and rejects any delivery whose source and target are the same branch. | `ork ship` exits with `policy.violation` before touching the remote. |
+| 13 | No dispatch through a paid provider when the policy is `subscription-only`. An environment variable that redirects `claude` to a paid provider is a blocker, because the cost shows up on the bill and not at the gate. | `ork doctor` and the `provider` policy, evaluated at the `phase.dispatch` gate and in `ship`. |
+| 14 | Permissions on a file created by a script do not widen access: no `chmod 777`, no state file with the execute bit. | Reading of the diff of the scripts and hooks. |
+
+## Audit conduct
+
+| # | Check | How it is proven |
+|---|---|---|
+| 15 | The audited scope is declared before the findings: which directories, which history range, which artifacts. An audit without a declared scope is not reproducible and does not count as evidence. | The header of the report's security section. |
+| 16 | Each finding comes out categorized as blocker, warning or suggestion, with the `SEC n` item it violates. A finding without an item number is opinion. | The report's findings table. |
+| 17 | Absence of findings is stated as the result of a check, with what was looked at. "Nothing found" without a scope is different from "audited and clean", and the difference is written down. | The section text, against `SEC 15`. |
+
+## Network attack surface
+
+What the product EXPOSES. Items 5 to 8 look at the data that comes in through a boundary; these look at
+the boundary itself: which routes and endpoints exist, who can call them and at what cost. The
+`security-privacy` pack audits this section with a DETERMINISTIC scan (`ork audit surface`, rules
+SP8 to SP12), which runs inside `ork audit run security-privacy` and writes each finding to the
+debt board with `arquivo:linha` evidence and the command that reruns it.
+
+| # | Check | How it is proven |
+|---|---|---|
+| 18 | Every HTTP/API server route declared in production goes through an authentication/authorization layer, or is public by a recorded decision (login, sign-up, health, signed webhook). A route that is public by oversight is a blocker. | `ork audit surface --regra SP8`. The finding brings the route definition with `arquivo:linha`, the recognized framework and the command that proves the absence of a guard in the route block or in the file. |
+| 19 | An administration or operations endpoint (admin, console, debug, swagger/openapi, detailed health, metrics, `pprof`, cluster metadata) is not reachable from outside: there is a network restriction (allowlist, internal network) or oAuth/basic auth. A health check that returns version, hostname, database or dependency is an operations endpoint, not a health one. | `ork audit surface --regra SP9`, plus the network configuration or the middleware cited with `arquivo:linha`. |
+| 20 | An exposed route has a rate limit per IP and per identity, with special attention to the authentication path, password recovery, OTP, search, export and any public route that changes state. Without a limit, a brute-force costs no more than a request. | `ork audit surface --regra SP10`. Limit, quota or rpm middleware cited on the route, on the router that mounts it or on the gateway, with the file and the line. |
+| 21 | CORS does not combine a global origin with credentials, and an open origin does not appear in a service that carries personal data or sessions. An explicit list of origins, always. | `ork audit surface --regra SP11`. The finding cites the configuration with `arquivo:linha`, the origin wildcard and the credentials flag, each with the command that reruns it. |
+| 22 | The route definition declares the payload schema at the edge (schema, validator, typed model), and an invalid payload is rejected before the handler. Complements item 5, which looks at the USE of the data inside the handler. | `ork audit surface --regra SP12`, with the route definition and the absence of a schema at the entry point. |
+
+A finding that the scan marks with confidence `baixa` (low: there is middleware that `ork` does not classify,
+an unrecognized framework, a marker present in the file and absent from the route block) comes out as a
+**warning that asks for human confirmation**, never as a blocker: the machine says where to look, and
+the person decides whether it holds.
+
+## Recommendations (not a gate on this machine)
+
+- Scanning with a dedicated secret tool (gitleaks, trufflehog): not installed here. The
+  patterns in `core/src/policies.ts` cover Anthropic keys, OpenAI keys, AWS access keys, GitHub
+  tokens, PEM private keys and secret assignments in text, and the audit says it covered those
+  classes and no others.
+- Software composition analysis and artifact signing: out of reach for this machine; it comes out
+  `unavailable` with the reason, never as a silent pass.
+- Dynamic surface testing (port scanning, endpoint fuzzing, DAST): out of reach.
+  The scan for items 18 to 22 is STATIC and reads the route definition in the code: it does not see
+  routes generated at run time, nor a proxy, gateway or WAF in front of the service. Where that
+  layer exists, the finding still stands as a question and is resolved with the layer's evidence, never
+  in silence.