@orkastery/cli 0.5.3 → 0.6.0

package/assets/skills-en/phases/check-quality/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: check-quality
+description: "CHECK phase (F4): verification against the baseline, the five review axes, security and performance audits, a delegation audit and a single verdict. Routes to ork verify and to the four reviewer skills."
+bucket: phases
+roteia: "ork verify <thread> | ork gate request <thread>"
+license: MIT
+---
+
+# CHECK, verification
+
+## What this skill is
+
+A thin router for the CHECK phase. It consolidates what `ork` measured and what the four reviewers
+found, and produces **exactly one verdict**: PASSOU (passed), PRECISA DE MUDANCA (needs changes) or BLOQUEADO (blocked). It does not
+fix what it finds: fixing is GO's job.
+
+## How to route
+
+```bash
+ork verify <thread>                  # reexecuta claims e verify contra a baseline
+ork phase list <thread>              # o ledger, para a auditoria de delegacao
+ork worktree audit <thread>          # a worktree confere no proprio git
+ork gate request <thread>            # o pedido da pausa; o humano responde pelo canal autenticado
+```
+
+- Waits: never start verify, build or the suite with `&` inside the command, because the process gets lost and the session waits for a notice that never comes; run `ork verify` in the foreground, with `timeout` (it waits its turn in the heavy-resource queue), or use the host's background execution, which tells you when it finishes; never wait with `pgrep -f` whose pattern shows up in the command itself, because the loop finds itself and never ends: wait for the output file with a deadline, or for the saved PID.
+
+When the verdict is PRECISA DE MUDANCA, the GO-FIX / CHECK-REVERIFY sub-loop of block B3 is
+what conducts the way back, and it does not depend on a human until the final verdict:
+
+```bash
+ork fix open <thread>                # deriva a spec exata de cada correcao do verify real
+ork fix list <thread>                # as correcoes da rodada, com o tipo A ou B de cada uma
+ork fix reverify <thread>            # veredito POR correcao, mais o verify completo
+ork retry plan <thread>              # o que o ork faria pelo ultimo gate reprovado, e por que
+```
+
+Two guards the core enforces for you: a PARTIAL rerun is REFUSED when the round
+has a type B fix, and the manifest's escalation limit (`retry.max_tentativas`) sends the
+verdict up to a human in any mode, including `#Auto`.
+
+The catalog's four reviewers come in here: `code-reviewer`, `security-auditor`, `test-engineer`
+and `web-performance-auditor`. Each one runs in its own scope and returns categorized findings.
+
+## What CHECK delivers
+
+1. **Comparison against the baseline**, separating regression from pre-existing debt. Without that
+   separation, the report blames the thread for what was already broken.
+2. **The five axes**, each with findings or an explicit "none": correctness, security,
+   performance, maintainability, style.
+3. **Zero security blockers**, a hard condition, valid in any mode, including `#Auto`.
+4. **Delegation audit**, hunting under-classification and undue escalation with equal weight.
+5. **Fixes classified honestly:** type A is one line or equivalent, recorded, with
+   the affected checks rerun; type B sends the task back to GO, and the next CHECK is a
+   full rerun, never a partial one.
+6. **A single verdict**, in the thread directory, with every accepted warning carrying its record.
+
+## With `verify.security_scan` declared
+
+Without `verify.security_scan`, nothing in this section applies and CHECK is the usual one. With the key, `ork verify` runs `ork security-scan` and the verdict consolidates the scan:
+
+1. Read `report.md` and `report.json` in `.orkastery/security-scan/<sha>/`, in the main tree; the SHA is the verified HEAD's.
+2. Zero security blockers becomes: no `new` loop finding without a resolved verdict from the `security-auditor` (real and fixed, false positive dismissed with a recorded decision, or inconclusive with the `ork gate request` answered).
+3. A `new` finding with `loop: false` (`warn` in the report, such as quality, license or severity below the cut) goes to the right axis as a registered warning, with the name of who accepted it, never as a hidden blocker.
+4. A tool `unavailable` or `failed` is declared in the verdict and never counts as clean; with `ORK_SECURITY_SCAN_REQUIRED=1` it makes the scan exit 1.
+5. A fix coming from the scan goes back through GO-FIX, with the `security-remediation` skill; the proof is `ork fix reverify`, which reruns verify and the scan.
+6. The per-finding verdict reaches GO-FIX through the CHECK claim (`--fase CHECK`), one per real or false-positive finding, as the `security-auditor` skill says. `ork fix open <thread>` reruns verify and opens one correction per failed claim, type B for a real one (`claims.failed`) and type A for a false positive (`claims.unverifiable`), next to the type B correction of the `security_scan` command; `ork fix list <thread>` shows them to GO-FIX with the verdict text.
+7. Inconclusive does not open the request from inside the CHECK session: `ork gate request` refuses while the observer has not recorded the phase conclusion (`a conclusao da fase precisa estar registrada antes da pausa`), and `--motivo` only accepts a typed escalation already recorded in the ledger (`escalacao tipada nao comprovada`). The short question goes into the report, the session ends, and whoever conducts runs `ork gate request <thread> --formato telegram`, which opens the pause at the end of the block that ends at CHECK, with the report in the evidence. Among the live modes, only #Classic has that pause (GO-CHECK block); #Look and #Ork also paused at CHECK, but they are retired (I-43) and the request refuses for them. The request carries the gate's generic question (`Qual e o veredito sobre evidencias...?`): whoever conducts points the owner to the report's question, with the finding id. The owner's answer becomes a CHECK claim as the `security-auditor` skill says, before `ork fix open`. In a mode without that pause (#Maestro, #Auto), the request refuses (`modo nao preve pausa humana nesta fase`): the verdict is BLOQUEADO, with the question written, and nothing proceeds until the owner answers.
+
+## What the core checks for you
+
+The typed reasons of `ork` keep the verdict from being just talk: `claims.failed`,
+`verify.regression`, `verify.failed`, `policy.violation`, `cost.violation`, `tree.blocked`,
+`lease.busy`, `runtime.rate-limited`. All of them fail in any mode, because **the mode relaxes
+the pause, never the verification**. Each one has a deterministic retry action in
+`ork retry policy`, and `cost.violation` is the only one that NEVER gets an automatic retry.
+
+## Racionalizacoes comuns (Common rationalizations)
+
+| Excuse | Reality |
+|---|---|
+| "It's just a warning, we can let it through" | A warning passes with a named record of who accepted it and why. A warning accepted without a record is a hidden warning. |
+| "The fix was small, no need to run everything again" | A type B fix sent the task back to GO: the next CHECK is a full rerun. A partial rerun after type B is not a CHECK. |
+| "That test was already failing, ignore it" | "It was already failing" is a verifiable statement: the baseline is what answers it, and the debt goes into the report as declared. |
+| "The security blocker is theoretical" | Zero blockers is a hard condition. A blocker downgraded to a warning because the delivery was close is the process defect CHECK exists to expose. |
+| "Since I found it, I'll fix it right here" | CHECK does not fix. A finding becomes a GO task, with its own commit, or the reviewer ends up reviewing itself. |
+| "The thread is `#Auto`, so CHECK can be lighter" | The mode relaxes the pause, never the verification. `#Auto` runs the same CHECK; what it waives is waiting for the human. |
+
+## Bandeiras vermelhas (Red flags)
+
+- A report with two verdicts, or with none.
+- A review axis with no finding and no written "none".
+- A type B fix followed by a partial rerun.
+- A warning accepted without the name of who accepted it.
+- CHECK run without a baseline to compare against.
+- A `new` loop finding without a verdict passed off as zero blockers.
+- An inconclusive `new` scan finding carried by `ork gate request` from inside the CHECK session, or with a free-text `--motivo`.
+
+## Verification before leaving the phase
+
+Suite rerun on the real HEAD, five axes filled in, security with zero blockers,
+performance audited or waived in writing, delegation audited, a single verdict recorded and the evidence
+gate resolved by the path the mode requires. See `DoD 6` to `DoD 11`, `REVIEW 6` and `SEC 16`.

