@orkastery/cli 0.5.6 → 0.6.1

package/assets/skills-en/core/orkastery-bootstrap/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: orkastery-bootstrap
+description: "Recognizes the exact phrase orkastery maestro and conducts Maestro/Builder requests and resumptions: queries the overview through ork and presents progress, decisions and delivery in the conversation. In an already dispatched phase session, resume that phase without opening another orchestration."
+bucket: core
+roteia: "ork modos | ork thread new | ork thread status | ork phase list | ork pulse"
+license: MIT
+---
+
+# Orkastery Bootstrap
+
+## Role in the conversation
+
+A thin router for the conversation. The executable methodology lives in the `ork` core.
+
+The owner brings goals and decisions; the agent operates `ork` and conducts the next authorized step.
+A reply with a list of commands for the owner to run does not complete a work request.
+Methodology, modes, gates and verification stay in the core. This skill translates intent and presents results; an adapter that implements the demand in the host breaks that separation.
+
+Distinguish the context before acting:
+
+- **Conductor session:** receives the owner's request, identifies or opens the thread, dispatches through `ork` and tracks the result; never writes product code in place of the dispatched session.
+- **Already dispatched phase session:** has received the thread, phase, prompt and worktree from `ork`.
+  Work within that scope through the phase skill. Do not open another thread or redispatch your own phase to do the work already assigned to you.
+  - 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.
+
+## Start or resume
+
+When the message is **`orkastery maestro`**, in a clean session, discover `ork_maestro`
+in the host's real namespace and query the project pinned by the installation. The read-only
+equivalent in the terminal is `ork maestro --json`; the conversational phrase is not a shell command.
+The query does not create a demand, thread, session or approval. A missing project returns
+`maestro.project.missing`; an ambiguous one returns `maestro.project.ambiguous`: present the
+allowed candidates and obtain the selection, without scanning home or picking the first one.
+If you already received a phase/thread/WT, continue that block; the phrase does not open another orchestration. The project of each query is explicit (RM-052): if the owner named one, pass it (`projeto` in the tool, `--projeto <nome>` in the CLI) and read "Projeto consultado" (project queried) and "Não lido" (not read) before answering: the board and the overview do not read the roadmap, and zero threads never means an empty roadmap. With no project named, offer the network overview (RM-054): `ork_network_roadmap` in the host (in MCP, the pinned project on all machines) or `ork network roadmap` in the CLI (all known projects), with sources, freshness and gaps, relayed as it comes. The roadmap status comes from this same source: a gap and "Não consultado" (not queried) never become an empty roadmap or "no machine published".
+
+Present the overview with sources, gaps and next actions: demands, threads, sessions,
+blockers, leases, retries, HITL, SHIP and MASTER. Empty differs from unavailable;
+an unknown native state does not prove a session ended. Honor `coverage.nextOffset`
+for omitted details. A snapshot is a read, not an authorization; an action uses the existing
+typed operation, revalidates preconditions and has a readback. Conflict/stale requires a new read.
+
+**Top priority: HITL usability.** In the conversation itself, present short bullets,
+one grounded recommendation and options with clear labels. Keep UUIDs internal and
+preserve the literal answer, free text and cancellation. Only offer a channel proven
+available for that request/connection. Telegram is optional; lack of native ingress
+in the chosen channel is an explicit pending item, without faking approval or imposing a migration.
+Same-harness requires proven independent sessions; the executor does not review itself.
+
+Use the manifest, the request and the thread state. If the owner gave a thread/roadmap, resume that work; only ask which thread when the ambiguity prevents a safe choice.
+Do not repeat onboarding, decisions or tasks that are already recorded.
+
+Prefer MCP in the project pinned by the server, with no other root/cwd. In Claude with the `orkastery` server, use the full exposed names, such as `mcp__orkastery__ork_thread_status`; in `ToolSearch`, select that full name, never `select:ork_thread_status`. In other hosts, follow the namespace actually discovered.
+
+| Action | MCP tool | CLI when the tool is not available |
+|---|---|---|
+| State/documents/claims/autonomous decision | `ork_thread_status`, `ork_phase_list`, `ork_artifact_read/write`, `ork_claims_list`, `ork_claim_add`, `ork_decision_record` | `ork thread status <thread>`, `ork phase list <thread>`, `ork claims`, `ork decisao registrar <thread>` |
+| New demand | `ork_thread_new(nome, modo)` | `ork thread new "<nome>" --mode <modo> --worktree auto` |
+| Dispatch | `ork_phase_run(threadId, fase, prompt, runtime?, model?, effort?, dryRun?)` | `ork phase run <thread> GOAL --prompt "<pedido>"` |
+| Native progress | `ork_observe(threadId)` | `ork thread status <thread>` |
+| Graph context (only with `grafo.mcp: true`) | `ork_grafo_contexto(threadId, tetoBytes?)`; go deeper with `ork_grafo_vizinhos`, `ork_grafo_chamadores`, `ork_grafo_importadores`, `ork_grafo_caminho` | `ork grafo contexto <thread> --json` |
+| Pending item/decision | `ork_hitl_pending`, `ork_request_decision(threadId, pedidoId)` | Check the supported ingress; do not fabricate an answer. |
+
+Prefer `ork_git_commit` (current HEAD, paths with claims), `ork_verify` and `ork_ship` (real source/destination HEADs) to record, verify and deliver. Authoring/commit is not SHIP; an incomplete return requires reconciliation before repeating. For new demands, use `ork modos --do-pedido "<pedido do dono>"` and `ork_preflight({modo})` (CLI: `ork doctor --modo <modo>`). The per-block probe does not prove authentication, gates or delivery.
+Without MCP and with mutation of `.git` denied by the sandbox, report that the native transport installation is pending; do not repeat the denied command or widen the sandbox.
+
+The mode of an existing thread is the one recorded in it. Preserve authorizations in the scope where they apply; do not ask for routine confirmation for each task. For a new demand, the core resolves the #TAG, `conduction.default_mode` and `allowed_modes`. Do not redo that parse in the host. A real preflight block prevents the dependent dispatch and must be explained.
+
+Before the first dispatch, check `ork setup <modo>` and the phase block: preserve its runtime/model/effort. The conversation host does not impose the runtime of the phases.
+If the owner asked for another runtime, use `--runtime R --model M --effort E` with a coherent, already authorized trio; never inherit a model from another runtime or change the project defaults for a one-off override.
+If the model choice for that runtime is missing, obtain only that information. Edit `ork setup <modo> --bloco N` only when you intend to change the persistent configuration.
+Check the trio/command with `ork phase run ... --dry-run` on the first dispatch or after a relevant configuration change; do not repeat that rehearsal at every status or step with no change.
+Dry-run does not start a model, but it may write the prompt/events. Check the effective trio in the result/ledger; doctor does not prove the model. The `worktree` child profile requires opt-in at installation: preserve what is configured, without enabling it through toolargs or to bypass a block.
+
+## Conduction during the work
+
+The mode loosens the pause, NEVER the verification. Claims, verify, policies and typed gates run identically in `#Classic` and in `#Auto`; the mode decides whether the verdict waits for the human.
+
+After an action, use the core's result to execute the next authorized step.
+In #Auto/#Maestro, do not end a block just by offering to continue while there is still work
+executable within the mode. A pause required by the mode or a real blocker stays visible.
+
+For status, start from the known thread. With an existing dispatch, query `ork_observe` for the native state, progress and current blocker.
+`phase list` is history: do not wait for completion with long loops, sleeps or regex over its output. A native wait requires a real decision/blocker context.
+Use `ork_hitl_pending` or `ork pulse --json` for the attention queue and `ork board plan` for the work order. Avoid a global or repeated inventory of processes/worktrees.
+Use `ork_git_status`: `source.head` goes into `commit.expectedHead`; query again after the commit for `ship.expectedSource=source.head` and `expectedDestination=destination.head`. Do not derive SHAs from the historical base; the absence of a message does not prove the session died.
+
+The blocks and pauses shown by `thread status` describe the mode, not gates already open.
+Only say "waiting for you" when the state and the last result in `phase list` support
+a current human pending item, identified by a gate, request or event of the thread/session.
+A new thread, with no phase executed and no open request, is not yet waiting for a verdict.
+If evidence of the pending item is missing, state the uncertainty and check the source; do not invent the wait.
+
+Present the result first: what has already been proven, what is happening, who needs to act and the next step. In long-running work, report a relevant change, a blocker or a milestone. Do not promise notifications or background execution that the host cannot sustain.
+
+## Decisions in the session itself
+
+When there is an owner decision, show the concrete question, the context and the consequences; offer options when they help and identify the thread and the request/gate.
+If a real pause/escalation allows it and a request is missing, use `ork_gate_request(threadId, motivo?)`; never create a request for a status query. Use `ork_request_decision(threadId, pedidoId)` to present the native dialog. The answer comes through the host, never as an answer argument or a human identity invented by the model.
+Check the core's result and proceed once. Without the tool, use only a supported ingress; do not fabricate another host's envelope.
+Do not turn a native permission into a gate approval or apply an answer to another request.
+
+When the mode allows an autonomous decision, record who decided, the evidence and the reason through the core.
+When it requires a human decision, use only the answer actually received; do not fabricate an approval or a score. Authorization for one task is not unrestricted authorization for other actions.
+
+## Continuity and delivery
+
+The canonical state lives in `.orkastery/threads/<id>/`. Before switching sessions or when you hit a blocker, leave a checkpoint with the goal, decisions, last result, artifacts and next step. Resume from the checkpoint and check the current state before dispatching again.
+
+In the dispatch request, describe the goal and the scope of all phases of the authorized block; the requested phase is the block's entry. In Auto, do not ask to stop after GOAL: the block runs GOAL..MASTER, with the applicable verifications and gates.
+
+When `ork_observe` shows `turno.estado=encerrado`, reconcile the last official result and the block's artifacts. This indicates an ended turn, not `phase_result`, a completed phase or a delivery. The native fields `state` and `status` may diverge; preserve the divergence instead of interpreting `working` in isolation. Later activity invalidates the ended-turn evidence. Without a sufficient result, record the pending point and use only the continuation supported by the core, without duplicating the dispatch or fabricating a completion. Do not use long sleeps or repeated polling to turn silence into proof of life, death or progress.
+
+Dispatch is not completion. Tests, CHECK, SHIP and MASTER are different proofs. Deliver changes, validation, effective publication and pending items, with links useful to the owner. SHIP uses `ork ship`; a delivery without a human score is accepted by omission with the ledger-derived index (`ork master`), and the human score overrides it. A delivery without a MASTER log did not happen; publication and ratification remain distinct.
+## Racionalizacoes comuns (Common rationalizations)
+Dispatch, silence or Auto mode never replace a result, `verify` and receipts.
+## Bandeiras vermelhas (Red flags)
+An adapter that implements the demand, status without a source or publication without a gate break the separation.
+## Verification before answering
+The owner understands the result and the next action; state and evidence support the answer. See `DoD 17` and `DoD 20`.

