agentera 3.0.0-dev.51 → 3.0.0-dev.69

package/bundle/references/analysis/verification-policy.yaml

@@ -10,13 +10,11 @@ inventory:
   rules:
     - owner: stress
       path: packages/cli/test/stress/entityStorageStress.test.ts
-    - owner: performance
-      path: packages/cli/test/performance/analyticsEvidenceTierCap.test.ts
-    - owner: performance
-      path: packages/cli/test/performance/entityMigrationPreviewCap.test.ts
     - owner: performance
       path: packages/cli/test/performance/entityAuthorityPerformance.test.ts
       evidence_producer: true
+    - owner: capacity
+      prefix: packages/cli/test/capacity/
     - owner: package
       prefix: packages/cli/test/packaging/
 
@@ -48,12 +46,14 @@ release_qualification:
     overlap stops new work at the contract cleanup margin, settles owned children,
     removes its generated state on failure, and returns before the contract parent margin
   isolation: distinct_home_cache_user_global_config_and_report_per_child
-  resource_isolation: performance_runs_alone_after_batch_a_settles
+  resource_isolation: performance_runs_alone_after_batch_a_settles_with_one_worker_and_no_other_marked_owner_then_capacity_runs_serially_before_readers
   failure:
     first_observed_owner: preserved
     cancellable_process_groups: cancel
     generated_overlap: cooperative_stop_settle_and_cleanup_without_parent_force_kill
     performance_after_batch_failure: forbidden
+    capacity_after_performance_failure: forbidden
+    barrier_b_after_capacity_failure: forbidden
     barrier_b_after_performance_failure: forbidden
     barrier_b_after_batch_failure: forbidden
     receipt_after_any_failure: forbidden
@@ -74,6 +74,17 @@ owners:
   performance:
     config: packages/cli/vite.config.ts
     correction: Run `pnpm -C packages/cli test:performance`; check runner conditions and fix the named budget regression.
+    execution:
+      workers: 1
+      authoritative_runner:
+        provider: github_actions
+        runs_on: ubuntu-24.04
+        runner_class: github-hosted-ubuntu-24.04
+        runner_class_environment: AGENTERA_PERFORMANCE_RUNNER_CLASS
+        runner_identity_environment: AGENTERA_PERFORMANCE_RUNNER_IDENTITY
+        actions_environment: GITHUB_ACTIONS
+        platform: linux
+        architecture: x64
     integration:
       path: packages/cli/test/integration/performanceOwner.integration.mjs
       command: [pnpm, run, test:performance:integration]
@@ -109,16 +120,76 @@ owners:
         --outputFile: output redirection can suppress the evidence line
         --silent: output suppression can hide the evidence line
         --hideSkippedTests: output filtering can hide owner diagnostics
+  capacity:
+    config: packages/cli/vite.config.ts
+    correction: Run `pnpm -C packages/cli test:capacity`; fix the named production-capacity invariant or its fixture.
+    execution:
+      workers: 1
   package:
     config: packages/cli/vite.package.config.ts
     correction: Run `pnpm -C packages/cli verify:package`; fix package construction or the extracted-package assertion.
+    execution:
+      wall_time_budget_ms: 60000
+      budget_basis:
+        baseline:
+          source: docs/packaging/v3-release-workflow-baseline.json#measurements.package
+          command: pnpm -C packages/cli run verify:package
+          serial_runs_ms: [611675, 386578, 307207]
+          minimum_ms: 307207
+          note: Task 1 recorded a contention fingerprint, so the minimum is a historical ceiling rather than a direct target.
+        controlled_measurement:
+          measured_on: 2026-08-10
+          command: pnpm -C packages/cli run verify:package
+          serial_runs_ms: [12376, 11666, 11047]
+          owner_wall_time_runs_ms: [11415, 10789, 10202]
+          minimum_ms: 11047
+          median_ms: 11666
+          maximum_ms: 12376
+          test_files: 2
+          passed_tests: 11
+          fixture_construction_cycles: 2
+          deterministic_pack_runs: 2
+          extracted_smoke_runs: 1
+          machine:
+            platform: Linux x86_64
+            processor: AMD Ryzen 7 9800X3D
+            logical_cpus: 16
+            node: 22.23.2
+            pnpm: 10.30.3
+            load_average_at_start:
+              - [15.69, 16.16, 15.30]
+              - [13.97, 15.76, 15.18]
+              - [12.79, 15.38, 15.07]
+          conditions: Serial commands with existing dependencies and caches, no intentional verification overlap, and two independent construction roots per command.
+        remote_cold_measurement:
+          measured_on: 2026-08-12
+          owner_wall_time_ms: 28714
+          conditions: GitHub-hosted Ubuntu 24.04 with a shared Corepack download cache and otherwise isolated package state.
+        calibration_history:
+          superseded_single_construction_command_runs_ms: [7500, 7738, 7604, 11733, 11012, 9967, 14293]
+          note: These runs calibrated the candidate limits but do not represent the final two-construction snapshot.
+          rejected_candidate:
+            budget_ms: 10000
+            owner_wall_time_ms: 10429
+            command_wall_time_ms: 11733
+            outcome: tests_passed_budget_failed
+          stricter_candidate_validation:
+            budget_ms: 15000
+            owner_wall_time_runs_ms: [9859, 8962, 13069]
+            command_wall_time_runs_ms: [11012, 9967, 14293]
+            outcome: passed_repeatedly_before_final_fixture_strengthening
+        derivation:
+          formula: min(baseline_minimum_ms, max(ceil(controlled_maximum_ms * 1.25 / 5000) * 5000, ceil(remote_cold_ms * 2 / 5000) * 5000))
+          controlled_headroom_multiplier: 1.25
+          remote_cold_headroom_multiplier: 2
+          rounding_quantum_ms: 5000
 
 # Deterministic simultaneous-publication and stale-lock recovery evidence remains
 # source-owned. The independent 100-repetition stale-lock race is stress-owned.
 mixed_files: []