package/assets/skills-en/phases/go-implementation/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: go-implementation
+description: "GO phase (F3): slice-by-slice implementation inside the thread's worktree, one atomic commit per task, baseline recorded before starting. Routes to ork worktree ensure, ork verify --baseline and ork phase run GO."
+bucket: phases
+roteia: "ork worktree ensure | ork verify --baseline | ork phase run <thread> GO"
+license: MIT
+---
+
+# GO, implementation
+
+## What this skill is
+
+A thin router for the GO phase. **The presenting layer never writes product code:** the
+orchestra does the writing, dispatched by `ork`. This skill ensures the worktree, records the baseline,
+dispatches and then reruns the verification in the real world.
+
+## How to route
+
+```bash
+ork worktree ensure <thread>                  # worktree isolada, base resolvida pelo ork
+ork verify <thread> --baseline                # o estado do mundo ANTES de implementar
+ork phase run <thread> GO --prompt "<tarefa>"
+ork claims add <thread> <arquivo> --claim "<...>" --verificar "<comando>" --fase GO
+ork verify <thread>                           # reexecuta no HEAD real
+```
+
+- Waits: never start verify, build or the suite with `&` inside the command, because the process gets lost and the session waits for a notice that never comes; run `ork verify` in the foreground, with `timeout` (it waits its turn in the heavy-resource queue), or use the host's background execution, which tells you when it finishes; never wait with `pgrep -f` whose pattern shows up in the command itself, because the loop finds itself and never ends: wait for the output file with a deadline, or for the saved PID.
+
+## What GO delivers
+
+1. **One atomic commit per task**, with the thread and the task in the message, at most five files.
+2. **Work inside the thread's worktree.** The main tree is not a work area for any thread
+   whatsoever, and the base stamped in `thread.json` is what says where the thread started from.
+3. **Baseline recorded before the first line.** Without a baseline, a later failure cannot tell
+   regression from pre-existing debt, and the thread either takes someone else's blame or hides what broke.
+   On codex, whose sandbox does not write the thread state, `ork phase run` records the baseline before
+   releasing the block with GO: check the `baseline` field in `ork_thread_status` and carry on instead of stopping.
+4. **One claim per statement.** Every cited file, every cited test, every function said to be done becomes
+   a claim with a command. A pass reported by an agent is not a pass.
+5. **Nothing outside the PLAN's tasks.** An opportunistic improvement with no task is scope creep: it becomes
+   a proposal, never a commit hidden in the middle of the delivery. Whatever the diff does beyond what was agreed, the
+   reviewer has to discover alone, and that is how a small delivery turns into an expensive review.
+
+## With `verify.security_scan` declared
+
+Without `verify.security_scan`, this phase is the usual one. A fix that comes from a security scan finding uses the `security-remediation` skill: it fixes only the finding, and the proof is the scan rerun by `ork fix reverify`, not the agent's report. The spec carries one correction per finding triaged by CHECK, with the type and the verdict text (`ork fix list <thread>`): type A closes by writing the dismissal and attaching the command that proves it with `ork claims verificar <thread> <claim> --comando "<comando>"`.
+
+## What the core checks for you
+
+`ork verify` reruns claims and manifest commands on the real HEAD and compares against the baseline:
+a command that passed before and fails now comes out as `verify.regression`; what was already failing comes out as
+declared debt. A citation without backing comes out as `claims.failed`. All three fail in any mode.
+
+## Racionalizacoes comuns (Common rationalizations)
+
+| Excuse | Reality |
+|---|---|
+| "I ran it and it passed, you can trust me" | A reported pass is not a pass. `ork verify` reruns on the real HEAD, and the real output is what counts. |
+| "Let me commit everything together at the end" | One commit per task. A giant commit cannot be reverted, cannot be reviewed and does not tell which piece broke. |
+| "I'll work straight in the main tree, it's faster" | The main tree is not a thread work area. An isolated worktree is what allows N threads without collision. |
+| "Baseline is a waste of time, the repo is green" | If it really were green, the baseline would cost one command. Without it, every failure turns into an argument over whose fault it is. |
+| "While I was at it, I fixed something else along the way" | An improvement outside the PLAN's tasks is scope creep: it becomes a proposal, never a commit hidden in the middle of the delivery. |
+| "The failing test was already failing before" | That is exactly what the baseline answers by command, instead of by memory. |
+
+## Bandeiras vermelhas (Red flags)
+
+- A commit with dozens of files and a generic message.
+- Work happening outside the thread's worktree.
+- No baseline recorded before the first commit.
+- A file cited in the runtime summary that does not appear in `git show --stat`.
+- A test disabled or an assertion loosened to close the task.
+- A change in the diff that does not match any PLAN task.
+
+## Verification before leaving the phase
+
+Worktree checked by `ork worktree audit`, baseline recorded before GO, one commit per task,
+claims with a command for everything that was stated, and `ork verify` green or with the debt declared. See
+`DoD 1`, `DoD 2`, `DoD 3` and `DoD 4`.