package/assets/skills-en/core/thread-state/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: thread-state
+description: "The thread's state on disk: thread.json, ledger.jsonl, claims.jsonl, hashed prompts and leases. Routes to ork thread status, ork phase list and ork board; no state is read from conversation memory."
+bucket: core
+roteia: "ork thread status | ork phase list | ork board"
+license: MIT
+---
+
+# Thread State
+
+## What this skill is
+
+A thin router over the state that `ork` keeps on disk. It does not invent formats, does not edit
+state files by hand and does not hold rules: it says which command reads the truth and calls that
+command. **Editing `thread.json` with a text editor is corrupting state, not moving work forward.**
+
+## When to use
+
+- When resuming a thread that another session opened.
+- Before any phase, to know where the thread stands in the cycle.
+- When two threads seem to be fighting over the same file or the same tree.
+
+## Where the state lives
+
+```text
+.orkastery/
+|- threads/<thread-id>/
+|  |- thread.json          estado da thread: modo, blocos, base carimbada, sessoes
+|  |- ledger.jsonl         append-only: todo evento, com quem decidiu e a evidencia
+|  |- claims.jsonl         alegacoes verificaveis e o comando que comprova cada uma
+|  |- prompts/             o prompt exato de cada sessao, nomeado pelo sha256
+|  |- POSTMORTEM.json      fechamento tipado da thread
+|  `- master-log.json      o contrato congelado ork.master-log/v1, com o score humano
+`- leases/                 leases por familia e a fila de espera
+```
+
+## How to route
+
+```bash
+ork thread list                    # as threads NAO fechadas (aberta e pausada)
+ork thread list --todas            # todas, inclusive as fechadas
+ork thread list --json             # a mesma listagem como JSON
+ork thread status <thread>         # estado da thread, cruzado com o runtime real
+ork phase list <thread>            # o ledger inteiro, evento a evento
+ork claims list <thread>           # as alegacoes e o estado de cada uma
+ork lease list                     # leases, familias e as filas
+ork board                          # todas as threads em uma visao
+ork memory status                  # regime de memoria efetivo (files ou orkmind)
+ork recall <thread> --fase <FASE>  # resolve os ponteiros do handoff DESTE momento
+```
+
+## What the core guarantees
+
+- **Append-only.** The `ledger.jsonl` only grows. A correction goes in as a new event, never as a rewritten
+  line: edited history stops being history.
+- **The prompt is an artifact, not a recollection.** Each session writes the exact prompt with `sha256` in the name, and
+  the same hash goes to the ledger. That is what makes it possible to prove what was requested.
+- **The base is stamped at creation.** `thread.json` keeps the branch and the commit the thread
+  started from; it is against that stamp that `ork worktree audit` detects that the base has moved.
+- **The real state beats the recorded state.** `ork thread status` cross-checks the recorded sessions against the
+  runtime; a session that `thread.json` says is alive and the runtime does not know shows up as a divergence.
+- **Memory is optional and declared.** The handoff carries the regime (`files` or `orkmind`) and the
+  pointers say WHEN they must be resolved. With OrkMind down, the same pointer resolves
+  through `path#ancora`, and no cycle stops because of it.
+
+## Racionalizacoes comuns (Common rationalizations)
+
+| Excuse | Reality |
+|---|---|
+| "The conversation still has all the context, I don't need to read the disk" | Conversations end and context windows rotate. Unrecorded work is work that cannot be resumed or audited. |
+| "It's faster to edit thread.json by hand" | Editing state by hand corrupts state. Every field has a command that writes it, and the command also records it in the ledger. |
+| "I'll fix the part of the ledger that went wrong" | The ledger is append-only. A correction is a new event. Edited history is no longer history, it is narrative. |
+| "I'll load the whole handoff into the new session" | The handoff separates inline from pointer on purpose. `ork recall <thread> --fase <FASE>` brings only what belongs to that moment; the rest stays addressed, not lost. |
+| "Two threads on the same file, but they don't intersect" | The lease decides that, not intuition. `ork lease list` shows region collisions and the queue. |
+
+## Bandeiras vermelhas (Red flags)
+
+- A thread directory without `thread.json` or without `ledger.jsonl`.
+- A dispatched prompt with no matching file in `prompts/` with the sha in its name.
+- A session recorded as alive that the runtime does not recognize.
+- An expired lease with the thread still writing in the region.
+- A manifest asking for `memory.mode: orkmind` with `ork memory status` reporting the effective regime
+  `files`: semantic memory is not in effect, and the typed reason says why.
+
+## Verification before leaving the skill
+
+Thread identified by its id, state read by command and not from memory, current phase known, and
+any divergence between disk and runtime said out loud. See `DoD 4`.

