agentera 3.0.0-dev.22 → 3.0.0-dev.25

package/bundle/skills/agentera/schemas/artifacts/experiments.yaml

@@ -275,16 +275,17 @@ PUBLICATION:
     id: EP1
     operation: publish
     command: >-
-      agentera state experiments publish --objective OBJECTIVE_ID --number N
+      agentera state experiments publish --objective ID [--id ID]
       --input EXPERIMENT.yaml --format json
     description: >-
       The typed state writer is the mutation authority. It validates the
-      objective, identity, caller entry, existing projection, and final bytes
-      before assigning number and atomically publishing one experiment.
+      objective, identity, caller entry, and canonical entity state before
+      atomically publishing one experiment entity.
   2:
     id: EP2
-    identity: '<objective-id>/experiment:<non-negative-integer>'
-    cli_owned_fields: [number]
+    identity: bare_ten_letter_id
+    classification: experiments
+    cli_owned_fields: [id, artifact, objective]
     retry: byte_equivalent_identity_is_idempotent
     collision: same_identity_with_different_content_fails
     description: >-
@@ -292,14 +293,14 @@ PUBLICATION:
       pre-publication failures preserve active and archive projection bytes.
   3:
     id: EP3
-    projection: uniform_10_40_50
-    durable_archive: objective_scoped_immutable_full_detail
+    projection: bounded_entity_list
+    durable_archive: not_applicable
     description: >-
-      Publication validates and durably publishes the full experiment under
-      the objective directory before replacing the compacted projection. The
-      projection still retains 10 full entries and 40 one-line summaries.
+      Publication validates and durably publishes one immutable canonical
+      experiment entity. Bounded list output never compacts entity records.
   4:
     id: EP4
+    classification: legacy_migration_source_provenance
     archive_path: '.agentera/<objective-root>/<objective>/archive/experiments/<experiment-number>.yaml'
     canonical_objective_root: optimize
     readable_legacy_objective_roots: [optimera]
@@ -333,14 +334,13 @@ RETRIEVAL:
   1:
     id: ER1
     list: >-
-      agentera state experiments list --objective OBJECTIVE_ID [--limit N]
+      agentera state experiments list --objective ID [--limit N]
       [--cursor TOKEN] --format json
     get: >-
-      agentera state experiments get --objective OBJECTIVE_ID --number N
-      --format json
+      agentera state experiments get --id ID --format json
     description: >-
-      List returns newest-first objective-scoped identities from the bounded
-      projection and immutable archive. Get returns one exact identity.
+      List returns newest-first objective-scoped canonical entities. Get returns
+      one exact entity by bare ID.
   2:
     id: ER2
     cursor: opaque_snapshot_cursor
@@ -408,22 +408,22 @@ ARCHIVE:
 VALIDATION:
   1:
     id: EV1
-    rule: unique_experiment_numbers
+    rule: unique_entity_ids
     severity: error
     description: >-
-      Experiment numbers must be unique and sequential.
+      Experiment IDs must be unique project-wide and match the canonical pattern.
     checks:
-      - "All experiment numbers are unique across active and archived entries"
-      - "Experiment numbers are sequential starting from 0"
+      - "All experiment IDs are unique across canonical entities"
+      - "Every ID is ten lowercase letters"
   2:
     id: EV2
     rule: required_fields
     severity: error
     description: >-
-      Each full-detail experiment entry must have: number, date, label,
+      Each full-detail experiment entity record must have: date, label,
       hypothesis, method, change, metric, status, and conclusion.
     checks:
-      - "number is present and is a non-negative integer"
+      - "the envelope has id and artifact fields"
       - "date is present and matches YYYY-MM-DD HH:MM"
       - "label is present and non-empty"
       - "hypothesis is present and non-empty"

package/bundle/skills/agentera/schemas/artifacts/health.yaml

@@ -5,8 +5,9 @@
 # per-dimension grades (A-F), per-dimension findings with confidence, and
 # trend analysis against the prior audit.
 #
-# Structural pattern: UPPER_CASE groups with numbered entries and stable IDs,
-# following capability_schema_contract.yaml and protocol.yaml conventions.
+# The active authority is one health_audit entity per writer-owned file. The
+# numbered projection model below is retained only as an exact legacy migration
+# input schema; it is not an ordinary read or write contract after cutover.
 #
 # ── Field-by-field mapping: v1 HEALTH.md → v2 health.yaml ──
 #
@@ -53,10 +54,22 @@ meta:
     codebase health context.
   artifact_type: agent_facing
   path: ".agentera/health.yaml"
+  authority: legacy_migration_input_only
   producer: audit
   consumers: [document, status, audit, orchestrate, plan, build, vision]
   format: yaml
 
+ENTITY_AUTHORITY:
+  identity_fields: [id, artifact]
+  artifact: health
+  boundary: health_audit
+  retrieval:
+    list: agentera state health list --format json
+    get: agentera state health get --id ID --format json
+  mutation: agentera state health explain --verb append --format json
+  direct_file_edits: forbidden
+  legacy_schema_below: migration_input_only
+
 GROUP_PREFIXES:
   BUDGET: HB
   COMPACTION: HX

package/bundle/skills/agentera/schemas/artifacts/plan.yaml

@@ -4,8 +4,9 @@
 # why, constraints, scope boundaries, design approach, tasks with dependencies
 # and acceptance criteria, overall acceptance, and surprises.
 #
-# Structural pattern: UPPER_CASE groups with numbered entries and stable IDs,
-# following capability_schema_contract.yaml and protocol.yaml conventions.
+# The active authority uses one plan or plan_task entity per writer-owned file.
+# The aggregate model and ordinal fields below are retained only as an exact
+# legacy migration input schema; they are not ordinary post-cutover contracts.
 #
 # ── Field-by-field mapping: v1 PLAN.md → v2 plan.yaml ──
 #
@@ -47,10 +48,25 @@ meta:
     Consumed by capabilities that inspect or execute plan state.
   artifact_type: agent_facing
   path: ".agentera/plan.yaml"
+  authority: legacy_migration_input_only
   producer: [orchestrate, plan, build]
   consumers: [status, audit, orchestrate, plan, build]
   format: yaml
 
+ENTITY_AUTHORITY:
+  identity_fields: [id, artifact]
+  artifact: plan
+  boundaries: [plan, plan_task]
+  relationship: plan_task.record.plan is a bare plan ID
+  retrieval:
+    list: agentera state plan list --format json
+    get: agentera state plan get --id ID --format json
+    tasks_list: agentera state plan tasks list --plan-id ID --format json
+    task_get: agentera state plan tasks get --id ID --format json
+  mutation: agentera state plan explain --format json
+  direct_file_edits: forbidden
+  legacy_schema_below: migration_input_only
+
 GROUP_PREFIXES:
   BUDGET: PB
   HEADER: PH
@@ -103,10 +119,10 @@ HEADER:
     type: string
     required: true
     description: >-
-      Canonical plan lifecycle. Positional activity is derived from the
-      plan's location and is not persisted.
+      Canonical plan lifecycle. Open plans are active candidates, complete
+      plans satisfy every task, and archived plans are historical or abandoned.
     validation:
-      - "Must be one of: open, complete"
+      - "Must be one of: open, complete, archived"
   4:
     id: PH4
     field: reviewed
@@ -362,7 +378,7 @@ TASK:
 VALIDATION:
   1:
     id: PV1
-    rule: unique_task_numbers
+    rule: unique_entity_ids
     severity: error
     description: >-
       Task numbers must be unique within a plan and sequential.
@@ -380,7 +396,7 @@ VALIDATION:
     checks:
       - "level is present and is 'light' or 'full'"
       - "created is present and matches YYYY-MM-DD"
-      - "status is present and is 'open' or 'complete'"
+      - "status is present and is 'open', 'complete', or 'archived'"
       - "title is present and non-empty"
       - "what is present and non-empty"
       - "why is present and non-empty"
@@ -436,19 +452,21 @@ LIFECYCLE_CONTRACT:
       values:
         - open
         - complete
+        - archived
       meaning:
-        open: Work is unfinished, whether the plan is current or archived.
+        open: Work is active and unfinished.
         complete: Every task is complete.
+        archived: Historical or abandoned source; tasks may be incomplete or empty.
     position:
-      active: The plan occupies the docs-mapped current-plan path.
-      archived: The plan occupies the sibling archive directory.
-      persisted: false
+      active: A unique open entity plan supplies the default active selection.
+      archived: Archived lifecycle marks historical or abandoned entity plans; legacy archives occupy the sibling archive directory.
+      persisted: true
     execution:
       eligible: Only a plan at the current-plan path can supply executable work.
       archived: An archived plan is historical and non-executable regardless of status.
     forced_archive:
-      unfinished_status: open
-      effect: Move the plan to immutable history without claiming completion.
+      unfinished_status: archived
+      effect: Move the plan to immutable history without claiming completion or changing tasks.
   compatibility:
     legacy_read_window:
       scope: >-
@@ -456,7 +474,7 @@ LIFECYCLE_CONTRACT:
         active to open and completed to complete for artifacts produced by
         pre-canonical Agentera versions at the docs-mapped current-plan path
         or its sibling archive directory.
-      writers: Canonical writers and migrators must emit only open or complete.
+      writers: Ordinary create and status writers emit open or complete; only archive lifecycle and migration emit archived.
       removal_condition: >-
         Remove normalization only after the deterministic migration covers
         current plans, archives, fixtures, and bundled upgrade inputs, and
@@ -514,7 +532,7 @@ LIFECYCLE_CONTRACT:
         - .agentera/plan.yaml
         - plan.yaml
         - state.plan.
-        - artifact_id: plan
+        - artifact: plan
         - artifact: plan
         - active plan
         - archived plan
@@ -556,6 +574,7 @@ LIFECYCLE_CONTRACT:
       - packages/cli/src/cli/appContext.ts
       - packages/cli/src/cli/commands/state/plan*.ts
       - packages/cli/src/state/plan*.ts
+      - packages/cli/src/state/durability.ts
       - packages/cli/src/cli/commands/prime/*.ts
       - packages/cli/src/cli/capabilityContext/*.ts
       - packages/cli/src/cli/contracts/orientationState.ts
@@ -564,12 +583,14 @@ LIFECYCLE_CONTRACT:
       - packages/cli/src/eval/evalSkills.ts
     writers:
       - packages/cli/src/state/write/*.ts
+      - packages/cli/src/state/entityStorage.ts
       - packages/cli/src/cli/commands/state/write.ts
     migrators:
       - packages/cli/src/upgrade/migrateArtifacts*.ts
       - packages/cli/src/upgrade/upgradeOrchestrator.ts
       - packages/cli/src/upgrade/doctor.ts
       - packages/cli/src/cli/commands/prime/v1Migration.ts
+      - packages/cli/src/state/entityMigration*.ts
     schemas:
       - skills/agentera/schemas/artifacts/*.yaml
       - skills/agentera/capabilities/*/schemas/*.yaml

package/bundle/skills/agentera/schemas/artifacts/progress.yaml

@@ -4,8 +4,9 @@
 # in one development cycle: phase, work done, discoveries, verification,
 # next steps, and context envelope.
 #
-# Structural pattern: UPPER_CASE groups with numbered entries and stable IDs,
-# following capability_schema_contract.yaml and protocol.yaml conventions.
+# The active authority is one progress_cycle entity per writer-owned file. The
+# numbered projection model below is retained only as an exact legacy migration
+# input schema; it is not an ordinary read or write contract after cutover.
 #
 # ── Field-by-field mapping: v1 PROGRESS.md → v2 progress.yaml ──
 #
@@ -40,10 +41,22 @@ meta:
     capabilities that need recent work history and verification evidence.
   artifact_type: agent_facing
   path: ".agentera/progress.yaml"
+  authority: legacy_migration_input_only
   producer: build
   consumers: [document, status, audit, optimize, orchestrate, plan, build, vision, design]
   format: yaml
 
+ENTITY_AUTHORITY:
+  identity_fields: [id, artifact]
+  artifact: progress
+  boundary: progress_cycle
+  retrieval:
+    list: agentera state progress list --format json
+    get: agentera state progress get --id ID --format json
+  mutation: agentera state progress explain --verb append --format json
+  direct_file_edits: forbidden
+  legacy_schema_below: migration_input_only
+
 GROUP_PREFIXES:
   BUDGET: PB
   COMPACTION: PX

package/bundle/skills/agentera/schemas/artifacts/todo.yaml

@@ -3,16 +3,16 @@
 # Open issues and tasks maintained by build and audit. Severity-ranked
 # checklist of work to be done, resolved items, and deferred work.
 #
-# Note: TODO.md is a human-facing Markdown artifact. It remains at the
-# project root and is not migrated to YAML. This schema exists for validation
-# and CLI discovery consistency.
+# Marker-absent projects retain TODO.md as legacy authority. After durable
+# entity cutover, each item is authoritative in one shared-contract entity
+# file and `agentera state todo` renders the bounded human-facing view.
 
 meta:
   name: todo
   version: "1.0.0"
   description: >-
     Open issues and tasks. Produced by capabilities that file work or findings.
-    Human-facing: remains Markdown at project root.
+    Human-facing legacy aggregate before cutover; bounded entity view after cutover.
   artifact_type: human_facing
   path: "TODO.md"
   producer:

package/dist/capabilities/audit/instructions.js

@@ -1,4 +1,16 @@
 // Markdown instructions served via agentera prime --context audit --format json
 export const instructions = JSON.parse(String.raw `"# AUDIT\n\n**Integrity Navigation: Systematic Pattern Evaluation, Knowledge Tracing. Examine, Report, Advise.**\n\nCodebase health audit: multi-dimensional structural quality evaluation with evidence-based findings, confidence scores, and trajectory tracking. The retrospective counterpart to build's forward motion: is the codebase getting better or just bigger? Each invocation = one audit. Findings feed build's work selection via TODO.md.\n\nGlyph: **⛶** (protocol ref: SG3). Used in the mandatory exit marker.\n\nLean on \u0060evidence_context.source_contract\u0060 from \u0060agentera prime --context audit --format json\u0060 for evaluation startup. Do not re-encode its machine-readable rules in prose.\n\n---\n\n## State artifacts\n\n| Artifact | Role | Path |\n|----------|------|------|\n| health | produces_and_consumes | \u0060.agentera/health.yaml\u0060 |\n| todo | produces_and_consumes | TODO.md |\n| decisions | consumes | \u0060.agentera/decisions.yaml\u0060 |\n| progress | consumes | \u0060.agentera/progress.yaml\u0060 |\n| plan | consumes | \u0060.agentera/plan.yaml\u0060 |\n| docs | consumes | \u0060.agentera/docs.yaml\u0060 |\n| vision | consumes (protected) | \u0060.agentera/vision.yaml\u0060 |\n| design | consumes (optional) | DESIGN.md |\n| profile | consumes | Profile state from \u0060evidence_context.residual_risks\u0060 |\n\n### health.yaml shape\n\n\u0060\u0060\u0060yaml\naudits:\n  - number: 1\n    date: YYYY-MM-DD\n    dimensions: [architecture_alignment, test_health]\n    findings_summary: \"X critical, Y warnings, Z info\"\n    overall: stable\n    dimension_grades:\n      - dimension: architecture_alignment\n        grade: B\n    findings:\n      - severity: degraded\n        title: Finding title\n        confidence: 80\n        location: file:line\n        evidence: What was observed.\n        impact: Why this matters.\n        suggested_action: Specific fix or investigation.\n    trends: What improved, degraded, or changed.\n    patterns_observed: De facto architecture patterns.\n\u0060\u0060\u0060\n\nEvery finding MUST include \u0060location\u0060, \u0060evidence\u0060, \u0060impact\u0060, \u0060suggested_action\u0060, and \u0060confidence\u0060. WARN and FAIL findings MUST carry a reproducible anchor: \u0060location: <file>:<line>\u0060 (or \u0060not-applicable: <reason>\u0060). WARN rows with file:line citations SHOULD include \u0060verify_command\u0060 — the exact \u0060grep\u0060 or \u0060git show\u0060 invocation that reproduces the evidence at the cited line. Prose-only evidence for WARN/FAIL findings is incomplete.\n\n### Evidence context startup\n\nStart with \u0060agentera prime --context audit --format json\u0060. Use the returned \u0060evidence_context\u0060 for prior audit findings, known issues, decision caveats, protected-state boundaries, version checks, progress verification, and residual risks. If \u0060evidence_context\u0060 is absent or caveated for a state family you need, run the listed \u0060fallback_commands\u0060 first. Raw artifact reads are last-resort diagnostics, not normal startup behavior. Preserve caveats — they calibrate confidence, not approval to refresh state, read vision, edit objective state, or contact remotes.\n\n---\n\n## Workflow phases\n\nLinear: orient, select, assess, distill, report, connect.\n\n### Step 1: Orient\n\nUse \u0060evidence_context\u0060 for prior audits, decisions, TODO, and progress. Then project discovery: map directory structure, read dependency manifests, README, AGENTS.md, identify language/stack/build commands, \u0060git log --oneline -20\u0060.\n\nDerive change magnitude: \u0060git log --stat\u0060 on commits since the last audit timestamp to estimate total change volume. If the audit timestamp is unavailable, skip; default depth applies.\n\nList key structural facts (module boundaries, dependency patterns, test coverage gaps) in your response. These survive context compaction.\n\n**Exit-early stop condition**: if \u0060git diff\u0060 since the last audit timestamp shows no file changes, report \u0060─── ⛶ audit · complete ───\u0060 with \"no changes since last audit\" and stop.\n\n### Step 2: Select dimensions\n\nChoose dimensions based on the codebase and user request. Not every dimension applies; a 200-line CLI does not need the same audit as a monorepo.\n\n#### Available dimensions\n\n| Dimension | What it evaluates | When to include |\n|-----------|-------------------|-----------------|\n| Architecture alignment | Does the code match stated architecture? Pattern mismatches, module boundary violations, layering breaks. | \u0060.agentera/vision.yaml\u0060 or README describes architecture |\n| Pattern consistency | Are patterns used consistently? Naming, error handling, structure, abstractions. | Any codebase with 5+ modules or files |\n| Coupling health | Hidden dependencies, circular imports, god modules, inappropriate intimacy. | Any codebase with multiple modules |\n| Complexity hotspots | Functions too long, deeply nested, high fan-out, accumulated conditionals. | Any codebase |\n| Test health | Coverage gaps, test quality, test-to-code ratio, behavior vs implementation testing. | Project has tests |\n| Dependency health | Outdated deps, security advisories, unused deps, dep sprawl, pinning discipline. | Project has external dependencies |\n| Version health | Unreleased significant changes: \u0060feat\u0060/\u0060fix\u0060 commits since last version bump. | \u0060.agentera/docs.yaml\u0060 has a \u0060versioning\u0060 convention block |\n| Artifact freshness | Are state artifacts current relative to plan activity or recent development? Detects artifacts that should have been updated but weren't. | Plan context available or progress has entries |\n| Prose health | Do artifact entries respect writing rules? Verbosity overruns, abstraction creep, filler. | Project has 3+ artifact files |\n| Security hygiene | Hardcoded secrets, dangerous calls, injection patterns. Lightweight regex scan. | Any codebase |\n\n#### Depth guidance\n\nWhen change magnitude was derived in Step 1, apply advisory depth scaling:\n\n- **Light changes** (roughly ≤5 files, ≤200 lines since last audit): prioritize dimensions most relevant to changed areas. Skip dimensions with no intersection.\n- **Standard changes** (default): assess all applicable dimensions at normal depth.\n- **Heavy changes** (roughly ≥20 files or architectural-scope commits): assess all applicable dimensions and increase evidence depth.\n\nThese thresholds are guidelines, not hard rules. A 6-file change touching a critical security module warrants thorough depth.\n\n**User-specified dimensions**: audit only those. **Full audit or unspecified**: auto-select all applicable. Report selections before proceeding.\n\n### Step 3: Assess\n\nFor each selected dimension, run analysis and produce structured findings. Every finding MUST include: specific file and line references, quoted code or structural observation, explanation of why it matters, and confidence score (0-100, protocol: CS1-CS5).\n\nFor parallel analysis, use subagents — one per dimension. Each agent receives the dimension definition, relevant context files, and instructions to return findings matching the health.yaml finding shape.\n\n#### Version health\n\nOnly run if \u0060.agentera/docs.yaml\u0060 contains a \u0060versioning\u0060 convention block. Skip entirely if absent.\n\n- Read the \u0060versioning\u0060 convention to identify version file(s) and bump trigger rules\n- Run \u0060git log --oneline\u0060 to find \u0060feat\u0060 and \u0060fix\u0060 commits since the last modification date of the version file(s)\n- Count unbumped \u0060feat\u0060/\u0060fix\u0060 commits and note the age of the oldest one\n- Severity: warning (SF2) if 1-4 unbumped commits or age ≤ 7 days; critical (SF1) if 5+ unbumped commits or age > 7 days\n- If no \u0060feat\u0060/\u0060fix\u0060 commits since the last bump, this dimension is healthy with no finding\n\n#### Artifact freshness\n\nEvaluates whether state artifacts are current relative to plan activity or recent development.\n\n**With plan context** (\u0060.agentera/plan.yaml\u0060 has a created date and task history):\n\n- Read the plan's \u0060Created\u0060 date from its metadata\n- Identify dispatched capabilities by scanning task entries and progress cycle logs\n- For each dispatched capability, look up its expected artifacts in the staleness convention\n- Check each expected artifact's last modification: \u0060git log -1 --format=%aI -- <path>\u0060\n- An artifact is **stale** if its last modification predates the plan's creation date AND the owning capability was dispatched at least once during the plan\n- Severity: warning (SF2, confidence 70+). Plan-relative staleness carries causal evidence.\n- Artifacts that a capability reads but does not produce are not staleness candidates\n\n**Without plan context**:\n\n- Fall back to progress recency: an artifact is potentially stale if not modified since the most recent progress cycle entry date\n- If progress has no entries (fresh project), no staleness check applies\n- Severity: info (SF3, confidence 50-60). Advisory, not authoritative.\n\nStale artifact findings are reported like any other dimension finding but noted as context for the next plan cycle, not as blocking errors.\n\n#### Prose health\n\nEvaluate artifact prose quality against the three Self-Audit Protocol rules:\n\n- **Rule 1: Verbosity overrun** — approximate word count per entry. Entries exceeding their budget by 50%+ are findings.\n- **Rule 2: Abstraction creep** — scan each entry for ≥1 concrete anchor (file path, line number, commit hash 7+ hex chars, metric value with unit, identifier, direct quote). Entries with zero concrete anchors are findings.\n- **Rule 3: Filler accumulation** — flag entries with: meta-commentary about writing, hedging qualifiers, redundant transitions, self-referential process narration, filler introductions, summary preambles, excessive justification.\n\nUse \u0060agentera state decisions list --limit 20 --format json\u0060 for decision artifact prose context; preserve returned caveats. Read all project artifacts (\u0060.agentera/progress.yaml\u0060, \u0060.agentera/decisions.yaml\u0060, \u0060.agentera/plan.yaml\u0060, \u0060.agentera/health.yaml\u0060, TODO.md, CHANGELOG.md, \u0060.agentera/vision.yaml\u0060, DESIGN.md, \u0060.agentera/docs.yaml\u0060) when this dimension requires raw artifact prose inspection.\n\n#### Security hygiene\n\nLightweight regex-based scan for common security anti-patterns. Surface-level check, not a replacement for dedicated security analysis.\n\nScan for hardcoded secrets (API key patterns, token strings, private keys), dangerous function calls (\u0060eval()\u0060 on variables, \u0060exec()\u0060 with string concatenation, subprocess with unsanitized input), and injection patterns (SQL string concatenation, unsanitized shell construction). Use Grep across source files; exclude \u0060.git/\u0060, \u0060node_modules/\u0060, \u0060vendor/\u0060, \u0060__pycache__/\u0060.\n\n- Hardcoded secrets: warning (SF2, confidence 75-90)\n- Dangerous function calls: warning (SF2) or critical (SF1) depending on user input flow\n- Injection patterns: warning (SF2, confidence 60-80)\n\nEvery security hygiene finding MUST include a footer recommending dedicated security tools.\n\n### Step 4: Distill\n\nAfter analysis completes:\n\n1. **Filter**: discard findings below 50 confidence. Mark 50-69 as \"info\" (SF3) regardless of apparent severity.\n2. **Deduplicate**: merge by preference: (1) fullest context, (2) most evidence-rich dimension, (3) most recent. Preserve complementary evidence from discarded findings.\n3. **Cross-reference** against \u0060.agentera/decisions.yaml\u0060 and TODO.md (via \u0060agentera state decisions list --limit 20 --format json\u0060):\n   - Matches known decision → discard or downgrade to info (SF3)\n   - Matches known issue → \"already tracked\", skip\n   - Genuinely new → include at full severity\n4. **Grade** each dimension: **A** (no critical/warning), **B** (no critical, some warnings), **C** (1-2 critical or many warnings), **D** (multiple critical), **F** (pervasive critical).\n5. **Trajectory**: compare to prior audit — improving (VT12), degrading (VT13), stable. Calculate overall trajectory.\n\n### Step 5: Report\n\nRun \u0060agentera check lint --artifact health\u0060 on the draft entry before writing. Max 3 revision attempts. Flag with \u0060[post-audit-flagged]\u0060 if still failing.\n\nWrite the audit entry with \u0060agentera state health append --input PATH --format json\u0060 (or \u0060--input -\u0060 for YAML/JSON stdin). The writer assigns the audit number, validates the candidate and final compacted bytes, and applies shared retention before publishing. No reasoning in the artifact; the conversation preserves analysis, the artifact preserves conclusions.\n\nWhen updating existing entries, edit the specific YAML entry rather than rewriting unrelated history.\n\nCompaction is writer-owned; do not hand-compact the health artifact before or after the command.\n\n#### Report structure\n\n\u0060\u0060\u0060markdown\n## Audit N · YYYY-MM-DD\n\n**Dimensions assessed**: [list]\n**Findings**: X critical, Y warnings, Z info (N filtered by confidence)\n**Overall trajectory**: ⮉ improving | stable | ⮋ degrading vs Audit N-1\n**Grades**: Architecture [B] | Patterns [A] | Coupling [C] | Complexity [B] | Tests [D] | Deps [A] | Security [A]\n\n### [Dimension Name]: [Grade]\n\n#### ⇶ [Finding title], critical (confidence: N/100)\n#### ⇉ [Finding title], warning (confidence: N/100)\n#### ⇢ [Finding title], info (confidence: N/100)\n- **Location**: \u0060file:line\u0060 (or module/package)\n- **Evidence**: [quoted code or structural observation]\n- **Impact**: [what breaks, degrades, or risks]\n- **Suggested action**: [specific fix, investigation, or refactor]\n\n### Trends vs Audit N-1\n- **Improved**: [what got better and why]\n- **Degraded**: [what got worse and why]\n- **New findings**: [issues not present in prior audit]\n- **Resolved**: [prior findings no longer present]\n\n### Patterns Observed\n[De facto architecture patterns extracted — the \"what IS\" independent of what's stated.]\n\u0060\u0060\u0060\n\n### Step 6: Connect\n\nFeed actionable findings into the suite:\n\n1. **TODO.md**: for each critical finding not already tracked, offer to add under the appropriate severity section. Severity mapping (protocol: SM1-SM3): critical (SF1) → \u0060## ⇶ Critical\u0060 (SI1), warning (SF2) → \u0060## ⇉ Degraded\u0060 (SI2), info (SF3) → \u0060## ⇢ Annoying\u0060 (SI4). Each entry: \u0060- [ ] [finding description]\u0060. Get user confirmation before writing.\n2. **\u0060.agentera/vision.yaml\u0060**: if architecture has intentionally evolved past stated architecture, suggest updating via discuss.\n3. **Present findings** and ask if the user wants to: file to TODO.md, deliberate via discuss, deep-dive on a dimension, or investigate a specific finding.\n\n---\n\n## Safety rails\n\n<critical>\n\n- MUST NOT modify source code. Audit audits; other capabilities fix.\n- MUST NOT file findings to TODO.md without explicit user confirmation.\n- MUST NOT present speculative findings (confidence < 50) as definitive problems.\n- MUST NOT flag findings that contradict deliberate decisions documented in \u0060.agentera/decisions.yaml\u0060. A deliberate decision is an implementation of intent, not a finding. Discard or downgrade.\n- MUST NOT report issues already tracked in TODO.md as new findings.\n- MUST NOT flag subjective style preferences as findings unless they violate stated principles in \u0060.agentera/vision.yaml\u0060, AGENTS.md, or the decision profile.\n- MUST NOT run destructive commands or install packages. Read-only assessment.\n- MUST NOT mark, infer, or user-confirm decision satisfaction — only the user confirms final satisfaction.\n\n</critical>\n\n---\n\n## Exit signals\n\nReport one of these statuses at workflow completion (protocol refs: EX1-EX4).\n\nFormat: \u0060─── ⛶ audit · <status> ───\u0060 followed by a summary sentence.\nFor flagged, stuck, and waiting: add \u0060▸\u0060 bullet details below the summary.\n\n- **complete** (EX1): All selected dimensions assessed, findings synthesized, grades assigned, \u0060health\u0060 artifact updated, actionable results presented.\n- **flagged** (EX2): Completed with notable caveats — dimensions skipped due to missing tooling, confidence too low to grade reliably, or critical findings require urgent attention beyond audit scope.\n- **stuck** (EX3): Cannot complete — project inaccessible, required language tooling unavailable and manual analysis not feasible, or filing to TODO.md declined with no safe way to surface results.\n- **waiting** (EX4): The audit target is ambiguous — no project identified, codebase too incomplete to assess, or dimensions requested cannot be evaluated without additional information.\n\n---\n\n## Cross-capability integration\n\nAudit is the feedback loop: it tells build whether its work is making things better.\n\n### Feeds\n\n- **⧉ build**: Critical and warning findings filed to TODO.md become candidates for build's work selection. \"Patterns Observed\" helps build understand the codebase's de facto architecture when planning changes.\n- **❈ discuss**: When an architecture mismatch is found, suggest discuss before fixes begin.\n- **≡ plan**: When multiple related structural issues are found, suggest plan for a remediation plan.\n- **⎘ optimize**: When a dimension grade is poor and the improvement is measurable (test coverage, dependency count, complexity score), suggest optimize.\n\n### Reads\n\n- **⧉ build output**: \u0060.agentera/progress.yaml\u0060 tells audit what was built recently. Recent changes are higher-priority audit targets.\n- **❈ discuss output**: \u0060.agentera/decisions.yaml\u0060 explains why things are the way they are. Findings that contradict deliberate decisions are not findings.\n- **◰ design output**: DESIGN.md provides identity constraints that audit can check for consistency.\n\n### Informed by\n\n- **♾ profile**: The decision profile calibrates what \"healthy\" means for this user. High-confidence quality preferences weight the grading.\n\n### Getting started\n\n**First audit**: \u0060/agentera audit\u0060 runs a full audit across all applicable dimensions, bootstraps \u0060health\u0060 artifact. Review findings, file critical ones to TODO.md, then \u0060/agentera build\u0060 picks them up.\n\n**Periodic health checks**: run audit every 5-10 build cycles, or when a major feature was added, significant refactoring occurred, the codebase feels harder to work in, or before a major architectural decision.\n\nStaleness detection: \u0060agentera prime\u0060 marks a health audit stale when \u0060AGENTERA_AUDIT_MAX_AGE_DAYS\u0060 (default 30) or \u0060AGENTERA_AUDIT_MAX_CYCLES\u0060 (default 10) since the last audit is exceeded. Either axis exceeding its threshold triggers staleness; when progress is absent, time-only evaluation still applies.\n\n**Targeted audits**: specify dimensions to narrow scope — \u0060/agentera audit architecture coupling\u0060.\n\n**After an audit**: Good grades (A/B) — keep building. Mixed (C) — file criticals, deliberate on warnings. Poor (D/F) — consider pausing feature work; use discuss for priorities, then build for structural fixes.\n\n### Orchestrate evaluation\n\nWARN and FAIL findings used by orchestrate evaluation reports MUST carry \u0060citation: <file>:<line>\u0060 per row (schema: \u0060agentera.inspekteraEvaluationReport.v1\u0060 in \u0060references/cli/capability-instruction-contract.yaml#evaluator_handoff\u0060)."`);
-export default instructions;
+export default instructions
+    .replace(/## State artifacts[\s\S]*?## Workflow phases/, `## State artifacts
+
+Health audits, decisions, progress cycles, plans, and plan tasks use entity authority: each record has \`id\` and \`artifact\`, lives in one writer-owned entity file, and is available through bounded list and exact \`get --id ID\` commands. Begin with \`agentera prime --context audit --format json\`, then use its fallback commands. Discover health writes with \`agentera state health explain --format json\` and append through the typed entity writer; never edit entity paths directly. TODO, vision, design, docs policy, and profile retain their declared editorial or protected boundaries.
+
+Publish a completed audit with \`agentera state health append --input PATH --format json\`.
+
+## Workflow phases`)
+    .replaceAll("`.agentera/decisions.yaml`", "the decisions entity view")
+    .replaceAll("`.agentera/progress.yaml`", "the progress entity view")
+    .replaceAll("`.agentera/health.yaml`", "the health entity view")
+    .replaceAll("`.agentera/plan.yaml`", "the plan entity view")
+    .replace("The writer assigns the audit number, validates the candidate and final compacted bytes, and applies shared retention before publishing.", "The writer assigns a bare ID, validates the entity, and publishes one canonical file.");
 //# sourceMappingURL=instructions.js.map

package/dist/capabilities/audit/instructions.js.map

@@ -1 +1 @@
-{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../../../src/capabilities/audit/instructions.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,MAAM,CAAC,MAAM,YAAY,GAAW,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAA,uymBAAuymB,CAAC,CAAC;AACl2mB,eAAe,YAAY,CAAC"}
+{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../../../src/capabilities/audit/instructions.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,MAAM,CAAC,MAAM,YAAY,GAAW,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAA,uymBAAuymB,CAAC,CAAC;AACl2mB,eAAe,YAAY;KACxB,OAAO,CAAC,8CAA8C,EAAE;;;;;;mBAMxC,CAAC;KACjB,UAAU,CAAC,4BAA4B,EAAE,2BAA2B,CAAC;KACrE,UAAU,CAAC,2BAA2B,EAAE,0BAA0B,CAAC;KACnE,UAAU,CAAC,yBAAyB,EAAE,wBAAwB,CAAC;KAC/D,UAAU,CAAC,uBAAuB,EAAE,sBAAsB,CAAC;KAC3D,OAAO,CAAC,yIAAyI,EAAE,uFAAuF,CAAC,CAAC"}

package/dist/capabilities/build/instructions.js

@@ -1,5 +1,18 @@
 // Capability instructions for build
 // Served via `agentera prime --context build --format json`. RFC 2119 modal vocab.
 export const instructions = JSON.parse(String.raw `"# BUILD\n\n**Relentless Execution: Autonomous Loops Iterating Software. Evolve, Refine, Adapt**\n\nGlyph: \u29c9 (protocol ref: SG2).\n\nAn autonomous development loop that evolves any software project one cycle at a time. Decisions grounded in the user's decision profile. Continuity lives in files, not memory.\n\nEach invocation = one cycle. After completing a cycle (orient through log, exit signal reported), **stop**. The next cycle starts only when the user explicitly requests it or switches to \u2388 orchestrate for autonomous multi-task execution. A compaction-continue prompt is not consent to start a new cycle.\n\nWhen offering execution mode choices after plan completion, label \u0060build\u0060 as \"one task, then stop\" and \u2388 orchestrate as \"all tasks autonomously.\"\n\n---\n\n## State artifacts\n\nBuild reads project state and writes progress, TODO, and changelog. Artifact path resolution is owned by SKILL.md.\n\n| Artifact | Role | Path |\n|----------|------|------|\n| \u0060progress\u0060 | produces | \u0060.agentera/progress.yaml\u0060 |\n| \u0060todo\u0060 | produces_and_consumes | \u0060TODO.md\u0060 |\n| \u0060changelog\u0060 | produces_and_consumes | \u0060CHANGELOG.md\u0060 |\n| \u0060vision\u0060 | consumes | \u0060.agentera/vision.yaml\u0060 |\n| \u0060plan\u0060 | produces_and_consumes | \u0060.agentera/plan.yaml\u0060 |\n| \u0060health\u0060 | consumes | \u0060.agentera/health.yaml\u0060 |\n| \u0060decisions\u0060 | consumes | \u0060.agentera/decisions.yaml\u0060 |\n| \u0060docs\u0060 | consumes | \u0060.agentera/docs.yaml\u0060 |\n| \u0060design\u0060 | consumes | \u0060DESIGN.md\u0060 |\n| \u0060profile\u0060 | consumes | \u0060status.profile\u0060 |\n\n### progress.yaml\n\n\u0060\u0060\u0060yaml\ncycles:\n  - number: N\n    timestamp: YYYY-MM-DD HH:MM\n    type: feat\n    phase: build\n    what: One-line summary of what shipped.\n    inspiration: External source, if any.\n    discovered: Issues or ideas found.\n    verified: Observed output, N/A tag, or rationale.\n    next: Most valuable next work.\n    context:\n      intent: Why this cycle happened.\n      constraints: What had to stay true.\n      unknowns: What remains uncertain.\n      scope: What changed.\narchive: []\n\u0060\u0060\u0060\n\nThe \u0060verified\u0060 field is mandatory for every cycle entry.\n\n### CHANGELOG.md\n\nPublic-facing change history. Keep-a-changelog format. Build appends entries under \u0060## [Unreleased]\u0060 based on commit type: \u0060feat\u0060 \u2192 Added, \u0060refactor/chore\u0060 \u2192 Changed, \u0060fix\u0060 \u2192 Fixed. On version bumps, promote the Unreleased section to a versioned heading.\n\n---\n\n## Workflow phases: The cycle\n\n### Vision bootstrap\n\nIf the vision artifact is absent and \u26e5 vision is not installed, ask the user for project direction inline (one question: \"What does this software make possible?\"). Write the answer to \u0060.agentera/vision.yaml\u0060 and proceed to the cycle. If \u26e5 vision is installed and the artifact is absent, suggest \u26e5 vision and wait for confirmation. In all other cases, skip straight to the cycle.\n\n### The cycle\n\nStep markers: display \u0060\u2500\u2500 step N/8: verb\u0060 before each step.\nSteps: orient, select, research, plan, dispatch, verify, commit, log.\n\n### Step 1: Orient\n\nStart from the Build execution-context seam:\n\n\u0060\u0060\u0060bash\nagentera prime --context build --format json\n\u0060\u0060\u0060\n\nIf \u0060execution_context.source_contract.complete_for_execution_context\u0060 is true, use \u0060execution_context\u0060 and included \u0060capability_context.state\u0060 as normal startup context. Do not read raw plan, progress, TODO, docs, health, decisions, changelog, vision, profile, or design artifacts to re-check selected work, acceptance criteria, constraints, verification expectations, or scope caveats.\n\nIf \u0060execution_context\u0060 is incomplete or caveated, preserve every caveat in the cycle report and run the listed \u0060execution_context.fallback_commands\u0060 before any last-resort raw artifact diagnostic.\n\n#### Decision satisfaction authority\n\nWhen a cycle touches decision satisfaction, agents MAY mark provisional satisfaction with evidence only. Build MUST NOT mark or imply user-confirmed satisfaction; only the user confirms final satisfaction. Missing, compacted, open, provisional, or review-needed satisfaction state remains a caveat and review pressure in the cycle report \u2014 automation MUST NOT reconstruct hidden outcomes or claim it proved user intent.\n\n#### Context consumption\n\nConsume these \u0060execution_context\u0060 fields:\n\n- \u0060work_selection\u0060: selected task or no-plan/completed-plan mode\n- \u0060acceptance_criteria\u0060: exact criteria for this cycle\n- \u0060constraints\u0060: plan constraints and protected-action boundaries\n- \u0060verification_expectations\u0060: expected validation and latest progress evidence\n- \u0060artifact_update_requirements\u0060: plan, TODO, changelog, and progress update obligations\n- \u0060changelog_boundary\u0060: current public-history boundary or fallback\n- \u0060scope_boundary\u0060: artifact-family scope and conservative source-file scope\n\nUse \u0060status.profile\u0060 for profile summary; stale or missing profile is a caveat, not approval to refresh profile state.\n\n#### Project discovery\n\nOn cycle 1 or when unfamiliar with the project:\n\n- Map the directory structure\n- Read dependency manifests and README.md, AGENTS.md\n- Identify build/test/lint commands\n- Read key source files to understand architecture\n\nRun \u0060git log --oneline -20\u0060 for recent changes.\n\nBefore proceeding, list the 3-5 facts that determine this cycle.\n\n**Exit-early stop condition (plan-driven mode only)**: If \u0060.agentera/plan.yaml\u0060 has \u0060header.status: complete\u0060 and every task is complete, perform a **plan-completion sweep** before archiving. A plan with blocked, skipped, or otherwise incomplete tasks is not complete and MUST remain visible for replanning.\n\nSweep checklist:\n\n1. **progress.yaml aggregate cycle entry**: run \u0060agentera state progress append ... --format json\u0060 with a summary of the whole plan.\n2. **CHANGELOG.md plan-level entries**: verify \u0060## [Unreleased]\u0060 covers each completed task's user-facing impact.\n3. **TODO.md milestone advance**: mark each plan task as \u0060## \u2713 Resolved\u0060.\n4. **health.yaml cross-reference**: mention any resolved findings.\n\nAfter the sweep, run \u0060agentera state plan archive --format json\u0060 and report exit signal \u0060complete: plan finished\u0060. The writer preserves immutable archive history and removes the active plan.\n\n### Step 2: Pick work\n\nChoose **one** focused increment. No backlog; decide by reasoning about the gap between vision and codebase, weighted against known issues.\n\nEach cycle: **build toward the vision, or fix something broken?** Consult the decision profile. A critical bug trumps a new feature; a minor nit does not block progress.\n\n**Building toward vision**: Read codebase and vision artifact, identify the gap, pick the smallest increment closing the most valuable part.\n\n**Fixing issues**: Pick from TODO.md by severity (critical > degraded > annoying).\n\n**Optimization-shaped work**: suggest \u2398 optimize for measurable metrics and wait for confirmation instead of silently delegating.\n\nWrite a 1-2 sentence rationale. Scope down aggressively.\n\nCompose a Context block for this cycle: intent, constraints, unknowns, and scope. Keep it \u226480 words.\n\n**Plan unknowns consumption**: If the selected task comes from \u2261 plan and the plan carries \u0060unknowns:\u0060, note in the cycle context which unknowns affect this task and what the execution resolved. Carry unresolved unknowns forward in the progress entry's \u0060context.unknowns\u0060 field.\n\n**Decision gate**: After selecting work, use \u0060agentera state decisions list --limit 20 --format json\u0060 and check whether any \u0060exploratory\u0060 (DL3) entries relate to the selected work area. Preserve returned \u0060missing_fields\u0060, \u0060compacted\u0060, \u0060caveats\u0060, and \u0060satisfaction.review_needed\u0060 pressure in the cycle context. If an exploratory decision is found: flag the uncertain foundation, suggest \u2748 discuss to firm up the decision, and wait for confirmation. In autonomous mode, proceed with the work but log the risk.\n\n### Step 3: Seek inspiration\n\nSearch for relevant external approaches before planning.\n\n1. **Assess**: bug fixes rarely benefit from inspiration. New features, architecture decisions, and unfamiliar domains do.\n2. **Search**: 2-3 targeted web queries for libraries, articles, repos, or patterns.\n3. **Analyze**: read promising finds deeply.\n4. **Integrate**: fold applicable patterns into the plan.\n\n### Step 4: Plan\n\nWrite a concrete plan: what changes in which files, expected behavior, verification approach.\n\nRead files you plan to modify before committing to the plan.\n\nKeep small enough for one agent session. Too large? Split and save the rest.\n\n### Step 5: Dispatch\n\nSpawn an implementation sub-agent in a git worktree for isolation. Commit pending artifact changes before branching so the subagent starts from current state (\u0060git status --porcelain\u0060; if empty, skip). Use the runtime-native subagent surface (Task tool, \u0060@agent\u0060 descriptor, etc.) \u2014 never spawn by running \u0060agentera build\u0060 or other capability-name CLI commands.\n\nBefore spawning, run \u0060git rev-list --count origin/main..HEAD\u0060. If count > 0, do not merge the worktree branch \u2014 fetch the diff and apply it to the main checkout.\n\nSubagent prompt:\n\n\u0060\u0060\u0060\nYou are implementing a focused change for [project].\n\n## Task\n[The plan]\n\n## Constraints\n- Implement ONLY what the plan describes. No scope creep.\n- Follow existing code patterns and conventions.\n- Read the files you are modifying before changing them.\n- Verify the change works as described, then run the project's test/build suite.\n- If you encounter a bug unrelated to your task, note it but do not fix it.\n\u0060\u0060\u0060\n\n### Step 6: Verify\n\nVerification has two phases: structural and behavioral. Both MUST pass before commit.\n\n**Phase A, structural verification**:\n\n1. Check the diff: does it match the plan?\n2. Functional check: does the changed behavior work end-to-end?\n3. Run the project's verification suite (test/build/lint).\n\n**Phase B, behavioral verification gate**: observe the new behavior by running the project's primary entrypoint against real project state:\n\n- CLI tool: invoke with realistic arguments\n- Library/SDK: run a smoke driver\n- Web service: send a request to a production-shaped endpoint\n- Skill repo: \u0060agentera check verify eval skills --skill <name>\u0060\n\nIf verification fails: diagnose, spawn a fix agent, re-verify.\n\n**N/A path**: If the cycle has no runnable behavior change, use \u0060N/A: <tag>\u0060 from the allowlist: \u0060docs-only\u0060, \u0060refactor-no-behavior-change\u0060, \u0060chore-dep-bump\u0060, \u0060chore-build-config\u0060, \u0060test-only\u0060.\n\n### Step 7: Commit\n\nCommit with a conventional commit message: \u0060type(scope): summary\u0060.\n\nTypes: \u0060feat\u0060, \u0060fix\u0060, \u0060docs\u0060, \u0060refactor\u0060, \u0060chore\u0060, \u0060test\u0060. Include all related files. MUST NOT commit partial or broken work.\n\nIf the current task is a version bump: read \u0060.agentera/docs.yaml\u0060 for the \u0060versioning\u0060 section. Update every file in \u0060version_files\u0060.\n\n### Step 8: Log\n\n**Before writing**, run \u0060agentera check lint --artifact <artifact> --text \"<draft>\"\u0060 (or \u0060--file <path>\u0060) on the draft entry to check verbosity overruns, abstraction creep, and filler accumulation. Max 3 revision attempts. Flag with \u0060[post-audit-flagged]\u0060 if still failing.\n\n**Dual-write**: build maintains \u0060.agentera/progress.yaml\u0060 and root \u0060CHANGELOG.md\u0060.\n\n- **TODO.md**: add newly discovered open issues in severity bands with \u0060- [ ]\u0060. Move completed work to \u0060## \u2713 Resolved\u0060 as \u0060- [x]\u0060 with a resolution summary.\n- **progress.yaml**: run \u0060agentera state progress append --type TYPE --phase build --what TEXT --intent TEXT --verified TEXT --format json\u0060. The writer assigns the number, inserts newest-first, validates, compacts, and returns post-write state.\n- **CHANGELOG.md**: append a one-line entry under \u0060## [Unreleased]\u0060.\n\nProgress compaction is writer-owned. When a plan task closes, run \u0060agentera state plan set-status --task N --status complete --format json\u0060 rather than editing the plan directly. TODO.md Resolved compaction follows the same 10/40/50 cap via the validate-artifact hook or \u0060agentera check compact --mode fix\u0060.\n\nThen stop. One cycle complete.\n\n---\n\n## Safety rails\n\n<critical>\n\n- MUST NOT push to any remote. Local commits only.\n- MUST NOT bypass the project's test/lint/build suite.\n- MUST NOT modify git config or skip git hooks.\n- MUST NOT force push, amend published commits, or run destructive git operations.\n- MUST NOT add placeholder data or functionality.\n- MUST NOT modify files outside the project directory.\n- MUST NOT modify the vision artifact during a cycle \u2014 only during vision bootstrap.\n- One cycle per invocation. MUST NOT attempt multiple cycles.\n\n</critical>\n\n---\n\n## Handling blocked work\n\nIf blocked:\n\n1. Log blocker in TODO.md with context and decision needed\n2. Log skipped attempt in progress.yaml\n3. Pick different work and complete a full cycle on that instead\n\n---\n\n## Exit signals\n\nReport one of these statuses at workflow completion (protocol refs: EX1-EX4).\n\nFormat: \u0060\u2500\u2500\u2500 \u29c9 build \u00b7 <status> \u2500\u2500\u2500\u0060 followed by a summary sentence.\nFor flagged, stuck, and waiting: add \u0060\u25b8\u0060 bullet details below the summary.\n\n- **complete** (EX1): One full cycle completed. Work selected, implemented, verified, committed, artifacts updated.\n- **flagged** (EX2): Cycle completed but with notable issues: verification warnings, scope reduction, or discoveries suggesting next cycle may face blockers.\n- **stuck** (EX3): Cannot complete: the vision artifact is missing and bootstrap can't proceed, all work blocked, or verification suite broken.\n- **waiting** (EX4): No vision artifact and no codebase to infer direction, or user instruction too ambiguous.\n\nBefore reporting any status, inspect the last 3 entries in progress.yaml. If all 3 record failed cycles, stop, log the failure pattern to TODO.md, and surface to the user. Do not attempt a 4th consecutive cycle on the same failing problem.\n\nAfter reporting an exit signal, the cycle is over \u2014 the next cycle requires an explicit user request or \u2388 orchestrate.\n\n---\n\n## Cross-capability integration\n\nBuild is part of a twelve-capability suite.\n\n### Delegates to \u26e5 vision\n\nWhen \u26e5 vision is installed and the vision artifact doesn't exist, suggest \u26e5 vision for deep vision creation. If vision is NOT installed, the vision bootstrap (above) is the standalone fallback.\n\n### Delegates to \u2398 optimize\n\nWhen picked work is optimization-shaped (improving a measurable metric), delegate to optimize.\n\n### Uses \u2b1a research\n\nIn Step 3 (Seek inspiration), search for external approaches. For deeper analysis, use \u0060/agentera research <url>\u0060.\n\n### Reads \u267e profile output\n\nEvery cycle runs the effective profile. Confidence thresholds (CS1-CS5) determine which entries are strong constraints vs suggestions.\n\n### Uses \u2748 discuss for complex decisions\n\nWhen work selection surfaces a decision too complex for inline resolution, suggest \u2748 discuss.\n\n### Consumes \u2261 plan plans\n\nWhen the plan artifact exists with pending tasks, Step 2 reads the plan instead of reasoning from vision. Pick next pending task with satisfied dependencies. Update task status. When \u0060header.status: complete\u0060 and every task is complete, run the plan-completion sweep, archive the plan, and preserve lineage/evidence.\n\n### Reads \u25a4 document output\n\n\u0060.agentera/docs.yaml\u0060 provides artifact path resolution and versioning conventions.\n\n### Reads \u25f0 design output\n\n\u0060DESIGN.md\u0060 provides visual identity context respected when building user-facing features.\n\n### Audited by \u26f6 audit\n\n\u0060.agentera/health.yaml\u0060 findings become candidates for work selection. Run \u26f6 audit every 5-10 cycles.\n"`);
-export default instructions;
+export default instructions
+    .replace(/## State artifacts[\s\S]*?## Workflow phases: The cycle/, `## State artifacts
+
+Progress, plans, health audits, and decisions use entity authority: each record has \`id\` and \`artifact\`, lives in one writer-owned entity file, and is read through exact, list, or bounded CLI commands. Use \`agentera state <artifact> explain --format json\` before every supported mutation; never edit entity paths directly. Vision, docs policy, changelog, design, and profile remain intentional singletons.
+
+Build appends progress with \`agentera state progress append\`, advances a plan task with its bare ID through \`agentera state plan set-status --id ID\`, and reads context from \`agentera prime --context build --format json\` plus declared fallback commands. Root \`TODO.md\` and \`CHANGELOG.md\` remain capability-owned editorial files.
+
+## Workflow phases: The cycle`)
+    .replaceAll("--number N", "--id ID")
+    .replaceAll("--task N", "--id ID")
+    .replaceAll("progress.yaml aggregate cycle entry", "progress entity record")
+    .replaceAll("**Dual-write**: build maintains `.agentera/progress.yaml` and root `CHANGELOG.md`.", "Build records entity progress through the typed writer and maintains root `CHANGELOG.md` separately.")
+    .replaceAll("`.agentera/health.yaml` findings", "Health findings returned by `agentera state health list --format json`")
+    .replace("If `.agentera/plan.yaml` has `header.status: complete` and every task is complete", "If the selected plan entity is complete and every related task entity is complete");
 //# sourceMappingURL=instructions.js.map

package/dist/capabilities/build/instructions.js.map

@@ -1 +1 @@
-{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../../../src/capabilities/build/instructions.ts"],"names":[],"mappings":"AAAA,oCAAoC;AACpC,mFAAmF;AACnF,MAAM,CAAC,MAAM,YAAY,GAAW,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAA,26gBAA26gB,CAAC,CAAC;AACt+gB,eAAe,YAAY,CAAC"}
+{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../../../src/capabilities/build/instructions.ts"],"names":[],"mappings":"AAAA,oCAAoC;AACpC,mFAAmF;AACnF,MAAM,CAAC,MAAM,YAAY,GAAW,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAA,26gBAA26gB,CAAC,CAAC;AACt+gB,eAAe,YAAY;KACxB,OAAO,CAAC,yDAAyD,EAAE;;;;;;8BAMxC,CAAC;KAC5B,UAAU,CAAC,YAAY,EAAE,SAAS,CAAC;KACnC,UAAU,CAAC,UAAU,EAAE,SAAS,CAAC;KACjC,UAAU,CAAC,qCAAqC,EAAE,wBAAwB,CAAC;KAC3E,UAAU,CAAC,oFAAoF,EAAE,sGAAsG,CAAC;KACxM,UAAU,CAAC,kCAAkC,EAAE,wEAAwE,CAAC;KACxH,OAAO,CAAC,mFAAmF,EAAE,mFAAmF,CAAC,CAAC"}

package/dist/capabilities/discuss/instructions.js

@@ -2,5 +2,15 @@
 // Served via `agentera prime --context discuss --format json`. RFC 2119 modal vocab per D71.
 // Rewritten per Decision 82 (D80 six-section spine, D79 direct-contract, D81 voice delegation).
 export const instructions = JSON.parse(String.raw `"# DISCUSS\n\n**Reflective Engagement: Socratic Observation Nexus. Examine, Reason, Arbitrate**\n\nGlyph: **❈** (protocol ref: SG4). Structured deliberation via Socratic questioning. Decisions captured as artifacts the suite consumes. The user thinks; discuss asks the right questions, challenges assumptions, and ensures sound reasoning before action.\n\nOne deliberation per invocation. The user controls when it ends.\n\nVoice: adopt the conversational voice declared in the project's vision artifact \u0060identity.voice\u0060 field when available — do not improvise a separate personality. In Create mode before a vision exists, run with a neutral operational stance: describe behavior, not personality.\n\n---\n\n## State artifacts\n\nDiscuss reads prior decisions and profile for context, writes decisions as its primary product, and touches vision/objective/todo only as protected follow-through.\n\n| Artifact | Role | Source |\n|---|---|---|\n| decisions | produces/consumes | \u0060agentera state decisions list --limit 20 --format json\u0060 |\n| profile | consumes | \u0060deliberation_context.profile.path\u0060 (session start) |\n| vision, objective, todo | protected writes | \u0060protected_write_boundaries\u0060 (confirmation required) |\n| docs | consumes | \u0060deliberation_context.docs_mapping\u0060 (path resolution) |\n\n**Startup contract**: trust \u0060deliberation_context\u0060 and \u0060raw_artifact_read_policy\u0060 from \u0060agentera prime --context discuss --format json\u0060. Use the included state families first; run listed \u0060fallback_commands\u0060 before any raw decisions artifact read. Do not manually locate schemas or defensively raw-read state the CLI already serves. Artifact path resolution is owned by SKILL.md; visual-token families (VT/SI/EX/SG/PH/DL) by \u0060skills/agentera/protocol.yaml\u0060.\n\n### decisions.yaml\n\n\u0060\u0060\u0060yaml\ndecisions:\n  - number: N\n    date: \"YYYY-MM-DD\"\n    question: what was being decided\n    context: relevant constraints, triggers, or prior decisions\n    alternatives:\n      - name: Option A\n        description: Tradeoffs.\n        status: chosen\n      - name: Option B\n        description: Tradeoffs.\n        status: rejected\n    choice: what was chosen\n    reasoning: the key insight or tradeoff that resolved it\n    confidence: firm\n    feeds_into: [vision]\n\u0060\u0060\u0060\n\nPreserve the semantic top-level fields exactly (\u0060question\u0060, \u0060context\u0060, \u0060alternatives\u0060, \u0060choice\u0060, \u0060reasoning\u0060, \u0060confidence\u0060, \u0060feeds_into\u0060). Each alternative has \u0060name\u0060, \u0060status\u0060 (chosen or rejected), and optional \u0060description\u0060.\n\nNumbering, insertion order, validation, and compaction are writer-owned. Discover the live contract with \u0060agentera state decisions explain --verb append --format json\u0060; append with \u0060agentera state decisions append ... --format json\u0060.\n\n---\n\n## The deliberation loop\n\nConversational-loop shape: scratchpad plus per-turn question loop; no linear progression. The loop runs until the user picks Done.\n\n### Startup\n\n1. Read the served \u0060deliberation_context\u0060 from \u0060agentera prime --context discuss --format json\u0060 — prior decisions (avoid re-deliberation), profile path for high-confidence entries, docs mapping. If a needed family is missing or CLI state is incomplete, run the listed \u0060fallback_commands\u0060 before raw reads.\n2. If a topic was provided: name what reaching the end of this deliberation looks like — the decision to lock, the understood-shape, or the resolved tension. It fixes scope; every question serves it. Then read just enough codebase context to ask informed questions (not a research binge); acknowledge high-confidence profile entries so settled ground isn't re-litigated. Reflect understanding in 1-2 sentences, then ask the first question through the runtime-native question tool. For \u0060discuss <topic>\u0060, that question is the first user-facing action after the reflection.\n3. If no topic was provided: ask what's on their mind.\n\n### Per turn\n\nAsk every user-facing deliberation question through the runtime-native question tool; concrete tool availability belongs to the active host runtime. **One question per turn, no exceptions; every question includes a \u0060Done\u0060 option.** This overrides the routing layer's generic status/handoff question-tool gate. If the user asks for a recommendation, put a provisional recommendation in the question text, then offer accept / challenge / alternative / stop. Don't ask about \"depth\" or \"mode.\" Read the room.\n\nAfter each answer, show a short scratchpad:\n\n\u0060\u0060\u0060\n── scratchpad\n\nDecision: one-liner framing of what's being decided, updated as understanding evolves\n\nConstraints:\n▸ hard requirements that any option must satisfy\n\nRuled out:\n▸ what this decision is explicitly not about — fixed by the destination, not by sharpness\n\nOptions:\n▸ the options being considered · emerging pros/cons\n\nCrux: the key tension or uncertainty that needs to resolve for the decision to land\n\u0060\u0060\u0060\n\n5-8 bullets max. Drop items that stop being relevant.\n\n**Questions** should do one of these (≤15 words each): **Clarify** (\"When you say X, do you mean A or B?\"), **Dig deeper** (\"What's driving that?\"), **Reframe** (\"From the user's perspective instead?\"), **Challenge** (\"Is that actually true, or always been done?\"), **Connect** (\"That sounds like the same tension as Y.\"), **Unstick** (\"If you had to decide right now, what would you pick?\"), **Scope** (\"What's in and what's out?\"), **Constrain** (\"What must NOT happen?\"), **Tradeoff** (\"You can't have both X and Y. Which do you optimize for?\").\n\n**Steering**:\n- When more than one thread is open, fan across them before going deep on one — a tangent often hides the real crux off to the side.\n- When verbal exchange is slow on a visual/structural/API-shaped decision, ask the user to rough out a sketch, outline, or stub you can react to. You never produce the artifact — you ask for it and question what it reveals.\n\nWhen the decision involves code, read files or search the web for better questions — just enough context. When the profile has signal, skip settled ground.\n\n**Pushback discipline** — honest friction, don't let vague answers slide:\n- **Demand specifics.** \"What does 'better' look like? What would you measure?\"\n- **Name hidden assumptions.** \"That assumes X — based on something you've seen, or a hunch?\"\n- **Reframe imprecise framing.** \"I think the real question is Y, not X.\"\n- **Don't lower the bar.** \"Earlier you wanted Z. This gives half. Is half enough?\"\n\n**Pressure-test committed directions** — when the user leans toward a consequential direction, challenge before offering alternatives: (1) name 1-3 context-specific blind spots; (2) present serious alternatives with concrete win conditions; (3) make the call with explicit confidence (DL1-DL3).\n\n**Red-flag phrasing banned** (weakens the challenge): \"That sounds reasonable\", \"Either way is fine\", \"It depends\" without naming the variable, \"There is no wrong answer here\", \"Both options are valid\" when one conflicts with constraints.\n\n**Satisfaction authority** — when deliberation touches decision satisfaction, capture provisional satisfaction with evidence only. Only the user confirms final satisfaction. If decisions are compacted, missing satisfaction state, open, provisional, or review-needed, preserve the caveat and review pressure in the scratchpad or decision note instead of reconstructing hidden outcomes or claiming automation proved intent.\n\n### When the user picks \"Done\"\n\nProduce something actionable.\n\n1. **Summarize**: where we landed (2-3 sentences), key insight, confidence (DL1/DL2/DL3).\n2. **Readiness check**: name any remaining fog — what's still unphrasable or unverified. A decision is ready to land when the remaining unknowns are sharp answerable questions, not fog you can't yet phrase. If fog remains and you're calling it firm (DL1), surface that as a tension to resolve before landing; provisional (DL2) or exploratory (DL3) may land with the fog named. The user still controls when to land — this names the tax, doesn't block the exit.\n3. **Offer to capture and connect** (relevant only): Log it → new numbered decision entry (always offered); Feed into vision (direction/scope/principles); Feed into objective (what to optimize); File to todo (surfaced tech debt); Just wrap up.\n4. **Pre-write self-audit**: run \u0060agentera check lint --artifact decisions --text \"<DRAFT>\"\u0060 (or \u0060--file <PATH>\u0060) on the draft entry to catch verbosity overruns, abstraction creep, and filler. Max 3 revision attempts; flag \u0060[post-audit-flagged]\u0060 if still failing.\n5. **Write artifacts**: append the chosen decision, confidence, and rationale through \u0060agentera state decisions append ... --format json\u0060. Update satisfaction only through \u0060agentera state decisions update --number N ...\u0060. vision / objective / todo — brief follow-up, draft presented for approval per \u0060protected_write_boundaries\u0060.\n\n---\n\n## Safety rails\n\n<critical>\n\n- MUST NOT make the decision for the user. Discuss helps them think; it does not decide.\n- MUST NOT skip to implementation. The pull to *just do the work* is the signal you've reached deliberation's edge — surface it and hand off to build, plan, or research. Discuss deliberates; it does not deliver.\n- MUST NOT modify vision, objective, or todo artifacts (the \u0060protected_write_boundaries\u0060) without explicit user confirmation. Present drafts; get approval.\n- MUST NOT ask compound questions. One question per turn, with a Done option.\n- MUST NOT fabricate or imply user-confirmed final decision satisfaction. Only the user confirms final satisfaction; provisional satisfaction requires evidence. Preserve compacted, missing, open, or review-needed satisfaction as caveats.\n- MUST NOT ignore the decision profile. Acknowledge high-confidence entries; treat low-confidence entries as hypotheses.\n- MUST NOT dismiss a user's stated concern. Explore it.\n\n</critical>\n\n---\n\n## Exit signals\n\nReport one of these statuses at workflow completion (protocol refs: EX1-EX4).\n\nFormat: \u0060─── ❈ discuss · <status> ───\u0060 followed by a one-sentence summary. For flagged, stuck, and waiting, add a \u0060▸\u0060 (VT15) bullet below the summary naming what needs attention.\n\n- **complete** (EX1): Deliberation reached a conclusion the user acted on; artifacts written with approval; confidence captured.\n- **flagged** (EX2): Deliberation concluded but unresolved or provisional; significant tensions unresolved; or the conclusion contradicts prior decisions without acknowledgment.\n- **stuck** (EX3): Cannot proceed — topic requires inaccessible external research, or a protected write failed.\n- **waiting** (EX4): No topic provided and the user hasn't responded, or deliberation surfaced that a different capability is needed first and the user hasn't confirmed how to proceed.\n\n---\n\n## Cross-capability integration\n\nDiscuss is the deliberation layer.\n\n- **Feeds ⧉ build**: direction decisions captured in vision; decision entries whose \u0060feeds_into\u0060 names vision give build reasoning context.\n- **Feeds ⎘ optimize**: what-to-optimize decisions captured in the objective artifact, resolved via optimize's active-objective inference.\n- **Triggers ⬚ research**: during deliberation, if external research is needed — \"Sounds like we need to research X with ⬚ research?\"\n- **Informed by ♾ profile**: read at session start; high-confidence entries acknowledged, low-confidence treated as hypotheses.\n- **Feeds ♾ profile**: the decisions artifact is high-signal input for profile's extraction scripts.\n- **Feeds ≡ plan**: when deliberation concludes with a decision to build something, the natural next step is ≡ plan.\n- **Triggered by ⛶ audit**: when audits reveal an architecture mismatch, audit suggests ❈ discuss to think through the response.\n\n**When to invoke** (inverse of feeds-into): run \u0060/agentera discuss\u0060 before a build session (think through direction before vision), before an optimize session (which metric matters and why, before the objective artifact), after a research analysis (evaluate which recommendations to adopt), or standalone whenever something complex needs thinking through.\n"`);
-export default instructions;
+export default instructions
+    .replace(/## State artifacts[\s\S]*?## The deliberation loop/, `## State artifacts
+
+Decisions use entity authority: every decision, revision, and satisfaction record has \`id\` and \`artifact\` and lives in one writer-owned entity file. Start from \`agentera prime --context discuss --format json\`; use bounded \`agentera state decisions list\` and exact \`get --id ID\` reads. Discover writes through \`agentera state decisions explain --format json\` and mutate only through the typed entity writer. Never edit entity paths directly. Vision, objective, TODO, docs policy, and profile retain their own protected or singleton boundaries.
+
+Append with \`agentera state decisions append\`; update satisfaction with \`agentera state decisions update --id ID\` after checking the live explain contract.
+
+## The deliberation loop`)
+    .replaceAll("--number N", "--id ID")
+    .replaceAll("--task N", "--id ID")
+    .replace("new numbered decision entry", "new decision entity");
 //# sourceMappingURL=instructions.js.map

package/dist/capabilities/discuss/instructions.js.map

@@ -1 +1 @@
-{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../../../src/capabilities/discuss/instructions.ts"],"names":[],"mappings":"AAAA,yFAAyF;AACzF,6FAA6F;AAC7F,gGAAgG;AAChG,MAAM,CAAC,MAAM,YAAY,GAAW,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAA,gzYAAgzY,CAAC,CAAC;AAC32Y,eAAe,YAAY,CAAC"}
+{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../../../src/capabilities/discuss/instructions.ts"],"names":[],"mappings":"AAAA,yFAAyF;AACzF,6FAA6F;AAC7F,gGAAgG;AAChG,MAAM,CAAC,MAAM,YAAY,GAAW,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAA,gzYAAgzY,CAAC,CAAC;AAC32Y,eAAe,YAAY;KACxB,OAAO,CAAC,oDAAoD,EAAE;;;;;;yBAMxC,CAAC;KACvB,UAAU,CAAC,YAAY,EAAE,SAAS,CAAC;KACnC,UAAU,CAAC,UAAU,EAAE,SAAS,CAAC;KACjC,OAAO,CAAC,6BAA6B,EAAE,qBAAqB,CAAC,CAAC"}

package/dist/capabilities/document/instructions.js

@@ -1,4 +1,12 @@
 // Markdown instructions served via agentera prime --context document --format json
 export const instructions = JSON.parse(String.raw `"# DOCUMENT\n\n**Documentation Origin: Knowledge Unified, Methodology Enforced, Notation Traced. Encode, Record, Archive**\n\nOwns the docs-first workflow (DTC: Document, Test, Code): document intended behavior before tests and code, generate docs for existing code, maintain docs as projects evolve, verify docs against implementation.\n\nGlyph: **▤** (protocol ref: SG8). Used in the mandatory exit marker.\n\nTwo modes: **create** and **update**. Context-detected: no feature yet = intent-first; code exists = explore and generate.\n\nLean on \u0060closeout_context.source_contract\u0060 from \u0060agentera prime --context document --format json\u0060 for closeout synchronization startup. Do not re-encode its machine-readable rules in prose. Artifact path resolution is owned by SKILL.md.\n\n---\n\n## State artifacts\n\nDocument writes and reads the docs index and individual doc files across the project.\n\n| Artifact | Role | Path |\n|----------|------|------|\n| \u0060docs\u0060 | produces_and_consumes | \u0060.agentera/docs.yaml\u0060 |\n| \u0060todo\u0060 | produces_and_consumes | \u0060TODO.md\u0060 |\n| \u0060changelog\u0060 | consumes | \u0060CHANGELOG.md\u0060 |\n| \u0060vision\u0060 | consumes | \u0060.agentera/vision.yaml\u0060 |\n| \u0060progress\u0060 | consumes | \u0060.agentera/progress.yaml\u0060 |\n| \u0060decisions\u0060 | consumes | \u0060.agentera/decisions.yaml\u0060 |\n| \u0060health\u0060 | consumes | \u0060.agentera/health.yaml\u0060 |\n| \u0060design\u0060 | consumes | \u0060DESIGN.md\u0060 |\n| \u0060profile\u0060 | consumes | \u0060status.profile\u0060 |\n\n### docs.yaml shape\n\n\u0060\u0060\u0060yaml\nlast_audit: YYYY-MM-DD\nconventions:\n  doc_root: .\n  style: technical, concise\n  auto_gen: []\n  version_files: []\n  semver_policy:\n    feat: minor\n    fix: patch\n    docs/chore/test: no bump\nmapping:\n  - artifact: VISION.md\n    path: .agentera/vision.yaml\n    producers: [vision, build]\nindex:\n  - document: README\n    path: README.md\n    last_updated: YYYY-MM-DD\n    status: current\n\u0060\u0060\u0060\n\n### Closeout context\n\nStart from \u0060agentera prime --context document --format json\u0060. When \u0060closeout_context.source_contract.complete_for_closeout_context\u0060 is true, use it for artifact mappings, version policy, TODO blockers, changelog boundary, progress evidence, and benchmark evidence. If incomplete, preserve every caveat and run the listed \u0060fallback_commands\u0060 before any raw artifact read. Raw artifacts are write targets or last-resort diagnostics, not normal closeout inputs.\n\n---\n\n## Workflow phases\n\nMode-split: detect context first, then run the matching workflow.\n\n| Context | Mode |\n|---------|------|\n| No \u0060.agentera/docs.yaml\u0060 exists | First-run survey |\n| Feature doesn't exist yet, user wants to document intent | Intent-first |\n| Code exists, docs don't | Explore-and-generate |\n| Docs exist, may be stale | Update-and-verify |\n| Broad \"audit the docs\" / \"are docs up to date\" | Update-and-verify |\n\nFor final documentation or metadata synchronization, follow the closeout context startup contract above before reading TODO, docs, changelog, or progress artifacts directly.\n\n### First-run survey (convention detection)\n\nStep markers: display \u0060── step N/3: verb\u0060 before each step.\nSteps: explore, propose, write.\n\n### Step 1: Explore structure\n\nDetect documentation conventions:\n\n1. **Doc root**: check docs/, doc/, documentation/, wiki/, or root. Default to root.\n2. **Existing docs**: README, AGENTS.md, CONTRIBUTING.md, API docs, guides\n3. **Auto-generated docs**: TypeDoc, Storybook, OpenAPI/Swagger, GoDoc, Rustdoc, Javadoc. Record each with output path.\n4. **Style**: infer tone, structure patterns, formatting conventions from existing docs\n5. **Version files**: package.json, Cargo.toml, pyproject.toml, etc. Note files and current values. None found = omit versioning from \u0060.agentera/docs.yaml\u0060.\n\n### Step 2: Propose conventions\n\nDraft \u0060.agentera/docs.yaml\u0060 from the artifact schema and observed repository conventions:\n\n1. **Conventions**: doc_root, style, auto_gen from observations. If version files found, populate \u0060version_files\u0060 and ask about semver policy. No version files = omit block.\n2. **Artifact mapping**: paths consistent with project's doc organization\n3. **Index**: all discovered docs (auto-generated = \u0060generated\u0060, existing = \u0060current\u0060)\n\nPresent for user approval. If artifacts exist at root but mapping places them elsewhere, offer to relocate via \u0060git mv\u0060; if declined, update mapping to match actual locations.\n\n### Step 3: Write docs.yaml\n\n**Before writing**, run \u0060agentera check lint --artifact docs --text \"<draft>\"\u0060 (or \u0060--file <path>\u0060) on the draft entry to check verbosity overruns, abstraction creep, and filler accumulation. Max 3 revision attempts. Flag with \u0060[post-audit-flagged]\u0060 if still failing.\n\nWrite the approved convention map to \u0060.agentera/docs.yaml\u0060. After writing, proceed to the originally requested mode, or stop if the survey was the entire request.\n\n### Intent-first mode (docs before code)\n\nDocs-first workflow: document what a feature SHOULD do before building. Docs become the spec.\n\nStep markers: display \u0060── step N/4: verb\u0060 before each step.\nSteps: understand, write, update, suggest.\n\n### Step 1: Understand the intent\n\nBrief conversation (2-4 questions): what, who reads it, what format, what detail level.\n\nRead \u0060.agentera/vision.yaml\u0060 for direction/audience. Use decision profile per protocol confidence scale (CS1-CS5) for doc style preferences if available.\n\n### Step 2: Write the documentation\n\nWrite docs in the appropriate location: project-level (README, AGENTS.md) to standard paths, feature docs to the project's docs directory, inline docs to source files.\n\n**Principles**: follow \u0060.agentera/docs.yaml\u0060 style conventions, infer details from existing docs. Write as intended steady state (evergreen, non-temporal). Primary audience first. Concrete examples. DRY across doc files.\n\nWhen presenting drafts, introduce what you wrote and why: what choices you made, what you left out on purpose, what you'd want feedback on. Present draft for approval before writing.\n\n### Step 3: Update docs index\n\nAdd or update the relevant entry in \u0060.agentera/docs.yaml\u0060:\n\n- Document name and path\n- Date written\n- Status: \u0060current\u0060\n\n**Before writing**, run \u0060agentera check lint --artifact docs --text \"<draft>\"\u0060 (or \u0060--file <path>\u0060) to check verbosity overruns, abstraction creep, and filler accumulation. Max 3 revision attempts. Flag with \u0060[post-audit-flagged]\u0060 if still failing.\n\n### Step 4: Suggest next steps\n\n- Feature docs: suggest ≡ plan to plan implementation\n- Standalone docs: suggest update-and-verify mode later for verification\n\n### Explore-and-generate mode (docs for existing code)\n\nCode exists, docs don't. Read codebase and generate.\n\nStep markers: display \u0060── step N/4: verb\u0060 before each step.\nSteps: explore, gaps, generate, update.\n\n### Step 1: Explore\n\n1. Map directory structure, read dependency manifests\n2. Read existing docs to see what's already documented\n3. Read key source files: architecture, public APIs, patterns\n4. Read \u0060.agentera/vision.yaml\u0060 for direction/audience. Use \u0060agentera state progress list --limit 20 --format json\u0060 and \u0060agentera state decisions list --limit 20 --format json\u0060 for recent project context; carry returned \u0060missing_fields\u0060, \u0060compacted\u0060, \u0060caveats\u0060, and \u0060satisfaction.review_needed\u0060 pressure into documentation scope instead of raw-reading missing historical context.\n5. \u0060git log --oneline -20\u0060 for context\n\n**Exit-early stop condition**: If \u0060.agentera/docs.yaml\u0060 exists with coverage at 100% and no files have changed since the last document audit (\u0060git log --since\u0060 the last audit date shows no changes), report exit signal \u0060complete\u0060 (EX1): documentation current, and stop.\n\n### Step 2: Identify gaps\n\nCompare what exists against what should be documented: README.md accuracy, AGENTS.md presence, API docs, CLI docs with usage, configuration docs, architectural decision docs.\n\n### Step 3: Generate\n\nWrite docs for gaps, prioritized: (1) README, (2) AGENTS.md, (3) API/CLI docs, (4) architecture docs. Follow \u0060.agentera/docs.yaml\u0060 style conventions.\n\nWhen presenting drafts, introduce what you wrote and why: what you learned from the code, what design choices the doc reflects, what you're less sure about. Present drafts for approval.\n\n### Step 4: Update docs index\n\nCreate or update \u0060.agentera/docs.yaml\u0060 with all items. Edit specific YAML entries when updating status/dates. If \u0060.agentera/docs.yaml\u0060 doesn't exist, run first-run survey first.\n\n**Before writing**, run \u0060agentera check lint --artifact docs --text \"<draft>\"\u0060 (or \u0060--file <path>\u0060) to check verbosity overruns, abstraction creep, and filler accumulation. Max 3 revision attempts. Flag with \u0060[post-audit-flagged]\u0060 if still failing.\n\n### Update-and-verify mode (audit-driven)\n\nDocs exist but may be out of sync with implementation.\n\nStep markers: display \u0060── step N/4: verb\u0060 before each step.\nSteps: discover, verify, report, update.\n\n### Step 1: Discover\n\nIdentify all doc files: root (README, AGENTS.md, etc.), directories (docs/, .github/), config comments. Read \u0060.agentera/docs.yaml\u0060 for current index. Track auto-generated docs as \u0060generated\u0060. Skip node_modules/, .git/, vendor/.\n\n### Step 2: Verify\n\nCheck each doc file on two dimensions — content accuracy and prose quality.\n\n**Content accuracy** (per doc file):\n\n- **Gaps**: documented features/APIs/behaviors that don't exist in code\n- **Staleness**: changed signatures, removed features, outdated setup instructions\n- **Redundancies**: duplicated content across doc files\n- **Misalignments**: docs contradict actual code behavior\n\nFor each finding: quote the doc section, reference code location (file:line), explain the discrepancy.\n\n**Prose quality**: run \u0060agentera check lint --artifact docs --file <path>\u0060 on each tracked doc. Report any \u0060[post-audit-flagged]\u0060 markers from prior runs. Skip entries with \u0060generated\u0060 or \u0060missing\u0060 status.\n\n### Step 3: Report and fix\n\nSurface findings at standard severity levels (protocol: SF1-SF3):\n\n- **critical** (SF1): doc section contradicts code, or instructions that would cause user errors\n- **warning** (SF2): verbosity above budgets, abstraction creep, accumulated filler patterns, pre-existing \u0060[post-audit-flagged]\u0060 markers\n- **info** (SF3): minor style issues, single banned pattern in an otherwise clean entry\n\nFor each finding, offer to: fix the doc, file to TODO.md (code is wrong per the docs-first workflow), or skip.\n\n### Step 4: Update docs index\n\nUpdate \u0060.agentera/docs.yaml\u0060 with:\n- Audit date\n- Status changes (■ current / ▣ stale / □ missing)\n- Coverage numbers\n\n**Before writing**, run \u0060agentera check lint --artifact docs --text \"<draft>\"\u0060 (or \u0060--file <path>\u0060) to check verbosity overruns, abstraction creep, and filler accumulation. Max 3 revision attempts. Flag with \u0060[post-audit-flagged]\u0060 if still failing.\n\n---\n\n## Safety rails\n\n<critical>\n- MUST NOT write or modify documentation without explicit user approval. Present drafts and get confirmation.\n- MUST NOT update docs to match broken code. Per the docs-first workflow, if code diverges from docs, the code is wrong. Document the divergence as an issue in TODO.md.\n- MUST NOT write temporal documentation (changelogs, \"we recently added...\"). Write as the intended steady state: evergreen and non-temporal.\n- MUST NOT duplicate information across doc files. Keep it DRY: reference, don't repeat.\n- MUST NOT write generic filler documentation. Every sentence MUST be specific to this project. If there's nothing useful to say about a section, omit it.\n- MUST NOT skip the verification step in update mode. Every doc claim MUST be checked against code.\n- MUST NOT auto-generate documentation without reading the code it describes. Understanding precedes documentation.\n- MUST NOT mark or imply user-confirmed decision satisfaction — only the user confirms final satisfaction.\n</critical>\n\n---\n\n## Exit signals\n\nReport one of these statuses at workflow completion (protocol refs: EX1-EX4).\n\nFormat: \u0060▤ document · <status>\u0060 followed by a summary sentence.\nFor flagged, stuck, and waiting: add \u0060▸\u0060 bullet details below the summary.\n\n- **complete** (EX1): Documentation was written, updated, or audited successfully; docs index is current, and all drafted content received user approval before writing.\n- **flagged** (EX2): Documentation tasks completed but gaps remain (e.g., some doc files could not be verified against code, coverage is partial, or the audit found issues that were logged but not yet fixed).\n- **stuck** (EX3): Cannot proceed because a user approval step was declined, a required artifact is missing or inaccessible, or a contradicting doc-vs-code situation requires a decision the capability should not make autonomously.\n- **waiting** (EX4): The documentation intent is unclear: the target audience, format, or scope of what to document was not specified and cannot be inferred from the codebase or the docs index.\n\n---\n\n## Cross-capability integration\n\nDocument is part of a twelve-capability suite. It is the documentation layer and owns the docs-first workflow.\n\n### Feeds\n\n- **≡ plan**: In the docs-first workflow, document writes intent docs first, then plan breaks them into implementation tasks. The docs become the spec that plan's acceptance criteria verify against. When the plan includes documentation tasks, document handles them.\n- **⧉ build**: When document writes intent-first docs for a feature that doesn't exist yet, build implements code to match those docs. The docs are the target state; if code diverges from docs, the code is wrong per the docs-first workflow.\n- **♾ profile**: Documentation decisions (what to document, how, at what depth) are signal for profile's extraction scripts.\n\n### Informed by\n\n- **❈ discuss**: \u0060.agentera/decisions.yaml\u0060 explains why things are the way they are. Document reads it to understand project context.\n- **⛶ audit**: Health findings may include documentation gaps. Audit's architecture alignment dimension can surface undocumented modules or APIs.\n- **⛥ vision**: \u0060.agentera/vision.yaml\u0060 sets the project's direction and audience. Document reads it to understand who the documentation is for and what tone to use.\n- **◰ design**: \u0060DESIGN.md\u0060 provides visual identity context that document respects when generating user-facing documentation, ensuring docs match the project's declared aesthetic and voice.\n- **♾ profile**: The decision profile calibrates documentation style: the user's preferences for detail level, tone, format, and which docs they consider essential.\n\n### Getting started\n\n**Docs-first workflow**: document before building.\n1. ▤ document: write intent docs for the feature (what it should do, how it should work)\n2. ≡ plan: plan the implementation with acceptance criteria derived from the docs\n3. ⧉ build: build to match the docs\n4. ▤ document: update-and-verify mode to verify docs still match implementation\n\n**Document existing code**: explore-and-generate mode reads the codebase and writes docs for what exists. Review generated docs for accuracy and completeness.\n\n**Project bootstrap**: ⛥ vision → ▤ document (README, AGENTS.md) → ≡ plan → ⧉ build.\n"`);
-export default instructions;
+export default instructions
+    .replace(/## State artifacts[\s\S]*?## Workflow phases/, `## State artifacts
+
+Documentation inventory entries, progress cycles, decisions, and health audits use entity authority: every record has \`id\` and \`artifact\`, lives in one writer-owned entity file, and is read through bounded list or exact \`get --id ID\` commands. Start from \`agentera prime --context document --format json\` and use declared fallbacks. Discover documentation-inventory mutations with \`agentera state docs explain --format json\` and use the typed entity writer; never edit entity paths directly. The docs mapping and policy, vision, changelog, design, and profile remain intentional singletons.
+
+## Workflow phases`)
+    .replaceAll("`.agentera/decisions.yaml`", "the decisions entity view")
+    .replaceAll("`.agentera/progress.yaml`", "the progress entity view")
+    .replaceAll("`.agentera/health.yaml`", "the health entity view");
 //# sourceMappingURL=instructions.js.map

package/dist/capabilities/document/instructions.js.map

@@ -1 +1 @@
-{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../../../src/capabilities/document/instructions.ts"],"names":[],"mappings":"AAAA,mFAAmF;AACnF,MAAM,CAAC,MAAM,YAAY,GAAW,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAA,ypfAAypf,CAAC,CAAC;AACptf,eAAe,YAAY,CAAC"}
+{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../../../src/capabilities/document/instructions.ts"],"names":[],"mappings":"AAAA,mFAAmF;AACnF,MAAM,CAAC,MAAM,YAAY,GAAW,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAA,ypfAAypf,CAAC,CAAC;AACptf,eAAe,YAAY;KACxB,OAAO,CAAC,8CAA8C,EAAE;;;;mBAIxC,CAAC;KACjB,UAAU,CAAC,4BAA4B,EAAE,2BAA2B,CAAC;KACrE,UAAU,CAAC,2BAA2B,EAAE,0BAA0B,CAAC;KACnE,UAAU,CAAC,yBAAyB,EAAE,wBAAwB,CAAC,CAAC"}

package/dist/capabilities/index.js

@@ -4,19 +4,20 @@
 // imports this barrel from `../capabilities/index.js` so source-mode (vitest)
 // and dist-mode (npm install) resolve the same path.
 import { instructions as statusInstructions } from "./status/instructions.js";
+import { statusStartupInstructions } from "./status/startupInstructions.js";
 import { instructions as visionInstructions } from "./vision/instructions.js";
-import { instructions as discussInstructions } from "./discuss/instructions.js";
+import discussInstructions from "./discuss/instructions.js";
 import { instructions as researchInstructions } from "./research/instructions.js";
-import { instructions as planInstructions } from "./plan/instructions.js";
-import { instructions as buildInstructions } from "./build/instructions.js";
-import { instructions as optimizeInstructions } from "./optimize/instructions.js";
-import { instructions as auditInstructions } from "./audit/instructions.js";
-import { instructions as documentInstructions } from "./document/instructions.js";
+import planInstructions from "./plan/instructions.js";
+import buildInstructions from "./build/instructions.js";
+import optimizeInstructions from "./optimize/instructions.js";
+import auditInstructions from "./audit/instructions.js";
+import documentInstructions from "./document/instructions.js";
 import { instructions as profileInstructions } from "./profile/instructions.js";
 import { instructions as designInstructions } from "./design/instructions.js";
-import { instructions as orchestrateInstructions } from "./orchestrate/instructions.js";
+import orchestrateInstructions from "./orchestrate/instructions.js";
 export const CAPABILITY_INSTRUCTIONS = {
-    status: statusInstructions,
+    status: statusStartupInstructions(statusInstructions),
     vision: visionInstructions,
     discuss: discussInstructions,
     research: researchInstructions,

package/dist/capabilities/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/capabilities/index.ts"],"names":[],"mappings":"AAAA,uCAAuC;AACvC,uEAAuE;AACvE,0EAA0E;AAC1E,8EAA8E;AAC9E,qDAAqD;AACrD,OAAO,EAAE,YAAY,IAAI,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9E,OAAO,EAAE,YAAY,IAAI,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9E,OAAO,EAAE,YAAY,IAAI,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAChF,OAAO,EAAE,YAAY,IAAI,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAClF,OAAO,EAAE,YAAY,IAAI,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1E,OAAO,EAAE,YAAY,IAAI,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5E,OAAO,EAAE,YAAY,IAAI,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAClF,OAAO,EAAE,YAAY,IAAI,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5E,OAAO,EAAE,YAAY,IAAI,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAClF,OAAO,EAAE,YAAY,IAAI,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAChF,OAAO,EAAE,YAAY,IAAI,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9E,OAAO,EAAE,YAAY,IAAI,uBAAuB,EAAE,MAAM,+BAA+B,CAAC;AAExF,MAAM,CAAC,MAAM,uBAAuB,GAA2B;IAC7D,MAAM,EAAE,kBAAkB;IAC1B,MAAM,EAAE,kBAAkB;IAC1B,OAAO,EAAE,mBAAmB;IAC5B,QAAQ,EAAE,oBAAoB;IAC9B,IAAI,EAAE,gBAAgB;IACtB,KAAK,EAAE,iBAAiB;IACxB,QAAQ,EAAE,oBAAoB;IAC9B,KAAK,EAAE,iBAAiB;IACxB,QAAQ,EAAE,oBAAoB;IAC9B,OAAO,EAAE,mBAAmB;IAC5B,MAAM,EAAE,kBAAkB;IAC1B,WAAW,EAAE,uBAAuB;CACrC,CAAC;AAEF,MAAM,UAAU,+BAA+B,CAAC,UAAkB;IAChE,OAAO,iCAAiC,UAAU,kBAAkB,CAAC;AACvE,CAAC;AAED,MAAM,UAAU,wBAAwB,CAAC,UAAkB;IACzD,OAAO,4BAA4B,UAAU,gBAAgB,CAAC;AAChE,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/capabilities/index.ts"],"names":[],"mappings":"AAAA,uCAAuC;AACvC,uEAAuE;AACvE,0EAA0E;AAC1E,8EAA8E;AAC9E,qDAAqD;AACrD,OAAO,EAAE,YAAY,IAAI,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9E,OAAO,EAAE,yBAAyB,EAAE,MAAM,iCAAiC,CAAC;AAC5E,OAAO,EAAE,YAAY,IAAI,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9E,OAAO,mBAAmB,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAE,YAAY,IAAI,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAClF,OAAO,gBAAgB,MAAM,wBAAwB,CAAC;AACtD,OAAO,iBAAiB,MAAM,yBAAyB,CAAC;AACxD,OAAO,oBAAoB,MAAM,4BAA4B,CAAC;AAC9D,OAAO,iBAAiB,MAAM,yBAAyB,CAAC;AACxD,OAAO,oBAAoB,MAAM,4BAA4B,CAAC;AAC9D,OAAO,EAAE,YAAY,IAAI,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAChF,OAAO,EAAE,YAAY,IAAI,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9E,OAAO,uBAAuB,MAAM,+BAA+B,CAAC;AAEpE,MAAM,CAAC,MAAM,uBAAuB,GAA2B;IAC7D,MAAM,EAAE,yBAAyB,CAAC,kBAAkB,CAAC;IACrD,MAAM,EAAE,kBAAkB;IAC1B,OAAO,EAAE,mBAAmB;IAC5B,QAAQ,EAAE,oBAAoB;IAC9B,IAAI,EAAE,gBAAgB;IACtB,KAAK,EAAE,iBAAiB;IACxB,QAAQ,EAAE,oBAAoB;IAC9B,KAAK,EAAE,iBAAiB;IACxB,QAAQ,EAAE,oBAAoB;IAC9B,OAAO,EAAE,mBAAmB;IAC5B,MAAM,EAAE,kBAAkB;IAC1B,WAAW,EAAE,uBAAuB;CACrC,CAAC;AAEF,MAAM,UAAU,+BAA+B,CAAC,UAAkB;IAChE,OAAO,iCAAiC,UAAU,kBAAkB,CAAC;AACvE,CAAC;AAED,MAAM,UAAU,wBAAwB,CAAC,UAAkB;IACzD,OAAO,4BAA4B,UAAU,gBAAgB,CAAC;AAChE,CAAC"}