agentera 3.0.0-dev.8 → 3.0.0-dev.81

package/bundle/references/meta/retained-reference-authority.yaml

@@ -0,0 +1,171 @@
+schema_version: agentera.retainedReferenceAuthority.v1
+live_roots:
+  - references
+  - skills/agentera/references
+inventory:
+  - path: references/adapters/package-publication.json
+    classification: current
+    production_owner: { module: packages/cli/scripts/publication-transaction.mjs, symbol: PUBLICATION_CONTRACT }
+    consumers:
+      - { kind: runtime, module: packages/cli/scripts/publication-transaction.mjs, symbol: PUBLICATION_CONTRACT, consumption: loads }
+      - { kind: runtime, module: packages/cli/src/registries/packagePublication.ts, symbol: loadPackagePublicationModel, consumption: loads }
+  - path: references/adapters/package-registry.yaml
+    classification: current
+    production_owner: { module: packages/cli/src/registries/packageRegistry.ts, symbol: loadRegistry }
+    consumers:
+      - { kind: runtime, module: packages/cli/src/registries/packageRegistry.ts, symbol: loadRegistry, consumption: loads }
+  - path: references/adapters/product-v1-reset.yaml
+    classification: current
+    production_owner: { module: packages/cli/src/upgrade/productV1ResetAuthority.ts, symbol: loadProductV1ResetAuthority }
+    consumers:
+      - { kind: runtime, module: packages/cli/src/upgrade/productV1ResetAuthority.ts, symbol: loadProductV1ResetAuthority, consumption: loads }
+  - path: references/analysis/evidence-tier-authority.yaml
+    classification: current
+    production_owner: { module: packages/cli/src/registries/evidenceTierContract.ts, symbol: loadEvidenceTierContract }
+    consumers:
+      - { kind: runtime, module: packages/cli/src/registries/evidenceTierContract.ts, symbol: loadEvidenceTierContract, consumption: loads }
+  - path: references/analysis/personal-glossary-evaluation-authority.yaml
+    classification: current
+    production_owner: { module: packages/cli/src/eval/glossaryEvaluation.ts, symbol: loadGlossaryEvaluationAuthority }
+    consumers:
+      - { kind: runtime, module: packages/cli/src/eval/glossaryEvaluationSuccessReport.ts, symbol: validateGlossaryEvaluationSuccessReport, consumption: loads }
+  - path: references/analysis/personal-glossary-holdout.yaml
+    classification: current
+    production_owner: { module: packages/cli/src/eval/glossaryEvaluation.ts, symbol: loadGlossaryEvaluationHoldout }
+    consumers:
+      - { kind: runtime, module: packages/cli/src/eval/glossaryEvaluationSuccessReport.ts, symbol: validateGlossaryEvaluationSuccessReport, consumption: loads }
+  - path: references/analysis/personal-glossary-evaluation-corpus.yaml
+    classification: current
+    production_owner: { module: packages/cli/src/eval/glossaryEvaluation.ts, symbol: loadGlossaryEvaluationBehaviorFixture }
+    consumers:
+      - { kind: runtime, module: packages/cli/src/eval/glossaryEvaluationSuccessReport.ts, symbol: validateGlossaryEvaluationSuccessReport, consumption: loads }
+  - path: references/analysis/verification-policy.yaml
+    classification: current
+    production_owner: { module: packages/cli/scripts/verify-lane.mjs, symbol: loadContract }
+    consumers:
+      - { kind: runtime, module: packages/cli/scripts/verify-lane.mjs, symbol: loadContract, consumption: loads }
+  - path: references/artifacts/artifact-registry-interface-model.yaml
+    classification: current
+    production_owner: { module: packages/cli/src/registries/artifactRegistry.ts, symbol: loadArtifactRegistry }
+    consumers:
+      - { kind: runtime, module: packages/cli/src/registries/artifactRegistry.ts, symbol: loadArtifactRegistry, consumption: loads }
+  - path: references/artifacts/glossary-entry-contract.yaml
+    classification: current
+    production_owner: { module: packages/cli/src/registries/glossaryEntryContract.ts, symbol: glossaryEntryAuthorityPath }
+    consumers:
+      - { kind: runtime, module: packages/cli/src/registries/glossaryEntryContract.ts, symbol: personalGlossaryOutputContract, consumption: loads }
+  - path: references/artifacts/state-storage-authority.yaml
+    classification: current
+    production_owner: { module: packages/cli/src/state/stateStorageAuthority.ts, symbol: loadStateStorageAuthority }
+    consumers:
+      - { kind: runtime, module: packages/cli/src/state/stateStorageAuthority.ts, symbol: loadStateStorageAuthority, consumption: loads }
+  - path: references/artifacts/verbosity-budget-authority.yaml
+    classification: current
+    production_owner: { module: packages/cli/src/registries/verbosityBudgetContract.ts, symbol: inspectArtifactVerbosityBudget }
+    consumers:
+      - { kind: runtime, module: packages/cli/src/registries/verbosityBudgetContract.ts, symbol: inspectArtifactVerbosityBudget, consumption: loads }
+  - path: references/cli/app-lifecycle-vocabulary.yaml
+    classification: current
+    production_owner: { module: packages/cli/src/validate/vocabularyAuthority.ts, symbol: validateVocabularyAuthority }
+    consumers:
+      - { kind: validator, module: packages/cli/src/validate/vocabularyAuthority.ts, symbol: validateVocabularyAuthority, consumption: loads }
+  - path: references/cli/bundle-skill-vocabulary.yaml
+    classification: delete
+  - path: references/cli/capability-instruction-contract.yaml
+    classification: current
+    production_owner: { module: packages/cli/src/cli/capabilityContext/progress.ts, symbol: evaluatorHandoffOutputRequirementsFromContract }
+    consumers:
+      - { kind: runtime, module: packages/cli/src/cli/capabilityContext/progress.ts, symbol: evaluatorHandoffOutputRequirementsFromContract, consumption: loads }
+  - path: references/cli/hybrid-route-contract.yaml
+    classification: current
+    production_owner: { module: packages/cli/src/registries/hybridRoute.ts, symbol: resolveRouteRequest }
+    consumers:
+      - { kind: runtime, module: packages/cli/src/registries/hybridRoute.ts, symbol: resolveRouteRequest, consumption: loads }
+  - path: references/cli/update-channels.yaml
+    classification: current
+    production_owner: { module: packages/cli/src/release/releaseMetadata.ts, symbol: readReleaseMetadata }
+    consumers:
+      - { kind: validator, module: packages/cli/src/release/releaseMetadata.ts, symbol: readUpdateChannels, consumption: loads }
+  - path: references/cli/vocabulary-index.yaml
+    classification: current
+    production_owner: { module: packages/cli/src/validate/vocabularyAuthority.ts, symbol: validateVocabularyAuthority }
+    consumers:
+      - { kind: validator, module: packages/cli/src/validate/vocabularyAuthority.ts, symbol: validateVocabularyAuthority, consumption: loads }
+  - path: references/cli/vocabulary.md
+    classification: current
+    production_owner: { module: packages/cli/src/validate/vocabularyAuthority.ts, symbol: validateVocabularyAuthority }
+    consumers:
+      - { kind: validator, module: packages/cli/src/validate/vocabularyAuthority.ts, symbol: validateVocabularyAuthority, consumption: loads }
+  - path: references/adapters/runtime-lifecycle-adapters.yaml
+    classification: migration-only
+    production_owner: { module: packages/cli/src/runtime/lifecycleAdapterContract.ts, symbol: loadRuntimeLifecycleAdapterContract }
+    consumers:
+      - { kind: runtime, module: packages/cli/src/runtime/lifecycleAdapterContract.ts, symbol: loadRuntimeLifecycleAdapterContract, consumption: loads }
+  - path: references/adapters/runtime-lifecycle-authority.yaml
+    classification: migration-only
+    production_owner: { module: packages/cli/src/runtime/lifecycleAuthority.ts, symbol: loadLifecycleAuthority }
+    consumers:
+      - { kind: runtime, module: packages/cli/src/runtime/lifecycleAuthority.ts, symbol: loadLifecycleAuthority, consumption: loads }
+  - path: references/adapters/runtime-lifecycle-operation-contract.yaml
+    classification: migration-only
+    production_owner: { module: packages/cli/src/runtime/lifecycleOperationContract.ts, symbol: loadLifecycleOperationContract }
+    consumers:
+      - { kind: runtime, module: packages/cli/src/runtime/lifecycleOperationContract.ts, symbol: loadLifecycleOperationContract, consumption: loads }
+  - path: references/adapters/runtime-retired-resources.yaml
+    classification: migration-only
+    production_owner: { module: packages/cli/src/runtime/nativeResourceCleanup.ts, symbol: loadNativeResourceCleanupContract }
+    consumers:
+      - { kind: runtime, module: packages/cli/src/runtime/nativeResourceCleanup.ts, symbol: loadNativeResourceCleanupContract, consumption: loads }
+  - path: references/cli/v3-handoff-manifest.schema.yaml
+    classification: delete
+  - path: references/adapters/package-surface-characterization.md
+    classification: runbook
+    maintainer: Agentera CLI maintainers
+    source_checkout_root: .
+    working_directory: .
+    command: pnpm -C packages/cli run pack:dry-run
+  - path: references/cli/routing-model.md
+    classification: runbook
+    maintainer: Agentera CLI maintainers
+    source_checkout_root: .
+    working_directory: .
+    command: node packages/cli/dist/bin/agentera.js route evaluate --format json
+  - path: references/cli/trigger-schema-enrichment.md
+    classification: runbook
+    maintainer: Agentera CLI maintainers
+    source_checkout_root: .
+    working_directory: .
+    command: node packages/cli/dist/bin/agentera.js check validate capability-contract --format json
+  - path: references/meta/retained-reference-authority.yaml
+    classification: current
+    production_owner: { module: packages/cli/src/validate/retainedReferenceAuthority.ts, symbol: validateRetainedReferenceAuthority }
+    consumers:
+      - { kind: validator, module: packages/cli/src/validate/retainedReferenceAuthority.ts, symbol: validateRetainedReferenceAuthority, consumption: loads }
+  - path: references/cli/upgrade-repair-wording.md
+    classification: historical
+  - path: references/adapters/package-manifest-interface-model.yaml
+    classification: delete
+  - path: references/analysis/benchmark.md
+    classification: delete
+  - path: references/analysis/startup-measurement-contract.yaml
+    classification: delete
+  - path: references/cli/agent-ready-state-contract.yaml
+    classification: delete
+  - path: references/cli/audience-namespace-cli-migration.yaml
+    classification: delete
+  - path: references/cli/capability-instruction-structure.md
+    classification: delete
+  - path: references/cli/capability-tool-classification.yaml
+    classification: delete
+  - path: references/cli/parity-expected-actual-template.md
+    classification: delete
+  - path: references/cli/prime-consumer-compatibility.yaml
+    classification: delete
+  - path: references/cli/routing-execution-vocabulary.yaml
+    classification: delete
+  - path: references/cli/single-name-protocol.yaml
+    classification: delete
+  - path: references/meta/documentation-inventory.md
+    classification: delete
+  - path: skills/agentera/references/contract.md
+    classification: delete