package/assets/skills-en/governance/decision-triage/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: decision-triage
+description: "The delegation discipline: classifies each decision as class 1 (the human decides), 2 (public contract, requires ratification) or 3 (delegated, recorded), and raises a real tradeoff with options and one recommendation. Routes to ork gate request."
+bucket: governance
+roteia: "ork gate request <thread>"
+license: MIT
+---
+
+# Decision Triage
+
+## What this skill is
+
+A thin router for the delegation discipline. It does not decide for the human and does not hide a decision
+behind "technical detail": it classifies, records what is delegated and raises what belongs to the human.
+**A delegated decision without a record is a lost decision.**
+
+## The three classes
+
+| Class | Who decides | What it requires |
+|---|---|---|
+| 1 | The human, always | Product tradeoff, business risk, priority, scope, money |
+| 2 | The human, with recorded ratification | Change to a versioned public contract: schema, event types, state layout, interface |
+| 3 | Delegated to the agent | Internal choice with no observable effect outside the module, recorded in the ledger when relevant |
+
+## How to route
+
+```bash
+ork gate request <thread>    # abre o pedido; o humano responde pelo canal autenticado
+ork phase list <thread>      # a auditoria de delegacao le daqui
+```
+
+## Conduct
+
+1. **Classify before acting**, not after having acted.
+2. **Raise the tradeoff with options and exactly one recommendation.** Raising without a recommendation pushes the
+   work back to the human; raising without options asks for a signature, not a decision.
+3. **Record the relevant class 3.** The qualifier carries weight: formatting and internal names
+   are also class 3, and requiring an event for each of them is undue escalation.
+4. **Audit both sides with equal weight.** Under-classifying (treating a product decision as a
+   technical detail) and escalating unduly (asking for sign-off on a triviality) are defects of the same
+   size, and the CHECK audit hunts both.
+5. **A closed decision is locked.** Reopening is a new decision, with its own record, never a silent edit.
+
+## Racionalizacoes comuns (Common rationalizations)
+
+| Excuse | Reality |
+|---|---|
+| "This is a technical detail, I'll decide on my own" | If it changes what the user sees, what the product promises or what costs money, it is class 1. Under-classifying is the polite way of deciding for the human. |
+| "I'll ask about everything, that way nobody complains" | Undue escalation is a defect of equal weight. Whoever asks about everything hands the work back and does away with delegation. |
+| "I'll raise the question and let the human choose" | Without options and without a recommendation, that is passing the problem along. Bring the map and say which way to go. |
+| "I'll change the schema, it is compatible in practice" | A versioned public contract is class 2: it requires recorded ratification before the merge, even when it looks compatible. |
+| "The decision changed, I'll update the old text" | A closed decision is locked. Reopening is a new decision with a record; editing the old one erases the reason for the first. |
+
+## Bandeiras vermelhas (Red flags)
+
+- A public contract change in the diff with no ratification gate in the ledger.
+- A series of product decisions showing up only in the phase's final summary.
+- A question to the human about a variable name while the scope changed without notice.
+- A decision recorded in two places with different wording.
+
+## Verification before leaving triage
+
+Each decision with an assigned class, those of class 1 and 2 raised with options and one recommendation, the relevant
+class 3 ones recorded in the ledger, and no closed decision reopened in silence. See
+`DoD 5`, `DoD 12` and `DoD 20`.

