@orkastery/cli 0.5.1 → 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/assets/orkmind_bridge.py

@@ -10,6 +10,7 @@ import math
 import os
 import re
 import sys
+from datetime import datetime, timezone
 
 
 class LegacyProvenanceCollision(ValueError):
@@ -370,6 +371,102 @@ async def health(store):
 ORK_COLLECTIONS = ('decision', 'handoff', 'rule', 'learning', 'roadmap')
 
 
+def no_universo(entry, tenant, agora=None):
+    """RM-038: o predicado unico do universo da busca (indice, vetor, FTS e status).
+
+    O search_by_tags governado ja tira expiradas e injection_risk; o search_by_text nao tira
+    injection_risk. O mesmo predicado vale nos dois caminhos, com o tenant conferido como item
+    de lista: texto nunca casa por substring. `agora` e o instante de ANTES da leitura: o que a
+    biblioteca devolveu como ativo continua ativo aqui, sem corrida de expiracao.
+    """
+    tags = getattr(entry, 'tags', None)
+    projeto = tags.get('project') if isinstance(tags, dict) else None
+    expira = getattr(entry, 'expires_at', None)
+    if expira is not None and expira.tzinfo is None:
+        expira = expira.replace(tzinfo=timezone.utc)
+    return (getattr(entry, 'collection', None) in ORK_COLLECTIONS
+            and isinstance(projeto, list) and tenant in projeto
+            and not getattr(entry, 'injection_risk', False)
+            and (expira is None or expira > (agora or datetime.now(timezone.utc))))
+
+
+async def ate_o_fim(contar, ler):
+    """RM-038: le com a janela da contagem mais um; janela cheia conta e le de novo uma vez.
+
+    Cheia so acontece com escrita concorrente entre a contagem e a leitura. Uma escrita isolada
+    se resolve na segunda leitura; cheia de novo, a resposta e falhar alto, nunca cortar.
+    """
+    for _ in range(2):
+        limite = await contar() + 1
+        lidas = await ler(limite)
+        if len(lidas) < limite:
+            return lidas
+    raise QueryError('memory.query.window-saturated')
+
+
+def universo_contract(request):
+    valid = isinstance(request, dict) and set(request) == {'op', 'tenant'}
+    tenant = request.get('tenant') if valid else None
+    if (not valid or request['op'] != 'universo' or not isinstance(tenant, str) or not tenant.strip()
+            or len(tenant) > 128 or re.search(r'[\x00-\x1f\x7f]', tenant) is not None):
+        raise QueryError('memory.universo.invalid')
+
+
+# Contagem SO de numeros: nenhuma coluna de conteudo sai da base por aqui. O tenant e o mesmo
+# predicado da leitura governada por tag (`tags @> {"project": [tenant]}`), que usa o indice de tags.
+FORA_DA_BUSCA_SQL = """
+    SELECT
+      count(*) FILTER (WHERE collection = ANY(%s) AND injection_risk
+                         AND (expires_at IS NULL OR expires_at > now())) AS injecao,
+      count(*) FILTER (WHERE collection = ANY(%s) AND expires_at IS NOT NULL AND expires_at <= now()) AS expiradas,
+      count(*) FILTER (WHERE NOT (collection = ANY(%s))) AS outras_colecoes
+    FROM memories
+    WHERE tags @> jsonb_build_object('project', jsonb_build_array(%s::text))
+"""
+
+
+async def contar_fora_da_busca(store, tenant):
+    """RM-038: quantas entradas do tenant ficam fora do universo e por que.
+
+    A API governada nao devolve o que filtra; a contagem le a tabela pela conexao do adapter
+    pgvector (o mesmo acesso do lock de add e handoff), so com count(*). Em outro backend a
+    contagem nao e medida e volta None.
+    """
+    if getattr(getattr(store, 'capabilities', None), 'backend', None) != 'pgvector':
+        return None
+    conn = await store.inner._get_conn()
+    colecoes = list(ORK_COLLECTIONS)
+    cur = await conn.execute(FORA_DA_BUSCA_SQL, (colecoes, colecoes, colecoes, tenant))
+    linha = await cur.fetchone()
+    return {'injecao': int(linha['injecao']), 'expiradas': int(linha['expiradas']),
+            'outrasColecoes': int(linha['outras_colecoes'])}
+
+
+async def universo(request, store):
+    """RM-038: o universo da busca do tenant, lido ate o fim, uma leitura governada por colecao.
+
+    O tenant e filtro na origem: texto de outro tenant nunca sai da base por aqui. A janela e a
+    colecao inteira mais um (ate_o_fim). Entrada fora do predicado e violacao. O vetor gravado na
+    base nao viaja: o ork nao o usa.
+    """
+    tenant = request['tenant']
+    agora = datetime.now(timezone.utc)
+    entradas = []
+    for colecao in ORK_COLLECTIONS:
+        async def contar(colecao=colecao):
+            return await store.count(colecao)
+        async def ler(limite, colecao=colecao):
+            return await store.search_by_tags({'project': [tenant]}, collection=colecao, limit=limite)
+        lidas = await ate_o_fim(contar, ler)
+        if any(e.collection != colecao or not no_universo(e, tenant, agora) for e in lidas):
+            raise QueryError('memory.query.scope-violation')
+        entradas.extend(lidas)
+    if len({e.id for e in entradas}) != len(entradas):
+        raise QueryError('memory.query.scope-violation')
+    return {'entradas': [e.model_dump(mode='json', exclude={'embedding'}) for e in entradas],
+            'foraDaBusca': await contar_fora_da_busca(store, tenant)}
+
+
 def fts_contract(request):
     valid = isinstance(request, dict) and set(request) == {'op', 'tenant', 'texto'}
     def text(value, maximum):