-# Production-cap analytics, entity authority, and migration-preview wiring are intentionally
-# separate from proportional source fixtures and run through performance in
-# scheduled/release.
+# Deterministic response-cap behavior remains source-owned. Production-scale
+# capacity and machine-sensitive performance have separate owners and run in
+# that order during scheduled/release verification.
 
 policies:
   targeted: [source]
@@ -126,23 +197,19 @@ policies:
   fast: [source]
   local: [source]
   merge: [source, package]
-  scheduled: [source, stress, performance]
-  release: [source, stress, performance, package]
+  scheduled: [source, stress, performance, capacity]
+  release: [source, stress, performance, capacity, package]
 
 # Task 1 classified probabilistic stale-lock repetition as scheduled/release
 # evidence after proportional deterministic lock correctness remained in source.
 # Therefore merge receives lock evidence through source, while scheduled also
 # executes the stress owner.
 
-# Pre-commit routing chooses release policy for authority and verification
-# surfaces. All other paths retain the existing targeted source routing.
+# Pre-commit routing marks authority, verification, and specialized-owner
+# surfaces as ci_owned. The local hook runs only source-owned route guards and
+# typecheck; required CI executes the unchanged release policy authoritatively.
+# All other paths retain targeted source routing.
 conservative_routing:
-  receipt_reuse:
-    environment: AGENTERA_PRECOMMIT_SOURCE_CANDIDATE_DIR
-    command: [node, scripts/release-qualification.mjs, source-check]
-    success: skip_source_or_release_policy_only
-    absent_or_invalid: preserve_existing_policy
-    path_is_authority: false
   exact:
     - .lefthook.yml
     - protocol.yaml
@@ -168,23 +235,31 @@ conservative_routing:
     - packages/cli/scripts/reject-direct-prepack.mjs
     - packages/cli/scripts/publication-transaction.mjs
     - packages/cli/scripts/release-qualification.mjs
+    - packages/cli/scripts/release-readiness.mjs
     - packages/cli/scripts/release-benchmark.mjs
     - packages/cli/src/validate/activationConjunction.ts
     - packages/cli/src/validate/activationArtifactEvidence.ts
+    - packages/cli/src/validate/activationArtifactEvidenceTypes.ts
     - packages/cli/src/validate/activationEvidenceManifest.ts
     - packages/cli/src/validate/activationPackageSemantics.ts
     - packages/cli/src/validate/bootstrapAuthority.ts
     - packages/cli/src/registries/activationTuples.ts
     - packages/cli/src/registries/packagePublication.ts
     - packages/cli/test/sourceSetup.ts
+    - packages/cli/test/state/todoDocsEntities.test.ts
+    - packages/cli/test/upgrade/upgradeEntityCutover.test.ts
+    - packages/cli/test/scripts/precommitVitest.test.ts
     - packages/cli/test/helpers/sourceSubprocess.ts
     - packages/cli/test/helpers/runtimeBootstrapMatrix.ts
     - packages/cli/test/helpers/preCutoverBootstrapDispatcher.mjs
     - packages/cli/test/helpers/runtimeProofCliBoundary.mjs