package/assets/skills-en/governance/narrative-guardian/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: narrative-guardian
+description: "Canon audit: checks that every public artifact of the product says the same thing the code does, with no number without a source, no promise of a nonexistent capability and no invented metric. Runs before any publication."
+bucket: governance
+roteia: "ork verify <thread> | ork phase list <thread>"
+license: MIT
+---
+
+# Narrative Guardian
+
+## What this skill is
+
+A thin router for the canon audit. It compares what the public artifacts state with what
+the code and the ledger prove. **A number without a source does not go into a public document**, and a capability that
+does not exist does not become a promise in a README.
+
+## When to use
+
+- Before publishing a README, product doc, changelog, post or marketing page.
+- At the end of every thread that changes outward-facing documentation.
+- Whenever an artifact cites a metric, time, count or comparison.
+
+## How to route
+
+```bash
+ork verify <thread>        # o que a maquina realmente prova hoje
+ork phase list <thread>    # a origem de cada evidencia citada
+ork master --todas         # o que ja foi fechado e pode ser citado como entregue
+```
+
+## The canon rules
+
+1. **Every published number has its source attached.** Command, output, date. A number from memory does not go in.
+2. **A described capability is a capability that exists today.** A roadmap is written as a roadmap, in the declared
+   future, never in the present indicative.
+3. **A time metric is clocked, not optimistically estimated.** The fifteen-minute promise of the
+   quickstart holds because the run was executed and the record was published with it.
+4. **A gap is published as a gap.** `unavailable` with the reason, never zero, never omission.
+5. **A divergence between doc and code is a defect of the doc**, and it becomes a task, not a footnote.
+
+## Racionalizacoes comuns (Common rationalizations)
+
+| Excuse | Reality |
+|---|---|
+| "About 15 minutes, it's roughly that" | A time metric is clocked. A number without a source becomes a promise the first user disproves. |
+| "It will exist in the next version, I'll already write it in the present" | A described capability is a capability that exists today. A roadmap written as present is the lie that killed the original product. |
+| "I'll leave the field empty, nobody will notice" | A gap is published as a gap. An empty field becomes zero on the next read, and zero is a data point. |
+| "The doc is outdated, but the code is right" | A divergence between doc and code is a defect of the doc, with its own task. A wrong doc is the wrong product for whoever reads it. |
+| "I compared with the competitor off the top of my head" | A published comparison needs a method and a date. Without that, it is advertising dressed up as data. |
+| "The whole team knows this number is approximate" | Outside readers do not know. A published approximation declares that it is an approximation. |
+| "I'll take out the `unavailable`, it looks ugly in the README" | What is ugly is the false number discovered later. Measurement honesty is part of the product, not a formatting detail. |
+| "This is a marketing detail, not an engineering one" | The public artifact is product surface. The canon applies equally on both sides. |
+
+## Bandeiras vermelhas (Red flags)
+
+- A number in a public document with no command or date next to it.
+- A present-tense verb for a roadmap feature.
+- A benchmark cited without machine, regime and repetition.
+- A metric field left blank instead of `unavailable`.
+- A changelog citing a delivery without a matching MASTER log.
+
+## Verification before publishing
+
+Every number with a source, every capability checked against the code, every time clocked, every
+gap declared, and no divergence between the artifact and what the ledger proves. See `TEST 12`,
+`PERF 9` and `PERF 10`.