package/assets/skills-en/phases/goal-definition/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: goal-definition
+description: "GOAL phase (F1): a verifiable goal, exploration of the real repository, explicit assumptions, impact map, risks and observable success criteria, all tied to claims with a verification command. Routes to ork phase run GOAL and ork claims add."
+bucket: phases
+roteia: "ork phase run <thread> GOAL | ork claims add"
+license: MIT
+---
+
+# GOAL, goal definition
+
+## What this skill is
+
+A thin router for the GOAL phase. It does not explore the repository on its own and does not implement
+anything: it dispatches the phase through `ork` and turns the result into claims that `ork` reruns.
+**GOAL does not implement.**
+
+## How to route
+
+```bash
+ork thread new "<nome>" --mode <modo>
+ork phase run <thread> GOAL --prompt "<pedido do builder>"
+ork claims add <thread> <arquivo> --claim "<alegacao>" --verificar "<comando>" --fase GOAL
+ork verify <thread> --so-claims
+ork gate request <thread>
+```
+
+## What GOAL delivers
+
+1. **A goal in three paragraphs, at least.** Even a one-line fix gets a GOAL of
+   three paragraphs: compact means smaller, never absent.
+2. **Exploration of the real repository.** The exploration targets the actual repository, not the model's
+   memory. Cite concrete files and excerpts or the exploration did not happen.
+3. **Explicit assumptions.** An implicit assumption is the biggest source of rework and is treated as a
+   process defect. Writing the assumption costs one line; finding out in GO that it is wrong costs the
+   thread.
+4. **Impact map.** What changes, what it touches and what stays out, with what stays out written down.
+5. **Observable success criteria.** Latency, coverage, verifiable behavior: never
+   an adjective. In a fix request, reproducing the defect is a mandatory GOAL criterion.
+6. **Risks and ambiguities**, each with what would turn it into a blocker.
+
+## What the core checks for you
+
+Every success criterion becomes `ork claims add ... --verificar "<comando>"`, and `ork verify` reruns
+the command on the real HEAD. A statement without a command comes back as `claims.unverifiable`; a statement that fails
+comes back as `claims.failed`, a typed reason that fails in any mode.
+
+## Racionalizacoes comuns (Common rationalizations)
+
+| Excuse | Reality |
+|---|---|
+| "I already know this framework, we can skip the exploration" | The exploration targets the real repository, not the model's memory. Without a cited file and excerpt, the GOAL is a plausible summary of code nobody opened. |
+| "Listing assumptions is red tape, they are obvious" | An implicit assumption is the biggest source of rework. What is obvious to the writer is usually a surprise in GO. |
+| "The criterion is that it works well and the user likes it" | An adjective is not a metric. A criterion that does not become a command gates nothing, and the gate is where autonomy is lost. |
+| "The repository is empty, there is nothing to explore" | Exploring an empty repository is still exploring: write down what was verified as absent, or the absence becomes an implicit assumption. |
+| "The bug is obvious, I don't need to reproduce it first" | A fix whose defect was never reproduced does not prove it fixed anything. Reproducing the defect is a mandatory GOAL criterion. |
+
+## Bandeiras vermelhas (Red flags)
+
+- A GOAL with no cited file or excerpt from the repository.
+- Missing assumptions, or ones discovered later as a surprise during GO.
+- A success criterion written with an adjective.
+- A fix request with no step that reproduces the defect.
+- A GOAL that already brings implementation code: GOAL does not implement.
+
+## Verification before leaving the phase
+
+A goal with three paragraphs, exploration citing real files, written assumptions, an impact map with
+what stays out, criteria turned into claims with a command, and the goal gate resolved by the
+path the mode requires. See `DoD 17` and `DoD 18`.