+    - packages/cli/test/integration/runtimeBootstrapMatrix.test.ts
+    - packages/cli/test/integration/sourcePackageParity.test.ts
     - references/analysis/verification-policy.yaml
     - scripts/precommit-vitest.sh
   prefixes:
     - .github/workflows/
+    - packages/cli/test/capacity/
     - packages/cli/test/packaging/
     - references/adapters/
     - references/artifacts/

package/bundle/references/artifacts/state-storage-authority.yaml

@@ -17,11 +17,14 @@ authority:
     Shared entity storage plus the progress, decisions, health, plan, objective,
     experiment, TODO-item, and documentation-inventory family writers and retrieval,
     plus one-way forward import, are implemented but activate entity authority only
-    from the durable cutover marker. The preserved
+    from the durable cutover marker. A marker-absent Git root with no .agentera
+    residue is fresh_uninitialized and may publish that marker only with its first
+    complete Plan create. The preserved
     singleton families remain legacy files. The
     numbered archives, aggregate overlays, and aggregate revision documents
     remain migration input while that marker is absent; no independent legacy
-    read or repair mutation remains.
+    read or repair mutation remains, and every other marker-absent residue fails
+    closed without publication.
 
 entity_target:
   status: progress_decisions_health_plan_objective_experiment_todo_and_docs_implemented_other_families_declared
@@ -44,9 +47,11 @@ entity_target:
     remaining_families: declared_not_implemented
     rule: >-
       Every implemented family selects entity behavior only when the durable
-      cutover marker is valid. Marker-absent ordinary consumers fail with
-      migration_required; the read-only migration preview and readiness checks do
-      not create entity state or write both authorities.
+      cutover marker is valid. The sole marker-absent exception is fresh Plan
+      create at a proven fresh_uninitialized Git root; it publishes one complete
+      plan graph and marker or rolls back. Other marker-absent consumers fail
+      closed; the read-only migration preview and readiness checks do not create
+      entity state or write both authorities.
   public_schema:
     canonical_identity_field: id
     canonical_classification_field: artifact
@@ -1193,16 +1198,30 @@ entity_migration:
       mode: entities
       source_fingerprint: lowercase_sha256_of_bound_migration_inputs
       preview_digest: lowercase_sha256_of_bound_migration_preview
-    absent_mode: legacy
+    absent_mode: classified
     invalid_behavior: fail_without_fallback
     detection: read_only
-    publication_owner: development_channel_v2_to_v3_upgrade
+    publication_owner: recognized_legacy_development_upgrade_or_fresh_plan_create
     selection: >-
       Project state and CLI installation state are independent dimensions. A v3
       CLI selects this cutover for recognized marker-absent v2 aggregate state
       whether the CLI runs from a self-contained npm package or a source
-      checkout. Pending v1 Markdown state and marker-absent state with no
-      recognized v2 entity input are rejected with manual recovery instructions.
+      checkout. A Git-root project with no .agentera path is fresh_uninitialized:
+      Plan startup remains read-only and its first Plan create is the sole
+      initializer. Pending v1 Markdown, partial, corrupt, and unknown
+      marker-absent state are rejected with their read-only recovery instructions.
+  fresh_initialization:
+    classification: >-
+      fresh_uninitialized requires an exact Git root, absent .agentera state
+      root, no entity records, no recognized aggregate migration input, and no
+      unknown Agentera-owned residue. Ordinary root documents, table-based TODO
+      files, and report directories are user-owned and do not participate.
+    startup: plan_context_is_read_only_and_operable_without_upgrade_apply
+    writer: state_plan_create_only
+    dry_run: previews_marker_plan_and_tasks_without_filesystem_effects
+    apply: publishes_plan_and_tasks_then_marker_with_ordinary_rollback_on_failure
+    other_writers: reject_without_initialization_route
+    global_runtime_resources: not_read_or_changed
   invocation:
     explicit_apply: full_upgrade_yes_only
     dry_run: optional_read_only_preview
@@ -1269,7 +1288,7 @@ entity_migration:
         Deterministic legacy plan lifecycle normalization is part of entity
         projection during cutover. Upgrade retains the original legacy YAML as
         source and recovery evidence instead of rewriting it first.
-      empty_state: unsupported_unknown_source_with_manual_handoff
+      empty_state: fresh_plan_create_only_other_marker_absent_state_manual_handoff
       existing_entity_state: validate_then_no_op
   source_scope:
     included_entities: entity_target.entities