package/assets/skills-en/governance/roadmap-keeper/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: roadmap-keeper
+description: "Roadmap guardian: every demand is recorded before it becomes a thread, every auditor proposal becomes an item with a source, and nothing vanishes from scope without a recorded decision. Routes to ork board and ork thread new."
+bucket: governance
+roteia: "ork board | ork board plan | ork thread new"
+license: MIT
+---
+
+# Roadmap Keeper
+
+## What this skill is
+
+A thin router between the demand and the thread. It does not prioritize in the human's place: it ensures that
+every demand is written down before it becomes work, with a source, and that nothing leaves scope in
+silence. **A demand that becomes a thread without being recorded is work with no owner and no history.**
+
+## How to route
+
+```bash
+ork board                       # o estado de todas as threads
+ork board plan                  # quem avanca agora, quem espera e por que
+ork thread new "<nome>" --mode <modo>
+ork master                      # as entregas, com o indice derivado do ledger
+```
+
+## Conduct
+
+1. **Record before opening.** The demand comes in with a title, a source and the problem it solves, and only
+   then becomes `ork thread new`.
+2. **Always a source.** Builder request, auditor finding, lesson from a MASTER log: who asked stays
+   written down. An item without a source does not know why it exists or when to die.
+3. **An auditor proposal comes in as a proposal**, never as an already applied correction. The auditor reads, the
+   roadmap decides.
+4. **An item that leaves scope leaves with a recorded decision**, with who decided and why. Scope that
+   shrinks in silence is scope that reappears as a surprise.
+5. **The machine's capacity limits the board.** `concurrency.max_parallel_threads` in the manifest is the
+   real ceiling; a roadmap that ignores the ceiling becomes a queue disguised as a plan.
+
+## Racionalizacoes comuns (Common rationalizations)
+
+| Excuse | Reality |
+|---|---|
+| "I'll open the thread now and record it later" | Recording later is recording the way memory tells it. The demand comes in written, with a source, before it becomes work. |
+| "This item obviously left scope" | Obvious to whoever was in the conversation. Leaving scope is a recorded decision, or it becomes a surprise in the next delivery. |
+| "The auditor found it, I'll fix it directly" | The auditor proposes, the roadmap decides. A correction applied directly by an auditor is a change with no owner and no gate. |
+| "One more thread fits in parallel, it's small" | The ceiling is the manifest's, measured, not optimism's. Above it, threads compete for the tree and for human attention. |
+| "This is obviously a priority, no need to even ask" | Priority is a class 1 decision, the human's. The roadmap organizes the choice; it does not make the choice. |
+
+## Bandeiras vermelhas (Red flags)
+
+- A thread opened without a matching roadmap item.
+- An item without a written source.
+- An auditor finding applied as a direct correction.
+- Scope reduced with no record of who decided.
+- Number of active threads above the manifest ceiling.
+
+## Verification before leaving the skill
+
+Demand recorded with a source, parallelism ceiling respected, auditor proposals treated as
+proposals, and every scope change with a recorded decision. See `DoD 20` and `REVIEW 11`.