package/assets/skills-en/phases/master-metrics/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: master-metrics
+description: "MASTER phase (F6): typed POSTMORTEM, MASTER log in the frozen ork.master-log/v1 contract and the human score from 0 to 5 with a justification. Routes to ork master and ork master <thread> --aceitar-omissao."
+bucket: phases
+roteia: "ork master <thread> --score N --justificativa \"...\" | ork master <thread> --aceitar-omissao"
+license: MIT
+---
+
+# MASTER, closing and score
+
+## What this skill is
+
+A thin router for the MASTER phase. It does not invent numbers, does not round scores and does not close a thread
+without a human: it calls `ork master`, which validates against the frozen contract and refuses whatever does not
+comply. **A delivery without a MASTER log did not happen.**
+
+## How to route
+
+```bash
+ork master classes                            # as classes de falha do catalogo fixo
+ork master <thread> --score 4 --justificativa "<texto>" --classe base-avancou --por <quem>
+ork master                                    # as entregas, com o indice derivado do ledger
+ork master --todas                            # inclusive as ja pontuadas
+ork master <thread> --aceitar-omissao         # aceita so a entrega desta thread, com indice e insumos no ledger
+ork master --aceitar-omissao --dry-run        # lista o que a forma sem thread fecharia, sem gravar
+```
+
+An agent closes only its own thread: `ork master <thread> --aceitar-omissao`. Without the thread, the command
+accepts ALL of the project's delivered threads, including those of other parallel fronts (which happened three
+times on 2026-10-03); run from an agent process with more than one, `ork` warns on stderr.
+
+## What MASTER delivers
+
+1. **Typed POSTMORTEM**, with the phases traversed, what failed and the failure class taken from a
+   fixed catalog: `sem-falha`, `erro-de-spec`, `base-avancou`, `conflito`, `rate-limit`, `modelo`,
+   `processo`, `scope-creep`, `outra`. An invented class is refused by the command.
+2. **MASTER log in the `ork.master-log/v1` contract**, frozen: changing the contract without changing the version
+   fails, because a telemetry contract is a public contract.
+3. **Integer human score from 0 to 5, with a non-empty justification.** The score belongs to the human, always. In
+   the modes with no MASTER pause, the delivery is accepted by default, with the ledger-derived index, which
+   no agent types; the human score, when it comes, overrides it.
+4. **Evidence pointing to the ledger and the POSTMORTEM**, with counts of events, sessions and claims. A log
+   without evidence is refused.
+
+## What the core checks for you
+
+`ork master` refuses and **writes nothing** when the score is outside 0 to 5, when the justification
+is empty, when the class is outside the catalog, when a phase is outside the canonical cycle,
+when the contract was changed without changing the version and when evidence is missing. A partial refusal that
+writes half is worse than a full refusal.
+
+## Racionalizacoes comuns (Common rationalizations)
+
+| Excuse | Reality |
+|---|---|
+| "Score 5 because it delivered, justification later" | An empty justification is refused by the command. A score without a written reason teaches the next thread nothing. |
+| "I'll give it 4.5, it landed between the two" | The score is an integer from 0 to 5. A scale with half points turns into a negotiation, and what is measured here is conduction, not goodwill. |
+| "The failure class for this one was 'almost worked'" | The catalog is fixed. An invented class is refused, because a free-form class destroys comparability between threads. |
+| "I'll fill in the MASTER log later, the delivery already went out" | A delivery without a MASTER log did not happen. A postponed learning phase is a learning phase that does not exist. |
+| "The mode is `#Auto`, so the score can be automatic" | The score is human in every mode. `#Auto` changes when it is given (the delivery is accepted by default and the human score overrides it), never who gives it. |
+
+## Bandeiras vermelhas (Red flags)
+
+- A thread delivered without `master-log.json`.
+- A score recorded without the name of who rated it.
+- A failure class outside the fixed catalog, or no class on a thread that had rework.
+- A score typed by an agent in the human's name.
+
+## Verification before leaving the phase
+
+Typed POSTMORTEM recorded, MASTER log valid against `ork.master-log/v1`, integer score with
+justification and rater, and evidence pointing to the ledger and the POSTMORTEM. See `DoD 16`.