@@ -2854,7 +2873,7 @@ mutation_grammar:
       preconditions: [entity_mode_marker_is_valid, activation_is_absent_or_replay, todo_reconciliation_is_valid, inactive_projection_is_complete_one_to_one_and_safe, confirmed_effect_sha256_is_authorized_for_preview_or_replay]
       owned_fields: [reconciliation, public_document, activation]
       input: { mode: none, sources: [], cli_owned_fields: [] }
-      recovery: Preview and review every reported safe activation effect before explicit confirmed apply; unsafe inactive evidence requires non-mutating owner correction and replanning.
+      recovery: Preview and review every reported safe activation effect before explicit confirmed apply; unsafe inactive evidence requires the separate effect-bound owner-correction operation.
       examples: ['npx -y agentera@next state todo activate --dry-run --format json', 'npx -y agentera@next state todo activate --effect-sha256 EFFECT_SHA256 --yes --format json']
       bounds: { max_input_utf8_bytes: 0, max_collection_items: 256 }
       compacts: true
@@ -2877,6 +2896,26 @@ mutation_grammar:
         - { flag: --effect-sha256, field: effect_sha256, kind: string }
         - { flag: --yes, field: confirmed, kind: boolean }
 
+    - artifact: todo
+      verb: correct-owners
+      class: batch_transaction
+      selectors: []
+      preconditions: [entity_mode_marker_is_valid, reconciliation_marker_is_absent_and_unsafe_inactive_or_exact_effect_replay, input_is_complete_one_to_one_owner_mapping, completed_markdown_work_is_not_reopened, confirmed_effect_sha256_and_owner_mapping_are_authorized_for_preview_or_replay]
+      owned_fields: [reconciliation, public_document, activation]
+      input:
+        mode: structured
+        root: one unsafe TODO owner mapping
+        sources: [file, stdin]
+        structured_sources: [file, stdin]
+        cli_owned_fields: []
+      recovery: Supply one complete id/source_line owner mapping, preview its bounded effect, then apply only the exact returned effect; malformed, ambiguous, unmatched, or stale evidence is rejected without effects.
+      examples: ['npx -y agentera@next state todo correct-owners --input owner-mapping.yaml --dry-run --format json', 'npx -y agentera@next state todo correct-owners --input owner-mapping.yaml --effect-sha256 EFFECT_SHA256 --yes --format json']
+      bounds: { max_input_utf8_bytes: 32768, max_collection_items: 256 }
+      compacts: true
+      fields:
+        - { flag: --effect-sha256, field: effect_sha256, kind: string }
+        - { flag: --yes, field: confirmed, kind: boolean }
+
     - artifact: todo
       verb: create
       class: record_payload

package/bundle/skills/agentera/SKILL.md

@@ -34,11 +34,13 @@ documentation after deterministic abstention; it learns that contract from the C
 
 ## Bootstrap
 