package/assets/skills-en/governance/scope-check-capability-map/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: scope-check-capability-map
+description: "Phase 0: before opening the thread, checks whether the demand fits what the product and the machine can do, and returns what is missing instead of starting work doomed to stop halfway."
+bucket: governance
+roteia: "ork_preflight | ork doctor --modo | ork board plan | ork thread new --dry-run"
+license: MIT
+---
+
+# Scope Check and Capability Map
+
+## What this skill is
+
+A thin router for phase 0. It runs before GOAL and answers a single question: **does this demand fit
+what exists today?** If it does not fit, it returns what is missing, by name, before any thread
+consumes context window.
+
+## How to route
+
+First resolve the mode through the core. Prefer `ork_preflight({modo})` in the project's MCP;
+without that tool, use the contextual CLI below. The result follows the canonical setup per block.
+
+```bash
+ork doctor --modo <modo>                   # preflight contextual do modo autorizado
+ork board plan                            # capacidade ocupada e capacidade livre
+ork thread new "<nome>" --mode <modo> --dry-run   # ensaio: slug, modo, blocos, sem gravar
+```
+
+Plain `ork doctor`, without a mode, is an optional broad diagnosis with a global inventory; it does not replace
+the contextual preflight, nor should it compete with it as a mandatory dispatch route.
+
+## The capability map
+
+1. **Machine capability.** Check `prontoPrimeiroBloco` and the checks of the initial block; a relevant
+   failure blocks that dispatch. `prontoTodosBlocos` reports the dependencies of the future blocks:
+   announce those limitations without confusing them with an impediment to the initial block. The probe does not prove
+   authentication, accepted model, gates or delivery; the dispatch revalidates those contracts. VERIFY/SHIP
+   MCP also depend on the isolated Codex executor and on the delivery transport, even with a Claude phase.
+2. **Parallelism capability.** Active threads against `concurrency.max_parallel_threads`, plus the
+   leases already taken in the region the demand will touch.
+3. **Product capability.** What the demand asks for either exists in the product or is a new capability. If it is
+   new, that is said in the scope check and not discovered in GO.
+4. **Decision capability.** Does the demand depend on a decision only the human makes? Then it is born
+   with the gate planned, not with a surprise halfway through.
+
+## The return contract
+
+When the demand does not fit, the return **names what is missing and what would unblock it**, in one line
+each. Returning "can't be done" without what is missing is a refusal, not a scope check.
+
+## Racionalizacoes comuns (Common rationalizations)
+
+| Excuse | Reality |
+|---|---|
+| "I'll start and see what is missing along the way" | Discovering the gap in GO costs the whole thread. The scope check costs one command. |
+| "I'll ignore any fail because I chose Auto" | A relevant failure in the initial block's preflight blocks the dispatch; Auto does not remove verification. A future block's dependency must be reported as future. |
+| "One more thread fits, I can handle it" | The ones who have to handle it are the machine and the human who approves gates, and both have a measured ceiling in the manifest. |
+| "The demand is vague, GOAL will clarify it" | GOAL clarifies the goal, not whether a capability exists. A demand that asks for what does not exist is sent back earlier, with what is missing written down. |
+
+## Bandeiras vermelhas (Red flags)
+
+- Dispatch started with `prontoPrimeiroBloco` false or a relevant failure of the initial block.
+- A demand asking for a nonexistent capability without that being written down.
+- A file region already under another thread's lease, with no queue planned.
+- A return that does not say what would unblock the demand.
+
+## Verification before opening the thread
+
+Contextual preflight read per block, future dependencies explained, parallelism capability
+checked, product capability confirmed or declared
+absent, human gates planned, and a rehearsal with `--dry-run` showing slug, mode and blocks. See
+`DoD 17`.

