agentera 3.0.0-dev.39 → 3.0.0-dev.41

package/bundle/references/cli/agent-ready-state-contract.yaml

@@ -62,7 +62,7 @@ slash_route_aliases:
     Decision 43 aliases are exact `/agentera <alias>` routes, not CLI state
     commands. Teaching `status`, `build`, `audit`, or `document` as CLI commands
     would blur route vocabulary with state access; the shared word `plan` keeps
-     separate meanings as `/agentera plan` routing and `agentera state plan` state.
+     separate meanings as `/agentera plan` routing and `agentera state plan list` state.
 doctor:
   status: implemented_hard_rename
   command: doctor
@@ -170,7 +170,7 @@ structured_output:
             - summary_fields
             - entry_fields
           complete_semantics: >-
-            When `complete_for_plan_artifact` is true, `agentera state plan --format
+            When `complete_for_plan_artifact` is true, `agentera state plan list --format
             json` includes plan summary metadata, tasks, dependencies, acceptance
             criteria, evidence, overall acceptance, surprises, and previous-plan
             archive references needed for normal read-only startup/evaluation
@@ -376,7 +376,7 @@ startup_completeness:
     before any raw artifact read. Complete startup state must never require raw
     artifact reads for normal capability startup.
   current_cli_fallback:
-     - agentera state plan --format json
+     - agentera state plan list --format json
   state_families_added:
     - plan task details, dependencies, acceptance criteria, and evidence summaries
     - docs artifact mapping and source-contract completeness metadata
@@ -492,7 +492,7 @@ evidence_context_target_contract:
         caveats:
           - profile-derived state is stale and must not trigger profile refresh
           - orchestration_context is incomplete for missing decisions, vision, and profile state
-      - command: agentera state plan --format json
+      - command: agentera state plan list --format json
         included_state:
           - active plan header and summary
           - task dependencies
@@ -502,7 +502,7 @@ evidence_context_target_contract:
           - previous_plan_archived pointer
         missing_state: []
         raw_artifact_reads_required: false
-      - command: agentera state docs --format json
+      - command: agentera state docs list --format json
         included_state:
           - artifact mapping
           - version files
@@ -510,7 +510,7 @@ evidence_context_target_contract:
           - indexed document freshness
         missing_state: []
         raw_artifact_reads_required: false
-      - command: agentera state todo --format json
+      - command: agentera state todo list --format json
         included_state:
           - open 2.3.10 evidence-context TODO
           - deferred 2.3.11 and 2.3.12 source-contract TODOs
@@ -567,22 +567,22 @@ evidence_context_target_contract:
     required_for_normal_task_evaluation:
       - family: evaluation_target
         source: plan/orchestration CLI state
-        fallback: agentera state plan --format json
+        fallback: agentera state plan list --format json
       - family: plan_criteria
-        source: agentera state plan --format json entries.acceptance
+        source: agentera state plan list --format json entries.acceptance
         fallback: none when complete_for_plan_artifact is true
       - family: progress_verification
         source: agentera state progress list --limit 20 --format json latest verification
         fallback: agentera state progress get --id ID --format json
       - family: docs_state
-        source: agentera state docs --format json summary and entries
-        fallback: agentera state docs --format json
+        source: agentera state docs list --format json summary and entries
+        fallback: agentera state docs list --format json
       - family: health_state
         source: agentera state health list --limit 20 --format json latest audit
         fallback: agentera state health get --id ID --format json
       - family: todo_state
-        source: agentera state todo --format json known issues and source-contract TODOs
-        fallback: agentera state todo --format json
+        source: agentera state todo list --format json known issues and source-contract TODOs
+        fallback: agentera state todo list --format json
       - family: source_contract
         source: evidence_context.source_contract
         fallback: listed existing CLI commands before raw reads

package/bundle/references/cli/audience-namespace-cli-migration.yaml

@@ -259,7 +259,7 @@ decision_reconciliation:
   decision_45:
     routine_state_aliases: >-
       Routine state names stay stable via top-level aliases during migration. Canonical
-      reads become `agentera state <name>`; envelopes, field selection, and
+      reads become `agentera state <name> list`; envelopes, field selection, and
       source_contract semantics are unchanged.
     slash_route_separation: >-
       Decision 43 slash aliases remain excluded from the CLI command surface. The
@@ -273,10 +273,10 @@ plan_routing_distinction:
       Request-to-capability routing — start or continue Planera planning work. This
       is not a CLI command and does not read `.agentera/plan.yaml` by itself.
   state_read:
-    invocation: agentera state plan
+    invocation: agentera state plan list
     legacy_alias: >-
       Top-level `agentera plan` is capability routing, not a state-read alias;
-      use `agentera state plan` for project state.
+      use `agentera state plan list` for project state.
     surface: CLI routine state read
     meaning: >-
       Read-only access to the active plan artifact summary, tasks, acceptance
@@ -287,11 +287,11 @@ plan_routing_distinction:
     surface: CLI top-level capability routing command
     meaning: >-
       Emits plan capability routing guidance prose/schemas pointers. Does not replace
-      `state plan` reads or `/agentera plan` slash routing. Capability startup JSON
+      `state plan list` reads or `/agentera plan` slash routing. Capability startup JSON
       remains `agentera prime --context plan --format json`.
   agent_guidance: >-
     Use `/agentera plan` when the user wants planning work routed to Planera; use
-    `agentera state plan` when the agent needs plan artifact state; use
+    `agentera state plan list` when the agent needs plan artifact state; use
     `agentera plan` for capability routing guidance; use
     `agentera prime --context plan` for bounded plan startup context.
 migration_phases:

package/bundle/references/cli/prime-consumer-compatibility.yaml

@@ -213,7 +213,7 @@ field_classification:
     rationale: >-
       Default-only when no docs state. Task 2 omits it from the default bare
       briefing when docs.exists is false (see default_emission_omission_contract);
-      recovery via `agentera state docs`.
+      recovery via `agentera state docs list --format json`.
   - field: progress
     status: required
     rationale: opencode reads progress.latest; status brief references shipped work.
@@ -223,7 +223,8 @@ field_classification:
       Default-only when none active. Task 2 omits it from the default bare
       briefing when objective.active is false (see
       default_emission_omission_contract); status derives "none active" from
-      state_presence.active.objective. Recovery via `agentera state objective`.
+      state_presence.active.objective. Recovery via
+      `agentera state objective list --format json`.
   - field: state_presence
     status: required
     rationale: Owns missing-versus-empty semantics; must not be omitted.
@@ -250,7 +251,10 @@ field_classification:
       recover the current history.
   - field: shared_skill
     status: required
-    rationale: Canonical shared-skill path and read-only diagnosis.
+    rationale: >-
+      Canonical shared-skill status and read-only diagnosis. Bare prime omits
+      the privacy-sensitive absolute path; doctor or an explicit shared_skill
+      field read recovers full path diagnostics.
   - field: decision_attention
     status: conditional
     rationale: Null unless returned decisions require satisfaction review.
@@ -442,13 +446,13 @@ default_emission_omission_contract:
         the sole v1 signal.
     - field: docs
       omitted_when: docs.exists !== true
-      recovery_command: agentera state docs
+      recovery_command: agentera state docs list --format json
       disambiguated_by: >-
         state_presence.available.docs and state_presence.absence.docs carry the
         missing-vs-empty signal for the docs artifact family.
     - field: objective
       omitted_when: objective.active !== true
-      recovery_command: agentera state objective
+      recovery_command: agentera state objective list --format json
       disambiguated_by: >-
         state_presence.active.objective is false; status derives "none active"
         from state_presence rather than from an emitted default-only objective
@@ -475,9 +479,10 @@ default_emission_omission_contract:
   # `--dashboard` (full fidelity, 35000-byte budget), `--fields <name>`, and the
   # `--context` capsule are NOT projected and keep the full payload. The byte
   # gate is deterministic pretty-JSON UTF-8 measurement; an over-budget brief is
-  # rejected in favor of a bounded degraded envelope (status ok, brief.brief
-   # block signals degraded) that keeps command/status/mode/state_presence/a
-   # bounded brief source_contract and the byte-budget error with a recovery command.
+  # rejected in favor of a bounded degraded envelope (status ok, brief.status
+  # signals degraded). Every successful envelope keeps bounded plan selection,
+  # executable next_action, canonical history evidence, profile,
+  # state_presence, source_contract, and the byte-budget recovery.
   brief_omission_contract:
     implemented_by: packages/cli/src/cli/commands/prime/briefOrientation.ts:briefOrientationPayload
     applies_to: default bare prime (no --fields, no --dashboard, no --context)
@@ -494,6 +499,9 @@ default_emission_omission_contract:
       omitted_when_default). issues ships as the deprecated count-only
       transition projection and excludes canonical todo.detail.
     projected_subdetail:
+      - field: startup.path_diagnostics
+        reason: startup_path_diagnostics
+        recovery: agentera doctor --format json
       - field: plan.tasks
         reason: plan_task_detail
         recovery: agentera state plan tasks list --format json
@@ -502,10 +510,16 @@ default_emission_omission_contract:
         recovery: agentera state plan list --format json
       - field: plan.diagnostics
         reason: plan_diagnostics
-        recovery: agentera state plan --format json
-      - field: history.{progress,decisions,health}.entries
+        recovery: agentera state plan list --format json
+      - field: history.progress.entries
+        reason: startup_history_entries
+        recovery: agentera state progress list --format json
+      - field: history.decisions.entries
+        reason: startup_history_entries
+        recovery: agentera state decisions list --format json
+      - field: history.health.entries
         reason: startup_history_entries
-        recovery: agentera state <artifact> list --limit 20 --format json
+        recovery: agentera state health list --format json
       - field: project_integration.phases
         reason: phase_blockers
         recovery: agentera doctor --format json
@@ -518,21 +532,47 @@ default_emission_omission_contract:
       - field: profile.bounded_signals
         reason: profile_signal_detail
         recovery: agentera profile --format json
+    history_projection:
+      count_fields: [total, returned, remaining, full, summary]
+      degraded_fields: [caveats, degraded_history]
+      provenance_fields: [source_contract]
+      recovery_fields: [retrieval.list, retrieval.get]
+      semantics: >-
+        Progress, decisions, and health retain canonical entity-history counts.
+        A degraded or compacted history retains bounded caveats, explicit
+        summary-only counts, source-contract provenance, and exact list/get
+        pointers. It never reconstructs omitted records or infers decision
+        satisfaction; explicit firm, provisional, missing, compacted, and
+        review-needed evidence remains unchanged when present.
     never_collapsed: >-
       state_presence is projected to its finite contract-owned active, available,
       any_active, absence_explained, and absence keys rather than copied verbatim;
       known boolean values and absence reasons remain bounded, so missing versus
       present-but-empty stays behaviorally distinguishable even for adversarial
       caller objects. source_contract is likewise projected to bounded known
-      fields and named recovery pointers. plan.first_pending, progress.latest,
-      health.grade/trajectory, todo counts, next_action.object, and attention
-      are retained as the routing-essential leaves consumers read.
+      fields and named recovery pointers. Every successful normal or degraded
+      envelope keeps plan.first_pending identity, dependencies, acceptance, and
+      exact task get; next_action keeps its executable identity, capability,
+      phase, eligibility, and exact retrieval. Canonical history counts,
+      degraded caveats, and exact history recovery remain bounded consumer
+      evidence. Every bare-prime projection omits absolute app-home,
+      source-root, shared-skill, schema, and project path diagnostics while
+      retaining app/shared-skill status, stable source identity, truthful
+      presence, and doctor recovery. brief.path_diagnostics_recovery retains
+      that doctor command even when compact or irreducible metadata omits the
+      full recovery catalog. Normal and degraded projections retain bounded progress and
+      health signals; degraded projections also retain bounded TODO counts and
+      attention. Optional startup paths, plan task catalogs, and next-action
+      alternatives compact before selected routing or canonical history evidence.
     fallback_behavior: >-
       The detailed degraded envelope is byte-gated again after utf8_bytes is
-      settled. If it cannot fit, a compact and then an irreducible finite routing
-      envelope are tried deterministically. If the configured budget cannot hold
-      the irreducible envelope, briefOrientationPayload fails explicitly rather
-      than emitting over-budget stdout.
+      settled. If it cannot fit, the recovery catalog, optional source-contract
+      detail, next-action alternatives, and free text compact proportionally
+      before selected plan, executable next_action, or canonical history
+      evidence. A compact and then irreducible finite routing envelope are tried
+      deterministically. If the configured budget cannot hold that routing
+      evidence, briefOrientationPayload fails explicitly rather than returning
+      exit zero without an executable task or emitting over-budget stdout.
 
 # ---------------------------------------------------------------------------
 # Fixtures used by packages/cli/test/cli/primeCompatibilityBoundary.test.ts.

package/bundle/references/cli/vocabulary-index.yaml

@@ -42,7 +42,7 @@ normalization_rules:
     use: agentera prime source data, status dashboard rendered briefing
     avoid: Treating raw CLI labels as the user-facing dashboard.
   - rule: Routine state uses the state namespace.
-    use: agentera state plan, agentera state docs, agentera state health
+    use: agentera state plan list, agentera state docs list, agentera state health list
     avoid: agentera plan, agentera docs, or agentera health as routine state commands.
   - rule: query is advanced access.
     use: agentera query --list-artifacts, agentera query <artifact>

package/bundle/references/cli/vocabulary.md

@@ -173,9 +173,10 @@ Primary route aliases are slash-route vocabulary, not CLI command vocabulary:
 
 Do not teach primary aliases as CLI state commands. v3 orientation is
 `agentera prime` (capability ID `status` via `prime --context status`); routine
-state reads use `agentera state plan`, `state progress`, `state health`,
-`state todo`, `state decisions`, `state docs`, `state objective`,
-`state experiments`, and advanced `state query`. The v2 stable distribution
+record reads use `agentera state plan list`, `state progress list`,
+`state health list`, `state todo list`, `state decisions list`, `state docs list`,
+`state objective list`, objective-scoped `state experiments list`, exact
+`get --id ID`, and advanced `state query`. The v2 stable distribution
 retains `hej` and the rest of the Swedish capability surface per Decision 70.
 
 When capability prose recommends another capability, use the handoff label

package/bundle/skills/agentera/SKILL.md

@@ -212,14 +212,33 @@ npx -y agentera@next state <progress|decisions|plan|health> explain --verb <verb
 
 Common mutations:
 
-- `npx -y agentera@next state progress append ... --format json`
-- `npx -y agentera@next state decisions append ... --format json`
+- `npx -y agentera@next state progress append --input <path|-> --format json`
+- `npx -y agentera@next state decisions append --input <path|-> --format json`
+- `npx -y agentera@next state decisions amend --id ID --base-sha256 HASH --input <path|-> --format json`
 - `npx -y agentera@next state decisions update --id ID ... --format json`
 - `npx -y agentera@next state plan create --input plan.yaml --format json`
-- `npx -y agentera@next state plan update|set-status --id ID ... --format json`
-- `npx -y agentera@next state plan set-plan-status --status complete --format json`
+- `npx -y agentera@next state plan append [--plan PLAN_ID] --input task.yaml --format json`
+- `npx -y agentera@next state plan update --id TASK_ID [--plan PLAN_ID] --input task-patch.yaml --format json`
+- `npx -y agentera@next state plan set-status --id TASK_ID --status STATUS --format json`
+- `npx -y agentera@next state plan set-plan-status [--plan PLAN_ID] --status complete --format json`
 - `npx -y agentera@next state plan archive --format json`
 - `npx -y agentera@next state health append --input audit.yaml --format json`
+- `npx -y agentera@next state todo create --input todo.yaml --format json`
+- `npx -y agentera@next state todo update --id ID --input todo-patch.yaml --format json`
+- `npx -y agentera@next state todo set-severity|supersede|resolve|reopen --id ID ... --format json`
+
+TODO create input is a full YAML/JSON typed record. TODO update input is a
+patch: omitted fields remain unchanged and only `target_version`,
+`requirements`, `acceptance`, and `readiness` accept typed clears. Public TODO
+fields remain TODO.md-owned; readiness, dependencies, gates, evidence, and
+lifecycle metadata remain Agentera-owned. Lifecycle verbs are flag-only and do
+not accept record payloads.
+
+Plan create task numbers and dependency values are create-local symbolic
+ordinals inside one atomic input document; the writer removes them before
+publishing bare ten-letter plan and task envelope IDs. A legacy composite
+`header.id` is migration-only and is never a public selector. Post-publication
+task append/update payloads use only mutable task content and bare task IDs.
 
 Add `--dry-run` to preview any mutation without publishing it. Artifacts not
 listed above are outside the typed writer contract and remain governed by their

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

@@ -67,9 +67,9 @@ ARTIFACTS:
     local_role: consumes
     description: >-
       Build consumes status profile summary first and reads profile grounding
-      only from `agentera report profile-grounding --format json`. Missing,
-      stale, or malformed state is a caveat and does not authorize refresh or
-      direct profile reads during normal startup.
+      only from `agentera report profile-grounding --format json` when shared
+      validity is `valid`. Absent or repair-needed state preserves exact
+      recovery and does not authorize refresh or direct profile reads.
   9:
     id: A9
     artifact: docs

package/bundle/skills/agentera/capabilities/build/schemas/validation.yaml

@@ -113,10 +113,12 @@ VALIDATION:
     rule: sanitized_profile_grounding
     description: >-
       Build MUST ground only from the `content` returned by `agentera report