-Run one pre-cutover `@next` call for orientation. It is read-only in clean, v2,
-partially migrated, and v3 projects. Clean, v2, and partial state returns
-`blocked` with the exact full entity-upgrade command in
-`state_cutover.recovery_command`; v3 returns `ok` unless health is degraded.
-The JSON also returns bounded app status, state slices, attention, and startup
+Run one pre-cutover `@next` call for orientation. It is read-only in fresh, v2,
+partially migrated, and v3 projects. A Git-root project with no `.agentera`
+state is `fresh_uninitialized`: `prime --context plan` is operable and its first
+`state plan create` is the sole initializer. Recognized v2 state returns the
+full entity-upgrade recovery; partial, corrupt, and unknown marker-absent state
+returns read-only recovery. V3 returns `ok` unless health is degraded. The JSON
+also returns bounded app status, state slices, attention, and startup
 availability.
 
 ```bash

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

@@ -28,12 +28,13 @@ ARTIFACTS:
     artifact: progress
     local_role: produces_and_consumes
     description: >-
-      Operational cycle log and the sole durable channel for bounded autonomous
-      glossary caveat lifecycle evidence. Build consumes latest progress evidence from
-      execution_context first, then bounded `npx -y agentera@next state progress list --limit
-       20 --format json` discovery or exact `state progress get --id ID`
-      retrieval, and appends one entry per cycle with mandatory Verified field.
-      Compacted by applying schema COMPACTION rules.
+      Durable project-outcome log and the sole durable channel for bounded
+      autonomous glossary caveat lifecycle evidence. Build consumes latest
+      progress evidence from execution_context first, then bounded `npx -y
+      agentera@next state progress list --limit 20 --format json` discovery or
+      exact `state progress get --id ID` retrieval. The typed writer's
+      progress_write_policy governs whether a cycle appends zero or one record;
+      every appended cycle has a mandatory non-empty verified field.
   5:
     id: A5
     artifact: health

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

@@ -4,9 +4,10 @@ EXIT_CONDITIONS:
     condition: complete
     description: >-
       One full cycle completed. Work was selected, implemented, and verified
-      against the project's test/build suite. Required TODO, progress,
-      changelog, and plan closeout updates preceded the cycle's single
-      conventional commit.
+      against the project's test/build suite. Required artifact updates
+      preceded the cycle's single conventional commit. They include TODO,
+      changelog, and plan updates. Progress is present for policy-required
+      cases and optional for allowed durable outcomes.
     exit_signal: complete
   2:
     id: E2
@@ -14,8 +15,8 @@ EXIT_CONDITIONS:
     description: >-
       The cycle completed but with notable issues. Possible causes:
       verification passed but with warnings, the committed work is narrower
-      than intended due to scope reduction, or discoveries logged in
-      progress state suggests the next cycle may face blockers.
+      than intended due to scope reduction, or durable discoveries recorded in
+      progress state suggest the next cycle may face blockers.
     exit_signal: flagged
   3:
     id: E3

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

@@ -3,9 +3,10 @@ VALIDATION:
     id: V1
     rule: verified_field_mandatory
     description: >-
-      Every progress entity record MUST have a verified field. The field
-      carries either observed output from the primary entrypoint, an allowlisted
-      N/A tag, or a free-form rationale of at least 8 words.
+      Every progress entity record appended by Build MUST have a non-empty
+      verified field. The field carries either observed output from the primary
+      entrypoint, an allowlisted N/A tag, or a free-form rationale of at least 8
+      words.
     severity: critical
     checks:
       - "Every cycle entry has a verified field"
@@ -16,10 +17,15 @@ VALIDATION:
     description: >-
       Build executes exactly one cycle per invocation. After logging required
       artifacts (Step 7) and committing once (Step 8), the capability MUST stop.
-      Multiple cycles require separate invocations or an explicit user request.
+      The typed progress_write_policy determines whether the cycle appends zero
+      or one progress record. Multiple cycles require separate invocations or an
+      explicit user request.
     severity: critical
     checks:
-      - "Only one progress entity is appended per invocation"
+      - "At most one progress entity is appended per invocation"
+      - "Durable outcomes needed by future work may append one verified record"
+      - "Required glossary caveats and plan-completion sweeps append one verified record"
+      - "Attempt-only cycles with no durable project truth append no record"
   3:
     id: V3
     rule: no_remote_push
@@ -41,14 +47,16 @@ VALIDATION:
       - "Vision artifact not modified outside brainstorm"
   5:
     id: V5
-    rule: consecutive_failure_guard
+    rule: attempt_history_authority
     description: >-
-      If the last 3 bounded progress records all report failed cycles, build
-      MUST stop and surface the pattern to the user. Do not attempt a 4th
-      consecutive cycle on the same failing problem.
+      Build MUST NOT reconstruct task or release attempt history from progress.
+      Plan evaluations own task attempts, while qualification and publication
+      receipts own release attempts and retry state. Missing retry state does
+      not authorize an attempt-only progress record.
     severity: critical
     checks:
-      - "Failure pattern checked before cycle start"
+      - "Progress is not used as task or release attempt history"
+      - "Retry state comes only from its owning plan or receipt authority"
   6:
     id: V6
     rule: artifact_path_resolution

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

@@ -705,12 +705,15 @@ LIFECYCLE_CONTRACT:
       - packages/cli/src/cli/commands/prime/*.ts
       - packages/cli/src/cli/capabilityContext/*.ts
       - packages/cli/src/cli/contracts/orientationState.ts
+      - packages/cli/src/cli/migrationRequired.ts
       - packages/cli/src/cli/startupCompletenessContract.ts
       - packages/cli/src/hooks/sessionStart.ts
       - packages/cli/src/eval/evalSkills.ts
+      - packages/cli/src/state/stateMode.ts
     writers:
       - packages/cli/src/state/write/*.ts
       - packages/cli/src/state/entityStorage.ts
+      - packages/cli/src/state/entityPublicationContext.ts
       - packages/cli/src/cli/commands/state/write.ts
     migrators:
       - packages/cli/src/upgrade/migrateArtifacts*.ts

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

@@ -1,8 +1,9 @@
 # Progress Artifact Schema
 #
-# Cycle-by-cycle operational log for build. Each entry records what happened
-# in one development cycle: phase, work done, discoveries, verification,
-# next steps, and context envelope.
+# Durable project-outcome log for build. A Build invocation can produce zero or
+# one entry. The typed writer's progress_write_policy decides whether future
+# work needs the outcome or a governed glossary caveat. Attempt-only evidence
+# stays outside progress.
 #
 # The optional glossary_caveat envelope, Build writer, and bounded prime reader
 # are active. Build remains the sole progress producer; Plan may only emit the
@@ -42,8 +43,8 @@ meta:
   name: progress
   version: "1.0.0"
   description: >-
-    Cycle-by-cycle operational log. Produced by build. Consumed by
-    capabilities that need recent work history and verification evidence.
+    Durable project-outcome log. Produced by build. Consumed by capabilities
+    that need recent project truth and verification evidence.
   artifact_type: agent_facing
   path: ".agentera/progress.yaml"
   authority: legacy_migration_input_only
@@ -59,6 +60,7 @@ ENTITY_AUTHORITY:
     list: npx -y agentera@next state progress list --format json
     get: npx -y agentera@next state progress get --id ID --format json
   mutation: npx -y agentera@next state progress explain --verb append --format json
+  write_policy: input_schema.semantics.progress_write_policy
   direct_file_edits: forbidden
   legacy_schema_below: migration_input_only
   semantic_recency:
@@ -141,7 +143,7 @@ COMPACTION:
       use the direct state get contract.
   5:
     id: PX5
-    trigger: "When build writes a new cycle entry"
+    trigger: "When build writes a new durable outcome entry"
     description: >-
       Compaction runs when the producing skill writes a new entry.
       If >10 full-detail entries exist and their numbered archives verify,

package/dist/capabilities/build/instructions.js

@@ -6,7 +6,7 @@ export default instructions
 
 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 is the sole owner of explicitly confirmed project terminology publication through \`agentera state glossary publish --input REQUEST\`. Glossary publication records the approval and shared entry atomically; it does not authorize glossary lookup, personal-profile mutation, or docs-mapping mutation. Build reads \`capability_context.startup.outcome\` and availability from \`agentera prime --context build --format json\`; use a deferred row's exact \`detail_command\` for detail. When no current executable plan exists, explicit transient work may instead start through \`agentera prime --context build --input <file|-> --format json\` with an \`agentera.buildExecutionRequest.v1\` mapping containing exactly \`schema_version\`, \`scope\`, and \`acceptance\`. This input is bounded, read-only, never persists or creates plan state, and conflicts with current plan-owned execution. Read profile grounding only from the \`content\` returned by \`agentera report profile-grounding --format json\` when its shared validity is \`valid\`; preserve exact absent or repair-needed recovery and never direct-read PROFILE.md. The grounding command excludes the owned personal Glossary section and fails closed on invalid sources. Root \`TODO.md\` and \`CHANGELOG.md\` remain capability-owned editorial files.
+Build reads whether progress is allowed or required from the \`guidance\` and \`input_schema.semantics.progress_write_policy\` returned by \`agentera state progress explain --verb append --format json\`. Required cases append through the typed writer; allowed durable outcomes may append when future work needs them. Build advances a plan task with its bare ID through \`agentera state plan set-status --id ID\`, and is the sole owner of explicitly confirmed project terminology publication through \`agentera state glossary publish --input REQUEST\`. Glossary publication records the approval and shared entry atomically; it does not authorize glossary lookup, personal-profile mutation, or docs-mapping mutation. Build reads \`capability_context.startup.outcome\` and availability from \`agentera prime --context build --format json\`; use a deferred row's exact \`detail_command\` for detail. When no current executable plan exists, explicit transient work may instead start through \`agentera prime --context build --input <file|-> --format json\` with an \`agentera.buildExecutionRequest.v1\` mapping containing exactly \`schema_version\`, \`scope\`, and \`acceptance\`. This input is bounded, read-only, never persists or creates plan state, and conflicts with current plan-owned execution. Read profile grounding only from the \`content\` returned by \`agentera report profile-grounding --format json\` when its shared validity is \`valid\`; preserve exact absent or repair-needed recovery and never direct-read PROFILE.md. The grounding command excludes the owned personal Glossary section and fails closed on invalid sources. Root \`TODO.md\` and \`CHANGELOG.md\` remain capability-owned editorial files.
 
 ## Workflow phases: The cycle`)
     .replaceAll("--number N", "--id ID")