package/assets/skills-en/phases/plan-specification/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: plan-specification
+description: "PLAN phase (F2): a plan with sliced tasks, queryable touch_paths, decisions D1..Dn with a single home and an executable verify per task. Routes to ork phase run PLAN and ork lease acquire."
+bucket: phases
+roteia: "ork phase run <thread> PLAN | ork lease acquire"
+license: MIT
+---
+
+# PLAN, specification
+
+## What this skill is
+
+A thin router for the PLAN phase. It does not write the plan's code and does not decide on its own what is the
+human's tradeoff: it dispatches the phase through `ork` and turns the plan into tasks with a verify.
+**PLAN does not implement.**
+
+## How to route
+
+```bash
+ork phase run <thread> PLAN --prompt "<pedido do builder>"
+ork lease acquire "path:<glob>" --thread <thread> --motivo "PLAN reservou a regiao"
+ork gate request <thread>
+ork handoff export <thread> --proxima-fase GO
+```
+
+## What PLAN delivers
+
+1. **Tasks sliced until they fit in one atomic commit.** At most five files per task.
+   A task larger than that goes back to slicing before GO, not during it.
+2. **`touch_paths` per task.** The path the task will touch is declared up front, and it is what
+   justifies the `path:<glob>` lease. An undeclared region is a collision waiting to happen.
+3. **One executable verify per task.** Every task carries the command that proves it is finished.
+   A task without a verify is a wish, not a task.
+4. **Decisions D1..Dn with a single home.** Each decision lives in one place only, and once decided
+   it is locked. Reopening is a new decision with a record, never a silent edit of the previous one.
+5. **What stays out of scope**, written down, so that CHECK can call scope creep whatever
+   shows up beyond that.
+
+## What the core checks for you
+
+The `path:<glob>` lease of `ork` refuses two threads in the same region and queues the second with a
+position; the typed handoff carries the closed decisions to the next phase without depending on the session
+remembering them.
+
+## Racionalizacoes comuns (Common rationalizations)
+
+| Excuse | Reality |
+|---|---|
+| "The plan is already in my head, writing it down slows me down" | A plan that is not on disk does not survive a context window rotation, and the next phase starts by guessing. |
+| "This task is big but cohesive, leave it whole" | A task larger than five files goes back to slicing. An atomic commit is what makes whatever goes wrong reversible. |
+| "I'll decide that tradeoff later, in the middle of GO" | A tradeoff decided in the middle of GO is decided in a hurry and without a record. A decision has a single home and locks when closed. |
+| "Writing a verify per task is ceremony" | A task without a verify is a wish. Without a command, "done" becomes the agent's opinion and CHECK has nothing to compare against. |
+| "I don't need to declare touch_paths, it's obvious where I'll make changes" | The lease comes from `touch_paths`. An undeclared region is the normal way for two threads to run over each other. |
+
+## Bandeiras vermelhas (Red flags)
+
+- A task without a verify command.
+- A task that touches more than five files.
+- A decision repeated in two places in the plan, with different wording.
+- `touch_paths` missing on a thread that runs in parallel with another.
+- A PLAN that already brings the finished code: PLAN does not implement.
+
+## Verification before leaving the phase
+
+Tasks sliced with a verify, `touch_paths` declared, decisions with a single home and locked,
+out of scope written down, and the assumptions gate resolved by the path the mode requires. See
+`DoD 19` and `DoD 20`.