-      profile-grounding --format json`; it MUST NOT direct-read PROFILE.md.
+      profile-grounding --format json` when shared validity is valid; it MUST
+      preserve absent/repair-needed recovery and MUST NOT direct-read PROFILE.md.
     severity: critical
     checks:
       - "Sanitized grounding command used after prime startup"
+      - "Prime and report validity objects agree before content use"
       - "Raw profile path not read"
   12:
     id: V12

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

@@ -41,7 +41,8 @@ ARTIFACTS:
     description: >-
       Discuss reads only sanitized non-glossary content from `agentera report
       profile-grounding --format json` at session start. It never direct-reads
-      the profile path; malformed owned Glossary boundaries fail closed.
+      the profile path. It uses content only when the shared validity object is
+      valid; absent or repair-needed results fail closed with exact recovery.
   6:
     id: A6
     artifact: docs

package/bundle/skills/agentera/capabilities/discuss/schemas/validation.yaml

@@ -81,10 +81,12 @@ VALIDATION:
     rule: sanitized_profile_grounding
     description: >-
       Discuss MUST ground only from the `content` returned by `agentera report
-      profile-grounding --format json`; it MUST NOT direct-read PROFILE.md.
+      profile-grounding --format json` when shared validity is valid; it MUST
+      preserve absent/repair-needed recovery and MUST NOT direct-read PROFILE.md.
     severity: critical
     checks:
       - "Sanitized grounding command used at session start"
+      - "Prime and report validity objects agree before content use"
       - "Raw profile path not read"
   9:
     id: V9

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

@@ -55,8 +55,8 @@ ARTIFACTS:
     description: >-
       Plan reads only sanitized non-glossary content from `agentera report
       profile-grounding --format json` to calibrate planning depth and pattern
-      preferences. It never direct-reads the profile path; malformed owned
-      Glossary boundaries fail closed.
+      preferences. It never direct-reads the profile path and uses content only
+      for shared validity `valid`; absent and repair-needed results fail closed.
   9:
     id: A9
     artifact: docs

package/bundle/skills/agentera/capabilities/plan/schemas/validation.yaml

@@ -92,10 +92,12 @@ VALIDATION:
     rule: sanitized_profile_grounding
     description: >-
       Plan MUST ground only from the `content` returned by `agentera report
