@aibyzero/byz 0.0.0 → 0.1.1

package/workflows/cm/runtime/logging.md

@@ -0,0 +1,206 @@
+# CM run logging contract
+
+CM records workflow events at two levels:
+
+```text
+{SPECS_DIR}/运行日志.jsonl
+${CM_WORKFLOW_LOG_HOME:-~/.cm-workflow/logs}/
+├── index.jsonl
+└── runs/YYYY-MM/{run_id}.jsonl
+```
+
+The specs log is the portable recovery and audit source of truth. The user-global
+tree is a private analysis mirror across projects, sessions, Codex, and Claude
+Code. It is not telemetry and nothing is transmitted off the machine.
+
+## Writer
+
+Resolve `scripts/cm-log-event.py` from the active CM Workflow root. It uses only
+the Python standard library:
+
+```bash
+python3 "{CM_WORKFLOW_ROOT}/scripts/cm-log-event.py" \
+  --workflow cm-ai \
+  --event task_start \
+  --runtime codex \
+  --project-root "{CODE_PROJECT}" \
+  --specs-dir "{SPECS_DIR}" \
+  --detail "正在开发登录接口" \
+  --data-json '{"node":"N3","feature":"1.login","task":"T-003","role":"coder"}'
+```
+
+Use `runtime: codex`, `claude`, or `unknown` according to the runtime actually
+observed. Optional `role` and model values describe visible configuration only;
+never infer an exact backend model. When a requested model is routed to a
+different effective model, record `requested_model`, `effective_model`,
+`provider`, `purpose`, and `model_equivalent`; never report an alias as the
+effective model.
+
+The writer prints one compact JSON result containing `event_id`, `run_id`,
+project/global log paths, `global_written`, `pointer_written`, `deduplicated`,
+and `degraded`.
+Preserve the returned `run_id` for a standalone flow. With a specs directory,
+`.cm-run.json` stores the active run id so a resumed session automatically
+continues the same run. If that pointer is unavailable, the writer reconstructs
+the active/terminal state from the authoritative project log. After `run_done`,
+the next `run_start` creates a new run.
+
+## Event envelope
+
+Each output line contains:
+
+```json
+{
+  "schema_version": 1,
+  "event_id": "<uuid>",
+  "run_id": "<stable run id>",
+  "at": "<ISO-8601 with timezone>",
+  "workflow": "cm-ai",
+  "event": "task_start",
+  "phase": "start",
+  "runtime": "codex",
+  "project": "my-app",
+  "project_path": "<canonical path when known>",
+  "specs_path": "<canonical path when known>",
+  "detail": "<one plain-language line>"
+}
+```
+
+Existing project logs without these fields remain valid historical input. New
+events use this envelope. Event-specific fields are supplied by `--data-json`
+and may not replace envelope fields.
+
+## Required lifecycle events
+
+| Workflow/action | Event | Phases or required data |
+| --- | --- | --- |
+| each workflow run | `run_start` / `run_done` | start once; terminal result in detail/data |
+| PRD and approval | `spec_lifecycle` | `generated`, `awaiting_review`, `approved`, `changed` |
+| PRD phase timing | `progress` | paired `start`/`complete`; operation_id, phase_name, segment |
+| N1–N8 | existing node/task/review/degrade/pause/resume/decision/error/qa/done events | preserve existing semantics |
+| long external, desktop, or browser step | `progress` | `start`, `checkpoint`, `complete`; operation id and observable milestone |
+| any QA invocation | `test_run` | `start`, `case_start`, `case_complete`, `case_blocked`, `complete`; case counts, result, report |
+| temporary resource | `resource` | `acquired`, `released`, `cleanup_failed`; unique non-secret `resource_id` per acquisition and stable `resource_kind` |
+| External Expert | `external_expert` | `route`, `dispatch`, `complete`; route/mode/state/evidence metadata |
+| role routing | `decision` | `phase: route`; role, adapter, requested_model, source, purpose, route_state |
+| managed model-call claim | `model_call` | `claimed`; unique call_id and complete safe route identity, atomically written before HTTP |
+| observed model call | `model_usage` | `complete`; the same route identity, usage_state, outcome, and verified counts when available |
+| Git delivery | `delivery` | `commit`, `push`, `pull_request`; identifiers only after success |
+
+Do not invent `push` or `pull_request` events before the remote side effect
+succeeds. External Expert `dispatch` records the observed dispatch state, not
+mere intent. `LOCAL` selected without AUTO or an explicit External Expert
+invocation does not need an event.
+
+Model-call usage follows `runtime/model-efficiency.md`. `model_call/claimed` is
+an idempotency claim, not proof of provider completion; the matching
+`model_usage/complete` records the observed outcome. The writer allows token
+*counts* only on the strict `model_usage` field allowlist; credential-like token
+fields remain forbidden. When a claim exists, completion must match its
+`workflow`, `runtime`, `stage`, `role`, `adapter`, `requested_model`, `source`,
+and `purpose`; a completed call id cannot later be claimed. A route decision is
+not a model call, and a requested model alias is not an observed effective model.
+The bundled `openai-compatible` completion is rejected unless its matching claim
+already exists; standalone usage events remain available only to other
+call-owning adapters.
+
+## Progress, recovery, and cleanup
+
+Keep progress event-based. Do not add a background heartbeat, timer, or polling
+service merely to make the log look active.
+
+`cm-prd` phase timing follows `skills/cm-prd/references/phase-timing.md`. Duration comes from
+paired envelope timestamps; callers do not write guessed `duration_ms`. A hard pause closes the
+active segment with `outcome: awaiting_input`, and resume uses a higher segment so human wait is
+not counted as active workflow time. Stages that did not run emit no timing pair.
+
+Use the dependency-free read-only report for recent `cm-prd` runs:
+
+```bash
+python3 "{CM_WORKFLOW_ROOT}/scripts/cm-prd-timing.py" --last 5
+```
+
+It reads only the local global mirror, reports paired active segments, and labels incomplete pairs
+instead of guessing their duration. It does not write logs or workflow state.
+
+Use the dependency-free usage report for recent runs when call-owning adapters
+have emitted verified usage events:
+
+```bash
+python3 "{CM_WORKFLOW_ROOT}/scripts/cm-usage-report.py" --last 10
+```
+
+It keeps unavailable calls explicit and does not estimate missing tokens or cost.
+Claims without a matching valid usage completion are listed separately as
+unresolved and are not counted as calls, outcomes, or Token usage.
+
+1. Before a potentially long external command, desktop launch, browser case, or
+   model turn, write `progress/start`; write `progress/checkpoint` only at an
+   actually observed milestone, and `progress/complete` when it ends.
+2. Every blocking browser case writes `test_run/case_start` followed by exactly
+   one `case_complete` or `case_blocked`. When a specs directory exists, update
+   `.cm-status.json` at the same checkpoints so live status and the audit log do
+   not disagree; standalone `$cm-test` runs do not create that file. A phased
+   `test_run/start` must end in `test_run/complete`; `task_done`/`run_done` are
+   mechanically rejected while the invocation or any case remains open.
+3. A temporary profile, process, model alias, worktree, or fixture writes
+   `resource/acquired` before use with `cleanup_required: true`. Its cleanup
+   writes `resource/released`; cleanup failure writes `resource/cleanup_failed`
+   and keeps the task blocked. Terminal phases require the same `resource_id`
+   and `resource_kind`, but do not repeat `cleanup_required`.
+4. `resource_id` identifies one acquisition lifetime, not a path, credential,
+   token, or secret. While the acquisition remains active, only an exact retry
+   reuses that ID; any distinct acquisition uses a new ID. After `released`, the
+   ID cannot be acquired again. A delayed exact retry remains deduplicated and
+   does not reopen the resource. The writer never guesses which acquisition a
+   delayed cleanup belongs to.
+5. The writer checks resource events in the current run before `task_done`,
+   legacy `done`, or `run_done`. Any latest `acquired` or `cleanup_failed`
+   without a later `released` blocks completion. Malformed resource events or
+   an unreadable authoritative log also block completion. Historical runs
+   without resource events remain compatible.
+
+For recoverable operational mistakes, prefer a `warning` event. New warning and
+error events include `severity`, `impact`, `recovered`, `attempt`, and `outcome`.
+Use `severity: error` only when the current task cannot continue; a successful
+retry is `warning` with `recovered: true`. The writer's sensitive-field rejection
+remains authoritative—choose safe metadata names instead of weakening it.
+
+## Write and degradation rules
+
+1. When `{SPECS_DIR}` exists, write the project event first, then mirror the
+   identical event id into the global run file.
+2. A global-mirror failure appends a project-side `degrade` event with
+   `phase: global_log`, warns once, and returns success. The project log remains
+   authoritative.
+3. A project-log failure returns non-zero; do not claim the event was recorded.
+4. A standalone flow without specs has only the global destination. Global
+   failure returns non-zero and must be reported.
+5. `index.jsonl` contains lightweight `running` and `done` run records. Full
+   events stay in per-run files, avoiding one contended global stream.
+6. Global directories/files are user-private (`0700`/`0600` where supported).
+   The location can be changed only through the explicit
+   `CM_WORKFLOW_LOG_HOME` environment variable.
+7. A run keeps the global file selected at its start even when it crosses a
+   month boundary. Pointer failure degrades to project-log recovery and does not
+   invalidate events that were already durably appended.
+8. `.cm-run.lock` and the private global `.cm-write.lock` serialize concurrent
+   writers. Completely identical retries in one run reuse a deterministic
+   `event_id`; callers must include an attempt/task identifier in `data` when
+   two otherwise identical events are intentionally distinct.
+
+## Privacy and size boundary
+
+Logs contain metadata, counts, identifiers, relative evidence references, and
+short decisions. Never log:
+
+- complete prompts or model responses;
+- source, diff, document, or local-file contents;
+- API keys, tokens, passwords, cookies, authorization headers, private keys, or
+  recovery codes;
+- customer data, browser state, databases, or internal endpoints.
+
+Keep `detail` to one line and at most 500 characters. Put test/review detail in
+`.reviews/`, External Expert detail in `.external/`, and code truth in Git. The
+writer rejects sensitive field names, but callers still own content
+minimization and redaction.