package/assets/skills-en/phases/security-remediation/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: security-remediation
+description: "Fixing a security scan finding in GO: fixes only the finding triaged as real, requires a declared rotation for a secret, raises a dependency to the lowest fixed version and proves it by the rerun scan. Routes to ork fix and ork security-scan."
+bucket: phases
+roteia: "ork fix open | ork fix list | ork claims verificar | ork fix reverify | ork security-scan"
+license: MIT
+---
+
+# Security remediation
+
+## What this skill is
+
+A thin router for the fix that comes from a `new` loop finding of `ork security-scan`, after the `security-auditor` triaged it as real. It applies only with `verify.security_scan` declared and runs inside GO, in the thread worktree, with the conduct of [go-implementation](../go-implementation/SKILL.md).
+
+## How to route
+
+```bash
+ork fix open <thread>
+ork fix list <thread>
+git ls-remote --heads <remoto> <branch>
+ork security-scan
+ork claims verificar <thread> <claim> --comando "<comando>"
+ork fix reverify <thread>
+ork decisao registrar <thread> ...
+```
+
+## What the remediation delivers
+
+1. **Only the finding.** The fix changes what the finding points at (rule, `arquivo:linha`) and nothing around it: neighbouring refactoring is scope creep and hides the fix inside the diff.
+2. **The secret leaves the code AND has a declared rotation.** Removing it from the file does not undo the leak (`SEC 2`): history is not cleaned by fixing the code. The fix only closes with the rotation declared to the credential owner, dated and verified, not promised. The secret value never goes to the report, the commit or the prompt.
+   - **Whoever fixes also never prints the value.** The auditor's rule applies in GO: the finding's line, its neighbours and the commit that brought it do not go to the session output through any tool (Read, `sed -n`, `head`, `cat`, `grep -n`, editor, `git show`, `git log -p`, diff). Edit without reading, by the report's line number: delete the line (`sed -i '<n>d' <arquivo>`) or replace it whole (`sed -i '<n>s/.*/<substituto>/' <arquivo>`, with the replacement reading the credential from the environment or the vault, never with the value). A multi-line secret (a PEM key): the end of the block comes out only as a number (`command grep -n -- '-----END' <arquivo> | cut -d: -f1`) and the range is deleted with `sed -i '<n>,<m>d' <arquivo>`. Check by the scan, not by eye: the finding's `fingerprint` leaves the new report. In the history rewrite below, redo the commits the same way, without `git diff` or `git show` of the secret's commit.
+   - **A secret that entered in the thread leaves the thread history.** Gitleaks scans the commits of `<base>..HEAD`, and the finding stays `new` while a thread commit carries the value. Never just delete the line in a new commit. With the thread branch on no remote (`git ls-remote --heads <remoto> <branch>` exits 0 and empty for every `git remote`; a non-zero exit is doubt, not absence), rewrite only the thread commits from the one that brought the secret: `git reset --soft <commit anterior ao segredo>`, with the target at the thread base or after it (`git merge-base --is-ancestor <base> <alvo>`), and the commits again without the value, without `push --force`. Rewriting a thread commit not yet published is the path the method already uses, and `ork ship publicar` pushes without force: rewritten history that was already published would be refused at push anyway.
+   - **A branch already published is not rewritten.** The finding stays `new`, because the commit remains in `<base>..HEAD`. The rotation declared and verified is still mandatory, and the way out is a dismissal citing the declared rotation, decided by the owner: the finding goes back to CHECK as inconclusive and, with the answer, becomes type A like any dismissal.
+3. **A dependency goes to the lowest fixed version**, the one the report indicates, with the justification of the choice in the commit. Jumping to the latest brings changes nobody asked for.
+4. **The proof is the rerun scan.** The proof is the scan rerun by `ork fix reverify`, which `ork` runs on the real HEAD; the agent's statement that it "fixed it" is not proof. The finding must be gone from the new report, and no `new` may have come in. **The scan reads only the committed HEAD:** the scanned tree is a checkout of the HEAD commit, so a fix, a dismissal entry or a config not yet committed is invisible to it. Commit before rerunning.
+5. **A dismissal is a type A fix**, and only when the triager classified a false positive. The entry goes to `.ork-security/dismissals.json` with `fingerprint`, `tool`, `rule`, `file`, `reason`, `decidedBy`, `decisionRef` (the reference of the decision recorded with `ork decisao registrar`) and `date`; without a reason and a recorded decision, the config is invalid and the scan exits 1.
+6. **An excluded file is not fixed.** A finding in a path the scan config excludes goes back to triage: either the finding is in another file, or the exclusion is wrong, and changing the exclusion is a recorded decision, not a shortcut.
+7. **One correction per finding.** The `ork fix open` spec carries, next to the correction of the `security_scan` command, one correction per CHECK claim, with the type and the verdict text (`ork fix list <thread>`): type B for a real one, type A for a false positive. Type A closes with the dismissal entry and with the command that proves it attached to the claim (`ork claims verificar <thread> <claim> --comando "<comando>"`); the real finding's claim fails and passes with the whole scan, so type B closes when the rerun scan exits with no `new` loop finding, not only when this `fingerprint` is gone.
+
+## What the core checks for you
+
+`ork security-scan` exits 1 on a `new` loop finding (every new secret; new dependency, SAST, IaC and workflow findings at `high` or `critical`) and on an invalid dismissal. `ork fix reverify` gives the verdict per fix and refuses a partial rerun after type B. A tool `unavailable` or `failed` never counts as clean.
+
+## Racionalizacoes comuns (Common rationalizations)
+
+| Excuse | Reality |
+|---|---|
+| "I took the secret out of the code, it is resolved" | The secret is still valid and still in the history. The rotation declared to the owner and verified is missing. |
+| "I deleted the line in a new commit, the finding goes away" | Gitleaks scans `<base>..HEAD`: the old commit still carries the value and the finding stays `new`. Rewrite the unpublished thread history and declare the rotation. |
+| "Since I am here, I will tidy the rest of the file" | The fix is only the finding. The rest becomes a proposal, with its own task and commit. |
+| "I will go to the newest version, it is safer" | The lowest fixed version, with a justification. The newest brings changes nobody assessed. |
+| "It worked here, the finding must be gone" | The proof is the rerun scan, not the impression of whoever fixed it. |
+| "It is a false positive, I dismiss it and done" | A dismissal requires the triage, the reason and the recorded decision. Without them the config goes invalid. |
+
+## Bandeiras vermelhas (Red flags)
+
+- A secret removed from the file with no rotation declared to the owner.
+- A thread secret fixed only by a new commit, with the commit that brought it still in `<base>..HEAD`.
+- `push --force` to clean the history of a published branch.
+- A fix closed without `ork fix reverify` and without a new scan.
+- A diff with a change that is not the finding.
+- A dependency that skipped several versions with no justification.
+- An entry in `.ork-security/dismissals.json` without `reason` or without `decisionRef`.
+- A secret value pasted in the commit, the report or the prompt.
+- The secret's line read or printed to edit it (Read, `sed -n`, `cat`, `git show`) instead of the edit by line number.
+- The scan rerun with the fix or the dismissal still uncommitted.
+
+## Verification before leaving the fix
+
+Diff restricted to the finding, rotation declared and the thread history without the secret's commit when it was a secret, version justified when it was a dependency, a complete dismissal entry when it was type A, and `ork fix reverify` green with the finding out of the new report. See `SEC 1`, `SEC 2` and `SEC 10`.