-      profile-grounding --format json`; it MUST NOT direct-read PROFILE.md.
+      profile-grounding --format json` when shared validity is valid; it MUST
+      preserve absent/repair-needed recovery and MUST NOT direct-read PROFILE.md.
     severity: critical
     checks:
       - "Sanitized grounding command used during Orient"
+      - "Prime and report validity objects agree before content use"
       - "Raw profile path not read"
   10:
     id: V10

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

@@ -9,7 +9,9 @@ ARTIFACTS:
       deterministic personal Glossary section containing shared glossary entries
       and lifecycle metadata; rendering and persistence are active while lookup
       remains deferred. Profile writes this in both Full and Validate modes,
-      then reads it for validation and update context.
+      then reads it for validation and update context. Prime exposes its
+      canonical resolved path only inside `prime --context profile`; no other
+      Prime context or profile-grounding failure may serialize that path.
   2:
     id: A2
     artifact: decisions

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

@@ -69,4 +69,5 @@ ARTIFACTS:
     artifact: profile
     local_role: consumes
     description: >-
-      Status reads this to report profile status (loaded/not found) in the briefing.
+      Status reports profile validity as valid, absent, or repair_needed and
+      keeps freshness separate without exposing profile paths or content.

package/bundle/skills/agentera/capability_schema_contract.yaml