@@ -26,7 +26,7 @@ When autonomous or no-pause execution cannot resolve required review, do not use
 Advice, tension, clarification, and caveat lifecycle never call \`agentera state glossary publish\`, create or reuse an approval, replace proposal-digest confirmation, satisfy decisions or plan state, or grant Discuss or Audit publication authority. Explicit project publication remains the separate Build-owned digest-confirmed operation.`)
     .replaceAll("progress.yaml aggregate cycle entry", "progress entity record")
     .replace("Every cycle runs the effective profile.", "Every cycle uses only the sanitized non-glossary profile content returned by `agentera report profile-grounding --format json`.")
-    .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("**Dual-write**: build maintains `.agentera/progress.yaml` and root `CHANGELOG.md`.", "Build conditionally 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")
     .replace("orient through log, exit signal reported", "orient through commit, exit signal reported")
@@ -36,10 +36,10 @@ Advice, tension, clarification, and caveat lifecycle never call \`agentera state
 
 **Before writing**, run \`agentera check lint --artifact <artifact> --text "<draft>"\` (or \`--file <path>\`) on the draft entry to check verbosity overruns, abstraction creep, and filler accumulation. Max 3 revision attempts. Flag with \`[post-audit-flagged]\` if still failing.
 
-Build records entity progress through the typed writer and maintains root \`CHANGELOG.md\` separately. Complete every required artifact update before committing so implementation, tests, and cycle state land together.
+Build conditionally records entity progress through the typed writer and maintains root \`CHANGELOG.md\` separately. Complete every required artifact update before committing so implementation, tests, and cycle state land together.
 
 - **TODO.md**: add newly discovered open issues in severity bands with \`- [ ]\`. Move completed work to \`## ✓ Resolved\` as \`- [x]\` with a resolution summary.
-- **progress**: write one YAML/JSON cycle mapping and run \`agentera state progress append --input <path|-> --format json\`. The writer assigns \`id\`, \`artifact\`, and \`publication_order\`, validates the record, atomically publishes one entity, and returns post-write state. Record-content flags are retired.
+- **progress**: run \`agentera state progress explain --verb append --format json\` and apply its \`progress_write_policy\`. If it requires progress, write one YAML/JSON cycle mapping and run \`agentera state progress append --input <path|-> --format json\`. If it only allows progress, write at most one record when future work needs the durable outcome as a milestone. Otherwise make no progress write. Every appended record has a non-empty \`verified\` field. The writer assigns \`id\`, \`artifact\`, and \`publication_order\`, validates the record, atomically publishes one entity, and returns post-write state. Record-content flags are retired.
 - **CHANGELOG.md**: append a one-line entry under \`## [Unreleased]\`.
 - **plan**: when a plan task closes, run \`agentera state plan set-status --id ID --status complete --format json\` rather than editing the plan directly.
 
@@ -53,4 +53,7 @@ Types: \`feat\`, \`fix\`, \`docs\`, \`refactor\`, \`chore\`, \`test\`. Include i
 
 If the current task is a version bump: read \`.agentera/docs.yaml\` for the \`versioning\` section. Update every file in \`version_files\` before committing.
 
-Then stop. One cycle complete.`);
+Then stop. One cycle complete.`)
+    .replace("- `artifact_update_requirements`: plan, TODO, changelog, and progress update obligations\n- `changelog_boundary`", "- `artifact_update_requirements`: plan, TODO, changelog, and progress update obligations\n- `progress_logging_requirements`: required, conditional, or absent progress status plus the authoritative writer policy and guidance command\n- `changelog_boundary`")
+    .replace("1. 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", "1. Log a durable blocker in TODO.md with context and the decision needed\n2. Apply the typed progress writer guidance; do not record attempt-only detail when no durable project truth changed\n3. Pick different work and complete a full cycle on that instead")
+    .replace("Before 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.", "Do not reconstruct attempt or retry history from progress. Plan evaluation owns task attempts, and qualification or publication receipts own release attempts. Use those authorities when explicit retry state is available; absence of retry state is not evidence of a progress record.");

package/dist/cli/capabilityContext/build.js

@@ -8,6 +8,7 @@ import { planLifecycleState } from "../planLifecycleState.js";
 import { discoverProjectVerification } from "./projectVerification.js";
 import { deferredStartupFamilies } from "./startupAggregation.js";
 import { preCutoverCommand } from "../preCutoverCommand.js";
+import { progressWritePolicy } from "../../state/progressWritePolicy.js";
 const TRANSIENT_BUILD_INPUT_COMMAND = preCutoverCommand("prime --context build --input <file|-> --format json");
 const TRANSIENT_BUILD_STDIN_COMMAND = preCutoverCommand("prime --context build --input - --format json");
 function transientSourceProvenance(request, field) {
@@ -155,10 +156,16 @@ export function buildExecutionContext(capability, schemas, plan, progress, healt
         };
     const artifactUpdateRequirements = buildArtifactUpdateRequirements(plan, docs);
     if (buildRequest !== null) {
-        artifactUpdateRequirements.required_families = ["progress", "todo", "changelog"];
+        artifactUpdateRequirements.required_families = ["todo", "changelog"];
+        artifactUpdateRequirements.conditional_families = ["progress"];
         artifactUpdateRequirements.plan_status_update_required = false;
         artifactUpdateRequirements.policy = "Transient no-plan work does not create, mutate, or require plan state.";
     }
+    const progressRequirement = archiveOnly
+        ? "none"
+        : mode === "completed_plan_sweep"
+            ? "required"
+            : "conditional";
     return {
         capability: "build",
         mode,
@@ -197,8 +204,10 @@ export function buildExecutionContext(capability, schemas, plan, progress, healt
         },
         artifact_update_requirements: artifactUpdateRequirements,
         progress_logging_requirements: {
-            append_cycle: buildRequest !== null || !archiveOnly,
-            verified_field_mandatory: true,
+            requirement: progressRequirement,
+            verified_field_mandatory_when_appended: true,
+            policy: progressWritePolicy(),
+            guidance_command: preCutoverCommand("state progress explain --verb append --format json"),
             latest_progress_verification_pointer: progressVerification.latest_progress_verification_pointer ?? null,
             source_provenance: sourceProvenance("progress", STATE_FAMILY_LIST_COMMANDS.progress),
         },

package/dist/cli/capabilityContext/planState.js

@@ -168,15 +168,19 @@ export function buildArtifactUpdateRequirements(plan, docs) {
     const mapping = asList(docs.mapping);
     const mapped = mapping.filter((e) => e && typeof e === "object" && e.artifact).map((e) => e.artifact);
     const archiveOnly = Boolean(plan.exists) && plan.active === false;
+    const completionSweep = plan.active === true && Boolean(plan.complete_plan);
     return {
-        required_families: archiveOnly ? [] : ["plan", "progress", "todo", "changelog"],
+        required_families: archiveOnly
+            ? []
+            : ["plan", "todo", "changelog", ...(completionSweep ? ["progress"] : [])],
+        conditional_families: archiveOnly || completionSweep ? [] : ["progress"],
         protected_families: ["vision", "objective", "profile", "installed_app"],
         docs_mapping_available: Boolean(docs.exists && mapping.length > 0),
         mapped_artifacts: mapped,
         plan_status_update_required: plan.active === true,
         policy: archiveOnly
             ? "Archived plan history is non-executable and requires no execution artifact updates."
-            : "Update execution artifacts during the cycle; do not mutate protected state without explicit approval.",
+            : "Update required execution artifacts during the cycle; evaluate conditional progress through its typed writer guidance and do not mutate protected state without explicit approval.",
         source_provenance: sourceProvenance("docs", STATE_FAMILY_FALLBACK_COMMANDS.docs, "summary.mapping"),
     };
 }

package/dist/cli/capabilityContext/startupAggregation.js

@@ -50,7 +50,7 @@ export function deferredStartupFamilies(contract) {
  * only through `agentera schema`, never through a startup payload.
  */
 export function startupAggregation(contract, health, cutover = null, todoReconciliation = null) {
-    const cutoverRequired = cutover?.status !== undefined && cutover.status !== "complete";
+    const cutoverRequired = cutover?.status === "required" || cutover?.status === "invalid_lifecycle";
     const reconciliationRequired = todoReconciliation?.status === "action_required";
     const blocked = cutoverRequired || reconciliationRequired || (typeof contract.schema_error === "string" && contract.schema_error.length > 0);
     const degraded = health.startup_outcome === "degraded";

package/dist/cli/commands/doctor.js

@@ -121,7 +121,7 @@ export function renderDoctorStatus(status, retiredResources) {
     }
     else if (unsafeInactiveTodo) {
         lines.push("");
-        lines.push("Next: complete the owner correction and replan before any TODO mutation.");
+        lines.push("Next: supply the complete owner mapping, preview the reported correction, then use its exact apply_command.");
     }
     else if (todoReconciliation) {
         lines.push("");

package/dist/cli/commands/prime/briefOrientation.js

@@ -732,7 +732,6 @@ function degradedBriefEnvelope(payload, budget, attemptedBytes, mode) {
         budget_utf8_bytes: budget,
         projection: "degraded",
         attempted_utf8_bytes: attemptedBytes,
-        path_diagnostics_recovery: PATH_DIAGNOSTICS_RECOVERY,
         error: {
             class: "brief_output_budget",
             message: "the configured budget cannot contain the detailed recovery envelope",