package/assets/skills-en/phases/ship-release/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: ship-release
+description: "SHIP phase (F5): merge serialized by lease, update against the base, push proven by command and a rollback plan. Routes to ork ship, which only delivers with the push verified on the remote."
+bucket: phases
+roteia: "ork ship <thread> --para <base>"
+license: MIT
+---
+
+# SHIP, delivery
+
+## What this skill is
+
+A thin router for the SHIP phase. It does not merge by hand, does not push a branch on the side and does not decide
+on its own that the push may happen: it calls `ork ship`, which serializes the merge by lease and **proves
+the push by comparing the local sha with what the remote reports**.
+
+## How to route
+
+```bash
+ork worktree sync <thread>                  # rebasa quando a base avancou
+ork ship <thread> --para main --dry-run     # ensaio: mostra tudo, nao toca em nada
+# autorizacao humana registrada: vai no proprio ship, com o nome de quem autorizou
+ork ship <thread> --para main --autorizar-push <quem>
+ork phase list <thread>                     # a prova: mergeSha, shaRemoto, pushVerificado
+```
+
+## What SHIP delivers
+
+1. **Serialized merge.** The `main-tree` lease lets one thread at a time touch the target tree; the
+   others join a queue with a position, instead of fighting over the same checkout.
+2. **Update against the latest base**, with full revalidation whenever the update
+   brought changes. A verdict computed before the update describes a diff that no longer exists.
+3. **Push proven by command.** `ork` compares the local sha with `git ls-remote` on the remote and records
+   `pushVerificado` in the ledger. **A push reported without the remote's sha counts as a push that did not happen.**
+4. **Contract guard.** Nothing in the final diff changes a versioned public contract without a ratified
+   class 2 decision, and the guard runs again after the update against the base.
+5. **Rollback plan**, written before the merge, with the exact revert command.
+
+## What the core checks for you
+
+The `push_direto_na_base` policy is blocking: source equal to target, source equal to the project's base
+branch, or a delivery with no delta while the local base is ahead of the remote (the push would publish a commit that
+did not go through a thread merge) fails before `ork` touches the remote. A merge that ship itself
+already made and that did not reach the remote (push refused, `--sem-push`) does not count: running ship again pushes it.
+A busy target tree comes out as `tree.blocked`; a lease held by another thread comes out as
+`lease.busy`.
+
+## Racionalizacoes comuns (Common rationalizations)
+
+| Excuse | Reality |
+|---|---|
+| "I already pushed, it worked" | A push is proven by command or it did not happen. The remote's sha is the evidence; the feeling of success is not. |
+| "I'll merge straight into the base, it's a single commit" | A direct push to the base is a blocking policy. Delivery comes from the thread's branch, always. |
+| "The base moved, but my diff does not touch that" | Update and revalidate. An update can bring a change that touches a contract, and the previous verdict described a different diff. |
+| "I'll think about rollback if something goes wrong" | A rollback plan written before the merge, or the plan will be written under pressure, in broken production. |
+| "The queue is slow, I'll merge on the side" | A merge outside the queue is the collision the queue exists to prevent. Wait for your position or release the lease with a record. |
+| "The mode is `#Classic`, so the push needs no authorization" | It does: the authorization is given in advance and **recorded** in the ledger, not waived. A mode relaxes when the human speaks, never whether they speak. |
+
+## Bandeiras vermelhas (Red flags)
+
+- A merge without a CHECK report with the verdict PASSOU (passed).
+- A push without `pushVerificado` in the ledger.
+- A contract guard run only before the update against the base.
+- A missing thread branch: the delivery going out from the base itself.
+- No rollback plan in the phase artifact.
+
+## Verification before leaving the phase
+
+Base updated and revalidated, contract guard rerun on the final diff, merge through the lease
+queue, push with the remote's sha in the ledger and a written rollback plan. See `DoD 12` to `DoD 15` and
+`SEC 12`.