@@ -281,7 +281,7 @@ ROUTE_ALIASES:
   canonical_name_precedence: true
   cli_boundary: >-
     Slash routes and state commands are distinct: `/agentera plan` routes to
-    the plan capability, while `agentera state plan` remains the
+    the plan capability, while `agentera state plan list` remains the
     state-oriented CLI command for reading plan state. Do not add capability or
     alias commands to the CLI.
   primary_aliases:

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

@@ -5,10 +5,16 @@
 # and acceptance criteria, overall acceptance, and surprises.
 #
 # 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.
+# The aggregate model below is the complete atomic plan-create input. Its task
+# numbers and numeric/string dependency references are create-local symbols,
+# not persisted identities. Fields explicitly labeled migration-only remain
+# compatibility input and are not ordinary post-cutover entity contracts.
 #
-# ── Field-by-field mapping: v1 PLAN.md → v2 plan.yaml ──
+# ── Legacy migration-input mapping: v1 PLAN.md → v2 plan.yaml ──
+#
+# The ordinal task fields in this mapping are create-local symbolic references.
+# They are valid only inside one atomic `state plan create --input` document and
+# are removed when the writer publishes plan and plan_task entities.
 #
 # v1 Field                              v2 Field               v2 ID
 # ─────────────────────────────────────────────────────────────────────
