@orkastery/cli 0.5.3 → 0.5.6

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

@@ -0,0 +1,135 @@
+# Software product documentation standard
+
+> Version 1.1 · Applies to: platforms, systems, modules and features · Companion document: [Product roadmap standard](roadmap-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 documentation unit
+
+This standard describes **the product and its verifiable behavior**, from the platform context to the technical contracts. Create one page per relevant entity; a feature (`Feature`) is the recommended unit for specifying behavior. Lengthy details, such as OpenAPI contracts and data schemas, can live in their own files, linked by stable identifiers.
+
+Use the hierarchy `Platform → System/Service → Module → Submodule/Domain → Feature`. A use case belongs to a feature; an operation represents an action of that feature. Entities and fields describe data; APIs, endpoints, events, triggers and jobs describe interfaces and execution. The same service or contract can serve several features: keep one canonical source and reference it, without copying divergent definitions.
+
+The **roadmap** records the problems, hypotheses, choices, priorities and progress of changes. This documentation records current behavior and, when needed, future specification explicitly identified as such. Relate both through IDs and links; do not treat a proposal as an already delivered feature.
+
+## 2. Mandatory conventions
+
+| Rule | How to apply |
+| --- | --- |
+| Identity | Assign stable IDs, for example `PLAT-01`, `SYS-01`, `MOD-01`, `FEAT-042`, `UC-042-01`, `BR-042-01`, `API-01`, `EVT-01`, `JOB-01` and `RM-042`. Renaming does not change the ID. In Orkastery, the number of a new FEAT comes from `ork roadmap feat`, reserved across machines; never from the highest number on your branch. |
+| Scope and state | Say whether what the page describes is `vigente` (current), `em desenvolvimento` (in development), `proposto` (proposed) or `descontinuado` (discontinued), with environment, version and verification date. |
+| Traceability | Link feature ↔ roadmap item ↔ use cases/rules ↔ contracts/schemas ↔ code/PR ↔ tests/evidence ↔ release. Use `Not applicable: reason` when a section does not make sense. |
+| Source | Distinguish `confirmed` (code, contract, test or approved decision), `planned` (roadmap item) and `to be validated`. Never fill a gap by silent inference. |
+| Form | Use clear language, in the language the product's docs are written in; keep the exact names of code, endpoints, flags and events in backticks. Dates in ISO 8601 with time zone; explicit units. |
+| Responsibility | Record the page's human owner, the technical approver when applicable and the last review. An AI agent can propose changes, with source and human review defined by the team. |
+| History | Behavior changes require updating the page and linking it to the roadmap item/release; relevant technical decisions point to an ADR. |
+
+## 3. Documentation categories
+
+Fill in the applicable fields. For reusable entities, create their own pages and link their IDs to the feature page.
+
+### 3.1 Context and architecture
+
+| Field | What to record |
+| --- | --- |
+| Platform; system/service; module; submodule | IDs, names and links to their respective parents. |
+| Purpose; boundaries | Problem addressed, the component's responsibility and what does not belong to it. |
+| Dependencies | Internal/external services and impact in case of failure. |
+| Repository; code location | URL, directories and reference version/commit. |
+| Deployment; environments | Deploy model, environments and regions actually used. |
+| Isolation; configuration | Tenancy model and system parameters; cite names, effect, default and environment, never secret values. |
+| Retention | Data types, retention period, disposal and approved policy/decision. |
+
+### 3.2 Features and behavior
+
+| Field | What to record |
+| --- | --- |
+| Feature; actors/personas | ID, purpose, participating users and systems. |
+| Use cases; operations | IDs and names; CRUD operations and business actions kept separate. |
+| Preconditions; trigger | Required state and the action/event that starts the flow. |
+| Main flow; alternatives | Observable steps and paths for error, cancellation, timeout and recovery. |
+| Postconditions | Persisted changes, emitted messages and external effects. |
+| Business rules | Atomic rule with ID, condition, result and exceptions. |
+| Acceptance criteria | Testable scenarios, preferably Given/When/Then, linked to the rules. |
+| Interface | Screens, components, states, accessibility and a reference to the approved prototype. |
+
+### 3.3 Data and fields
+
+Define each entity once. For each field, record `technical name`, `label`, `type`, `unit`, `required`, `nullability`, `limits`, `validation`, `format/mask`, `default value`, `sensitivity classification`, `retention` and `source/destination`. Explain differences between the UI, API and database representations; for example, `refund_amount_cents` is an integer in cents and appears as currency in the interface. Relate the table/migration/schema and the contract version. Do not use a format regex as proof that a document number is semantically valid.
+
+### 3.4 APIs and integrations
+
+Record `API/integration`, `protocol and version`, `provider/consumer`, `method and endpoint`, `path/query/header params`, `authentication`, `authorization`, `request`, `success response`, `errors`, `pagination`, `usage limits`, `timeout`, `idempotency`, `compatibility` and a link to the OpenAPI or canonical contract. Include sanitized examples without credentials; spell out the behavior on failures and with previous versions.
+
+### 3.5 Events, triggers and scheduled tasks
+
+Record `event ID/name/version`, `producer`, `trigger`, `payload/schema`, `broker/topic`, `consumers`, `delivery/ordering`, `retry/backoff`, `DLQ`, `idempotency`, `observability` and `retention`. For jobs, include `ID`, `owner`, `schedule expression`, `time zone`, `timeout`, `concurrency`, `effects`, `retry` and the reprocessing procedure. A cron in UTC needs a readable description and a time zone reference.
+
+### 3.6 Observability and operations
+
+Record `correlation_id/trace_id`, logs and allowed fields, technical and business metrics, SLI/SLO with a measurement window, alerts and thresholds, dashboards, error tracking, health checks, runbook, audit events and expected impact on cost/capacity. Distinguish a service objective (SLO) from a contractual commitment (SLA).
+
+### 3.7 Security, governance and compliance
+
+Record risk, roles and the permission matrix (RBAC/ABAC), authentication/session, encryption and secrets management, handling of personal data, masking in logs, input validation, origin policies when there is a browser, applicable regulatory requirements, maintenance window and rollback procedure. Cite internal policies and approved decisions instead of assuming that every cited regulation applies.
+
+## 4. Feature page template
+
+Reserve the number with `ork roadmap feat --thread <thread>` and copy [the template](../produto/_modelo-feature.md) for each feature; replace the brackets with values or with `Not applicable: reason`. The frontmatter is the layer that agents and the checker read; the body is the layer that people read. Add tables of fields and contracts when there are several elements.
+
+Frontmatter keys of a feature:
+
+| Key | Content | Checked by `ork docs verificar` |
+| --- | --- | --- |
+| `id`, `tipo`, `titulo` | `FEAT-000`, `feature`, name | ID format, file name, uniqueness |
+| `estado` | `vigente`, `em desenvolvimento`, `proposto` or `descontinuado` | value from the standard |
+| `pai` | `MOD-00` | exists and is from the level above |
+| `roadmap` | list of `RM-000` | exists, and the item cites the feature back |
+| `owner`, `aprovador` | people | presence |
+| `verificado_em`, `versao` | ISO 8601 with time zone; branch@commit | format |
+| `fontes.codigo`, `fontes.testes`, `fontes.docs` | paths relative to the root | **exist in the repository** |
+| `fontes.simbolos` | `file#name` | **the name appears in the file** |
+| `fontes.contratos` | contract IDs (`ork.hitl/v2`) | **appear in `fontes.codigo`** |
+| `fontes.comandos` | commands of the product's CLI | **the CLI declares the command** |
+
+## 5. Review and synchronization
+
+Before approving a change, check IDs and links, behavior and exceptions, names and types against code/migrations, API/event contracts, permissions, tests and the real environment. Update the documentation together with the implementation change; mark differences as `to be validated` with an owner and a deadline. Automation or an agent can compare sources and prepare a diff, but must record the commit/contract consulted and must not turn an assumption into a fact. Execution status and priority decisions live in the [roadmap standard](roadmap-de-produto.md).
+
+In Orkastery, this comparison has an owner and a command:
+
+- `ork docs verificar`: runs in CI on every PR; fails a page whose `fontes` no longer exist, or with a broken link, a repeated ID or a forgotten template field.
+- `ork docs sincronizar`: runs on the project's machine; reads the threads' ledger and git and updates **only facts** (merge, phase), never status because time has passed. Without `--escrever`, it only shows what would change.
+- `ork docs init`: creates this structure in any product conducted by Orkastery.
+
+## 6. Three readers and SDLC facts (Orkastery adaptation)
+
+Every page is read by three readers at the same time. If one of them is left behind, the page has failed.
+
+### 6.1 Person with ADHD
+
+- **Answer first.** Right below the title, a `> **Em uma frase:**` (in one sentence) line of up to 240 characters.
+- **State at a glance.** State, verification date and version appear before any explanation.
+- **One idea per line.** Bullets instead of paragraphs; a paragraph with more than 600 characters raises a warning.
+- **Sections always have the same names.** Anyone who has read one page knows where everything is on the next.
+- **Nothing silently empty.** A section without content says `Not applicable: reason` or `To be defined: owner, deadline`.
+
+### 6.2 Parity checker
+
+- The page asserts checkable things: paths, symbols, contracts, commands, commits.
+- A divergence between page and repository is a **lint error**, not a matter of opinion.
+- The checker never fills a gap or infers a state; it only points them out.
+
+### 6.3 AI models and agents
+
+- YAML frontmatter with fixed keys and values (section 4); stable IDs in the file name and in the title.
+- `ork docs verificar --json` returns the findings with a typed rule (`docs.paridade.fonte`, `docs.leitura.resumo`...).
+- An agent can propose the change; review and decision stay with people (section 2, Responsibility).
+
+### 6.4 SDLC facts of the Orkastery method
+
+- **Product facts** go into the documentation: the feature is `vigente`, in which version, verified when, against which sources.
+- Delivery progress (thread, phase, CHECK, merge) is recorded in the [roadmap](roadmap-de-produto.md), in the item's `sdlc` section.
+- **Conduction micro-decisions stay out**: which claim was re-registered, which GO-FIX fixed a test, which session dropped. That lives in the thread's ledger.

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/dist/adapters/claude-bg.js

@@ -42,11 +42,13 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.JANELA_CURTA_MAX_MS = exports.NOME_ADAPTER = void 0;
+exports.JANELA_CURTA_MAX_MS = exports.MOD_DOS_TETOS = exports.MINIMO_DA_API_DE_MODS = exports.NOME_ADAPTER = void 0;
 exports.ambienteDoPerfil = ambienteDoPerfil;
 exports.semContextoDeDespacho = semContextoDeDespacho;
 exports.disponivel = disponivel;
 exports.versao = versao;
+exports.modsParaOClaude = modsParaOClaude;
+exports.agentTeamsDoDespacho = agentTeamsDoDespacho;
 exports.montarComando = montarComando;
 exports.extrairSessionId = extrairSessionId;
 exports.listarSessoes = listarSessoes;
@@ -73,6 +75,7 @@ const path = __importStar(require("node:path"));
 const runtime_context_1 = require("../runtime-context");
 const runtime_profiles_1 = require("../runtime-profiles");
 const mcp_grafo_1 = require("../mcp-grafo");
+const locale_1 = require("../locale");
 function exec(cmd, args, cwd, timeoutMs, ambiente = (0, runtime_ambiente_1.ambienteDeAssinatura)()) {
     return (0, util_1.exec)(cmd, args, cwd, timeoutMs, ambiente);
 }
@@ -138,6 +141,63 @@ function versao() {
 }
 /** Ferramentas de arquivo negadas no PLAN: o plano sai pelo núcleo, não pelo disco. */
 const ESCRITA_DE_ARQUIVO = ['Edit', 'Write', 'NotebookEdit'];
+/** O contexto do despacho conferido para o host Claude Code (D4 do RM-037: o host errado recusa antes de tudo). */
+function validarDoClaude(contexto, cwd) {
+    if (contexto.host !== 'claude-code')
+        throw Error('runtime.context.invalid: host Claude esperado');
+    return (0, runtime_context_1.validarContextoRuntime)(contexto, cwd);
+}
+/** RM-059 (T0.7, D2): a API de mods saiu no Claude Code 2.1.287; nenhum mod vai a um `claude` mais velho. */
+exports.MINIMO_DA_API_DE_MODS = '2.1.287';
+/** `2.1.296 (Claude Code)` vira `[2, 1, 296]`; texto sem versao vira `null`. */
+function versaoNumerica(texto) {
+    const m = /(\d+)\.(\d+)\.(\d+)/.exec(texto ?? '');
+    return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+}
+function atende(versao, minimo) {
+    const i = versao.findIndex((parte, j) => parte !== minimo[j]);
+    return i < 0 || versao[i] > minimo[i];
+}
+/**
+ * RM-059 (T0.7, D2): os mods de fase que este `claude` carrega. O mod que pede versao mais nova fica de
+ * fora e o despacho segue, porque o nucleo nao depende de mod; versao ilegivel nao leva mod nenhum. Mod
+ * cuja dependencia ficou de fora (por versao, ou por ser so de papel `dono`) tambem fica: sem ela, ele
+ * carregaria pela metade na sessao de fase.
+ */
+function modsParaOClaude(mods, versao) {
+    const atual = versaoNumerica(versao);
+    if (!atual)
+        return [];
+    const piso = versaoNumerica(exports.MINIMO_DA_API_DE_MODS);
+    let vao = mods.filter((m) => atende(atual, piso) && atende(atual, versaoNumerica(m.claudeCodeMinimo) ?? piso));
+    for (;;) {
+        const nomes = new Set(vao.map((m) => m.nome));
+        const sobram = vao.filter((m) => m.dependencias.every((d) => nomes.has(d)));
+        if (sobram.length === vao.length)
+            return vao;
+        vao = sobram;
+    }
+}
+/** RM-059 (T10.4): o mod que aplica os tetos de agent teams dentro da sessao de fase. */
+exports.MOD_DOS_TETOS = 'ork-portao';
+/**
+ * RM-059 (T10.4, D11 da thread ork-rm059portao): o que o despacho acrescenta ao `--settings` para agent teams no
+ * piloto, e so quando o contexto validado trouxe os tetos (manifesto ligado, GO no bloco) e o Portao de Tarefas esta
+ * entre os mods que vao de fato a sessao: sem ele, ninguem aplicaria os tetos. A sessao de fundo nao tem `tmux`, entao
+ * os teammates rodam no mesmo processo (`teammateMode` `in-process`).
+ */
+function agentTeamsDoDespacho(tetos, mods) {
+    if (!tetos || !mods.some((m) => m.nome === exports.MOD_DOS_TETOS))
+        return null;
+    return {
+        env: {
+            CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS: '1',
+            ORK_AGENT_TEAMS_TEAMMATES: String(tetos.teammates),
+            ORK_AGENT_TEAMS_CUSTO_USD: String(tetos.custo_usd),
+        },
+        teammateMode: 'in-process',
+    };
+}
 /** Monta a linha de comando exata do despacho (usada tambem pelo `--dry-run`). */
 function montarComando(pedido) {
     const args = ['--bg', pedido.prompt, '--name', pedido.nome];
@@ -153,13 +213,17 @@ function montarComando(pedido) {
     // O `claude --bg` entrega a sessao a um processo reserva do daemon da conta, e o daemon guarda o
     // ambiente de quem o iniciou: pelo ambiente, a sessao nascia com a identidade de outro despacho.
     // Medido em 28/09/2026 (2.1.284): o `env` de `--settings` chega ao Bash da sessao e vence o herdado.
-    const doDespacho = pedido.ambienteExtra ?? {};
-    if (Object.keys(doDespacho).length)
-        args.push('--settings', JSON.stringify({ env: doDespacho }));
-    if (pedido.contextoRuntime) {
-        if (pedido.contextoRuntime.host !== 'claude-code')
-            throw Error('runtime.context.invalid: host Claude esperado');
-        const contexto = (0, runtime_context_1.validarContextoRuntime)(pedido.contextoRuntime, pedido.cwd);
+    const contexto = pedido.contextoRuntime ? validarDoClaude(pedido.contextoRuntime, pedido.cwd) : null;
+    // RM-059 (T0.7): cada mod de fase conferido entra com o proprio --plugin-dir, depois do plugin do Orkastery.
+    const mods = !contexto || contexto.modsDeFase.length === 0 ? []
+        : modsParaOClaude(contexto.modsDeFase, pedido.versaoClaude !== undefined ? pedido.versaoClaude : versao());
+    // RM-059 (T10.4): agent teams so no piloto, com os tetos no env e o Portao na sessao; sem eles, o --settings de antes.
+    const teams = agentTeamsDoDespacho(contexto?.agentTeams, mods);
+    const doDespacho = { ...(pedido.ambienteExtra ?? {}), ...(teams ? teams.env : {}) };
+    if (Object.keys(doDespacho).length) {
+        args.push('--settings', JSON.stringify(teams ? { env: doDespacho, teammateMode: teams.teammateMode } : { env: doDespacho }));
+    }
+    if (contexto) {
         const consultas = [...CONSULTAS_MCP, ...(contexto.grafoMcp ? consultasDoGrafoMcp() : [])];
         // Somente o servidor gerado: nao mesclar MCP de outros escopos nesta sessao filha.
         const permissoes = contexto.permissoesFilho === 'worktree'
@@ -169,7 +233,7 @@ function montarComando(pedido) {
         const allow = plano ? [...consultas, 'mcp__orkastery__ork_artifact_write', 'mcp__orkastery__ork_decision_record']
             : permissoes?.allow ?? consultas;
         const deny = [...(plano ? ESCRITA_DE_ARQUIVO : []), ...(permissoes?.deny ?? [])];
-        args.push('--plugin-dir', contexto.instalacao, '--strict-mcp-config', '--mcp-config', JSON.stringify({ mcpServers: { orkastery: contexto.servidor } }), '--allowedTools', allow.join(','));
+        args.push('--plugin-dir', contexto.instalacao, ...mods.flatMap((m) => ['--plugin-dir', m.dir]), '--strict-mcp-config', '--mcp-config', JSON.stringify({ mcpServers: { orkastery: contexto.servidor } }), '--allowedTools', allow.join(','));
         if (deny.length)
             args.push('--disallowedTools', deny.join(','));
     }
@@ -203,15 +267,15 @@ function listarSessoes(cwd, todas = false, ambiente = (0, runtime_ambiente_1.amb
  * falha aqui (o observador e o pulse não concluem nada dele); só o inventário o trata como fonte
  * ausente, com a correção.
  */
-function consultarSessoes(cwd, todas = false, ambiente = (0, runtime_ambiente_1.ambienteDeAssinatura)()) {
+function consultarSessoes(cwd, todas = false, ambiente = (0, runtime_ambiente_1.ambienteDeAssinatura)(), prazoMs = 60000) {
     const args = ['agents', '--json'];
     if (todas)
         args.push('--all');
-    const r = exec('claude', args, undefined, 60000, ambiente);
+    const r = exec('claude', args, undefined, prazoMs, ambiente);
     if (r.error === 'ENOENT')
-        return { ok: false, ausente: true, sessoes: [], detalhe: 'binário `claude` fora do PATH' };
+        return { ok: false, ausente: true, sessoes: [], detalhe: (0, locale_1.textoDoCatalogo)((m) => m.pulse.claudeForaDoPath) };
     if (!r.ok)
-        return { ok: false, sessoes: [], detalhe: `claude agents falhou (código ${r.code})` };
+        return { ok: false, sessoes: [], detalhe: (0, locale_1.textoDoCatalogo)((m) => m.pulse.claudeAgentsFalhou(r.code)) };
     let dados;
     try {
         const bruto = JSON.parse(r.stdout);

package/dist/adapters/codex.js

@@ -48,6 +48,7 @@ exports.montarComando = montarComando;
 exports.extrairThreadId = extrairThreadId;
 exports.acharRollout = acharRollout;
 exports.parseRateLimitCodex = parseRateLimitCodex;
+exports.ambienteDoFilho = ambienteDoFilho;
 exports.despachar = despachar;
 exports.logs = logs;
 const codex_controller_1 = require("./codex-controller");
@@ -351,6 +352,14 @@ function parseRateLimitCodex(saida, agoraMs = Date.now()) {
     const linha = (saida ?? '').split('\n').find((l) => frase.test(l)) ?? saida;
     return { resetEm: null, fonte: 'sem-horario', trecho: linha.trim().slice(0, 200) };
 }
+/**
+ * O ambiente do filho do despacho: o do processo, sem provider pago, com o contexto da condução POR
+ * CIMA. RM-052 (fatia 2, D2): a ordem importa, porque e o extra que neutraliza o `ORK_PROJETO` e o
+ * modo host herdados de quem despachou.
+ */
+function ambienteDoFilho(pedido, base = process.env) {
+    return { ...ambienteDoDespacho(base, pedido.perfil), ...(pedido.ambienteExtra ?? {}) };
+}
 /** Despacho governado exige vínculo: nenhum fallback implícito para codex exec. */
 function despachar(pedido) {
     if (!pedido.vinculo)
@@ -370,7 +379,7 @@ function despachar(pedido) {
     }
     let ambiente;
     try {
-        ambiente = { ...ambienteDoDespacho(process.env, pedido.perfil), ...(pedido.ambienteExtra ?? {}) };
+        ambiente = ambienteDoFilho(pedido);
     }
     catch (e) {
         return { ok: false, comando: [], sessionId: null, verificada: false, stdout: '', stderr: '', erro: e.message };