package/assets/skills-en/reviewers/code-reviewer/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: code-reviewer
+description: "Code reviewer for CHECK: goes through the five axes of code-review-axes.md on the thread diff and returns findings categorized as blocker, warning or suggestion. Never fixes what it finds."
+bucket: reviewers
+roteia: "ork verify <thread> | references/code-review-axes.md"
+license: MIT
+---
+
+# Code Reviewer
+
+## What this skill is
+
+A thin router that applies [code-review-axes.md](../../../references/code-review-axes.md) to the
+thread diff. **The separation is the central rule: whoever reviews does not fix.** A finding becomes a GO task,
+with its own commit, or the reviewer ends up reviewing their own work and the review ceases to exist.
+
+## How to route
+
+```bash
+ork worktree audit <thread>          # confere a worktree no proprio git
+ork verify <thread>                  # a suite reexecutada no HEAD real
+git diff <base>...HEAD               # o escopo declarado da revisao
+```
+
+## Scope and conduct
+
+1. **The scope is declared before the findings:** which diff, which range, which files.
+   A review without a declared scope is not reproducible.
+2. **All five axes are covered, every one of them.** An axis with no finding comes out with an explicit "none"; silence
+   is not evidence that anyone looked.
+3. **Every finding comes out with exactly one category** and the item it violates, in the format `REVIEW 7`.
+   A finding without a category is opinion.
+4. **No rewriting someone else's code in the middle of the review.** The reviewer points out the place, the reason
+   and the cost; the change happens in GO.
+
+## What the core checks for you
+
+A cited file or test that does not exist in the diff comes back as `claims.failed` in `ork verify`; the
+reviewer does not need to trust the runtime's summary, it re-runs.
+
+## Racionalizacoes comuns (Common rationalizations)
+
+| Excuse | Reality |
+|---|---|
+| "Since I found it, I will fix it right here" | Whoever reviews does not fix. A reviewer who edits ends up reviewing their own work, and the review becomes a formality. |
+| "The diff is big, I will review only what looks important" | Partial scope is a partial result: declare what was left out, or the report asserts more than it looked at. |
+| "I let style slide, it is not important" | Style is a suggestion, except when it breaks a project tool, and then it is already a correctness issue. The rule is to categorize, not to ignore. |
+| "This axis does not apply to this diff" | Then write "none" and why. A blank axis is indistinguishable from a forgotten axis. |
+| "I will leave it as a warning so it does not hold up the delivery" | Category is not negotiated out of haste. A blocker downgraded because the delivery was close is the process defect the axis exists to expose. |
+
+## Bandeiras vermelhas (Red flags)
+
+- A reviewer commit inside the branch they are reviewing.
+- A finding without a category, or without the `REVIEW n` it violates.
+- A report without a declared scope.
+- Duplication pointed out without saying where the code should come from.
+
+## Verification before leaving the review
+
+Scope declared, five axes filled in, each finding with a category and an item, no edit made
+by the reviewer, and the consolidated verdict delivered to CHECK. See `REVIEW 1` to `REVIEW 12` and `DoD 8`.