@@ -26,7 +32,7 @@
 # ## Scope / **Out**: <list>            SCOPE.excluded         PL12
 # ## Scope / **Deferred**: <list>       SCOPE.deferred         PL13
 # ## Design                             PLAN.design            PL14
-# ### Task N: <name>                    TASK.number            PL15
+# ### Task N: <name>                    TASK.number            PL15 (create-local only)
 # (task name from heading)              TASK.name              PL16
 # **Depends on**: <text>                TASK.depends_on        PL17
 # **Status**: <status>                  TASK.status            PL18
@@ -65,7 +71,34 @@ ENTITY_AUTHORITY:
     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
+  aggregate_schema_below: atomic_create_input
+  migration_compatibility: explicitly_labeled_fields_only
+
+CANONICAL_ENTITY_CONTRACT:
+  authority: typed_state_writer
+  envelope_identity:
+    plan:
+      field: id
+      format: bare_ten_letter_id
+      selector: --id ID
+      assignment: writer_assigned_on_create
+    plan_task:
+      field: id
+      format: bare_ten_letter_id
+      selector: --id ID
+      assignment: writer_assigned_on_append
+  create_local_symbols:
+    scope: one_atomic_plan_create_input
+    task_field: number
+    dependency_accepted_forms: [positive_integer, canonical_numeric_string]
+    dependency_normalization: canonical_numeric_string_before_resolution
+    publication: remove_number_and_resolve_dependencies_to_bare_entity_ids
+  migration_compatibility:
+    header_id:
+      format: composite_plan_identity
+      status: migration_only_noncanonical
+      public_selector: forbidden
+    legacy_task_references: convert_to_bare_entity_ids_during_migration
 
 GROUP_PREFIXES:
   BUDGET: PB