@@ -379,14 +476,16 @@ def fts_contract(request):
 
 
 async def fts(request, store):
-    """FTS da biblioteca (I-38 D9) com fronteira de tenant obrigatoria: devolve so ids, na ordem do ranking."""
+    """FTS da biblioteca (I-38 D9) restrito ao universo da busca (RM-038): so ids, na ordem do ranking."""
     # A janela cobre a base inteira: ausencia so conta quando nada ficou de fora do corte.
-    limit = await store.count() + 1
-    entries = await store.search_by_text(request['texto'], limit=limit)
-    if len(entries) >= limit:
-        raise QueryError('memory.query.window-saturated')
-    return {'ids': [e.id for e in entries if e.collection in ORK_COLLECTIONS
-                    and request['tenant'] in (e.tags or {}).get('project', [])]}
+    agora = datetime.now(timezone.utc)
+    async def contar():
+        return await store.count()
+    async def ler(limite):
+        return await store.search_by_text(request['texto'], limit=limite)
+    entries = await ate_o_fim(contar, ler)
+    # O search_by_text alcanca injection_risk; o universo nao. Mesmo predicado do indice.
+    return {'ids': [e.id for e in entries if no_universo(e, request['tenant'], agora)]}
 
 
 async def execute(request, store):
@@ -403,6 +502,9 @@ async def execute(request, store):
     if op == 'fts':
         fts_contract(request)
         return await fts(request, store)
+    if op == 'universo':
+        universo_contract(request)
+        return await universo(request, store)
     if op == 'query':
         tags, collection, limit = query_contract(request)
         # GovernedStore conserva validade, anti-injection e visibilidade existentes.
@@ -417,8 +519,12 @@ async def execute(request, store):
         return [e.model_dump(mode='json') for e in entries]
     if op == 'export':
         collection = request['collection']
-        count = await store.count(collection)
-        entries = await store.search_by_tags({}, collection=collection, limit=count + 1)
+        async def contar():
+            return await store.count(collection)
+        async def ler(limite):
+            return await store.search_by_tags({}, collection=collection, limit=limite)
+        # RM-038: le ate o fim; janela cheia de novo e falha alta, nunca corte em silencio.
+        entries = await ate_o_fim(contar, ler)
         return [e.model_dump(mode='json') for e in entries]
     if op == 'get':
         entry = await store.retrieve(request['id'])
@@ -538,6 +644,8 @@ async def main(request):
         health_contract(request)
     if isinstance(request, dict) and request.get('op') == 'fts':
         fts_contract(request)
+    if isinstance(request, dict) and request.get('op') == 'universo':
+        universo_contract(request)
     native_schema_fields()
     from orkmind.core.config import OrkMindConfig
     from orkmind.store.factory import create_store