package/bundle/skills/agentera/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: agentera
 description: >
-  One agent, one CLI, many capabilities. Per-capability prose lives in
+  One agent, one CLI, many capabilities. Per-capability instructions live in
   `packages/cli/src/capabilities/<name>/instructions.ts` and the runtime serves
-  it through `agentera prime --context <name> --format json`. Use this skill
+  it through `npx -y agentera@next prime --context <name> --format json`. Use this skill
   for /agentera and Agentera capability requests; bare `/agentera` runs the
-  agentera prime orientation dashboard path instead of a generic greeting.
+  prime orientation dashboard path instead of a generic greeting.
 version: "3.0.0"
 spec_sections: [1, 2, 3, 4, 5, 6, 11, 13, 18, 19, 20, 22, 23]
 capabilities:
@@ -25,63 +25,122 @@ capabilities:
 
 # agentera
 
-One agent, one CLI, many capabilities. The CLI is the routing brain — it owns
-project memory, capability prose, routing judgment, and the worker-spec contract.
-The host agent learns one contract: the CLI.
+One agent, one CLI, many capabilities. The CLI owns project memory,
+capability instructions, the deterministic routing tiers, and the worker-spec
+contract. The host owns open-ended semantic judgment from the trigger intent
+documentation after deterministic abstention; it learns that contract from the CLI.
 
 ---
 
 ## Bootstrap
 
