# Coordination documents and registers Harness process authority belongs to native engine domain writers and their current actor, scope and state contracts. Recorded document versions are provenance, not replacement credentials. This file records lifecycle verbs and the two surfaces that took over the retired project register: the issue store (open items) and its separate reviewed migration/activation lifecycle. Field schemas, section meanings and per-document semantics are owned by `mstar-artifacts`; the capture duty and the register's migration mapping by `mstar-project-governance`; phase and close semantics by `mstar-iteration`. What follows is the CLI face. For ordinary lifecycle intents use the owning public verb rather than replacing a snapshot as a setup step. Current authority derives coherent projections and action-local prerequisites; protected documents have no raw byte-version replacement recipe here. Preserve an `applied` or `partial` receipt and resolve only its outstanding conflict; do not treat partial success as a mutation-free refusal. For the open-issue store, discover JSON shapes with `mstar-harness schema CaptureInput`, `OccurrenceInput`, `IssueTriage`, `ClosureEvidence`, and `IssueLink` before `issue add|occurrence|triage|close|waive|duplicate|supersede|link` (the corresponding verb help owns flags). `ClosureEvidence` has disposition-specific required fields; use the schema rather than guessing from a prior refusal. Store reads/export need no write payload. Plan-scoped `issue-add` and `issue-close` are separate authority routes, not substitutes for the unscoped actor's explicit operation and issue-revision inputs. Complete synthetic `CaptureInput` example (adapt evidence, timestamp and semantic keys to the observed finding; do not copy this observation into a live store): ```json { "projectId": "example-project", "title": "Example failed boundary", "kind": "bug", "severity": "medium", "impact": "A user cannot finish the example operation", "acceptance": "The operation succeeds for the valid boundary input", "sourceIdentity": "example-report:case-1", "rootCauseKey": "example-boundary-handling", "acceptanceKey": "valid-boundary-operation", "occurrenceKey": "example-run-1", "sourceKind": "review", "location": "src/example.ts:42", "observedBehavior": "Valid boundary input was rejected", "evidence": ["example scoped observation"], "discoveredAt": "2026-01-01T00:00:00Z" } ``` ## The execution authority and its historical import sources ACTIVE root/workflow/plan/merge-exclusion/session authority is `{HARNESS_DIR}/store.db` (`execution_*`), read through `mstar status validate` / `mstar plan show` and written only through public workflow/plan verbs. The files below are **read-only import/history**. `mstar store upgrade` directly reads recognized v1/v2 execution sources and preserves their original bytes; standalone `mstar migrate` staging is retired. Public persist and engine `ArtifactKind` accept `review` and `json` only. | Historical import file | Path shape | Holds | |---|---|---| | root register | `{HARNESS_DIR}/status.json` | schema version, update timestamp, and the registry of active workflows (id, type, start, directory) | | workflow snapshot | `{WORKFLOW_DIR}//snapshot.json` | one lifecycle: plan rows, coordination blocks, leases, branch anchors, delivery block | The root register is a registry, not a plan store: plan rows live in `execution_plans`; open findings live in store issues. A third legacy document still exists — the project register `{PROJECT_DIR}//residuals.json`. It is **migration history only**: it stays readable for the migration mapping, but it is no longer a write surface, and no command maintains it (see § Open items and § Store lifecycle). ## Protection levels **Active file-route guard first** — raw root/snapshot/session-file writes and deletes refuse `execution.direct-write-refused`; reads refuse `execution.consumer-not-ready`, including canonical generic-file aliases. Do not retry via `persist json`; use the public verb. **Unconditionally retired** — `residuals` kind refuses `persist.kind-retired`; project residual registers are migration history, not a live persist read/write surface. The root/snapshot file kinds are outside the persist surface entirely — it accepts `review` and `json` only. Open findings use issue verbs. **Unprotected** — the review envelope kind and unrelated generic files. They keep the ordinary put / get / list / delete contract, delete is an idempotent no-op when absent, and there is no confirmation prompt. A review envelope is not a coordination document: its schema and validation belong to the review workflow's owning skill; the store face only persists and reads it. Enumeration reflects what exists: listing a kind prints its stored keys, one per line ascending, with no header, and an empty kind prints nothing and exits `0`. A missing backing file lists as empty rather than erroring. ## Protected document writes Use the supported lifecycle action for the current authority, not a raw protected-document replacement recipe. Root/snapshot/session files and retired residual registers have no live replacement writer. A digest or `absent` is historical information, not a mandatory mutation flag or consumed byte-CAS token. Current semantic validation, native transactions/CAS, numeric revisions, active execution tokens and genuine business integration exclusion remain separate requirements; there is no application file/directory mutex. ## Lifecycle close Closing one finished lifecycle is a single verb whose work has a fixed order: 1. consult the registered delivery kind and its recorded evidence; 2. write terminal workflow state in the ACTIVE execution store; 3. unregister the root entry, idempotently. ```sh # the coordinator's own reference plus the workflow's full execution token mstar status workflow-close --workflow --session-ref \ --expect --operation --reason [--harness ] [--json] ``` Read the action-local receipt: the close acts on store rows, not file bytes, and a refusal leaves the protected documents unchanged. - dangling leases or unfinished plan rows refuse; - incomplete or absent delivery evidence for the registered kind refuses, and the workflow row stays running with its root entry still registered; - a **coordinated** workflow refuses a session-less close — it reports that the workflow is coordinated and that the close needs the authority that owns it. Only that workflow's own coordinator can close it; a plan session's reference is not sufficient. The close carries its own reason; the retired file-route `--ended-at` input is a usage refusal. - An uncoordinated workflow closes with or without the coordinator's authority. Failure between steps 2 and 3 is reported as a partial close. A re-run finishes it, and a fully closed retry rewrites nothing. The close verb is the lifecycle route for a finished workflow: the protected staging files refuse the generic delete face, and the removed residual-archival command fails and names the issue disposition that replaced it. ## Lifecycle reopen A `failed` or `stopped` lifecycle returns to `running` on the SAME id through `mstar workflow reopen`; a `completed` lifecycle is never reopened and keeps `workflow.reopen-completed` with no override: ```sh mstar workflow reopen --workflow --reason --attestation \ [--expect ] [--operation ] [--harness ] ``` The header keeps its identity anchors, plan rows, session rows and retained operation receipts, and the workflow re-enters the ACTIVE registry. Reopening is an explicit operator authorization: `--reason` is recorded, and `--attestation` is a required recovery-scope JSON document whose `attestedAt` + `operator.actor` / `operator.authorizationRef` are the authorization (no installed consumer is required, and an empty `stoppedSessions` is valid). The attestation is self-reported operator evidence — its structure is validated, the operator's authorization is never verified against host liveness. `--expect` is the closed header's terminal token; `mstar status validate` publishes that header as an identity row (`data.authority.terminalUnregistered[]`, or `data.authority.terminalAdoptions[]` for an adopted close) carrying only `id`, `status` and `revision`, never the token. Omitting `--expect` is safe: the verb reads the token from the authority and passes it as the CAS itself. The transition binds no coordinator: resume ownership afterwards through the ordinary bind/recover route. ## Open items: the issue store Open findings are issues in `{HARNESS_DIR}/store.db`; the project register above is migration history and no command maintains it. The capture contract, its authorization and the migration mapping live in **`mstar-project-governance`「Issue capture」** — this file only names the transport. - **Capture** is plan-scoped (`mstar plan issue-add`; `--session-ref`/`--operation` under the caller's independently acquired `--session-id`/`sessionId`, the execution token supplied only as an explicit constraint — on plan operations an omitted one is derived by the engine from the plan's own read; the report names the DB-assigned issue ids and revisions) or unscoped (`mstar issue add`). A recurrence appends an occurrence to the existing issue instead of opening a second one. - **Close** is a separate authorized act with a terminal disposition: `mstar plan issue-close` on the plan's own linked issue (`--issue`, `--disposition`, `--expect-issue`), or `mstar issue close|waive|duplicate|supersede` unscoped. Each mutation is CAS-guarded by the issue revision. - **Removed plan aliases:** residual-add/residual-close are absent, not a compatibility/refusal path. Use issue-add/issue-close under the coordinator; no second findings store. Status backlog-register/backlog-close retain their independently documented refusal surface. - **Reading is not a rollup of the registers.** `mstar status tech-debt` prints the store's open-issue rollup and `mstar status findings-cleanup ` enforces the plan's mode over its **linked open issues**; a missing, corrupt or staged store refuses (exit 1) instead of reporting an empty rollup. ## Store lifecycle: migration, activation, retirement `store init` creates a fresh active issue/catalog store; `store upgrade` opens/creates the store, imports recognizable execution state, activates authority and reports skipped inputs. Neither requires routine `activate` afterwards. The sequence below is the **staged migration** route; `activate` consumes its reviewed apply and attestation, not an init receipt. Initialization semantics → `mstar-conventions`. **When no store exists**, a consumer command refuses `store.not-initialized` (exit 1) instead of falling back to file state. Recovery names the two bootstrap paths and the third disposition: a genuinely empty workspace runs `mstar harness scaffold` then `mstar store init`; a workspace holding historical file state runs `mstar store upgrade --harness --operator ` to import it and activate the store; and a workspace that needs no execution authority uses **conversation tracking (no-plan mode)** — plans stay unregistered and the gates still apply. ```sh mstar store migrate --out # default: read-only preview manifest (writes no DB) mstar store migrate --apply --manifest # the explicit reviewed apply → staged store mstar store backup --out # consistent native database image, verified read-only mstar store activate --manifest --attestation # the barrier mstar store retire --manifest # moves the reviewed legacy sources under a ledger ``` - **`migrate`** previews a reviewable manifest and no DB; reviewed apply commits issue/catalog/receipt import into a staged store. Ordinary mutations remain refused until activation. Source identity/path/state requirements remain; legacy project registers stay migration history and are never a live capture path. - **`backup`** writes a SQLite-consistent `VACUUM INTO` database image (committed WAL state included) and verifies it by reopening the copy read-only. The image supplies its own identity and row facts; independently sampled live counts do not freeze time. Ordinary docs/logs/notes are neither frozen nor copied as transactional authority. Copying the live `store.db` alone without its WAL is not a backup. - **`activate`** is the barrier. It requires the reviewed apply receipt to be the **final** one, a compatible-consumer attestation (installed entrypoints and versions, quiesced sessions, the approving operator — never session credentials) and a verified backup; the state flip, the epoch increment and the receipt commit in one transaction. Ordinary mutations work only afterwards, and every command checks epoch and state. - **`retire`** moves the reviewed legacy registers and index sections into `{HARNESS_DIR}/archived/store-migration//` under a resumable per-item ledger, checking active identity, epoch, current paths and item state and preserving copy-before-remove ordering. Content-digest changes alone do not refuse retirement or replay. An unreviewed register path still refuses `store.legacy-write-detected`; resume uses current item/path/state facts and archive presence, not recorded-byte equality. Execution migration apply/activate/retire requests no longer take `manifestHash`, activation no longer takes `coverageDigest`, and restore no longer takes `acceptLossDigest`. Generated manifest/coverage/loss digests remain historical diagnostics only. Use current verb help for the remaining actor, authorization, identity, path, state and numeric revision inputs; no digest-confirmation flag or replacement seal is required. **Execution restore.** `mstar store execution restore-preview` assesses whole-domain loss from a verified backup; `restore` uses the same live database pathname/inode and one native owning transaction to replace issue/catalog/execution/host authority with a new epoch. Trust, schema/integrity/FK safety, operator authorization, loss acknowledgement, stale-preview refusal and operation replay remain required. A verified pre-restore safety image is captured outside the mutation transaction. No live database rename, WAL/SHM removal, retained-body freeze or ordinary-file rollback is part of restore. Current verb help owns exact inputs and post-commit retry/recovery; a committed outcome is never described as mutation-free failure. **Fresh-store failure phases.** `store.publication-failed` preserves the OS cause and means no store was published at the canonical path: fix the named filesystem condition (permissions, space or hard-link support) and retry the same entry, or select a supported filesystem with `--harness`. `store.created-handle-failed` means the store was already created, activated and published but opening its handle failed; the diagnostic preserves that actual cause and the complete store remains. `store init` stays create-only, so continue an interrupted upgrade with `mstar store upgrade --harness --operator ` after the named condition clears; do not delete the published store or retained sources. **Readiness guidance (not an action).** These are the readiness checks an operator performs *before* a live activation; running a documentation or source task performs none of them, and no stored flag stands in for them. Activation is an authorized ops act under a recorded, bounded authorization covering the affected installed CLI/plugin upgrades or reloads; credentials and unrelated global configuration stay out of scope. Ready means every compatible consumer is quiesced and then reloaded, upgraded or explicitly excluded, and old software is kept out by that operational barrier — a marker, a chmod or a missing register cannot stop an old binary. If a host cannot reload safely, **stop at that host's exact manual-restart step**, have the user restart, then re-check entrypoint, runtime, version and session identity read-only before activating. Execution stays **unavailable** until an ACTIVE authority exists: a staged store serves no ordinary mutation, a workspace without a store bootstraps (`mstar harness scaffold` + `mstar store init`, or `mstar store upgrade`) or uses conversation tracking (no-plan mode), and the historical input files are migration sources, never live execution authority. A below-floor runtime or missing capability refuses actionably rather than falling back to JSON. ## Authorization The protected writes are authorized, not merely gated: - every coordinated authority mutation uses the transport that owns it — the scope's execution token plus an independently acquired caller identity — rechecked inside its native transaction; - **a reference and a token are not credentials a caller declares or forwards.** The active reference is a lookup into stored session rows; it grants nothing without the independently acquired caller the engine compares in its own transaction. Both the reference and every token stay with the coordinator or PM session: handing one to a leaf executor, or restating a token in a leaf's assignment, is a scope violation regardless of intent; - **no resume stands in for recovery**, and no recovery stands in for a fresh bind: a stopped owner is replaced by the recovery verb that owns its authority, never by a copied id, a restarted launcher or a hand-edited record; - the store face's own escape hatches are narrowed: an injected store cannot serve the coordinated surface, and the protected kinds refuse the direct faces entirely.