@@ -165,11 +198,11 @@ HEADER:
     type: string
     required: false
     description: >-
-      Stable plan identity assigned by the typed writer at first publication and
-      retained unchanged when the plan moves from active to archived history.
-      Legacy plans without this field derive a read-only identity.
+      Migration-only source identity. Canonical plan identity is the bare
+      ten-letter envelope `id` assigned by the typed writer; this source
+      `header.id` is never a public selector.
     validation:
-      - "Must match plan:<lowercase RFC 9562 UUID> when present"
+      - "Composite header.id is accepted only by legacy migration compatibility"
 
 PLAN:
   1:
@@ -324,11 +357,12 @@ TASK:
     type: integer
     required: true
     description: >-
-      Task number within the plan. Sequential, starting from 1.
-      May include a descriptive name (e.g., 'Task 2: Shared Protocol').
+      Create-local symbolic task ordinal within one atomic plan input.
+      Sequential values start at 1, are removed on publication, and are never
+      a canonical entity identity or public selector.
     validation:
-      - "Must be a positive integer"
-      - "Must be unique within the plan"
+      - "Must be a positive integer in the create input"
+      - "Must be unique within that atomic input"
   2:
     id: PT16
     field: name
@@ -342,11 +376,24 @@ TASK:
   3:
     id: PT17
     field: depends_on