package/workflows/cm/runtime/model-efficiency.md

@@ -0,0 +1,201 @@
+# CM model-call efficiency contract
+
+This contract reduces repeated API context and verbose model output without
+reducing requirements, tests, independent review, approval, or evidence. It is
+an execution contract for model-call owners; it is not a model gateway and does
+not claim visibility into calls made by Codex, Claude, or a declared adapter.
+
+## Minimal role packet
+
+Build one packet for the current role and current task. Reference durable files
+by path and include only the slices needed for the decision; do not paste the
+same project overview, full specs, full source files, or prior conversation into
+every role call.
+
+| Role | Required dynamic packet |
+| --- | --- |
+| `analyst` | current requirement, relevant business-map slice, known constraints, unresolved questions |
+| `planner` | analyst result, affected modules/interfaces, approved constraints, acceptance-criteria candidates |
+| `coder` | one task, mapped ACs, relevant design contracts, allowed files, verification commands, current attempt |
+| `tester` | test contract/cases in scope, declared commands, environment facts, concise failure evidence when retrying |
+| `reviewer` | current task handoff, task-only diff/new files, mapped ACs and rules, verification summary, pre-task dirty exclusions |
+| `browser_qa` | selected browser cases, target environment/route, setup and cleanup facts, expected observable results |
+
+Every packet states `workflow`, `stage`, `role`, objective, stable artifact
+references, current identifiers, constraints, and expected output shape. A
+missing required item is reported as missing; it is not replaced with guessed
+context. The reviewer package in `runtime/review.md` and test evidence in
+`runtime/test-contract.md` remain minimum quality requirements, not optional
+content to trim.
+
+Start targeted. Escalate only when a concrete dependency, ambiguity, changed
+shared contract, or review finding shows that the packet is insufficient.
+Record the reason and newly added scope; do not reread or resend unchanged full
+context. `cm-prd` additionally follows its progressive context-scope contract.
+
+## Stable prefix
+
+When an integration owns the prompt assembly, keep reusable instructions in
+this order:
+
+1. safety and authorization boundary;
+2. CM workflow/stage boundary;
+3. applicable project rules;
+4. role contract;
+5. output schema.
+
+Append the dynamic role packet after that prefix. Keep stable sections byte-for-
+byte unchanged during one run when their source has not changed. Put timestamps,
+attempt ids, diffs, task text, test output, and conversation history only in the
+dynamic packet.
+
+Prompt caching is optional. Enable it only through an adapter/runtime capability
+that is actually available, and only report cache reads/writes returned by that
+adapter. A stable prefix improves reuse even when no cache API exists, but CM
+must never claim a cache hit from prefix stability alone.
+
+## Compact output
+
+Ask each role for its decision artifact, not a narration of its reasoning:
+
+- analyst/planner: deltas, decisions, open questions, AC/task mappings;
+- coder: changed paths, verification, blockers, scope deviation;
+- tester/browser QA: case verdicts, counts, failing identifiers, evidence paths;
+- reviewer: findings first, verdict, blocking count, reviewed scope.
+
+Do not repeat the prompt, full specs, source, diff, or successful command output.
+For failures retain the exit code, failing case/command, first actionable error
+and evidence path; avoid arbitrary truncation that hides the root error. Durable
+detail stays in the existing specs/review/test artifacts. Main logs keep only
+safe identifiers, counts, outcomes, and short summaries.
+
+## Verified usage event
+
+### Bundled OpenAI-compatible boundary
+
+`roles.*.adapter: openai-compatible` resolves to `managed-adapter`. The role
+owner invokes the bundled standard-library boundary instead of treating it as
+unavailable:
+
+```bash
+export CM_OPENAI_COMPATIBLE_ENABLED=true
+export CM_OPENAI_COMPATIBLE_BASE_URL="https://models.example.invalid/v1"
+export CM_OPENAI_COMPATIBLE_API_KEY="<set outside project config>"
+
+python3 "{CM_WORKFLOW_ROOT}/scripts/cm-openai-compatible-call.py" \
+  --workflow cm-prd --stage design_generation --role planner --runtime codex \
+  --requested-model planner-default --call-id "{unique_call_id}" \
+  --project-root "{CODE_PROJECT}" --specs-dir "{SPECS_DIR}" \
+  --run-id "{run_id}" < "{ROLE_PACKET_JSON}"
+```
+
+The stdin JSON has exactly two fields. The adapter canonicalizes the stable
+prefix in the declared order, so callers do not depend on JSON key order.
+`dynamic_packet` requires the seven fields shown below and permits only one
+optional `context` object for role-specific material. Its workflow, stage, and
+role must match the CLI identity; rejected packets create neither a claim nor an
+HTTP request:
+
+```json
+{
+  "stable_prefix": {
+    "safety": "applicable safety and authorization boundary",
+    "workflow": "current CM workflow and stage boundary",
+    "project_rules": "only the applicable stable project rules",
+    "role": "current role contract",
+    "output_schema": "compact role output schema"
+  },
+  "dynamic_packet": {
+    "workflow": "cm-prd",
+    "stage": "design_generation",
+    "role": "planner",
+    "objective": "current objective",
+    "identifiers": {},
+    "constraints": [],
+    "context": {"requirement": "only the task-relevant material"},
+    "expected_output": "compact plan"
+  }
+}
+```
+
+The three environment variables are invocation authority, endpoint, and secret;
+none belong in `.cm-workflow.yml`, command arguments, evidence, or logs. HTTP is
+accepted only for loopback fixtures; remote endpoints require HTTPS. The adapter
+connects directly to the configured endpoint and does not inherit environment
+proxy settings or follow redirects. It
+first records an atomic `model_call/claimed` event, then sends the packet, prints
+only the model's text result to stdout, and writes one verified `model_usage`
+event at the same response boundary. A repeated or concurrent invocation with
+the same run and `call_id` is rejected before HTTP, including a call id that
+already has a completion, so retries that represent a new provider call must use
+a new `call_id`. `--run-id` is required when no
+`--specs-dir` is provided, keeping the claim and completion in one global-only
+run. Exit states are:
+
+- `0`: model result returned and usage event recorded;
+- `1`: call/response failed and an error outcome was recorded;
+- `2`: configuration or input was rejected before any HTTP call;
+- `3`: model result returned in stdout but usage logging failed—do not
+  automatically repeat the model call.
+- `4`: model call or response failed and the error outcome could not be logged;
+  the pre-call claim remains unresolved and must not be treated as completed
+  evidence.
+
+The role owner records a warning/blocking outcome for nonzero exits and never
+silently substitutes another model.
+
+This boundary returns text; it does not edit files, run commands, approve specs,
+or satisfy N4 by itself. The local orchestrator applies accepted results and
+retains all existing execution and review gates. Other adapters remain
+`declared-adapter` until they have their own verified boundary.
+
+### Event contract
+
+The component that actually owns a completed model-call boundary may write one
+`model_usage/complete` event through `scripts/cm-log-event.py`:
+
+```bash
+python3 "{CM_WORKFLOW_ROOT}/scripts/cm-log-event.py" \
+  --workflow cm-prd --event model_usage --phase complete --runtime codex \
+  --project-root "{CODE_PROJECT}" --specs-dir "{SPECS_DIR}" \
+  --detail "planner model call completed" \
+  --data-json '{"call_id":"planner-20260806-0001","stage":"design_generation","role":"planner","adapter":"company-api","requested_model":"planner-default","effective_model":"provider-model-v2","source":"api","purpose":"cm-prd:design_generation","usage_state":"observed","input_tokens":1200,"output_tokens":300,"cache_read_tokens":800,"cache_write_tokens":0,"duration_ms":2500,"outcome":"success"}'
+```
+
+Rules:
+
+1. `call_id` is a non-secret id unique to one real call within the run. The
+   bundled boundary claims it before HTTP and refuses reuse; a distinct or
+   recovery call uses a new id. The writer still deduplicates an exact retry of
+   a standalone event write.
+2. `workflow`, `runtime`, `stage`, `role`, `adapter`, `requested_model`, `source`,
+   and `purpose` form the safe call identity. A completion for an existing claim
+   must match all eight fields; ordering is claim first, completion second.
+3. `observed` means the adapter/runtime returned the values. Input and output
+   counts are required; cache counts and duration are optional.
+4. `unavailable` carries no token counts. It may carry a measured `duration_ms`
+   when the integration observed the call boundary but received no usage data.
+5. A Skill that cannot see the call boundary or adapter response writes only its
+   normal route/progress evidence; it does not fabricate a `model_usage` event.
+6. `requested_model` is configuration. `effective_model` is present only when
+   the runtime/provider reports it. Do not infer either from a subscription badge.
+7. Never log prompts, responses, source code, diffs, customer data, credentials,
+   headers, endpoints, or provider payloads. The writer accepts only the small
+   model-usage field allowlist and rejects negative counts.
+8. Token counts are not cost. CM v1 does not estimate money or combine cache
+   counters into input/output totals.
+
+Read the private local summary with:
+
+```bash
+python3 "{CM_WORKFLOW_ROOT}/scripts/cm-usage-report.py" --last 10
+python3 "{CM_WORKFLOW_ROOT}/scripts/cm-usage-report.py" --last 10 --json
+```
+
+The report deduplicates event ids and per-run call ids, rejects malformed usage
+rows and conflicting claim identities, requires claim-before-completion ordering,
+separates observed and unavailable calls, and never guesses missing usage.
+A bundled `openai-compatible` usage row without its prior claim is invalid and
+is never counted; other call-owning adapters may still emit standalone usage.
+A `model_call/claimed` row without a matching valid completion is reported as an
+unresolved claim; it is not counted as a completed call, outcome, or Token usage.