-Run `agentera prime` for orientation. The JSON it returns is the complete
-contract — app status, state slices, attention items, next action, and the
-source contract that declares what's complete and what requires fallback.
+Run one pre-cutover `@next` call for orientation. It is read-only in fresh, v2,
+partially migrated, and v3 projects. A Git-root project with no `.agentera`
+state is `fresh_uninitialized`: `prime --context plan` is operable and its first
+`state plan create` is the sole initializer. Recognized v2 state returns the
+full entity-upgrade recovery; partial, corrupt, and unknown marker-absent state
+returns read-only recovery. V3 returns `ok` unless health is degraded. The JSON
+also returns bounded app status, state slices, attention, and startup
+availability.
 
 ```bash
-npx -y agentera prime
+npx -y agentera@next prime --context status --format json
 ```
 
+An `ok` outcome needs no fallback or second dashboard call. Follow an exact
+recovery command for other outcomes; every returned v3 command stays on
+`npx -y agentera@next`. Do not use bare or stable-channel CLI forms before
+stable promotion. For deeper read-only evidence, run
+`npx -y agentera@next doctor --format json`.
+
 For capability-specific startup context:
 
 ```bash
-npx -y agentera prime --context <capability> --format json
+npx -y agentera@next prime --context <capability> --format json
 ```
 
-This returns the capability's prose, declared read/write needs, artifact
-inventory, included/missing state, and fallback commands. Use it before
-reading the instructions module directly.
+This returns the capability's instructions, declared read/write needs, artifact
+inventory, and `capability_context.startup`. Check its `outcome` (`ok`,
+`degraded`, or `blocked`). The `availability` rows identify bounded included
+families and deferred families; use a deferred row's `detail_command` for
+detail. Use this response before reading the instructions module directly.
 
-For static routing guidance (agentera vs native tools):
+For static routing guidance (CLI vs native tools):
 
 ```bash
-npx -y agentera prime --guidance
+npx -y agentera@next prime --guidance
 ```
 
+### Upgrade from v2 to v3 development
+
+The preview is optional. Apply is one full command:
+
+```bash
+npx -y agentera@next upgrade --channel development --project "$PWD" --dry-run
+npx -y agentera@next upgrade --channel development --project "$PWD" --yes
+```
+
+Apply requires the complete v2 migration source to be tracked by Git and
+unchanged at `HEAD`. The boundary is one-way: there is no rollback, restore,
+non-Git, or partial cross-major workflow. Rerun the same apply command after an
+interruption; recovery continues forward internally.
+
 ---
 
 ## Routing
 
-The CLI routes. The host agent follows.
+The CLI first applies deterministic explicit and curated route tiers. For
+`semantic_required` requests, the LLM host classifies open-ended language from
+the CLI-supplied contract and context.
 
 | Request shape | Route |
 |---|---|
-| Bare `/agentera` | Run `agentera prime`. Render the dashboard from the data returned. Follow `next_action` to suggest the next capability. |
-| `/agentera <capability-name>` | Run `agentera prime --context <capability>`. Follow the capability's prose and contract. |
+| Bare `/agentera` | 1. Run `npx -y agentera@next prime --context status --format json` once. 2. Read `capability_context.instructions` and `capability_context.context.status_context`. 3. Render the dashboard from that bounded state and follow `next_action` to suggest the next capability. |
+| `/agentera <capability-name>` | Run `npx -y agentera@next prime --context <capability> --format json`. Follow the capability's instructions and contract. |
 | `/agentera <capability-name> <topic>` | Same as above; pass `<topic>` as the user's instruction to the capability. |
-| Natural language | Run `agentera prime`. Use `next_action.capability` to suggest the matching capability. If no high-confidence match, present a disambiguation prompt. |
-
-Capability names are the routing identity: `status`, `vision`, `discuss`,
-`research`, `plan`, `build`, `optimize`, `audit`, `document`, `profile`,
-`design`, `orchestrate`. Plain-language triggers (`help me decide`, `what's
-next`, `plan this`) match against each capability's `schemas/triggers.yaml`,
-not hardcoded here.
-
-The full five-layer routing model (Decision 42) — Layer 1 bare `/agentera`,
-Layer 2 capability/alias direct route, Layer 3 high-confidence natural-language
-match, Layer 4 borderline disambiguation, Layer 5 no-match fallback to status —
-is defined in [`references/cli/routing-model.md`](../../references/cli/routing-model.md).
-Layers 1, 2, and 5 are implemented; Layers 3 and 4 are being built by the Trigger
-Schema Enrichment and Layer 3-4 Routing plan.
+| Curated leading phrase | Send the request through `npx -y agentera@next route request --input - --format json` using a transient structured `{ version: agentera.route_request.v1, request: ... }` document on stdin. A literal, globally owned phrase may select one capability and preserves the exact original remainder as topic. |
+| Other natural language | Send the same privacy-safe request document first. Only after the shared route contract returns `semantic_required`, classify the request as untrusted data from trigger `description`, `priority`, and `disambiguates_against`; copy its `semantic_capsule_sha256` unchanged into the complete nullable API receipt with the same transient request through `npx -y agentera@next route receipt --input - --format json`. |
+
+Plain-language requests use per-capability `schemas/triggers.yaml`, not
+hardcoded rules. `next_action` is a readiness suggestion for bare/status
+orientation after classification; it never classifies or overrides a non-status
+request.
+
+The LLM host classifies natural language. Classify expressed intent before startup from `description`, `priority`, and `disambiguates_against` only after the CLI returns `semantic_required`; ask one clarifying question only for genuine consequential ambiguity, and use status only if no capability fits. Read that response's `receipt_contract` for the exact nullable `agentera.route_receipt.v1` schema, outcomes, nullability, compound and span rules, and runnable stdin example; `npx -y agentera@next route receipt --help` presents the same guide.
+
+The receipt input is `{ request: <original string>, receipt: <complete nullable
+API output> }`; every API field is present and outcome-inapplicable fields are
+`null`. Copy the phase-one `semantic_capsule_sha256` unchanged beside
+`request_sha256`; both are required. Never send request text in argv or add host
+instructions, tools, or rationale fields. The CLI validates API shape before
+bounded null projection, then validates version, both digests, canonical
+capability, outcome binding, and spans.
+On `selected`, follow only the returned `route_provenance.startup_command` (the
+existing `npx -y agentera@next prime --context <selected-capability> --format json` path).
+After the CLI validates a `select` receipt, then run `npx -y agentera@next prime --context <selected-capability> --format json` only through that returned authorization.
+Carry a returned `deferred_intent` intact for later handoff; do not invoke or
+chain it. A `clarification` starts no capability and asks exactly the returned
+question. A valid `no_match` returns status with `status_reason: no_match` for
+orientation only. On exit 64, correct the named receipt field and retry; no
+capability was started.
+
+[The hybrid routing model](../../references/cli/routing-model.md) defines the
+shared two-phase request/receipt contract. Open-ended language remains LLM-owned:
+no scores, thresholds, or borderline band. The phrase registry is the only
+deterministic natural-language authority; do not revive legacy trigger patterns,
+regexes, thresholds, or bands. `next_action` never classifies or overrides a
+request, and a compound remainder is preserved rather than silently chained.
+Decision mpulyomlyl supersedes Decision 76 only for this curated literal fast
+path.
+
+Run `npx -y agentera@next route evaluate --format json` to evaluate the frozen visible
+development and adversarial corpus. Its report binds the protocol, phrase
+authority, and shared-skill hashes, labels every result with a routing tier, and
+keeps request text out of output. It proves protocol conformance, not semantic
+generalization. It does not invoke a semantic host: deterministic and
+receipt-validation conformance and run-specific local p95 values are measured
+locally, while semantic model quality and latency are host-dependent and
+explicitly unmeasured.
 
 Handoff verbs:
 
@@ -96,27 +155,16 @@ Capability handoffs use glyph plus canonical name (e.g. `⧉ build`, `≡ plan`)
 
 ## Dashboard rendering
 
-When rendering the prime dashboard for the user, transform the CLI's source
-labels into the README-style layout. Do not paste raw `prime` JSON or raw
-labels (`mode:`, `profile:`, `health:`, etc.) as the briefing.
-
-```text
-┌─┐┌─┐┌─┐┌┐┌┌┬┐┌─┐┬─┐┌─┐
-├─┤│ ┬├┤ │││ │ ├┤ ├┬┘├─┤
-┴ ┴└─┘└─┘┘└┘ ┴ └─┘┴└─┴ ┴
-
-─── status ─────────────────────────────
-  [metric lines: health, todo, plan, objective, profile as available]
-  [1-2 sentence narrative read closing the status section]
-─── attention ──────────────────────────
-─── next ───────────────────────────────
-```
-
-Metrics first, narrative read inside `status`, then attention and next. The todo
-summary line uses `critical · degraded · normal · annoying` in the order prime
-emits them. Omit `attention` only when the source has no attention items.
-Always include the `⌂ status · <status>` marker below the dashboard, and ask
-for confirmation before invoking the suggested downstream capability.
+The prime dashboard rendering contract — template, field-by-field rules, output
+budget, attention-item ordering, exit marker — is owned by the status capability
+instructions. `npx -y agentera@next prime --context status --format json` returns the full
+`capability_context.instructions` body and the bounded
+`capability_context.context.status_context` state and one
+`capability_context.startup` availability projection in one response. Render
+from that capsule without a separate bare-prime call or raw artifact read. An
+`ok` outcome needs no second call; for deferred detail, use only that family's
+exact `detail_command`.
+Ask for confirmation before invoking a state-changing downstream capability.
 
 The first response in a fresh interaction delivers the brief and a free-form
 continuation prompt, not a native question menu — unless the user explicitly
@@ -131,7 +179,8 @@ Proceed/Cancel handoff.
 - NEVER push to remote repos without explicit user instruction
 - NEVER modify `.agentera/vision.yaml` or objective state during execution cycles (only the user or the owning capability may change these)
 - NEVER commit secrets or credentials to any artifact or file
-- Respect artifact path resolution: check `.agentera/docs.yaml` for path overrides before accessing any agent-facing artifact
+- For supported mutations, use the state writer; it resolves `.agentera/docs.yaml` path overrides and validates the published bytes
+- For direct access to other agent-facing artifacts, respect `.agentera/docs.yaml` path overrides
 </critical>
 
 ---
@@ -155,17 +204,88 @@ Proceed/Cancel handoff.
 
 ---
 
+## Artifact writes
+
+The CLI state writer is the canonical mutation path for entity-backed state.
+Every public record has `id` and `artifact`, lives in one writer-owned entity
+file, and is retrieved through bounded `list` or exact `get --id` commands. Do
+not edit `.agentera/entities/` directly. The writer assigns bare IDs, validates
+records, publishes atomically, and supports filesystem-safe previews.
+
+Discover the live contract before constructing a write:
+
+```bash
+npx -y agentera@next state decisions explain --format json
+npx -y agentera@next state decisions explain --verb update --format json
+```
+
+The same pattern applies to every writable artifact:
+
+```bash
+npx -y agentera@next state <progress|decisions|plan|health> explain --verb <verb> --format json
+```
+
+Common mutations:
+
+- `npx -y agentera@next state progress append --input <path|-> --format json`
+- `npx -y agentera@next state decisions append --input <path|-> --format json`
+- `npx -y agentera@next state decisions amend --id ID --base-sha256 HASH --input <path|-> --format json`
+- `npx -y agentera@next state decisions update --id ID ... --format json`
+- `npx -y agentera@next state plan create [--force] --input plan.yaml --format json`
+- `npx -y agentera@next state plan append [--plan PLAN_ID] --input task.yaml --format json`
+- `npx -y agentera@next state plan update --id TASK_ID [--plan PLAN_ID] --input task-patch.yaml --format json`
+- `npx -y agentera@next state plan set-status --id TASK_ID --status STATUS --format json`
+- `npx -y agentera@next state plan set-plan-status [--plan PLAN_ID] --status complete --format json`
+- `npx -y agentera@next state plan archive [--plan ID] [--force] --format json`
+- `npx -y agentera@next state plan replace --predecessor PREDECESSOR_ID --successor SUCCESSOR_ID --format json`
+- `npx -y agentera@next state health append --input audit.yaml --format json`
+- `npx -y agentera@next state todo create --input todo.yaml --format json`
+- `npx -y agentera@next state todo update --id ID --input todo-patch.yaml --format json`
+- `npx -y agentera@next state todo set-severity --id ID ... --format json`
+- `npx -y agentera@next state todo supersede --id ID ... --format json`
+- `npx -y agentera@next state todo resolve --id ID ... --format json`
+- `npx -y agentera@next state todo reopen --id ID ... --format json`
+
+TODO create input is a full YAML/JSON typed record. TODO update input is a
+patch: omitted fields remain unchanged and only `target_version`,
+`requirements`, `acceptance`, and `readiness` accept typed clears. Public TODO
+fields remain TODO.md-owned; readiness, dependencies, gates, evidence, and
+lifecycle metadata remain Agentera-owned. Lifecycle verbs are flag-only and do
+not accept record payloads.
+
+Plan create task numbers and dependency values are create-local symbolic
+ordinals inside one atomic input document; the writer removes them before
+publishing bare ten-letter plan and task envelope IDs. A legacy composite
+`header.id` is migration-only and is never a public selector. Post-publication
+task append/update payloads use only mutable task content and bare task IDs.
+Without `--force`, an open plan blocks creation. With exactly one canonical open
+predecessor, forced create archives that plan without changing task, evaluation,
+or completion history, then records its bare ID in the successor's
+writer-owned `previous_plan_archived` field. Forced archive preserves the same
+history. Multiple implicit open candidates reject before effects. When they
+block a reader or implicit writer, use the targeted replacement command only
+after canonical evidence names both roles; list order never assigns predecessor
+or successor roles.
+
+Add `--dry-run` to preview any mutation without publishing it. Artifacts not
+listed above are outside the typed writer contract and remain governed by their
+owning capability's instructions and safety rails.
+`npx -y agentera@next schema --format json` exposes the machine-readable writer operation matrix under
+`state_writer` and on each writable `artifact_schemas[*].write_interface`.
+
+---
+
 ## Artifact path resolution
 
-Before reading or writing any artifact, check if `.agentera/docs.yaml` exists.
-If it has an Artifact Mapping section, use the path specified for each canonical
-filename. If `.agentera/docs.yaml` doesn't exist or has no mapping for a given
-artifact, use the default layout:
+The state writer resolves entity storage itself. Before directly reading or
+writing an intentional singleton outside the writer contract, check whether
+`.agentera/docs.yaml` maps it to another path. If no mapping exists, use the
+default singleton layout:
 
 - Human-facing artifacts at the project root: `TODO.md`, `CHANGELOG.md`, `DESIGN.md`
-- Agent-facing artifacts in `.agentera/` as YAML: `progress.yaml`, `decisions.yaml`, `health.yaml`, `plan.yaml`, `docs.yaml`, `vision.yaml`, `objective.yaml`, `experiments.yaml`
+- Agent-facing singletons: `.agentera/docs.yaml` and `.agentera/vision.yaml`
 
-Do not silently bypass the CLI and read raw `.agentera/*.yaml` files first. If
+Do not silently bypass the CLI and read raw entity files first. If
 CLI state declares complete coverage, do not perform defensive raw artifact
-reads. Use raw artifact reads only as a last-resort fallback after CLI
-fallback commands fail or declare incomplete state.
+reads. Use raw artifact reads only as a last-resort after the applicable
+availability row's exact detail command fails or state declares corruption.

package/bundle/skills/agentera/capabilities/audit/schemas/artifacts.yaml

@@ -1,17 +1,19 @@
 ARTIFACTS:
   1:
     id: A1
-    artifact_id: health
+    artifact: health
     local_role: produces_and_consumes
     description: >-
       Codebase health assessment with findings, dimension grades, and trajectory.
       Audit writes audit entries with per-dimension grades, findings with
       severity and confidence scores, trend comparisons, and de facto
       architecture patterns. During evaluation startup, Audit consumes health
-      state through CLI `evidence_context` before raw health artifact fallback.
+      state through CLI `evidence_context`, then bounded `npx -y agentera@next state health
+       list --limit 20 --format json` and exact `state health get --id ID`.
+      Raw health reads are diagnostic-only for corruption or CLI-defect investigation.
   2:
     id: A2
-    artifact_id: vision
+    artifact: vision
     local_role: consumes
     description: >-
       Audit treats vision state as protected during evidence-context startup;
@@ -19,56 +21,62 @@ ARTIFACTS:
       instead of forcing a raw vision read.
   3:
     id: A3
-    artifact_id: decisions
+    artifact: decisions
     local_role: consumes
     description: >-
-      Audit consumes decision caveats through CLI `evidence_context` and the
-      listed `agentera decisions --format json` fallback before raw decisions artifact fallback.
-      Compacted decision caveats must be preserved rather than reconstructed.
+      Audit consumes decision caveats through CLI `evidence_context`, then
+      bounded `npx -y agentera@next state decisions list --limit 20 --format json` discovery
+       and exact `state decisions get --id ID` retrieval. Raw decision reads
+      are diagnostic-only for corruption or CLI-defect investigation. Compacted
+      decision caveats must be preserved rather than reconstructed.
   4:
     id: A4
-    artifact_id: todo
+    artifact: todo
     local_role: produces_and_consumes
     description: >-
       Audit reads this to avoid re-reporting known issues and writes to it
       with user confirmation when filing
       critical and warning findings. During evaluation startup, known TODO state is
-      consumed through CLI `evidence_context` before raw TODO artifact fallback.
+      consumed through CLI `evidence_context`; raw TODO reads are diagnostic-only
+      for corruption or CLI-defect investigation.
   5:
     id: A5
-    artifact_id: progress
+    artifact: progress
     local_role: consumes
     description: >-
       Audit consumes latest progress verification and progress caveats through
-      CLI `evidence_context` before raw progress artifact fallback.
+      CLI `evidence_context`, then bounded `npx -y agentera@next state progress list --limit
+       20 --format json` discovery and exact `state progress get --id ID`
+      retrieval. Raw progress reads are diagnostic-only for corruption or
+      CLI-defect investigation.
   6:
     id: A6
-    artifact_id: plan
+    artifact: plan
     local_role: consumes
     description: >-
       Audit consumes evaluation target and plan criteria through CLI
-      `evidence_context` before raw plan artifact fallback. The plan's Created date
+      `evidence_context` before any diagnostic-only raw plan read. The plan's Created date
       still provides the artifact-current-state baseline when that state is needed.
   7:
     id: A7
-    artifact_id: design
+    artifact: design
     local_role: consumes
     description: >-
       Audit treats design state as optional during evidence-context startup;
-      missing design caveats from CLI `evidence_context` are preserved before any raw
-      design artifact fallback.
+      missing design caveats from CLI `evidence_context` are preserved before any
+      diagnostic-only raw design read.
   8:
     id: A8
-    artifact_id: docs
+    artifact: docs
     local_role: consumes
     description: >-
       Audit reads this first to resolve project-local artifact mappings
       and checks the versioning convention for the version health dimension. During
       evaluation startup, docs state and version-boundary caveats are consumed through
-      CLI `evidence_context` before raw docs artifact fallback.
+      CLI `evidence_context` before any diagnostic-only raw docs read.
   9:
     id: A9
-    artifact_id: profile
+    artifact: profile
     local_role: consumes
     description: >-
       Audit consumes profile status and stale-profile caveats through CLI

package/bundle/skills/agentera/capabilities/audit/schemas/exit.yaml

@@ -4,8 +4,8 @@ EXIT_CONDITIONS:
     condition: complete
     description: >-
       All selected audit dimensions were assessed, findings were synthesized,
-      grades were assigned, HEALTH.md was updated, and the user was presented
-      with actionable results.
+      grades were assigned, the health artifact was updated, and the user was
+      presented with actionable results.
     exit_signal: complete
   2:
     id: E2