-    type: list[string]
+    path: tasks[].depends_on
+    type: list[integer|string]
+    write_operations: [create]
+    accepted_forms:
+      atomic_plan_create: [positive_integer, canonical_numeric_string]
+      legacy_migration_only: [legacy_task_reference_string]
+    normalization: canonical_numeric_string_before_same_document_resolution
     required: false
     description: >-
-      Task dependencies. References task numbers or names that must
-      complete before this task can start. Empty for root tasks.
+      Numeric or numeric-string dependency references are create-local symbolic
+      task ordinals only inside the current complete plan create input. The writer
+      resolves them within that atomic document, removes the ordinal references,
+      and publishes dependencies as bare ten-letter task envelope IDs. Empty for
+      root tasks.
+    validation:
+      - positive_integer_or_canonical_numeric_string
+      - unique_after_normalization_within_task
+      - resolves_to_declared_task_ordinal_in_same_atomic_document
   4:
     id: PT18
     field: status
@@ -403,18 +450,20 @@ VALIDATION:
     rule: unique_entity_ids
     severity: error
     description: >-
-      Task numbers must be unique within a plan and sequential.
+      Create-local task ordinals must be unique within one atomic plan input and
+      sequential; they are not persisted entity identities.
     checks:
-      - "All task numbers are unique"
-      - "Task numbers are sequential starting from 1"
+      - "All create-local task ordinals are unique"
+      - "Create-local task ordinals are sequential starting from 1"
   2:
     id: PV2
     rule: required_fields
     severity: error
     description: >-
-      The plan must have: level, created, status, title, what, why,
-      scope.included, scope.excluded, and at least one task. Each task
-      must have number, name, and status.
+      A complete create input must have: level, created, status, title, what,
+      why, scope.included, scope.excluded, and at least one task. Each task's
+      number is create-local and is removed before identity conversion. Legacy
+      source documents use the separate migration compatibility contract.
     checks:
       - "level is present and is 'light' or 'full'"
       - "created is present and matches YYYY-MM-DD"
@@ -443,10 +492,14 @@ VALIDATION:
     rule: dependency_references
     severity: error
     description: >-
-      Task depends_on references must point to valid task numbers
-      within the same plan.
+      Create-local depends_on references must point to valid task ordinals in
+      the same atomic input before conversion to bare task IDs. Legacy source
+      references use the migration compatibility path, not this public writer
+      vocabulary.
     checks:
-      - "Each dependency references an existing task number"
+      - "Each create-local dependency is a positive integer or canonical numeric string"
+      - "Each normalized dependency references an existing task ordinal"
+      - "Each task's normalized dependency ordinals are unique"
       - "No circular dependency chains"
   5:
     id: PV5
@@ -463,12 +516,18 @@ LIFECYCLE_CONTRACT:
   authority: this schema
   canonical:
     identity:
+      field: id
+      format: bare_ten_letter_id
+      assignment: The typed entity writer assigns the envelope identity at first publication.
+      transition: Active and archived entity positions retain the identical bare identity.
+      legacy: Legacy source header.id is migration-only and never a public selector.
+      collision: Different canonical entities with one identity are ambiguous and never selected by path or time.
+    migration_source_identity:
       field: header.id
-      format: 'plan:<lowercase-rfc9562-uuid>'
-      assignment: The typed create writer assigns identity at first publication.
-      transition: Active and archived positions retain the identical identity.
-      legacy: Missing identity is derived deterministically at read time without rewriting bytes.
-      collision: Different documents with one identity are ambiguous and never selected by path or time.
+      format: 'plan:<lowercase-rfc9562-uuid> or legacy-plan:<sha256>'
+      status: migration_only_noncanonical
+      assignment: Read-only compatibility derivation or retained legacy source value.
+      public_selector: forbidden
     persisted_status:
       field: header.status
       values: