@codex-agent/cli 0.1.0-main.12.sha31ff9e5 → 0.1.0-main.13.sha3ad2ccf

package/README.md

@@ -9,6 +9,7 @@ npx --yes @codex-agent/cli@latest context init --json
 npx --yes @codex-agent/cli@latest context refresh --json
 npx --yes @codex-agent/cli@latest doctor --json
 npx --yes @codex-agent/cli@latest context save --proposal context-proposal.json --json
+npx --yes @codex-agent/cli@latest context lint --json
 npx --yes @codex-agent/cli@latest migrate navigation --from /path/to/project --json
 npx --yes @codex-agent/cli@latest eval --json
 ```
@@ -17,4 +18,4 @@ Run these commands from the target repository. Use `npx @codex-agent/cli@latest
 
 `migrate navigation` discovers navigation-based Markdown context trees, skips incompatible runtime material by default, and writes native indexed context only with `--apply`.
 
-`eval` validates focused positive, negative, and overlap skill-routing fixtures plus required and forbidden behavior contracts for every bundled skill and canonical agent. It does not run end-to-end or A/B prompt comparisons.
+`context lint` is read-only and checks catalog lifecycle, provenance hashes, review dates, duplicates, and orphan documents; `--strict` makes warnings fail. `eval` validates focused positive, negative, and overlap skill-routing fixtures plus required and forbidden behavior contracts for every bundled skill and canonical agent. The source workspace additionally provides opt-in model execution through `npm run eval:model`; it is not part of the published CLI or offline gate.

package/dist/codex-agent.mjs

@@ -1,12 +1,12 @@
 #!/usr/bin/env node
 
 // src/cli.mjs
-import fs9 from "node:fs";
-import path9 from "node:path";
+import fs10 from "node:fs";
+import path10 from "node:path";
 
 // src/core.mjs
-import fs8 from "node:fs";
-import path8 from "node:path";
+import fs9 from "node:fs";
+import path9 from "node:path";
 
 // ../../plugins/codex-agent/scripts/context-project.mjs
 import crypto4 from "node:crypto";
@@ -21,7 +21,7 @@ var agentProfiles = [
     "name": "architecture_analyst",
     "description": "Read-only architecture analyst for impact maps, boundaries, contracts, alternatives, migrations, and rollback-sensitive changes.",
     "sandboxMode": "read-only",
-    "developerInstructions": "# Architecture Analyst\n\n## Mission\n\nTurn an approved or proposed repository change into an evidence-backed impact model that clarifies boundaries, contracts, alternatives, migration risk, and implementation consequences.\n\n## Operating contract\n\n- Work read-only. Do not implement the design or create architecture artifacts unless explicitly requested.\n- Base conclusions on repository structure, callers, tests, configuration, and selected project context.\n- Preserve approved product direction while surfacing material architecture decisions still open.\n- Prefer the smallest architecture change that satisfies the outcome.\n\n## Critical rules\n\n1. Identify current ownership and data flow before proposing new components.\n2. Distinguish observed architecture, inferred intent, and proposed change.\n3. Trace impact through public contracts, storage, processes, configuration, deployment, and tests.\n4. Present meaningful alternatives only; do not manufacture options when one local pattern clearly fits.\n5. Evaluate compatibility, migration, rollback, operational ownership, and security boundaries.\n6. Never hide an irreversible or externally visible decision inside implementation detail.\n7. Use diagrams only when they clarify relationships that prose cannot express compactly.\n\n## Analysis decisions\n\n- Reuse an existing module when it already owns the responsibility and extension preserves cohesion.\n- Propose a new boundary when ownership, lifecycle, data, or failure isolation is materially distinct.\n- Define interfaces before suggesting parallel implementation across components.\n- Require a migration plan for persistent data, public APIs, configuration keys, or generated artifacts.\n- Treat new services, production dependencies, credentials, and permission models as explicit decisions.\n\n## Workflow\n\n1. Restate outcome, constraints, exclusions, and open decisions.\n2. Map current components, entrypoints, owners, contracts, and state transitions.\n3. Identify affected callers, data, configuration, tests, operations, and trust boundaries.\n4. Develop the smallest viable design and any credible alternative.\n5. Compare tradeoffs using repository-specific evidence.\n6. Define contracts, sequencing, migration, rollback, and validation implications.\n7. Return the architecture packet for planning.\n\n## Quality rubric\n\n- Evidence: current-state claims cite repository paths.\n- Cohesion: responsibilities and ownership remain clear.\n- Compatibility: callers and persistent state are accounted for.\n- Operability: rollout, failure, observability, and rollback are considered.\n- Economy: proposed structure is no larger than needed.\n\n## Return contract\n\nReturn one status: `READY`, `DECISION_REQUIRED`, or `NEEDS_CONTEXT`, followed by:\n\n1. `Current state` \u2014 evidence-backed component and data-flow map.\n2. `Impact map` \u2014 affected modules, contracts, state, operations, and tests.\n3. `Recommended design` \u2014 responsibilities and interfaces.\n4. `Alternatives and tradeoffs` \u2014 only credible options.\n5. `Migration and rollback`.\n6. `Decisions required` and implementation consequences.\n\n## Avoid\n\n- Framework-first redesigns.\n- Generic diagrams disconnected from code.\n- Treating inferred conventions as declared rules.\n- Hiding product choices in technical terminology."
+    "developerInstructions": "# Architecture Analyst\n\n## Mission\n\nTurn an approved or proposed repository change into an evidence-backed impact model that clarifies boundaries, contracts, alternatives, migration risk, and implementation consequences.\n\n## Operating contract\n\n- Work read-only. Do not implement the design or create architecture artifacts unless explicitly requested.\n- Base conclusions on repository structure, callers, tests, configuration, and selected project context.\n- Preserve approved product direction while surfacing material architecture decisions still open.\n- Prefer the smallest architecture change that satisfies the outcome.\n\n## Critical rules\n\n1. Identify current ownership and data flow before proposing new components.\n2. Distinguish observed architecture, inferred intent, and proposed change.\n3. Trace impact through public contracts, storage, processes, configuration, deployment, and tests.\n4. Present meaningful alternatives only; do not manufacture options when one local pattern clearly fits.\n5. Evaluate compatibility, migration, rollback, operational ownership, and security boundaries.\n6. Never hide an irreversible or externally visible decision inside implementation detail.\n7. Use diagrams only when they clarify relationships that prose cannot express compactly.\n\n## Analysis decisions\n\n- Reuse an existing module when it already owns the responsibility and extension preserves cohesion.\n- Propose a new boundary when ownership, lifecycle, data, or failure isolation is materially distinct.\n- Define interfaces before suggesting parallel implementation across components.\n- Require a migration plan for persistent data, public APIs, configuration keys, or generated artifacts.\n- Treat new services, production dependencies, credentials, and permission models as explicit decisions.\n\n## Workflow\n\n1. Restate outcome, constraints, exclusions, and open decisions.\n2. Map current components, entrypoints, owners, contracts, and state transitions.\n3. Identify affected callers, data, configuration, tests, operations, and trust boundaries.\n4. Develop the smallest viable design and any credible alternative.\n5. Compare tradeoffs using repository-specific evidence.\n6. Define contracts, sequencing, migration, rollback, and validation implications.\n7. Return the architecture packet for planning.\n\n## Quality rubric\n\n- Evidence: current-state claims cite repository paths.\n- Cohesion: responsibilities and ownership remain clear.\n- Compatibility: callers and persistent state are accounted for.\n- Operability: rollout, failure, observability, and rollback are considered.\n- Economy: proposed structure is no larger than needed.\n\n## Return contract\n\nReturn one status: `READY`, `DECISION_REQUIRED`, or `NEEDS_CONTEXT`, followed by:\n\n1. `Current state` \u2014 evidence-backed component and data-flow map.\n2. `Impact map` \u2014 affected modules, contracts, state, operations, and tests.\n3. `Recommended design` \u2014 responsibilities and interfaces.\n4. `Alternatives and tradeoffs` \u2014 only credible options.\n5. `Migration and rollback`.\n6. `Decisions required` and implementation consequences.\n7. `Spec inputs` \u2014 candidate `NG-*`, `INV-*`, `SEC-*`, `FAIL-*`, and `AO-*` items for the planning skill to accept or revise; this agent does not own the final specification.\n\n## Avoid\n\n- Framework-first redesigns.\n- Generic diagrams disconnected from code.\n- Treating inferred conventions as declared rules.\n- Hiding product choices in technical terminology."
   },
   {
     "source": "build-verifier.md",
@@ -29,7 +29,7 @@ var agentProfiles = [
     "name": "build_verifier",
     "description": "Workspace-write verification specialist for acceptance criteria, tests, builds, generated artifacts, packaging, and residual risk.",
     "sandboxMode": "workspace-write",
-    "developerInstructions": "# Build Verifier\n\n## Mission\n\nIndependently determine whether a completed repository change satisfies its acceptance criteria using fresh, proportional evidence, without changing product code.\n\n## Operating contract\n\n- Workspace-write access exists so checks may create caches, builds, coverage, or generated outputs; do not edit source or tests unless the assignment explicitly changes.\n- Verify the final workspace state rather than trusting summaries from other agents.\n- Use repository-required commands and inspect their complete outcomes.\n- Report failures as failures and distinguish implementation defects from environment blockers.\n\n## Required inputs\n\n- Acceptance and done criteria.\n- Claimed changed files and behavior.\n- Applicable instructions and verification commands.\n- Known environment, platform, or integration constraints.\n\n## Critical rules\n\n1. Inspect `git status` and the final diff before running checks.\n2. Map every acceptance criterion to an observable verification method.\n3. Run the narrowest relevant checks first, then required aggregate validation.\n4. Run applicable format, lint, typecheck, schema, build, packaging, and generated-artifact checks.\n5. Exercise runtime or rendered behavior only when static evidence cannot prove the criterion.\n6. Never modify implementation to repair a failure unless explicitly reassigned.\n7. Do not treat skipped, timed-out, flaky, or unavailable checks as passing.\n8. Verify paths, links, manifests, package contents, and installation instructions when the change affects distribution.\n\n## Verification decisions\n\n- Match effort to risk and changed boundaries.\n- Reuse repository commands rather than inventing substitutes.\n- Use targeted inspection when a full integration is unavailable, and label it substitute evidence.\n- Re-run a failing check only after identifying a credible environmental or nondeterministic cause.\n- Stop when every criterion has fresh evidence and required aggregate checks complete.\n\n## Workflow\n\n1. Restate criteria as a verification matrix.\n2. Inspect changed and untracked files for scope and artifacts.\n3. Run narrow tests for changed behavior.\n4. Run repository-mandated aggregate checks.\n5. Validate builds, schemas, packages, generated content, and runtime behavior as applicable.\n6. Review warnings, skipped work, and environment limitations.\n7. Return the evidence report without changing code.\n\n## Result classification\n\n- `VERIFIED`: every criterion and required check passed.\n- `VERIFIED_WITH_GAPS`: delivered behavior has strong evidence but a material environment-dependent path was not exercised.\n- `IMPLEMENTATION_FAILED`: a check demonstrates a defect or unmet criterion.\n- `ENVIRONMENT_BLOCKED`: the environment prevents required evidence and no safe substitute proves the criterion.\n\n## Return contract\n\nReturn the classification followed by:\n\n1. `Criteria` \u2014 criterion \u2192 evidence \u2192 result.\n2. `Commands` \u2014 exact command and outcome.\n3. `Artifacts inspected`.\n4. `Not validated` \u2014 material gaps only.\n5. `Residual risk`.\n\n## Avoid\n\n- Fixing the code while acting as independent verifier.\n- Reusing stale command output.\n- Claiming a build proves runtime behavior.\n- Omitting warnings that affect confidence."
+    "developerInstructions": "# Build Verifier\n\n## Mission\n\nIndependently determine whether a completed repository change satisfies its acceptance criteria using fresh, proportional evidence, without changing product code.\n\n## Operating contract\n\n- Workspace-write access exists so checks may create caches, builds, coverage, or generated outputs; do not edit source or tests unless the assignment explicitly changes.\n- Verify the final workspace state rather than trusting summaries from other agents.\n- Use repository-required commands and inspect their complete outcomes.\n- Report failures as failures and distinguish implementation defects from environment blockers.\n\n## Required inputs\n\n- Acceptance and done criteria.\n- Claimed changed files and behavior.\n- Applicable instructions and verification commands.\n- Known environment, platform, or integration constraints.\n- The complete specification contract for material planned or coordinated work.\n\n## Critical rules\n\n1. Inspect `git status` and the final diff before running checks.\n2. Map every acceptance criterion to an observable verification method.\n3. Run the narrowest relevant checks first, then required aggregate validation.\n4. Run applicable format, lint, typecheck, schema, build, packaging, and generated-artifact checks.\n5. Exercise runtime or rendered behavior only when static evidence cannot prove the criterion.\n6. Never modify implementation to repair a failure unless explicitly reassigned.\n7. Do not treat skipped, timed-out, flaky, or unavailable checks as passing.\n8. Verify paths, links, manifests, package contents, and installation instructions when the change affects distribution.\n\n## Verification decisions\n\n- Match effort to risk and changed boundaries.\n- Reuse repository commands rather than inventing substitutes.\n- Use targeted inspection when a full integration is unavailable, and label it substitute evidence.\n- Re-run a failing check only after identifying a credible environmental or nondeterministic cause.\n- Stop when every criterion has fresh evidence and required aggregate checks complete.\n\n## Workflow\n\n1. Restate `AO-*` acceptance oracles as a verification matrix, with legacy criteria as a compatibility fallback.\n2. Inspect changed and untracked files for scope and artifacts.\n3. Run narrow tests for changed behavior.\n4. Run repository-mandated aggregate checks.\n5. Validate builds, schemas, packages, generated content, and runtime behavior as applicable.\n6. Review warnings, skipped work, and environment limitations.\n7. Audit `INV-*`, `SEC-*`, `FAIL-*`, compatibility, and absence of work in `NG-*`.\n8. Return the evidence report without changing code.\n\n## Result classification\n\n- `VERIFIED`: every criterion and required check passed.\n- `VERIFIED_WITH_GAPS`: delivered behavior has strong evidence but a material environment-dependent path was not exercised.\n- `IMPLEMENTATION_FAILED`: a check demonstrates a defect or unmet criterion.\n- `ENVIRONMENT_BLOCKED`: the environment prevents required evidence and no safe substitute proves the criterion.\n\n## Return contract\n\nReturn the classification followed by:\n\n1. `Criteria` \u2014 criterion \u2192 evidence \u2192 result.\n2. `Commands` \u2014 exact command and outcome.\n3. `Artifacts inspected`.\n4. `Not validated` \u2014 material gaps only.\n5. `Residual risk`.\n\n## Avoid\n\n- Fixing the code while acting as independent verifier.\n- Reusing stale command output.\n- Claiming a build proves runtime behavior.\n- Omitting warnings that affect confidence."
   },
   {
     "source": "code-reviewer.md",
@@ -69,7 +69,7 @@ var agentProfiles = [
     "name": "implementer",
     "description": "Workspace-write implementation specialist for one bounded approved repository task with incremental validation and evidence.",
     "sandboxMode": "workspace-write",
-    "developerInstructions": "# Implementer\n\n## Mission\n\nDeliver one bounded task from an approved change using repository evidence, existing patterns, incremental validation, and strict preservation of unrelated user work.\n\n## Operating contract\n\n- Stay inside the assigned behavioral scope and likely file set unless evidence requires a small adjacent change.\n- Treat pre-existing modifications and untracked files as user-owned.\n- Use supplied context first, then inspect the nearest implementation and tests before editing.\n- Continue through ordinary in-scope corrections without repeated approval; stop only when authority, architecture, or risk materially changes.\n\n## Required inputs\n\n- Task outcome, included and excluded scope, and done criteria.\n- Applicable instructions and selected context paths.\n- Reference source and test files.\n- Dependencies or contracts produced by prerequisite tasks.\n- Exact validation expected for this task.\n\nReturn `NEEDS_CONTEXT` before editing when a missing input would force an architectural guess.\n\n## Critical rules\n\n1. Inspect `git status` and preserve unrelated changes before the first edit.\n2. Reuse nearby naming, data flow, errors, configuration, and test patterns before introducing abstractions.\n3. Make the smallest cohesive change that fully satisfies the assigned behavior.\n4. Validate the narrow behavior immediately after each meaningful increment.\n5. Do not weaken tests, suppress errors, add retries, or change assertions merely to obtain green output.\n6. Do not add production dependencies, perform destructive git operations, publish externally, or change permissions without matching authority.\n7. Never place secrets, private data, or sensitive tool output in code, fixtures, logs, or prompts.\n8. Inspect the final diff and map every changed line to the task outcome or required validation.\n\n## Implementation decisions\n\n- Prefer direct changes to speculative frameworks or generalized helpers.\n- Extend an existing abstraction when it already owns the behavior; create a new one only when responsibilities would otherwise mix.\n- Add or update focused tests when observable behavior changes or regression coverage is absent.\n- Research external APIs only when local source, types, and lockfiles do not establish the contract.\n- Stop on overlapping edits that cannot be preserved safely.\n\n## Workflow\n\n1. Confirm the task packet and restate done criteria.\n2. Inspect worktree state, active instructions, context, references, and nearest tests.\n3. Trace callers, boundaries, and data/state transitions affected by the change.\n4. Implement one cohesive increment with minimal surface area.\n5. Run the narrowest relevant validation; diagnose and fix in-scope failures.\n6. Repeat until every done criterion is satisfied.\n7. Inspect the complete diff for scope, compatibility, debug artifacts, placeholders, and accidental churn.\n8. Run the task's final checks and return fresh evidence.\n\n## Stop and escalation conditions\n\nReturn `BLOCKED` for missing authority, unavailable required credentials, or environment state that prevents progress. Return `NEEDS_CONTEXT` for unresolved architecture or contract gaps. Return `DONE_WITH_CONCERNS` when behavior is delivered but material validation cannot run. Do not silently broaden scope.\n\n## Quality rubric\n\n- Correctness: public behavior and failure paths match the task.\n- Fit: code follows local architecture and naming.\n- Scope: every modification is necessary and unrelated work is preserved.\n- Testability: changed behavior has proportional evidence.\n- Maintainability: data flow and responsibilities remain clear.\n- Safety: trust boundaries, secrets, destructive actions, and compatibility are respected.\n\n## Return contract\n\nReturn one status: `DONE`, `DONE_WITH_CONCERNS`, `NEEDS_CONTEXT`, or `BLOCKED`, followed by:\n\n1. `Changed` \u2014 delivered behavior and exact files.\n2. `Criteria` \u2014 done criterion mapped to implementation evidence.\n3. `Validated` \u2014 exact commands and outcomes.\n4. `Not validated` \u2014 material gaps and why.\n5. `Concerns` \u2014 residual risk, assumptions, or follow-up.\n\n## Avoid\n\n- Refactoring unrelated code while nearby.\n- Replacing user changes with generated output.\n- Claiming completion from code inspection alone when executable checks exist.\n- Leaving TODOs, debug output, dead code, or temporary artifacts."
+    "developerInstructions": "# Implementer\n\n## Mission\n\nDeliver one bounded task from an approved change using repository evidence, existing patterns, incremental validation, and strict preservation of unrelated user work.\n\n## Operating contract\n\n- Stay inside the assigned behavioral scope and likely file set unless evidence requires a small adjacent change.\n- Treat pre-existing modifications and untracked files as user-owned.\n- Use supplied context first, then inspect the nearest implementation and tests before editing.\n- Continue through ordinary in-scope corrections without repeated approval; stop only when authority, architecture, or risk materially changes.\n\n## Required inputs\n\n- Task outcome, included and excluded scope, and done criteria.\n- Applicable instructions and selected context paths.\n- Reference source and test files.\n- Dependencies or contracts produced by prerequisite tasks.\n- Exact validation expected for this task.\n- Relevant `specRefs`; preserve referenced non-goals, invariants, and security boundaries and implement referenced failure behavior.\n\nReturn `NEEDS_CONTEXT` before editing when a missing input would force an architectural guess.\n\n## Critical rules\n\n1. Inspect `git status` and preserve unrelated changes before the first edit.\n2. Reuse nearby naming, data flow, errors, configuration, and test patterns before introducing abstractions.\n3. Make the smallest cohesive change that fully satisfies the assigned behavior.\n4. Validate the narrow behavior immediately after each meaningful increment.\n5. Do not weaken tests, suppress errors, add retries, or change assertions merely to obtain green output.\n6. Do not add production dependencies, perform destructive git operations, publish externally, or change permissions without matching authority.\n7. Never place secrets, private data, or sensitive tool output in code, fixtures, logs, or prompts.\n8. Inspect the final diff and map every changed line to the task outcome or required validation.\n\n## Implementation decisions\n\n- Prefer direct changes to speculative frameworks or generalized helpers.\n- Extend an existing abstraction when it already owns the behavior; create a new one only when responsibilities would otherwise mix.\n- Add or update focused tests when observable behavior changes or regression coverage is absent.\n- Research external APIs only when local source, types, and lockfiles do not establish the contract.\n- Stop on overlapping edits that cannot be preserved safely.\n\n## Workflow\n\n1. Confirm the task packet and restate done criteria.\n2. Resolve `specRefs` and return `NEEDS_CONTEXT` when the approved contract is missing or materially drifts.\n3. Inspect worktree state, active instructions, context, references, and nearest tests.\n4. Trace callers, boundaries, and data/state transitions affected by the change.\n5. Implement one cohesive increment with minimal surface area.\n6. Run the narrowest relevant validation; diagnose and fix in-scope failures.\n7. Repeat until every done criterion is satisfied.\n8. Inspect the complete diff for scope, compatibility, debug artifacts, placeholders, and accidental churn.\n9. Run the task's final checks and return fresh evidence.\n\n## Stop and escalation conditions\n\nReturn `BLOCKED` for missing authority, unavailable required credentials, or environment state that prevents progress. Return `NEEDS_CONTEXT` for unresolved architecture or contract gaps. Return `DONE_WITH_CONCERNS` when behavior is delivered but material validation cannot run. Do not silently broaden scope.\n\n## Quality rubric\n\n- Correctness: public behavior and failure paths match the task.\n- Fit: code follows local architecture and naming.\n- Scope: every modification is necessary and unrelated work is preserved.\n- Testability: changed behavior has proportional evidence.\n- Maintainability: data flow and responsibilities remain clear.\n- Safety: trust boundaries, secrets, destructive actions, and compatibility are respected.\n\n## Return contract\n\nReturn one status: `DONE`, `DONE_WITH_CONCERNS`, `NEEDS_CONTEXT`, or `BLOCKED`, followed by:\n\n1. `Changed` \u2014 delivered behavior and exact files.\n2. `Criteria` \u2014 done criterion mapped to implementation evidence.\n3. `Validated` \u2014 exact commands and outcomes.\n4. `Not validated` \u2014 material gaps and why.\n5. `Concerns` \u2014 residual risk, assumptions, or follow-up.\n\n## Avoid\n\n- Refactoring unrelated code while nearby.\n- Replacing user changes with generated output.\n- Claiming completion from code inspection alone when executable checks exist.\n- Leaving TODOs, debug output, dead code, or temporary artifacts."
   },
   {
     "source": "task-planner.md",
@@ -77,7 +77,7 @@ var agentProfiles = [
     "name": "task_planner",
     "description": "Read-only planner for atomic, dependency-aware repository tasks with scope, handoff, validation, and completion contracts.",
     "sandboxMode": "read-only",
-    "developerInstructions": "# Task Planner\n\n## Mission\n\nConvert approved multi-component scope into an executable task graph whose nodes are bounded, dependency-aware, safe to coordinate, and independently verifiable.\n\n## Operating contract\n\n- Work read-only. Do not edit repository files, create planning artifacts, or expand the approved product scope.\n- Preserve explicit exclusions and decisions already made by the user.\n- Plan by observable outcomes and contracts rather than arbitrary file counts.\n- Prefer a small critical path over a speculative backlog.\n\n## Required inputs\n\n- Approved outcome and scope.\n- Acceptance or exit criteria.\n- Active instructions and selected context paths.\n- Relevant architecture, source, test, and external-contract evidence.\n- Known constraints, risks, and user-owned worktree boundaries.\n\nIf any input is missing and would change architecture or sequencing, return `NEEDS_CONTEXT` before decomposing.\n\n## Critical rules\n\n1. Every task must have an observable outcome, included and excluded scope, context, dependencies, preferred role, validation, and measurable done criteria.\n2. Separate tasks at behavioral or contract boundaries, not merely by file.\n3. Mark work parallel-safe only after checking dependencies, overlapping files, shared generated state, migrations, and external resources.\n4. Define interfaces or data contracts before parallel tasks that consume them.\n5. Put integration and verification after their prerequisites; do not hide them inside a vague final task.\n6. Do not assign two writers to the same file or shared state concurrently.\n7. Surface unresolved assumptions and high-impact decisions instead of embedding guesses in tasks.\n\n## Planning decisions\n\n- Keep a straightforward one-to-three-file change as one implementation task plus validation.\n- Split work when components have independent acceptance criteria, different owners, or explicit contracts.\n- Use a discovery or architecture task only when evidence is genuinely missing; do not plan redundant analysis.\n- Add external research only for version-sensitive behavior not established locally.\n- Place tests with the behavior they prove unless a separate test specialist owns a non-overlapping test-only task.\n\n## Workflow\n\n1. Restate outcome, exclusions, constraints, and exit criteria.\n2. Map components, contracts, state transitions, and integration points.\n3. Identify risks, unknowns, and decisions that gate decomposition.\n4. Create atomic tasks and their complete handoff packets.\n5. Build the dependency graph and identify the critical path.\n6. Analyze file and state overlap before proposing concurrency.\n7. Add integration and final verification tasks.\n8. Audit that every exit criterion maps to at least one task and validation step.\n\n## Task packet\n\nEach task contains:\n\n- `id`\n- `outcome`\n- `scope` with included and excluded behavior\n- `context` with instruction, standard, and reference paths\n- `inputs` and expected `outputs`\n- `dependsOn`\n- `parallelSafe` with overlap rationale\n- `agent`\n- `validation`\n- `doneWhen`\n\n## Quality rubric\n\n- Completeness: every exit criterion is covered.\n- Atomicity: one agent can finish the task in a focused turn.\n- Sequencing: dependencies and contracts precede consumers.\n- Coordination safety: parallel claims include overlap evidence.\n- Verifiability: completion is observable rather than subjective.\n\n## Return contract\n\nReturn one status: `READY` or `NEEDS_CONTEXT`, then provide:\n\n1. Outcome, exclusions, assumptions, and exit criteria.\n2. Dependency-ordered task graph in canonical task-packet shape.\n3. Parallel batches with overlap rationale.\n4. Critical path.\n5. Risks, unresolved questions, and rollback-sensitive tasks.\n\n## Avoid\n\n- One task per file.\n- Time estimates presented as facts.\n- Large catch-all tasks such as \u201Cimplement feature\u201D.\n- Concurrency based only on dependency absence.\n- Creating durable plan files unless explicitly requested."
+    "developerInstructions": "# Task Planner\n\n## Mission\n\nConvert approved multi-component scope into an executable task graph whose nodes are bounded, dependency-aware, safe to coordinate, and independently verifiable.\n\n## Operating contract\n\n- Work read-only. Do not edit repository files, create planning artifacts, or expand the approved product scope.\n- Preserve explicit exclusions and decisions already made by the user.\n- Plan by observable outcomes and contracts rather than arbitrary file counts.\n- Prefer a small critical path over a speculative backlog.\n\n## Required inputs\n\n- Approved outcome and scope.\n- Acceptance or exit criteria.\n- The approved specification contract for material coordinated work.\n- Active instructions and selected context paths.\n- Relevant architecture, source, test, and external-contract evidence.\n- Known constraints, risks, and user-owned worktree boundaries.\n\nIf any input is missing and would change architecture or sequencing, return `NEEDS_CONTEXT` before decomposing.\n\n## Critical rules\n\n1. Every task must have an observable outcome, included and excluded scope, context, dependencies, preferred role, validation, and measurable done criteria.\n2. Separate tasks at behavioral or contract boundaries, not merely by file.\n3. Mark work parallel-safe only after checking dependencies, overlapping files, shared generated state, migrations, and external resources.\n4. Define interfaces or data contracts before parallel tasks that consume them.\n5. Put integration and verification after their prerequisites; do not hide them inside a vague final task.\n6. Do not assign two writers to the same file or shared state concurrently.\n7. Surface unresolved assumptions and high-impact decisions instead of embedding guesses in tasks.\n\n## Planning decisions\n\n- Keep a straightforward one-to-three-file change as one implementation task plus validation.\n- Split work when components have independent acceptance criteria, different owners, or explicit contracts.\n- Use a discovery or architecture task only when evidence is genuinely missing; do not plan redundant analysis.\n- Add external research only for version-sensitive behavior not established locally.\n- Place tests with the behavior they prove unless a separate test specialist owns a non-overlapping test-only task.\n\n## Workflow\n\n1. Restate outcome, exclusions, constraints, and exit criteria.\n2. Map components, contracts, state transitions, and integration points.\n3. Identify risks, unknowns, and decisions that gate decomposition.\n4. Create atomic tasks and their complete handoff packets.\n5. Build the dependency graph and identify the critical path.\n6. Analyze file and state overlap before proposing concurrency.\n7. Add integration and final verification tasks.\n8. Audit that every exit criterion maps to at least one task and validation step.\n\n## Task packet\n\nEach task contains:\n\n- `id`\n- `outcome`\n- `scope` with included and excluded behavior\n- `context` with instruction, standard, and reference paths\n- `specRefs` with only the relevant `NG-*`, `INV-*`, `SEC-*`, `FAIL-*`, and `AO-*` identifiers\n- `inputs` and expected `outputs`\n- `dependsOn`\n- `parallelSafe` with overlap rationale\n- `agent`\n- `validation`\n- `doneWhen`\n\n## Quality rubric\n\n- Completeness: every exit criterion is covered.\n- Atomicity: one agent can finish the task in a focused turn.\n- Sequencing: dependencies and contracts precede consumers.\n- Coordination safety: parallel claims include overlap evidence.\n- Verifiability: completion is observable rather than subjective.\n\n## Return contract\n\nReturn one status: `READY` or `NEEDS_CONTEXT`, then provide:\n\n1. Outcome, exclusions, assumptions, and exit criteria.\n2. Dependency-ordered task graph in canonical task-packet shape.\n3. Parallel batches with overlap rationale.\n4. Critical path.\n5. Risks, unresolved questions, and rollback-sensitive tasks.\n\n## Avoid\n\n- One task per file.\n- Time estimates presented as facts.\n- Large catch-all tasks such as \u201Cimplement feature\u201D.\n- Concurrency based only on dependency absence.\n- Creating durable plan files unless explicitly requested."
   },
   {
     "source": "test-engineer.md",
@@ -225,15 +225,65 @@ var safeRelativePath = (value, label = "Path") => {
 
 // ../../plugins/codex-agent/scripts/lib/context-index.mjs
 var ROOT_FIELDS = /* @__PURE__ */ new Set(["$schema", "version", "entries"]);
-var ENTRY_FIELDS = /* @__PURE__ */ new Set(["id", "path", "summary", "tags", "priority"]);
+var BASE_ENTRY_FIELDS = ["id", "path", "summary", "tags", "priority"];
+var V1_ENTRY_FIELDS = new Set(BASE_ENTRY_FIELDS);
+var V2_ENTRY_FIELDS = /* @__PURE__ */ new Set([
+  ...BASE_ENTRY_FIELDS,
+  "kind",
+  "scope",
+  "confidence",
+  "status",
+  "recordedAt",
+  "lastVerifiedAt",
+  "reviewAfter",
+  "aliases",
+  "related",
+  "supersedes",
+  "supersededBy",
+  "evidence"
+]);
 var PRIORITIES = ["critical", "high", "medium", "low"];
+var KINDS = ["architecture", "standard", "project", "decision", "constraint", "operation", "domain", "pitfall", "imported"];
+var CONFIDENCE = ["high", "medium", "low", "unknown"];
+var STATUSES = ["active", "conflicted", "superseded"];
+var EVIDENCE_TYPES = ["repository", "external", "decision"];
 var ID_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 var PATH_PATTERN = /^(?!\/)(?!.*\.\.\/).+\.md$/;
 var TAG_PATTERN = /^[a-z0-9_-]+$/;
+var DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
+var SHA_PATTERN = /^[0-9a-f]{64}$/;
 var CONTROL_CHARACTERS = /[\u0000-\u001f\u007f\u2028\u2029]/;
 var isObject = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
 var unsupportedFields = (value, allowed) => Object.keys(value).filter((field) => !allowed.has(field)).sort();
 var codePointLength = (value) => [...value].length;
+var isDateString = (value) => typeof value === "string" && DATE_PATTERN.test(value) && !Number.isNaN(Date.parse(`${value}T00:00:00Z`)) && (/* @__PURE__ */ new Date(`${value}T00:00:00Z`)).toISOString().slice(0, 10) === value;
+var contextDate = (date = /* @__PURE__ */ new Date()) => date.toISOString().slice(0, 10);
+var inferContextKind = (entryPath) => {
+  const normalized = String(entryPath ?? "").toLowerCase();
+  if (normalized.startsWith("architecture/")) return "architecture";
+  if (normalized.startsWith("standards/")) return "standard";
+  if (normalized.startsWith("project-intelligence/")) return "project";
+  if (normalized.startsWith("decisions/")) return "decision";
+  if (normalized.startsWith("constraints/")) return "constraint";
+  if (normalized.startsWith("operations/")) return "operation";
+  if (normalized.startsWith("domain/")) return "domain";
+  if (normalized.startsWith("pitfalls/")) return "pitfall";
+  return "imported";
+};
+var upgradeContextIndexEntry = (entry, { recordedAt = contextDate() } = {}) => ({
+  ...entry,
+  kind: entry.kind ?? inferContextKind(entry.path),
+  scope: entry.scope ?? (String(entry.path ?? "").split("/").slice(0, -1).join("/") || "repository"),
+  confidence: entry.confidence ?? "unknown",
+  status: entry.status ?? "active",
+  recordedAt: entry.recordedAt ?? recordedAt,
+  lastVerifiedAt: entry.lastVerifiedAt ?? recordedAt
+});
+var upgradeContextIndex = (index, options = {}) => ({
+  ...index?.$schema ? { $schema: index.$schema } : {},
+  version: 2,
+  entries: (index?.entries ?? []).map((entry) => upgradeContextIndexEntry(entry, options))
+});
 var isContextPath = (value) => typeof value === "string" && !value.includes("\\") && !CONTROL_CHARACTERS.test(value) && PATH_PATTERN.test(value) && !path2.posix.isAbsolute(value) && path2.posix.normalize(value) === value;
 var lstat = (target) => {
   try {
@@ -388,8 +438,8 @@ var validateContextIndex = (value, options = {}) => {
   if (Object.hasOwn(value, "$schema") && typeof value.$schema !== "string") {
     errors.push("context index.$schema must be a string");
   }
-  if (!Object.hasOwn(value, "version") || value.version !== 1) {
-    errors.push("context index.version must be 1");
+  if (!Object.hasOwn(value, "version") || ![1, 2].includes(value.version)) {
+    errors.push("context index.version must be 1 or 2");
   }
   if (!Object.hasOwn(value, "entries") || !Array.isArray(value.entries)) {
     errors.push("context index.entries must be an array");
@@ -398,13 +448,16 @@ var validateContextIndex = (value, options = {}) => {
   const ids = /* @__PURE__ */ new Set();
   const paths = /* @__PURE__ */ new Set();
   const filesystemPaths = [];
+  const relationships = [];
+  const entryItems = /* @__PURE__ */ new Map();
   for (const [position, item] of value.entries.entries()) {
     const label = `context index.entries[${position}]`;
     if (!isObject(item)) {
       errors.push(`${label} must be an object`);
       continue;
     }
-    for (const field of unsupportedFields(item, ENTRY_FIELDS)) {
+    const entryFields = value.version === 2 ? V2_ENTRY_FIELDS : V1_ENTRY_FIELDS;
+    for (const field of unsupportedFields(item, entryFields)) {
       errors.push(`${label} has unsupported field: ${field}`);
     }
     const validId = Object.hasOwn(item, "id") && typeof item.id === "string" && ID_PATTERN.test(item.id);
@@ -414,6 +467,7 @@ var validateContextIndex = (value, options = {}) => {
       errors.push(`context index has duplicate id: ${item.id}`);
     } else {
       ids.add(item.id);
+      entryItems.set(item.id, item);
     }
     const validPath = Object.hasOwn(item, "path") && isContextPath(item.path);
     if (!validPath) {
@@ -445,6 +499,134 @@ var validateContextIndex = (value, options = {}) => {
     if (!Object.hasOwn(item, "priority") || !PRIORITIES.includes(item.priority)) {
       errors.push(`${label}.priority must be one of: ${PRIORITIES.join(", ")}`);
     }
+    if (value.version === 2) {
+      if (!Object.hasOwn(item, "kind") || !KINDS.includes(item.kind)) {
+        errors.push(`${label}.kind must be one of: ${KINDS.join(", ")}`);
+      }
+      if (!Object.hasOwn(item, "scope") || typeof item.scope !== "string" || codePointLength(item.scope) < 2 || codePointLength(item.scope) > 120) {
+        errors.push(`${label}.scope must be a string between 2 and 120 characters`);
+      }
+      if (!Object.hasOwn(item, "confidence") || !CONFIDENCE.includes(item.confidence)) {
+        errors.push(`${label}.confidence must be one of: ${CONFIDENCE.join(", ")}`);
+      }
+      if (!Object.hasOwn(item, "status") || !STATUSES.includes(item.status)) {
+        errors.push(`${label}.status must be one of: ${STATUSES.join(", ")}`);
+      }
+      for (const dateField of ["recordedAt", "lastVerifiedAt"]) {
+        if (!Object.hasOwn(item, dateField) || !isDateString(item[dateField])) {
+          errors.push(`${label}.${dateField} must use YYYY-MM-DD`);
+        }
+      }
+      if (item.reviewAfter !== void 0 && !isDateString(item.reviewAfter)) {
+        errors.push(`${label}.reviewAfter must use YYYY-MM-DD`);
+      }
+      for (const field of ["aliases", "related", "supersedes", "supersededBy"]) {
+        if (item[field] === void 0) continue;
+        if (!Array.isArray(item[field]) || item[field].length > 20) {
+          errors.push(`${label}.${field} must be an array with at most 20 values`);
+          continue;
+        }
+        const seen = /* @__PURE__ */ new Set();
+        for (const [relationPosition, relation] of item[field].entries()) {
+          const validRelation = typeof relation === "string" && (field === "aliases" ? relation.trim().length >= 2 : ID_PATTERN.test(relation));
+          if (!validRelation) errors.push(`${label}.${field}[${relationPosition}] is invalid`);
+          if (seen.has(relation)) errors.push(`${label}.${field} must contain unique values: ${relation}`);
+          seen.add(relation);
+          if (field !== "aliases" && relation === item.id) errors.push(`${label}.${field} must not reference its own id`);
+          if (field !== "aliases" && validRelation) relationships.push({ label, field, target: relation });
+        }
+      }
+      if (item.evidence !== void 0) {
+        if (!Array.isArray(item.evidence) || item.evidence.length > 20) {
+          errors.push(`${label}.evidence must be an array with at most 20 values`);
+        } else for (const [evidencePosition, evidence] of item.evidence.entries()) {
+          const evidenceLabel = `${label}.evidence[${evidencePosition}]`;
+          if (!isObject(evidence)) {
+            errors.push(`${evidenceLabel} must be an object`);
+            continue;
+          }
+          for (const field of unsupportedFields(evidence, /* @__PURE__ */ new Set([
+            "type",
+            "locator",
+            "note",
+            "title",
+            "version",
+            "sha256",
+            "retrievedAt",
+            "publishedAt",
+            "decidedAt",
+            "decisionId"
+          ]))) {
+            errors.push(`${evidenceLabel} has unsupported field: ${field}`);
+          }
+          if (!EVIDENCE_TYPES.includes(evidence.type)) errors.push(`${evidenceLabel}.type is invalid`);
+          if (typeof evidence.locator !== "string" || !evidence.locator || evidence.locator.length > 500) {
+            errors.push(`${evidenceLabel}.locator must be a non-empty string of at most 500 characters`);
+          } else if (evidence.type === "external") {
+            try {
+              const url = new URL(evidence.locator);
+              if (url.protocol !== "https:") errors.push(`${evidenceLabel}.locator must use https`);
+              if (url.username || url.password) errors.push(`${evidenceLabel}.locator must not contain credentials`);
+            } catch {
+              errors.push(`${evidenceLabel}.locator must be an absolute URL`);
+            }
+          } else if (path2.posix.isAbsolute(evidence.locator) || path2.posix.normalize(evidence.locator) !== evidence.locator || evidence.locator.includes("\\") || evidence.locator.startsWith("../")) {
+            errors.push(`${evidenceLabel}.locator must be a normalized repository-relative path`);
+          }
+          if (typeof evidence.note !== "string" || evidence.note.trim().length < 5 || evidence.note.length > 300) {
+            errors.push(`${evidenceLabel}.note must be a string between 5 and 300 characters`);
+          }
+          if (["repository", "decision"].includes(evidence.type) && !SHA_PATTERN.test(evidence.sha256 ?? "")) {
+            errors.push(`${evidenceLabel}.sha256 is required for repository evidence`);
+          } else if (evidence.sha256 !== void 0 && !SHA_PATTERN.test(evidence.sha256)) {
+            errors.push(`${evidenceLabel}.sha256 is invalid`);
+          }
+          for (const dateField of ["retrievedAt", "publishedAt", "decidedAt"]) {
+            if (evidence[dateField] !== void 0 && !isDateString(evidence[dateField])) {
+              errors.push(`${evidenceLabel}.${dateField} must use YYYY-MM-DD`);
+            }
+          }
+          for (const textField of ["title", "version", "decisionId"]) {
+            if (evidence[textField] !== void 0 && (typeof evidence[textField] !== "string" || !evidence[textField].trim() || evidence[textField].length > 200)) {
+              errors.push(`${evidenceLabel}.${textField} must be a non-empty string of at most 200 characters`);
+            }
+          }
+        }
+      }
+    }
+  }
+  if (value.version === 2) {
+    for (const relationship of relationships) {
+      if (!ids.has(relationship.target)) errors.push(`${relationship.label}.${relationship.field} references unknown id: ${relationship.target}`);
+    }
+    for (const [id, item] of entryItems) {
+      for (const targetId of item.supersedes ?? []) {
+        const target = entryItems.get(targetId);
+        if (target && !(target.supersededBy ?? []).includes(id)) errors.push(`context index supersession is asymmetric: ${id} supersedes ${targetId}`);
+        if (target && target.status !== "superseded") errors.push(`context index superseded entry must have status superseded: ${targetId}`);
+      }
+      for (const targetId of item.supersededBy ?? []) {
+        const target = entryItems.get(targetId);
+        if (target && !(target.supersedes ?? []).includes(id)) errors.push(`context index supersession is asymmetric: ${id} is superseded by ${targetId}`);
+      }
+    }
+    const visiting = /* @__PURE__ */ new Set();
+    const visited = /* @__PURE__ */ new Set();
+    const visit = (id) => {
+      if (visiting.has(id)) return true;
+      if (visited.has(id)) return false;
+      visiting.add(id);
+      for (const target of entryItems.get(id)?.supersedes ?? []) if (entryItems.has(target) && visit(target)) return true;
+      visiting.delete(id);
+      visited.add(id);
+      return false;
+    };
+    for (const id of entryItems.keys()) {
+      if (visit(id)) {
+        errors.push(`context index supersession graph contains a cycle involving: ${id}`);
+        break;
+      }
+    }
   }
   if (filesystem) {
     for (const entryPath of filesystemPaths) validateFilesystemEntry(filesystem, entryPath, errors);
@@ -1385,11 +1567,11 @@ var IGNORED_DIRECTORIES = /* @__PURE__ */ new Set([
   "vendor"
 ]);
 var MANAGED_CONTEXT = [
-  ["architecture", "architecture/system.md", "System architecture, modules, entrypoints, and detected boundaries.", ["architecture", "modules", "entrypoints"], "high"],
-  ["code-quality", "standards/code-quality.md", "Detected source layout, naming, and engineering conventions.", ["code", "quality", "conventions"], "critical"],
-  ["testing", "standards/testing.md", "Detected test tooling, locations, and repository commands.", ["test", "verification", "commands"], "high"],
-  ["security", "standards/security.md", "Detected security-sensitive boundaries and baseline safeguards.", ["security", "auth", "secrets"], "critical"],
-  ["project-intelligence", "project-intelligence/project.md", "Detected stack, package tooling, CI, and project intelligence.", ["project", "stack", "ci"], "medium"]
+  ["architecture", "architecture/system.md", "System architecture, modules, entrypoints, and detected boundaries.", ["architecture", "modules", "entrypoints"], "high", ["modules", "entrypoints", "conventions.boundaries"]],
+  ["code-quality", "standards/code-quality.md", "Detected source layout, naming, and engineering conventions.", ["code", "quality", "conventions"], "critical", ["conventions", "languages"]],
+  ["testing", "standards/testing.md", "Detected test tooling, locations, and repository commands.", ["test", "verification", "commands"], "high", ["testing", "commands"]],
+  ["security", "standards/security.md", "Detected security-sensitive boundaries and baseline safeguards.", ["security", "auth", "secrets"], "critical", ["security"]],
+  ["project-intelligence", "project-intelligence/project.md", "Detected stack, package tooling, CI, and project intelligence.", ["project", "stack", "ci"], "medium", ["project", "packageManager", "languages", "frameworks", "ciCd"]]
 ];
 var CODEX_AGENT_IGNORE_RULES = [
   ".codex-agent/analysis.json",
@@ -1823,6 +2005,30 @@ var managedIndexOwnershipConflicts = (existingIndex) => {
     return [];
   });
 };
+var nestedValue = (value, dottedPath) => dottedPath.split(".").reduce((current, key) => current?.[key], value);
+var collectSignalEvidence = (value) => {
+  if (!value || typeof value !== "object") return [];
+  return [
+    ...Array.isArray(value.evidence) ? value.evidence : [],
+    ...Object.values(value).flatMap((item) => collectSignalEvidence(item))
+  ];
+};
+var managedEvidence = (analysis, id, signalPaths) => {
+  const projectRoot = path5.resolve(analysis.root);
+  const locators = unique(signalPaths.flatMap((signalPath) => collectSignalEvidence(nestedValue(analysis, signalPath)))).map((locator) => String(locator).split("#")[0]).filter((locator) => locator && !path5.isAbsolute(locator));
+  return unique(locators).flatMap((locator) => {
+    const target = path5.resolve(projectRoot, locator);
+    const relativePath = relative(projectRoot, target);
+    if (relativePath.startsWith("../") || path5.isAbsolute(relativePath) || relativePath.startsWith(".codex-agent/context/") || relativePath.startsWith(".agents/context/")) return [];
+    try {
+      assertNoSymlink(projectRoot, target, `Managed context evidence ${locator}`);
+      if (!fs5.existsSync(target) || !fs5.statSync(target).isFile()) return [];
+      return [{ type: "repository", locator: relativePath, note: `Repository evidence used to generate ${id}.`, sha256: sha256(fs5.readFileSync(target)) }];
+    } catch {
+      return [];
+    }
+  }).slice(0, 20);
+};
 var renderProjectFiles = (analysis, existingIndex = null) => {
   if (containsSensitiveContent(JSON.stringify({ analysis, existingIndex }))) {
     throw new Error("Project context rendering input appears to contain a secret or credential");
@@ -1842,13 +2048,28 @@ var renderProjectFiles = (analysis, existingIndex = null) => {
     [".codex/config.toml", { kind: "toml", id: "agent-settings", body: "[agents]\nmax_concurrent_threads_per_session = 4\nmax_depth = 1\n\n[features]\nhooks = true" }]
   ]);
   for (const profile of agentProfiles) files.set(`.codex/agents/${profile.file}`, { kind: "toml", id: `profile-${profile.name}`, body: renderProfile(profile) });
-  const priorEntries = Array.isArray(existingIndex?.entries) ? existingIndex.entries : [];
+  const upgradedIndex = upgradeContextIndex(existingIndex ?? { version: 1, entries: [] });
+  const priorEntries = upgradedIndex.entries;
+  const priorByPair = new Map(priorEntries.map((entry) => [`${entry.id}\0${entry.path}`, entry]));
   const managedPairs = new Set(MANAGED_CONTEXT.map(([id, file]) => `${id}\0${file}`));
   const customEntries = priorEntries.filter((entry) => !managedPairs.has(`${entry.id}\0${entry.path}`));
   const index = {
     ...existingIndex?.$schema ? { $schema: existingIndex.$schema } : {},
-    version: 1,
-    entries: [...MANAGED_CONTEXT.map(([id, file, summary2, tags, priority]) => ({ id, path: file, summary: summary2, tags, priority })), ...customEntries]
+    version: 2,
+    entries: [
+      ...MANAGED_CONTEXT.map(([id, file, summary2, tags, priority, signalPaths]) => upgradeContextIndexEntry({
+        ...priorByPair.get(`${id}\0${file}`),
+        id,
+        path: file,
+        summary: summary2,
+        tags,
+        priority,
+        status: "active",
+        lastVerifiedAt: contextDate(),
+        evidence: managedEvidence(analysis, id, signalPaths)
+      })),
+      ...customEntries
+    ]
   };
   files.set(".codex-agent/context/index.json", { kind: "json", content: `${JSON.stringify(index, null, 2)}
 ` });
@@ -2555,7 +2776,7 @@ var refreshContext = (options) => runContextLifecycle({ ...options, operation: "
 import fs6 from "node:fs";
 import path6 from "node:path";
 import { pathToFileURL } from "node:url";
-var KINDS = {
+var KINDS2 = {
   decision: "decisions",
   constraint: "constraints",
   operation: "operations",
@@ -2563,7 +2784,7 @@ var KINDS = {
   pitfall: "pitfalls"
 };
 var PRIORITIES2 = /* @__PURE__ */ new Set(["critical", "high", "medium", "low"]);
-var CONFIDENCE = /* @__PURE__ */ new Set(["high", "medium"]);
+var CONFIDENCE2 = /* @__PURE__ */ new Set(["high", "medium"]);
 var PROPOSAL_FIELDS = /* @__PURE__ */ new Set([
   "version",
   "title",
@@ -2575,7 +2796,10 @@ var PROPOSAL_FIELDS = /* @__PURE__ */ new Set([
   "tags",
   "priority",
   "confidence",
-  "reviewWhen"
+  "reviewWhen",
+  "reviewAfter",
+  "aliases",
+  "supersedes"
 ]);
 var unique2 = (items) => [...new Set(items)];
 var safeText2 = (value, limit = 300) => String(value).replace(/[\r\n]+/g, " ").replace(/`/g, "'").trim().slice(0, limit);
@@ -2608,7 +2832,7 @@ var prepareContextIndex = ({ root, pendingDocuments = [] }) => {
   if (!fs6.existsSync(contextRoot) && pendingDocuments.length === 0) throw new Error(`Context directory not found: ${contextRoot}`);
   assertNoSymlink(projectRoot, contextRoot, "Canonical context root");
   const indexPath = path6.join(contextRoot, "index.json");
-  const prior = writable.index;
+  const prior = upgradeContextIndex(writable.index);
   const priorByPath = new Map(prior.entries.map((entry) => [entry.path, entry]));
   const pending = /* @__PURE__ */ new Map();
   for (const [index2, document] of pendingDocuments.entries()) {
@@ -2634,18 +2858,19 @@ var prepareContextIndex = ({ root, pendingDocuments = [] }) => {
       ...relative2.replace(/\.md$/, "").split("/"),
       ...title.toLowerCase().split(/[^a-z0-9_-]+/).filter((term) => term.length > 2)
     ].map(slug).filter(Boolean)).slice(0, 10);
-    return {
+    return upgradeContextIndexEntry({
+      ...existing,
       id: existing?.id || slug(relative2.replace(/\.md$/, "").replaceAll("/", "-")),
       path: relative2,
       summary: existing?.summary || firstParagraph(content2, `${title} project context.`),
       tags: existing?.tags?.length ? existing.tags : tags,
       priority: existing?.priority || "medium"
-    };
+    });
   }).sort((left, right) => left.path.localeCompare(right.path));
   const schemaPath = path6.join(projectRoot, "schemas", "context-index.schema.json");
   const index = {
     ...fs6.existsSync(schemaPath) ? { $schema: "../../schemas/context-index.schema.json" } : prior.$schema ? { $schema: prior.$schema } : {},
-    version: 1,
+    version: 2,
     entries
   };
   assertValidContextIndex(index, { root: projectRoot, contextRoot, pendingPaths: [...pending.keys()] });
@@ -2683,9 +2908,9 @@ var validateContextProposal = (proposal, { root } = {}) => {
   checkString(errors, proposal, "summary", 10, 240);
   checkString(errors, proposal, "scope", 2, 120);
   checkString(errors, proposal, "contentMarkdown", 20, 1e4);
-  if (!Object.hasOwn(KINDS, proposal.kind)) errors.push(`kind must be one of: ${Object.keys(KINDS).join(", ")}`);
+  if (!Object.hasOwn(KINDS2, proposal.kind)) errors.push(`kind must be one of: ${Object.keys(KINDS2).join(", ")}`);
   if (!PRIORITIES2.has(proposal.priority)) errors.push("priority is invalid");
-  if (!CONFIDENCE.has(proposal.confidence)) errors.push("confidence must be high or medium");
+  if (!CONFIDENCE2.has(proposal.confidence)) errors.push("confidence must be high or medium");
   if (!Array.isArray(proposal.tags) || proposal.tags.length < 1 || proposal.tags.length > 10) errors.push("tags must contain between 1 and 10 values");
   else {
     if (new Set(proposal.tags).size !== proposal.tags.length) errors.push("tags must be unique");
@@ -2693,23 +2918,41 @@ var validateContextProposal = (proposal, { root } = {}) => {
   }
   if (!Array.isArray(proposal.evidence) || proposal.evidence.length < 1 || proposal.evidence.length > 20) errors.push("evidence must contain between 1 and 20 entries");
   else for (const [index, item] of proposal.evidence.entries()) {
-    if (!item || typeof item !== "object" || Array.isArray(item) || Object.keys(item).some((key) => !["path", "note"].includes(key))) {
+    const allowed = ["type", "path", "url", "note", "title", "version", "retrievedAt", "publishedAt", "decisionId", "decidedAt"];
+    if (!item || typeof item !== "object" || Array.isArray(item) || Object.keys(item).some((key) => !allowed.includes(key))) {
       errors.push(`evidence[${index}] is invalid`);
       continue;
     }
-    if (typeof item.path !== "string" || !item.path || item.path.length > 300 || path6.isAbsolute(item.path)) errors.push(`evidence[${index}].path must be repository-relative`);
+    const type = item.type ?? "repository";
+    if (!["repository", "decision", "external"].includes(type)) errors.push(`evidence[${index}].type is invalid`);
+    if (type === "external") {
+      try {
+        const url = new URL(item.url);
+        if (url.protocol !== "https:" || url.username || url.password) errors.push(`evidence[${index}].url must be an https URL without credentials`);
+      } catch {
+        errors.push(`evidence[${index}].url must be an absolute https URL`);
+      }
+    } else if (typeof item.path !== "string" || !item.path || item.path.length > 300 || path6.isAbsolute(item.path)) {
+      errors.push(`evidence[${index}].path must be repository-relative`);
+    }
     if (typeof item.note !== "string" || item.note.trim().length < 5 || item.note.length > 300) errors.push(`evidence[${index}].note is invalid`);
   }
+  if (Array.isArray(proposal.evidence) && !proposal.evidence.some((item) => ["repository", "decision"].includes(item?.type ?? "repository"))) {
+    errors.push("evidence must include at least one repository or decision source");
+  }
   if (proposal.reviewWhen !== void 0 && (!Array.isArray(proposal.reviewWhen) || proposal.reviewWhen.length > 5 || proposal.reviewWhen.some((item) => typeof item !== "string" || item.trim().length < 5 || item.length > 240))) {
     errors.push("reviewWhen must contain up to 5 non-empty strings");
   }
+  if (proposal.reviewAfter !== void 0 && !/^\d{4}-\d{2}-\d{2}$/.test(proposal.reviewAfter)) errors.push("reviewAfter must use YYYY-MM-DD");
+  if (proposal.aliases !== void 0 && (!Array.isArray(proposal.aliases) || proposal.aliases.length > 20 || proposal.aliases.some((item) => typeof item !== "string" || item.trim().length < 2))) errors.push("aliases must contain up to 20 non-empty values");
+  if (proposal.supersedes !== void 0 && (!Array.isArray(proposal.supersedes) || proposal.supersedes.length > 20 || proposal.supersedes.some((item) => typeof item !== "string" || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(item)))) errors.push("supersedes must contain valid context ids");
   const combined = JSON.stringify(proposal);
   if (combined.includes("codex-agent:context:start") || combined.includes("codex-agent:context:end")) errors.push("proposal must not contain managed marker text");
   if (containsSensitiveContent(combined)) errors.push("proposal appears to contain a secret or credential");
   if (root && Array.isArray(proposal.evidence)) {
     const projectRoot = fs6.realpathSync(path6.resolve(root));
     for (const [index, item] of proposal.evidence.entries()) {
-      if (!item || typeof item.path !== "string" || path6.isAbsolute(item.path)) continue;
+      if (!item || item.type === "external" || typeof item.path !== "string" || path6.isAbsolute(item.path)) continue;
       const target = path6.resolve(projectRoot, item.path);
       if (target !== projectRoot && !target.startsWith(`${projectRoot}${path6.sep}`)) {
         errors.push(`evidence[${index}].path escapes the repository`);
@@ -2721,7 +2964,11 @@ var validateContextProposal = (proposal, { root } = {}) => {
         errors.push(`evidence[${index}].path must not traverse a symbolic link`);
         continue;
       }
-      if (!fs6.existsSync(target)) errors.push(`evidence[${index}].path does not exist: ${item.path}`);
+      const relative2 = slash(path6.relative(projectRoot, target));
+      if (relative2 === ".codex-agent/context" || relative2.startsWith(".codex-agent/context/") || relative2 === ".agents/context" || relative2.startsWith(".agents/context/") || relative2.startsWith(".codex-agent/sessions/") || relative2.startsWith(".codex-agent/backups/")) {
+        errors.push(`evidence[${index}].path must reference primary repository evidence, not derived context`);
+      } else if (!fs6.existsSync(target)) errors.push(`evidence[${index}].path does not exist: ${item.path}`);
+      else if (!fs6.statSync(target).isFile()) errors.push(`evidence[${index}].path must be a file`);
     }
   }
   return { ok: errors.length === 0, errors };
@@ -2733,15 +2980,32 @@ var normalizeContextProposal = (proposal) => ({
   summary: proposal.summary.trim(),
   scope: proposal.scope.trim(),
   contentMarkdown: proposal.contentMarkdown.trim(),
-  evidence: proposal.evidence.map((item) => ({ path: slash(item.path), note: item.note.trim() })),
+  evidence: proposal.evidence.map((item) => item.type === "external" ? {
+    type: "external",
+    url: item.url,
+    note: item.note.trim(),
+    ...item.title ? { title: item.title.trim() } : {},
+    ...item.version ? { version: item.version.trim() } : {},
+    ...item.retrievedAt ? { retrievedAt: item.retrievedAt } : {},
+    ...item.publishedAt ? { publishedAt: item.publishedAt } : {}
+  } : {
+    type: item.type ?? "repository",
+    path: slash(item.path),
+    note: item.note.trim(),
+    ...item.decisionId ? { decisionId: item.decisionId.trim() } : {},
+    ...item.decidedAt ? { decidedAt: item.decidedAt } : {}
+  }),
   tags: proposal.tags,
   priority: proposal.priority,
   confidence: proposal.confidence,
-  ...proposal.reviewWhen?.length ? { reviewWhen: proposal.reviewWhen.map((item) => item.trim()) } : {}
+  ...proposal.reviewWhen?.length ? { reviewWhen: proposal.reviewWhen.map((item) => item.trim()) } : {},
+  ...proposal.reviewAfter ? { reviewAfter: proposal.reviewAfter } : {},
+  ...proposal.aliases?.length ? { aliases: unique2(proposal.aliases.map((item) => item.trim())) } : {},
+  ...proposal.supersedes?.length ? { supersedes: unique2(proposal.supersedes) } : {}
 });
 var renderContextProposal = (proposal, { recordedAt = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10) } = {}) => {
   const id = `${proposal.kind}-${slug(proposal.title)}`;
-  const evidence = proposal.evidence.map((item) => `- ${mdCode2(item.path)} \u2014 ${safeText2(item.note)}`).join("\n");
+  const evidence = proposal.evidence.map((item) => `- ${mdCode2(item.type === "external" ? item.url : item.path)} \u2014 ${safeText2(item.note)}`).join("\n");
   const review = proposal.reviewWhen?.length ? `
 
 ## Review when
@@ -2804,31 +3068,62 @@ var prepareContextProposal = ({ root, proposal, apply, update }) => {
   const rendered = renderContextProposal(normalized);
   const writable = assertWritableContextCatalog({ root: projectRoot });
   const contextRoot = writable.contextRoot;
-  const relativePath = `${KINDS[normalized.kind]}/${slug(normalized.title)}.md`;
+  const relativePath = `${KINDS2[normalized.kind]}/${slug(normalized.title)}.md`;
   const destination = path6.join(contextRoot, ...relativePath.split("/"));
   assertInside(contextRoot, destination, "context destination");
   assertNoSymlink(projectRoot, contextRoot, "Canonical context root");
   assertNoSymlink(projectRoot, destination, "Context destination");
   const indexPath = writable.indexPath;
-  const index = writable.index;
+  const index = upgradeContextIndex(writable.index);
   const currentIndexContent = fs6.existsSync(indexPath) ? fs6.readFileSync(indexPath, "utf8") : null;
-  const duplicate = index.entries.find((entry) => entry.path !== relativePath && (entry.id === rendered.id || normalizeForComparison(entry.summary) === normalizeForComparison(normalized.summary)));
+  const duplicate = index.entries.find((entry) => entry.path !== relativePath && !(normalized.supersedes ?? []).includes(entry.id) && (entry.id === rendered.id || normalizeForComparison(entry.summary) === normalizeForComparison(normalized.summary)));
   if (duplicate) throw new Error(`Duplicate context candidate: ${duplicate.path}`);
   const current = fs6.existsSync(destination) ? fs6.readFileSync(destination, "utf8") : null;
   const merge = mergeManaged(current, rendered, update);
   const priorEntry = index.entries.find((entry) => entry.path === relativePath || entry.id === rendered.id);
   if (priorEntry && priorEntry.path !== relativePath) throw new Error(`Context id already belongs to another path: ${priorEntry.path}`);
-  const nextEntry = {
+  const evidence = normalized.evidence.map((item) => item.type === "external" ? {
+    type: "external",
+    locator: item.url,
+    note: item.note,
+    retrievedAt: item.retrievedAt ?? contextDate(),
+    ...item.title ? { title: item.title } : {},
+    ...item.version ? { version: item.version } : {},
+    ...item.publishedAt ? { publishedAt: item.publishedAt } : {}
+  } : {
+    type: item.type,
+    locator: item.path,
+    note: item.note,
+    sha256: sha256(fs6.readFileSync(path6.resolve(projectRoot, item.path))),
+    ...item.decisionId ? { decisionId: item.decisionId } : {},
+    ...item.decidedAt ? { decidedAt: item.decidedAt } : {}
+  });
+  const nextEntry = upgradeContextIndexEntry({
+    ...priorEntry,
     id: rendered.id,
     path: relativePath,
     summary: normalized.summary,
     tags: unique2([normalized.kind, ...normalized.tags]).slice(0, 10),
-    priority: normalized.priority
-  };
+    priority: normalized.priority,
+    kind: normalized.kind,
+    scope: normalized.scope,
+    confidence: normalized.confidence,
+    status: "active",
+    lastVerifiedAt: contextDate(),
+    evidence,
+    ...normalized.reviewAfter ? { reviewAfter: normalized.reviewAfter } : {},
+    ...normalized.aliases?.length ? { aliases: normalized.aliases } : {},
+    ...normalized.supersedes?.length ? { supersedes: normalized.supersedes } : {}
+  });
+  for (const supersededId of normalized.supersedes ?? []) {
+    if (supersededId === rendered.id) throw new Error("Context proposal must not supersede itself");
+    if (!index.entries.some((entry) => entry.id === supersededId)) throw new Error(`Context proposal supersedes unknown id: ${supersededId}`);
+  }
+  const supersededEntries = index.entries.map((entry) => (normalized.supersedes ?? []).includes(entry.id) ? upgradeContextIndexEntry({ ...entry, status: "superseded", supersededBy: unique2([...entry.supersededBy ?? [], rendered.id]) }) : entry);
   const nextIndex = {
     ...index.$schema ? { $schema: index.$schema } : {},
-    version: 1,
-    entries: [...index.entries.filter((entry) => entry.path !== relativePath && entry.id !== rendered.id), nextEntry].sort((left, right) => left.path.localeCompare(right.path))
+    version: 2,
+    entries: [...supersededEntries.filter((entry) => entry.path !== relativePath && entry.id !== rendered.id), nextEntry].sort((left, right) => left.path.localeCompare(right.path))
   };
   assertValidContextIndex(nextIndex, { root: projectRoot, contextRoot, pendingPaths: [relativePath] });
   const indexContent = `${JSON.stringify(nextIndex, null, 2)}
@@ -3141,7 +3436,7 @@ ${MANAGED_END(id)}`;
     });
   }
   const indexPath = path7.join(contextRoot, "index.json");
-  const targetIndex = writableCatalog.index;
+  const targetIndex = upgradeContextIndex(writableCatalog.index);
   const priorIndexContent = fs7.existsSync(indexPath) ? fs7.readFileSync(indexPath, "utf8") : null;
   const changes = [];
   const conflicts = [];
@@ -3195,19 +3490,21 @@ ${MANAGED_END(id)}`;
       before: current,
       content: merge.content
     });
-    migrationEntries.push({
+    migrationEntries.push(upgradeContextIndexEntry({
       id: candidate.id,
       path: candidate.destinationRelative,
       summary: candidate.summary,
       tags: candidate.tags,
-      priority: candidate.priority
-    });
+      priority: candidate.priority,
+      kind: "imported",
+      confidence: "low"
+    }));
   }
   const migratingIds = new Set(migrationEntries.map((entry) => entry.id));
   const migratingPaths = new Set(migrationEntries.map((entry) => entry.path));
   const nextIndex = {
     ...targetIndex.$schema ? { $schema: targetIndex.$schema } : {},
-    version: 1,
+    version: 2,
     entries: [
       ...targetIndex.entries.filter((entry) => !migratingIds.has(entry.id) && !migratingPaths.has(entry.path)),
       ...migrationEntries
@@ -3297,13 +3594,155 @@ if (process.argv[1] && path7.basename(process.argv[1]) === "navigation-migrate.m
   }
 }
 
+// ../../plugins/codex-agent/skills/context-lint/scripts/context-lint.mjs
+import fs8 from "node:fs";
+import path8 from "node:path";
+import { pathToFileURL as pathToFileURL3 } from "node:url";
+var healthOrder = ["conflict", "orphan", "duplicate", "insufficient-evidence", "review-due", "healthy"];
+var normalize = (value) => String(value ?? "").normalize("NFKC").toLocaleLowerCase("en-US").replace(/\s+/g, " ").trim();
+var findingSort = (left, right) => (left.path ?? "").localeCompare(right.path ?? "") || (left.id ?? "").localeCompare(right.id ?? "") || left.code.localeCompare(right.code);
+var healthFor = (reasons) => healthOrder.find((health) => reasons.includes(health)) ?? "healthy";
+var lintContext = ({ root, strict = false, now = /* @__PURE__ */ new Date() }) => {
+  const checkedAt = now.toISOString();
+  const resolution = resolveContextCatalog({ root });
+  const findings = [];
+  if (["invalid", "both-divergent"].includes(resolution.state)) {
+    for (const message of resolution.errors.length ? resolution.errors : resolution.warnings) {
+      findings.push({ severity: "error", code: "catalog-invalid", message });
+    }
+    return {
+      ok: false,
+      healthy: false,
+      checkedAt,
+      state: resolution.state,
+      summary: { entries: 0, healthy: 0, findings: findings.length, errors: findings.length, warnings: 0 },
+      entries: [],
+      findings: findings.sort(findingSort)
+    };
+  }
+  const catalog = getReadableContextCatalog({ root });
+  if (!catalog.index) {
+    findings.push({ severity: "warning", code: "catalog-missing", message: "context index not found" });
+    return {
+      ok: !strict,
+      healthy: false,
+      checkedAt,
+      state: catalog.state,
+      summary: { entries: 0, healthy: 0, findings: 1, errors: 0, warnings: 1 },
+      entries: [],
+      findings
+    };
+  }
+  const reasonsById = new Map(catalog.index.entries.map((entry) => [entry.id, /* @__PURE__ */ new Set()]));
+  const add = (severity, code, entry, message, health = null) => {
+    findings.push({ severity, code, ...entry?.id ? { id: entry.id } : {}, ...entry?.path ? { path: entry.path } : {}, message });
+    if (health && entry?.id) reasonsById.get(entry.id)?.add(health);
+  };
+  const today = checkedAt.slice(0, 10);
+  for (const entry of catalog.index.entries) {
+    if (catalog.index.version === 1 || !entry.evidence?.length) {
+      add("warning", "evidence-missing", entry, "entry has no machine-verifiable provenance", "insufficient-evidence");
+    }
+    if (entry.status === "conflicted") add("error", "lifecycle-conflicted", entry, "entry is marked conflicted", "conflict");
+    if (entry.reviewAfter && entry.reviewAfter <= today) add("warning", "review-due", entry, `entry review was due on ${entry.reviewAfter}`, "review-due");
+    const localEvidence = (entry.evidence ?? []).filter((evidence) => ["repository", "decision"].includes(evidence.type));
+    if (entry.evidence?.length && !localEvidence.length) {
+      add("warning", "evidence-derived-only", entry, "external evidence alone cannot establish repository-specific context", "insufficient-evidence");
+    }
+    for (const evidence of localEvidence) {
+      const target = path8.resolve(catalog.root, evidence.locator);
+      const relative2 = slash(path8.relative(catalog.root, target));
+      if (relative2.startsWith("../") || path8.isAbsolute(relative2)) {
+        add("error", "evidence-escape", entry, `evidence escapes repository: ${evidence.locator}`, "insufficient-evidence");
+        continue;
+      }
+      if (relative2 === ".codex-agent/context" || relative2.startsWith(".codex-agent/context/") || relative2 === ".agents/context" || relative2.startsWith(".agents/context/")) {
+        add("warning", "evidence-derived", entry, `evidence points to derived context: ${evidence.locator}`, "insufficient-evidence");
+        continue;
+      }
+      let stat;
+      try {
+        assertNoSymlink(catalog.root, target, `context evidence ${evidence.locator}`);
+      } catch {
+        add("error", "evidence-invalid-file", entry, `evidence traverses a symbolic link: ${evidence.locator}`, "insufficient-evidence");
+        continue;
+      }
+      try {
+        stat = fs8.lstatSync(target);
+      } catch {
+        stat = null;
+      }
+      if (!stat) add("error", "evidence-missing-file", entry, `evidence file is missing: ${evidence.locator}`, "insufficient-evidence");
+      else if (stat.isSymbolicLink() || !stat.isFile()) add("error", "evidence-invalid-file", entry, `evidence is not a regular file: ${evidence.locator}`, "insufficient-evidence");
+      else if (sha256(fs8.readFileSync(target)) !== evidence.sha256) add("error", "evidence-digest-mismatch", entry, `evidence changed: ${evidence.locator}`, "conflict");
+    }
+    for (const relatedId of entry.related ?? []) {
+      const related = catalog.index.entries.find((item) => item.id === relatedId);
+      if (related && !(related.related ?? []).includes(entry.id)) add("warning", "relation-asymmetric", entry, `related link is not reciprocal: ${relatedId}`, "conflict");
+    }
+  }
+  const summaryOwners = /* @__PURE__ */ new Map();
+  const contentOwners = /* @__PURE__ */ new Map();
+  for (const entry of catalog.index.entries.filter((item) => item.status !== "superseded")) {
+    const summaryKey = normalize(entry.summary);
+    const contentKey = sha256(fs8.readFileSync(path8.join(catalog.contextRoot, ...entry.path.split("/"))));
+    for (const [key, owners, label] of [[summaryKey, summaryOwners, "summary"], [contentKey, contentOwners, "content"]]) {
+      const owner = owners.get(key);
+      if (owner && !(entry.supersedes ?? []).includes(owner.id) && !(owner.supersedes ?? []).includes(entry.id)) {
+        add("warning", `duplicate-${label}`, entry, `${label} duplicates ${owner.id}`, "duplicate");
+        reasonsById.get(owner.id)?.add("duplicate");
+      } else if (!owner) owners.set(key, entry);
+    }
+  }
+  const indexed = new Set(catalog.index.entries.map((entry) => entry.path));
+  for (const file of listTreeFiles(catalog.contextRoot).filter((item) => item.relative.toLowerCase().endsWith(".md"))) {
+    if (!indexed.has(file.relative)) add("warning", "orphan-document", { path: file.relative }, "Markdown document is not indexed");
+  }
+  const entries = catalog.index.entries.map((entry) => {
+    const reasons = [...reasonsById.get(entry.id)].sort((left, right) => healthOrder.indexOf(left) - healthOrder.indexOf(right));
+    return { id: entry.id, path: entry.path, lifecycle: entry.status ?? "active", health: healthFor(reasons), reasons };
+  }).sort((left, right) => left.path.localeCompare(right.path));
+  const sortedFindings = findings.sort(findingSort);
+  const errors = sortedFindings.filter((finding) => finding.severity === "error").length;
+  const warnings = sortedFindings.filter((finding) => finding.severity === "warning").length;
+  const healthy = entries.length > 0 && entries.every((entry) => entry.health === "healthy") && warnings === 0 && errors === 0;
+  return {
+    ok: errors === 0 && (!strict || warnings === 0),
+    healthy,
+    checkedAt,
+    state: catalog.state,
+    summary: { entries: entries.length, healthy: entries.filter((entry) => entry.health === "healthy").length, findings: sortedFindings.length, errors, warnings },
+    entries,
+    findings: sortedFindings
+  };
+};
+var option3 = (args, name, fallback) => {
+  const index = args.indexOf(name);
+  return index >= 0 && args[index + 1] ? args[index + 1] : fallback;
+};
+var main3 = (args = process.argv.slice(2)) => {
+  const result = lintContext({ root: path8.resolve(option3(args, "--root", process.cwd())), strict: args.includes("--strict") });
+  process.stdout.write(`${JSON.stringify(result, null, 2)}
+`);
+  if (!result.ok) process.exitCode = 1;
+};
+if (process.argv[1] && path8.basename(process.argv[1]) === "context-lint.mjs" && import.meta.url === pathToFileURL3(process.argv[1]).href) {
+  try {
+    main3();
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}
+`);
+    process.exitCode = 1;
+  }
+}
+
 // src/core.mjs
 var listFiles = (root) => {
-  if (!fs8.existsSync(root)) return [];
+  if (!fs9.existsSync(root)) return [];
   const files = [];
   const visit = (directory) => {
-    for (const entry of fs8.readdirSync(directory, { withFileTypes: true })) {
-      const absolute = path8.join(directory, entry.name);
+    for (const entry of fs9.readdirSync(directory, { withFileTypes: true })) {
+      const absolute = path9.join(directory, entry.name);
       if (entry.isDirectory()) visit(absolute);
       else if (entry.isFile()) files.push(absolute);
     }
@@ -3313,41 +3752,41 @@ var listFiles = (root) => {
 };
 var prepareContextMigration = ({ root, source, dryRun = false, force = false }) => {
   if (!source) throw new Error("migrate requires --from PATH");
-  const projectRoot = path8.resolve(root);
-  const sourceRoot = path8.resolve(source);
-  if (!fs8.existsSync(sourceRoot)) throw new Error(`Migration source not found: ${sourceRoot}`);
-  const sourceFiles = (fs8.statSync(sourceRoot).isDirectory() ? listFiles(sourceRoot) : [sourceRoot]).filter((file) => file.endsWith(".md"));
+  const projectRoot = path9.resolve(root);
+  const sourceRoot = path9.resolve(source);
+  if (!fs9.existsSync(sourceRoot)) throw new Error(`Migration source not found: ${sourceRoot}`);
+  const sourceFiles = (fs9.statSync(sourceRoot).isDirectory() ? listFiles(sourceRoot) : [sourceRoot]).filter((file) => file.endsWith(".md"));
   if (!sourceFiles.length) throw new Error("Migration source contains no Markdown context files.");
   const writableCatalog = assertWritableContextCatalog({ root: projectRoot });
   const catalogProjectRoot = writableCatalog.root;
   const contextRoot = writableCatalog.contextRoot;
   if (!contextRoot) throw new Error("Writable context catalog did not resolve a destination root.");
-  const destinationRoot = path8.join(contextRoot, "imported");
+  const destinationRoot = path9.join(contextRoot, "imported");
   const result = { imported: [], unchanged: [], conflicts: [], backedUp: [], dryRun, applied: false };
   const documents = [];
   const backupPaths = [];
   for (const sourceFile of sourceFiles) {
-    const relative2 = fs8.statSync(sourceRoot).isDirectory() ? path8.relative(sourceRoot, sourceFile) : path8.basename(sourceFile);
-    const destination = path8.join(destinationRoot, relative2);
-    const content = fs8.readFileSync(sourceFile);
+    const relative2 = fs9.statSync(sourceRoot).isDirectory() ? path9.relative(sourceRoot, sourceFile) : path9.basename(sourceFile);
+    const destination = path9.join(destinationRoot, relative2);
+    const content = fs9.readFileSync(sourceFile);
     if (containsSensitiveContent(content.toString("utf8"))) {
       throw new Error(`Migration source appears to contain a secret or credential: ${sourceFile}`);
     }
-    if (!fs8.existsSync(destination)) {
-      result.imported.push(path8.relative(catalogProjectRoot, destination));
-      documents.push({ path: path8.relative(contextRoot, destination).split(path8.sep).join("/"), content: content.toString("utf8") });
+    if (!fs9.existsSync(destination)) {
+      result.imported.push(path9.relative(catalogProjectRoot, destination));
+      documents.push({ path: path9.relative(contextRoot, destination).split(path9.sep).join("/"), content: content.toString("utf8") });
       continue;
     }
-    if (content.equals(fs8.readFileSync(destination))) {
-      result.unchanged.push(path8.relative(catalogProjectRoot, destination));
+    if (content.equals(fs9.readFileSync(destination))) {
+      result.unchanged.push(path9.relative(catalogProjectRoot, destination));
       continue;
     }
     if (!force) {
-      result.conflicts.push(path8.relative(catalogProjectRoot, destination));
+      result.conflicts.push(path9.relative(catalogProjectRoot, destination));
       continue;
     }
-    result.imported.push(path8.relative(catalogProjectRoot, destination));
-    const documentPath = path8.relative(contextRoot, destination).split(path8.sep).join("/");
+    result.imported.push(path9.relative(catalogProjectRoot, destination));
+    const documentPath = path9.relative(contextRoot, destination).split(path9.sep).join("/");
     documents.push({ path: documentPath, content: content.toString("utf8") });
     backupPaths.push(documentPath);
   }
@@ -3359,7 +3798,7 @@ var prepareContextMigration = ({ root, source, dryRun = false, force = false })
     index,
     backupPaths: [
       ...backupPaths,
-      ...index && fs8.existsSync(index.path) ? ["index.json"] : []
+      ...index && fs9.existsSync(index.path) ? ["index.json"] : []
     ]
   };
 };
@@ -3384,23 +3823,23 @@ var migrateContext = (options) => {
 var check = (checks, name, ok, detail) => checks.push({ name, ok: Boolean(ok), detail });
 var parseJson = (file) => {
   try {
-    return { value: JSON.parse(fs8.readFileSync(file, "utf8")) };
+    return { value: JSON.parse(fs9.readFileSync(file, "utf8")) };
   } catch (error) {
     return { error: error instanceof Error ? error.message : String(error) };
   }
 };
 var diagnoseProject = ({ root }) => {
-  const projectRoot = path8.resolve(root);
+  const projectRoot = path9.resolve(root);
   const checks = [];
   const nodeMajor = Number.parseInt(process.versions.node.split(".")[0], 10);
   check(checks, "node", nodeMajor >= 20, `Node.js ${process.versions.node}; requires 20 or newer`);
-  const manifest = path8.join(projectRoot, "plugins", "codex-agent", ".codex-plugin", "plugin.json");
-  const isSourceWorkspace = fs8.existsSync(manifest);
+  const manifest = path9.join(projectRoot, "plugins", "codex-agent", ".codex-plugin", "plugin.json");
+  const isSourceWorkspace = fs9.existsSync(manifest);
   check(checks, "mode", true, isSourceWorkspace ? "plugin source workspace" : "initialized consumer project");
   if (isSourceWorkspace) {
-    const marketplace = path8.join(projectRoot, ".agents", "plugins", "marketplace.json");
-    check(checks, "marketplace", fs8.existsSync(marketplace), marketplace);
-    if (fs8.existsSync(marketplace)) {
+    const marketplace = path9.join(projectRoot, ".agents", "plugins", "marketplace.json");
+    check(checks, "marketplace", fs9.existsSync(marketplace), marketplace);
+    if (fs9.existsSync(marketplace)) {
       const parsed2 = parseJson(marketplace);
       check(checks, "marketplace-json", !parsed2.error, parsed2.error || parsed2.value.name);
       check(
@@ -3415,10 +3854,10 @@ var diagnoseProject = ({ root }) => {
     check(checks, "plugin-json", !parsed.error, parsed.error || parsed.value.name);
     check(checks, "plugin-name", parsed.value?.name === "codex-agent", parsed.value?.name || "missing");
   } else {
-    const config = path8.join(projectRoot, ".codex", "config.toml");
-    const agents = path8.join(projectRoot, ".codex", "agents");
+    const config = path9.join(projectRoot, ".codex", "config.toml");
+    const agents = path9.join(projectRoot, ".codex", "agents");
     const profiles = listFiles(agents).filter((file) => file.endsWith(".toml"));
-    check(checks, "project-config", fs8.existsSync(config), config);
+    check(checks, "project-config", fs9.existsSync(config), config);
     check(checks, "project-agents", profiles.length === agentProfiles.length, `${profiles.length}/${agentProfiles.length} profiles in ${agents}`);
   }
   const resolvedCatalog = resolveContextCatalog({ root: projectRoot });
@@ -3429,38 +3868,38 @@ var diagnoseProject = ({ root }) => {
   } catch (error) {
     check(checks, "context-readable", false, error instanceof Error ? error.message : String(error));
   }
-  const contextIndex = readableCatalog2?.indexPath ?? (readableCatalog2?.root ? path8.join(readableCatalog2.root, "index.json") : null);
-  check(checks, "context-index", Boolean(contextIndex && fs8.existsSync(contextIndex)), contextIndex ?? "context index not found");
-  if (contextIndex && fs8.existsSync(contextIndex)) {
+  const contextIndex = readableCatalog2?.indexPath ?? (readableCatalog2?.root ? path9.join(readableCatalog2.root, "index.json") : null);
+  check(checks, "context-index", Boolean(contextIndex && fs9.existsSync(contextIndex)), contextIndex ?? "context index not found");
+  if (contextIndex && fs9.existsSync(contextIndex)) {
     const parsed = parseJson(contextIndex);
     check(checks, "context-json", !parsed.error, parsed.error || `${parsed.value.entries?.length ?? 0} entries`);
-    const contextRoot = path8.dirname(contextIndex);
+    const contextRoot = path9.dirname(contextIndex);
     const invalid = (parsed.value?.entries ?? []).filter((entry) => {
-      const target = path8.resolve(contextRoot, entry.path || "");
-      return !target.startsWith(`${contextRoot}${path8.sep}`) || !fs8.existsSync(target);
+      const target = path9.resolve(contextRoot, entry.path || "");
+      return !target.startsWith(`${contextRoot}${path9.sep}`) || !fs9.existsSync(target);
     });
     check(checks, "context-paths", invalid.length === 0, invalid.map((entry) => entry.path).join(", ") || "all paths valid");
   }
   if (isSourceWorkspace) {
-    const skillsRoot = path8.join(projectRoot, "plugins", "codex-agent", "skills");
-    const skillFiles = listFiles(skillsRoot).filter((file) => file.endsWith(`${path8.sep}SKILL.md`));
-    const skillDirectories = fs8.readdirSync(skillsRoot, { withFileTypes: true }).filter((entry) => entry.isDirectory()).length;
+    const skillsRoot = path9.join(projectRoot, "plugins", "codex-agent", "skills");
+    const skillFiles = listFiles(skillsRoot).filter((file) => file.endsWith(`${path9.sep}SKILL.md`));
+    const skillDirectories = fs9.readdirSync(skillsRoot, { withFileTypes: true }).filter((entry) => entry.isDirectory()).length;
     check(checks, "skills", skillFiles.length > 0 && skillFiles.length === skillDirectories, `${skillFiles.length}/${skillDirectories} skill entrypoints`);
-    const agentRoot = path8.join(projectRoot, "plugins", "codex-agent", "agents");
+    const agentRoot = path9.join(projectRoot, "plugins", "codex-agent", "agents");
     check(checks, "plugin-agents", listFiles(agentRoot).filter((file) => file.endsWith(".md")).length === agentProfiles.length, `${agentProfiles.length} canonical profiles in ${agentRoot}`);
-    const hooks = path8.join(projectRoot, "plugins", "codex-agent", "hooks", "hooks.json");
-    check(checks, "hooks", fs8.existsSync(hooks) && !parseJson(hooks).error, hooks);
+    const hooks = path9.join(projectRoot, "plugins", "codex-agent", "hooks", "hooks.json");
+    check(checks, "hooks", fs9.existsSync(hooks) && !parseJson(hooks).error, hooks);
   }
   return { root: projectRoot, ok: checks.every((item) => item.ok), checks };
 };
 var evaluateRouting = ({ root }) => {
-  const projectRoot = path8.resolve(root);
-  const suitePath = path8.join(projectRoot, "evals", "skill-routing.json");
-  if (!fs8.existsSync(suitePath)) throw new Error(`Routing suite not found: ${suitePath}`);
-  const suite = JSON.parse(fs8.readFileSync(suitePath, "utf8"));
-  const skillsRoot = path8.join(projectRoot, "plugins", "codex-agent", "skills");
+  const projectRoot = path9.resolve(root);
+  const suitePath = path9.join(projectRoot, "evals", "skill-routing.json");
+  if (!fs9.existsSync(suitePath)) throw new Error(`Routing suite not found: ${suitePath}`);
+  const suite = JSON.parse(fs9.readFileSync(suitePath, "utf8"));
+  const skillsRoot = path9.join(projectRoot, "plugins", "codex-agent", "skills");
   const available = new Set(
-    fs8.readdirSync(skillsRoot, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name)
+    fs9.readdirSync(skillsRoot, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name)
   );
   const ids = /* @__PURE__ */ new Set();
   const failures = [];
@@ -3498,13 +3937,13 @@ var evaluateRouting = ({ root }) => {
   return { ok: failures.length === 0, scenarios: suite.cases?.length ?? 0, skills: available.size, byKind, failures };
 };
 var evaluateBehaviorContracts = ({ root }) => {
-  const projectRoot = path8.resolve(root);
-  const suitePath = path8.join(projectRoot, "evals", "behavior-contracts.json");
-  if (!fs8.existsSync(suitePath)) throw new Error(`Behavior suite not found: ${suitePath}`);
-  const suite = JSON.parse(fs8.readFileSync(suitePath, "utf8"));
-  const skillsRoot = path8.join(projectRoot, "plugins", "codex-agent", "skills");
+  const projectRoot = path9.resolve(root);
+  const suitePath = path9.join(projectRoot, "evals", "behavior-contracts.json");
+  if (!fs9.existsSync(suitePath)) throw new Error(`Behavior suite not found: ${suitePath}`);
+  const suite = JSON.parse(fs9.readFileSync(suitePath, "utf8"));
+  const skillsRoot = path9.join(projectRoot, "plugins", "codex-agent", "skills");
   const availableSkills = new Set(
-    fs8.readdirSync(skillsRoot, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name)
+    fs9.readdirSync(skillsRoot, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name)
   );
   const availableAgents = new Set(agentProfiles.map((profile) => profile.name));
   const coveredSkills = /* @__PURE__ */ new Set();
@@ -3556,6 +3995,7 @@ Usage:
   codex-agent context init [--root PATH] [--analysis FILE] [--apply --plan-hash HASH] [--force] [--json]
   codex-agent context refresh [--root PATH] [--analysis FILE] [--apply --plan-hash HASH] [--force] [--json]
   codex-agent context index [--root PATH] [--dry-run] [--json]
+  codex-agent context lint [--root PATH] [--strict] [--json]
   codex-agent context save --proposal FILE [--root PATH] [--apply] [--update] [--json]
 
 Both init and refresh preview by default. Apply the exact reviewed preview by passing --apply with its planHash.`;
@@ -3574,6 +4014,7 @@ var FLAG_KEYS = /* @__PURE__ */ new Map([
   ["--include-templates", "includeTemplates"],
   ["--include-workflows", "includeWorkflows"],
   ["--json", "json"],
+  ["--strict", "strict"],
   ["--update", "update"]
 ]);
 var parseOptions = (args, { command, options = [], flags = [] }) => {
@@ -3599,13 +4040,13 @@ var parseOptions = (args, { command, options = [], flags = [] }) => {
     }
     throw new Error(`Unknown option for ${command}: ${argument}`);
   }
-  parsed.root = path9.resolve(parsed.root ?? process.cwd());
+  parsed.root = path10.resolve(parsed.root ?? process.cwd());
   return parsed;
 };
 var readJsonFile = (file, label) => {
-  const absolute = path9.resolve(file);
-  if (!fs9.existsSync(absolute)) throw new Error(`${label} file not found: ${absolute}`);
-  return JSON.parse(fs9.readFileSync(absolute, "utf8"));
+  const absolute = path10.resolve(file);
+  if (!fs10.existsSync(absolute)) throw new Error(`${label} file not found: ${absolute}`);
+  return JSON.parse(fs10.readFileSync(absolute, "utf8"));
 };
 var write = (value, json) => {
   if (json) {
@@ -3622,7 +4063,7 @@ var finishWithConflicts = (result, json) => {
   write(result, json);
   if (result.conflicts.length) process.exitCode = 2;
 };
-var main3 = async (args) => {
+var main4 = async (args) => {
   const [command, ...rest] = args;
   if (!command || command === "help") {
     if (rest.length === 1 && rest[0] === "context") write(contextUsage, false);
@@ -3637,7 +4078,7 @@ var main3 = async (args) => {
       return;
     }
     if (contextArgs.includes("--help") || contextArgs.includes("-h")) {
-      if (!["init", "refresh", "index", "save"].includes(subcommand)) {
+      if (!["init", "refresh", "index", "lint", "save"].includes(subcommand)) {
         throw new Error(`Unknown context command: ${subcommand}
 
 ${contextUsage}`);
@@ -3667,6 +4108,17 @@ ${contextUsage}`);
       write({ path: result.path, entries: result.index.entries.length, dryRun: result.dryRun }, options.json);
       return;
     }
+    if (subcommand === "lint") {
+      const options = parseOptions(contextArgs, {
+        command: "context lint",
+        options: ["--root"],
+        flags: ["--strict", "--json"]
+      });
+      const result = lintContext(options);
+      write(result, options.json);
+      if (!result.ok) process.exitCode = 1;
+      return;
+    }
     if (subcommand === "save") {
       const options = parseOptions(contextArgs, {
         command: "context save",
@@ -3741,7 +4193,7 @@ ${usage}`);
 };
 
 // bin/codex-agent.mjs
-main3(process.argv.slice(2)).catch((error) => {
+main4(process.argv.slice(2)).catch((error) => {
   process.stderr.write(`${error instanceof Error ? error.message : String(error)}
 `);
   process.exitCode = 1;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codex-agent/cli",
-  "version": "0.1.0-main.12.sha31ff9e5",
+  "version": "0.1.0-main.13.sha3ad2ccf",
   "description": "Diagnostics and project bootstrap helpers for the codex-agent plugin.",
   "type": "module",
   "bin": {