package/workflows/cm/runtime/orchestration.md

@@ -0,0 +1,113 @@
+# CM Codex orchestration contract
+
+This contract governs `cm-ai`, `cm-fix`, and `cm-refactor` when they execute work in Codex.
+
+## Sources of truth
+
+- The active feature `tasks.md` is the authoritative business-task state.
+- Specs, `.cm-status.json`, `.cm-run.json`, `运行日志.jsonl`, `.reviews/`, `METRICS.md`, and `LESSONS.md` are authoritative audit artifacts.
+- Codex plans, subagent threads, and OMX state are disposable mirrors. Rebuild them from disk after a restart; never let them silently reverse a checked task.
+- `~/.cm-workflow/logs/` (or `CM_WORKFLOW_LOG_HOME`) is a private,
+  reconstructable cross-project mirror. It helps operators inspect many runs,
+  but it never overrides the specs-local artifacts.
+
+## Project role routing
+
+An optional project `.cm-workflow.yml`/`.yaml`/`.json` is loaded through
+`scripts/cm_workflow_config.py`; the shared contract is
+`runtime/workflow-routing.md`. The effective role mapping is projected into
+`cm-prd`, `cm-ai`, and `cm-test` as requested route metadata and stage
+instructions:
+
+- `cm-prd`: `analyst` → analysis, `planner` → design and task split;
+- `cm-ai`: `coder` → implementation, `tester` → task checks, `reviewer` → N4;
+- `cm-test`: `tester` → logic/commands, `browser_qa` → browser simulation;
+- `external_expert`: reasoning-only and still governed by
+  `runtime/external-expert.md`.
+
+The route resolver records the requested adapter/model alias without claiming
+an unobserved backend model. The bundled `openai-compatible` route is
+`managed-adapter`; other unavailable non-local adapters are `declared-adapter`,
+not a silent success. Missing configuration keeps the
+built-in current-runtime/local-tool defaults. Role routing never changes task
+authority, N1–N8 order, N4 independence, or Git permissions.
+The project validator rejects `openai-compatible` for `reviewer` until the N4
+evidence contract has a real managed-review channel; this prevents an advisory
+API call followed by a second gate-eligible review.
+
+At each model-backed role boundary, also apply `runtime/model-efficiency.md`:
+send the current role's minimal packet, retain the stable instruction prefix
+when the integration supports it, and request the compact role artifact. This
+changes context transport only; it does not remove ACs, tests, review evidence,
+or approval gates. Usage is logged only by a component that observes the actual
+call response.
+
+Only the main agent may update `tasks.md`, audit artifacts, shared status, or Git history. A worker edits only the files assigned to its task and returns a structured handoff. The main agent materializes and validates that evidence under `runtime/task-gates.md`; the worker response itself never advances workflow state.
+
+## Optional external reasoning
+
+CM is `EXPLICIT` by default. When the user asks for an external expert, selects
+an external route, or explicitly enables AUTO for the current task, read
+`runtime/external-expert.md`. AUTO may choose LOCAL, CONSULT, or VERIFY;
+HANDOFF is explicit-only. The external channel may discuss, research, diagnose,
+design tests, or critique, but it never becomes a code worker and never receives
+workflow write authority. The main agent selects and approves outbound context,
+implements accepted suggestions locally, and runs the normal verification.
+
+Version 1 external-expert evidence is advisory and cannot satisfy N4. A global
+router cannot silently enable CM AUTO. AUTO is invocation-scoped and never
+authorizes local-file content; do not enable it merely because the task is
+complex or the external service is already logged in.
+
+## OMX enhancement
+
+At workflow start, detect `omx` with `command -v omx`.
+
+- Available: start or resume the session, inspect `omx hud`, and mirror planned tasks/review status through supported OMX commands.
+- Unavailable or unhealthy: report `OMX mirror: unavailable` once and continue from disk in serial mode.
+
+OMX absence is not a reason to skip review, evidence, task marking, QA, or documentation.
+
+## Serial and parallel execution
+
+Serial is the default. `cm-ai` is explicitly allowed to delegate to Codex subagents only when all conditions hold:
+
+1. tasks have no dependency edge between them;
+2. their expected file sets do not overlap;
+3. neither task writes specs, metrics, logs, project instructions, lockfiles, migrations, or Git state;
+4. the available collaboration runtime can return reviewable handoffs.
+
+If any condition is uncertain, run serially. Never parallelize destructive migrations, production operations, fund/key operations, or tasks that share an interface still under design.
+
+Read-only parallel work does not require a worktree. Before two or more tasks
+write code concurrently, assign each task a registered worktree and unique
+branch, then run:
+
+```bash
+python3 {CM_WORKFLOW_ROOT}/scripts/cm-task-gate.py check-parallel-write \
+  --repo {CODE_PROJECT} \
+  --assignment T-001={WORKTREE_ONE} \
+  --assignment T-002={WORKTREE_TWO}
+```
+
+Any nonzero result means **run serially**. Do not improvise a shared checkout,
+detached worktree, or same-branch parallel write.
+
+## Worker payload
+
+Every delegated task includes:
+
+- task id and exact title;
+- relevant requirements, design contract, and acceptance criteria;
+- allowed file scope;
+- applicable role skill and discipline reference;
+- verification command(s);
+- prohibition on editing specs, status, metrics, reviews, or Git state;
+- fixed handoff format from `runtime/task-gates.md`: task/attempt, status, changed
+  files, verification, evidence, blockers, and scope deviations.
+
+## Resume behavior
+
+On every invocation, reread disk state. Treat `[x]` and `[DROPPED]` tasks as terminal unless the user explicitly reopens them. Find the first eligible unchecked task after dependency analysis. Do not trust conversation summaries for completion state.
+
+After each task, the main agent performs review, evidence checks, checkbox update, metrics, commit, and a fresh disk reread before selecting the next task.

package/workflows/cm/runtime/project-context.md

@@ -0,0 +1,37 @@
+# CM project-context contract
+
+This contract is shared by every CM workflow skill. Resolve paths from the active `SKILL.md`; never assume where Codex cached or installed the plugin.
+
+## Workflow root
+
+1. Let `SKILL_DIR` be the directory containing the active CM `SKILL.md`.
+2. The workflow root is normally `SKILL_DIR/../..`.
+3. Verify the candidate root contains `VERSION`, `templates/`, and `runtime/` before using it.
+4. If a user explicitly provides `CM_WORKFLOW_HOME`, prefer it after the same verification.
+5. Do not hardcode `~/.codex/plugins/cache`, `~/.agents/skills`, or `~/.claude` as the workflow root.
+
+This relative rule works both from a Codex plugin (`<plugin>/skills/<name>/SKILL.md`) and the legacy Claude installation (`~/.claude/skills/<name>/SKILL.md`).
+
+## Target project context
+
+Read context in this order:
+
+1. The `AGENTS.md` chain already supplied by Codex. If working outside Codex, read the nearest applicable `AGENTS.md` files from repository root to the current directory.
+2. The target project `.claude/CLAUDE.md`, when present, as a compatibility project map.
+3. Only the `.claude/rules/*.md` files relevant to the current task, plus `coding-style.md`, `testing.md`, and `security.md` when present.
+4. The target specs files named by the active workflow.
+
+When `AGENTS.md` and `.claude/CLAUDE.md` disagree, follow the more specific instruction that applies to the current path, unless it weakens a safety boundary. Record material conflicts in the task report.
+
+## `cm-init` output
+
+For an existing project, `cm-init` maintains both surfaces:
+
+- Root `AGENTS.md`: concise Codex-native project expectations, commands, safety boundaries, and an instruction to read relevant compatibility rules.
+- `.claude/CLAUDE.md` plus `.claude/rules/`: the existing CM/Claude compatibility contract.
+
+If either surface already exists, preserve user-authored content. Propose a merge or add a clearly bounded CM section; never overwrite the whole file without explicit approval.
+
+## Resource references
+
+Workflow templates live under `<workflow-root>/templates/`. Flow-specific references live beside the active skill under `references/`. Always open referenced files from those resolved locations instead of relying on a user-level installation path.