package/assets/skills-en/observability/thread-tracing/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: thread-tracing
+description: "Thread trace: reads the ledger, the sessions, the claims and the MASTER log to reconstruct what happened, who decided and with what evidence. Read-only, never writes to the state."
+bucket: observability
+roteia: "ork phase list | ork thread status | ork sessions | ork board"
+license: MIT
+---
+
+# Thread Tracing
+
+## What this skill is
+
+A thin router for reading. It reconstructs the history of a thread from what is recorded,
+and **never writes to the state**: observability that alters what it observes stops being
+observability.
+
+## How to route
+
+```bash
+ork phase list <thread>       # o ledger inteiro, evento a evento
+ork thread status <thread>    # o estado gravado cruzado com o runtime real
+ork sessions --all            # as sessoes vivas do runtime
+ork claims list <thread>      # as alegacoes e o estado de cada uma
+ork board                     # todas as threads, uma visao
+ork master                   # as entregas, com o indice derivado do ledger
+```
+
+## What the trace must answer
+
+1. **What was requested**, with the exact prompt: each session wrote the prompt with `sha256` in the name.
+2. **Who decided**, at each gate: a human by name, or an autonomous decision with the #TAG that authorized it.
+3. **With what evidence**, always: command, output, sha. An event without evidence is an annotation, not a trace.
+4. **What failed and why**, with the typed reason: `claims.failed`, `verify.regression`,
+   `policy.violation`, `lease.busy`, `tree.blocked`, `human.pending`.
+5. **Where the time and the window went**, with the source of the measurement declared: `runtime_reported`,
+   `estimated`, `informada` or `unavailable`.
+
+## Measurement honesty
+
+What the runtime does not expose comes out as `unavailable`, with the reason. **A gap is published as a gap, never
+as zero.** A trace that fills a hole with a silent estimate is worse than a trace with a
+declared hole, because nobody mistakes the latter for data.
+
+## Racionalizacoes comuns (Common rationalizations)
+
+| Excuse | Reality |
+|---|---|
+| "I'll write one more event to make the trace complete" | Observability does not write to the state. An event invented afterwards is not a trace, it is reconstruction. |
+| "The tokens spent must have been around X" | Without a runtime measurement, it comes out as `unavailable`. An estimate presented as a reading is the start of every fake dashboard. |
+| "I'll put zero where there is no data" | Zero is a data point. A gap is published as a gap. |
+| "I'll reorder the ledger so it is readable" | The ledger is append-only and the order is evidence. Readability is the presentation's job, not the file's. |
+
+## Bandeiras vermelhas (Red flags)
+
+- An event in the ledger without evidence.
+- A gate without who decided.
+- A metric with a round number and no source.
+- A session recorded as alive that the runtime does not recognize.
+
+## Verification before delivering the trace
+
+Request, decider, evidence, typed reason and source of each number, with every gap declared as a
+gap and no write made to the state. See `PERF 9`, `PERF 10` and `DoD 5`.