diff --git a/openspec/changes/agent-codex-vscode-active-agents-canonical-source-pl-2026-04-22-17-59/.openspec.yaml b/openspec/changes/agent-codex-vscode-active-agents-canonical-source-pl-2026-04-22-17-59/.openspec.yaml
new file mode 100644
index 0000000..25345f4
--- /dev/null
+++ b/openspec/changes/agent-codex-vscode-active-agents-canonical-source-pl-2026-04-22-17-59/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-04-22
diff --git a/openspec/changes/agent-codex-vscode-active-agents-canonical-source-pl-2026-04-22-17-59/proposal.md b/openspec/changes/agent-codex-vscode-active-agents-canonical-source-pl-2026-04-22-17-59/proposal.md
new file mode 100644
index 0000000..b74111c
--- /dev/null
+++ b/openspec/changes/agent-codex-vscode-active-agents-canonical-source-pl-2026-04-22-17-59/proposal.md
@@ -0,0 +1,41 @@
+## Why
+
+- Repeated Active Agents follow-ups still require editing two identical source trees:
+  `vscode/guardex-active-agents/` and
+  `templates/vscode/guardex-active-agents/`.
+- The repo's current install/runtime/test surfaces already treat
+  `vscode/guardex-active-agents/` as the primary bundle and the template tree
+  as a fallback/parity surface, so the duplicate editing cost is structural
+  rather than functional.
+- We need one canonical source of truth for the VS Code companion so future
+  runtime, inspect, icon, and docs changes stop creating mirror-only cleanup
+  work.
+
+## What Changes
+
+- Make `vscode/guardex-active-agents/` the canonical editable source for the
+  Active Agents extension bundle.
+- Keep `templates/vscode/guardex-active-agents/` as the managed distribution
+  copy, but refresh it from the canonical source through an explicit
+  repo-managed sync/repair path instead of manual dual edits.
+- Update the install/runtime/test/docs contract to reflect the canonical-source
+  model without changing the user-visible behavior of the extension.
+- Expand parity protection so the manifest, README, icon, and runtime files
+  stay aligned, not just `extension.js` and `session-schema.js`.
+
+## Impact
+
+- Affected surfaces:
+  `vscode/guardex-active-agents/*`,
+  `templates/vscode/guardex-active-agents/*`,
+  `scripts/install-vscode-active-agents-extension.js`,
+  `scripts/agent-session-state.js`,
+  `test/vscode-active-agents-session-state.test.js`,
+  `test/metadata.test.js`,
+  and README/install guidance.
+- Risk is moderate because setup/install/template consumers can drift if the
+  sync path is incomplete, but the operator-visible extension behavior should
+  remain unchanged.
+- Rollout should stay focused: land the canonical-source plumbing, prove
+  session/install behavior with focused tests, then finish the lane through the
+  normal Guardex PR and cleanup flow.
diff --git a/openspec/changes/agent-codex-vscode-active-agents-canonical-source-pl-2026-04-22-17-59/specs/vscode-active-agents-extension/spec.md b/openspec/changes/agent-codex-vscode-active-agents-canonical-source-pl-2026-04-22-17-59/specs/vscode-active-agents-extension/spec.md
new file mode 100644
index 0000000..cbe0a4d
--- /dev/null
+++ b/openspec/changes/agent-codex-vscode-active-agents-canonical-source-pl-2026-04-22-17-59/specs/vscode-active-agents-extension/spec.md
@@ -0,0 +1,38 @@
+## ADDED Requirements
+
+### Requirement: Canonical Active Agents source
+The system SHALL treat `vscode/guardex-active-agents/` as the single editable
+source of truth for the Active Agents VS Code companion bundle.
+
+#### Scenario: Editing the extension bundle
+- **WHEN** maintainers change the Active Agents extension implementation
+- **THEN** the authoritative edits happen under
+  `vscode/guardex-active-agents/`
+- **AND** the workflow does not require manual mirror edits under
+  `templates/vscode/guardex-active-agents/`.
+
+### Requirement: Derived template bundle parity
+The system SHALL provide an explicit repo-managed path that refreshes
+`templates/vscode/guardex-active-agents/` from the canonical source and guards
+parity for the full shipped bundle.
+
+#### Scenario: Refreshing the managed template bundle
+- **WHEN** the canonical Active Agents source changes
+- **THEN** the managed template bundle is refreshed from that canonical source
+- **AND** parity protection covers `package.json`, `README.md`, `icon.png`,
+  `extension.js`, and `session-schema.js`.
+
+### Requirement: Existing install and session-state consumers stay stable
+The system SHALL preserve the current local install and session-state behavior
+while the template bundle becomes derived.
+
+#### Scenario: Installing the extension locally
+- **WHEN** `node scripts/install-vscode-active-agents-extension.js` runs
+- **THEN** it installs the canonical Active Agents bundle
+- **AND** operators do not need template-only edits for local VS Code installs.
+
+#### Scenario: Resolving session state helpers
+- **WHEN** `node scripts/agent-session-state.js` loads the session schema module
+- **THEN** it resolves the canonical runtime bundle first
+- **AND** any retained template fallback stays behaviorally equivalent to the
+  canonical source.
diff --git a/openspec/changes/agent-codex-vscode-active-agents-canonical-source-pl-2026-04-22-17-59/tasks.md b/openspec/changes/agent-codex-vscode-active-agents-canonical-source-pl-2026-04-22-17-59/tasks.md
new file mode 100644
index 0000000..5236464
--- /dev/null
+++ b/openspec/changes/agent-codex-vscode-active-agents-canonical-source-pl-2026-04-22-17-59/tasks.md
@@ -0,0 +1,37 @@
+## Definition of Done
+
+This change is complete only when **all** of the following are true:
+
+- Every checkbox below is checked.
+- The agent branch reaches `MERGED` state on `origin` and the PR URL + state are recorded in the completion handoff.
+- If any step blocks (test failure, conflict, ambiguous result), append a `BLOCKED:` line under section 4 explaining the blocker and **STOP**. Do not tick remaining cleanup boxes; do not silently skip the cleanup pipeline.
+
+## Handoff
+
+- Handoff: change=`agent-codex-vscode-active-agents-canonical-source-pl-2026-04-22-17-59`; branch=`agent/codex/continue-vscode-extension-collab-plan-2026-04-22-17-59`; scope=`planning artifacts for the Active Agents canonical-source migration: stale-note audit, setup/doctor asset propagation, execution lanes, and focused proof surface`; action=`finish the planning lane now, then spin a fresh implementation branch from main for the actual source-tree migration`.
+- Copy prompt: Continue `agent-codex-vscode-active-agents-canonical-source-pl-2026-04-22-17-59` on branch `agent/codex/continue-vscode-extension-collab-plan-2026-04-22-17-59`. Work inside the existing sandbox, review the change tasks plus `openspec/plan/agent-codex-vscode-active-agents-canonical-source-pl-2026-04-22-17-59/`, keep the plan branch limited to artifacts/review evidence, and create a fresh implementation branch from `main` before touching runtime/setup code.
+
+## 1. Specification
+
+- [x] 1.1 Finalize proposal scope and acceptance criteria for `agent-codex-vscode-active-agents-canonical-source-pl-2026-04-22-17-59`.
+- [x] 1.2 Define normative requirements in `specs/vscode-active-agents-extension/spec.md`.
+
+## 2. Planning
+
+- [x] 2.1 Create an execution-ready plan workspace under `openspec/plan/agent-codex-vscode-active-agents-canonical-source-pl-2026-04-22-17-59/`.
+- [x] 2.2 Resolve the stale follow-up notes against current `main` and capture the real remaining issue: duplicate authored extension sources plus template-asset propagation risk.
+- [x] 2.3 Publish planner/architect/critic checkpoints, execution lanes, and proof surfaces for the canonical-source migration.
+
+## 3. Verification
+
+- [x] 3.1 Run `openspec validate agent-codex-vscode-active-agents-canonical-source-pl-2026-04-22-17-59 --type change --strict`.
+- [x] 3.2 Confirm `summary.md`, `phases.md`, `checkpoints.md`, and role `tasks.md` files describe the same canonical-source scope and keep runtime/UI work out of scope.
+- [x] 3.3 Record the planning validation evidence in the root completion handoff.
+
+Verification note: `openspec validate agent-codex-vscode-active-agents-canonical-source-pl-2026-04-22-17-59 --type change --strict` passed on the planning branch after the summary, phases, checkpoints, and role task boards were aligned around the canonical-source scope.
+
+## 4. Cleanup (mandatory; run before claiming completion)
+
+- [ ] 4.1 Run the cleanup pipeline: `gx branch finish --branch agent/codex/continue-vscode-extension-collab-plan-2026-04-22-17-59 --base main --via-pr --wait-for-merge --cleanup`. This handles commit -> push -> PR create -> merge wait -> worktree prune in one invocation.
+- [ ] 4.2 Record the PR URL and final merge state (`MERGED`) in the completion handoff.
+- [ ] 4.3 Confirm the sandbox worktree is gone (`git worktree list` no longer shows the agent path; `git branch -a` shows no surviving local/remote refs for the branch).
diff --git a/openspec/plan/agent-codex-vscode-active-agents-canonical-source-pl-2026-04-22-17-59/architect/tasks.md b/openspec/plan/agent-codex-vscode-active-agents-canonical-source-pl-2026-04-22-17-59/architect/tasks.md
new file mode 100644
index 0000000..18c4e92
--- /dev/null
+++ b/openspec/plan/agent-codex-vscode-active-agents-canonical-source-pl-2026-04-22-17-59/architect/tasks.md
@@ -0,0 +1,44 @@
+# architect tasks
+
+## 1. Spec
+
+- [x] 1.1 Define ownership boundaries, interfaces, and artifact responsibilities for `agent-codex-vscode-active-agents-canonical-source-pl-2026-04-22-17-59`.
+- [x] 1.2 Validate architecture constraints and non-functional requirements coverage.
+
+## 2. Tests
+
+- [x] 2.1 Define architectural verification checkpoints around source-path ownership, binary-safe asset copying, and managed-repo compatibility.
+- [x] 2.2 Validate that acceptance criteria map to concrete architecture decisions.
+
+## 3. Implementation
+
+- [x] 3.1 Review the plan for the main tradeoff tension: canonicalize to `vscode/` vs keep templates as the authored source.
+- [x] 3.2 Propose the synthesis path: keep `vscode/` authored, move setup/doctor/materialization to it, and demote any remaining template copy to derived output only.
+- [x] 3.3 Record architecture sign-off notes for downstream execution.
+
+## 4. Checkpoints
+
+- [x] [A1] READY - Architecture review checkpoint
+
+### A1 Acceptance Criteria
+
+- [x] The canonical source location is fixed to `vscode/guardex-active-agents/`.
+- [x] The plan names the managed-file/materialization seam instead of reopening runtime/UI behavior.
+- [x] Binary asset handling for `icon.png` is treated as a first-class migration requirement.
+
+### A1 Verification Evidence
+
+- [x] `planner/plan.md` documents the chosen direction and rejected alternatives.
+- [x] `phases.md` marks the architecture phase complete with the canonical-source decision.
+- [x] `checkpoints.md` records the architecture checkpoint and downstream risk.
+
+## 5. Collaboration
+
+- [x] 5.1 Owner recorded this lane before edits.
+- [x] 5.2 N/A - solo planning lane.
+
+## 6. Cleanup
+
+- [ ] 6.1 Finish the planning branch after validation with `gx branch finish --branch agent/codex/continue-vscode-extension-collab-plan-2026-04-22-17-59 --base main --via-pr --wait-for-merge --cleanup`.
+- [ ] 6.2 Record PR URL + final `MERGED` state in the handoff.
+- [ ] 6.3 Confirm sandbox cleanup (`git worktree list`, `git branch -a`) or append `BLOCKED:` and stop.
diff --git a/openspec/plan/agent-codex-vscode-active-agents-canonical-source-pl-2026-04-22-17-59/checkpoints.md b/openspec/plan/agent-codex-vscode-active-agents-canonical-source-pl-2026-04-22-17-59/checkpoints.md
new file mode 100644
index 0000000..c1ae55a
--- /dev/null
+++ b/openspec/plan/agent-codex-vscode-active-agents-canonical-source-pl-2026-04-22-17-59/checkpoints.md
@@ -0,0 +1,21 @@
+# Plan Checkpoints: agent-codex-vscode-active-agents-canonical-source-pl-2026-04-22-17-59
+
+Chronological checkpoint log for all roles.
+
+## 2026-04-22 16:06Z - Planner - [P1] READY
+
+- decision: treat the current request as a planning-only continuation on the reserved sandbox branch and publish a fresh execution board instead of reopening stale runtime notes.
+- verification: `summary.md`, `phases.md`, and `planner/plan.md` all isolate one remaining follow-up: canonicalize the Active Agents authored source and fix setup/doctor asset propagation.
+- risks/follow-ups: implementation must happen on a fresh branch from `main`; this planning lane does not touch runtime/setup code directly.
+
+## 2026-04-22 16:07Z - Architect - [A1] READY
+
+- decision: prefer `vscode/guardex-active-agents/` as the authored source of truth because install/tests/runtime already anchor there; treat any remaining template copy as derived/materialized output, not a second authored tree.
+- verification: the architecture notes cite `scripts/install-vscode-active-agents-extension.js`, `src/context.js`, and `src/scaffold/index.js` as the concrete boundaries that make binary-safe canonicalization necessary.
+- risks/follow-ups: setup/doctor still need a safe path for downstream repos, including `icon.png`.
+
+## 2026-04-22 16:08Z - Critic - [C1] READY
+
+- verdict: APPROVE
+- verification: the plan avoids redoing already-landed runtime work, names the real drift source, and maps acceptance criteria to targeted proof surfaces (`test/vscode-active-agents-session-state.test.js`, `test/metadata.test.js`, install/setup behavior, and OpenSpec validation).
+- risks/follow-ups: keep runtime/UI changes out of the canonicalization lane unless a blocker is proven during execution.
diff --git a/openspec/plan/agent-codex-vscode-active-agents-canonical-source-pl-2026-04-22-17-59/critic/tasks.md b/openspec/plan/agent-codex-vscode-active-agents-canonical-source-pl-2026-04-22-17-59/critic/tasks.md
new file mode 100644
index 0000000..df5db01
--- /dev/null
+++ b/openspec/plan/agent-codex-vscode-active-agents-canonical-source-pl-2026-04-22-17-59/critic/tasks.md
@@ -0,0 +1,44 @@
+# critic tasks
+
+## 1. Spec
+
+- [x] 1.1 Validate principle-driver-option consistency across the plan.
+- [x] 1.2 Validate risks, consequences, and mitigation clarity, including idempotency expectations.
+
+## 2. Tests
+
+- [x] 2.1 Validate testability and measurability of all acceptance criteria.
+- [x] 2.2 Validate that verification steps are concrete and reproducible.
+
+## 3. Implementation
+
+- [x] 3.1 Produce verdict `APPROVE` with actionable feedback.
+- [x] 3.2 Confirm the revised drafts resolve the main failure mode: planning the wrong stale runtime notes instead of the real source-of-truth debt.
+- [x] 3.3 Publish final quality/risk sign-off notes.
+
+## 4. Checkpoints
+
+- [x] [C1] READY - Quality gate checkpoint
+
+### C1 Acceptance Criteria
+
+- [x] The plan rejects stale runtime/icon follow-ups in favor of the real remaining debt.
+- [x] Every acceptance criterion maps to a concrete proof surface.
+- [x] The plan does not hide the binary-asset/setup risk behind generic “keep parity” wording.
+
+### C1 Verification Evidence
+
+- [x] `checkpoints.md` records an `APPROVE` verdict.
+- [x] `summary.md`, `phases.md`, and `planner/plan.md` all preserve the same canonical-source scope.
+- [x] The root change proposal/spec/tasks reflect the same testable boundaries.
+
+## 5. Collaboration
+
+- [x] 5.1 Owner recorded this lane before edits.
+- [x] 5.2 N/A - solo planning lane.
+
+## 6. Cleanup
+
+- [ ] 6.1 Finish the planning branch after validation with `gx branch finish --branch agent/codex/continue-vscode-extension-collab-plan-2026-04-22-17-59 --base main --via-pr --wait-for-merge --cleanup`.
+- [ ] 6.2 Record PR URL + final `MERGED` state in the handoff.
+- [ ] 6.3 Confirm sandbox cleanup (`git worktree list`, `git branch -a`) or append `BLOCKED:` and stop.
diff --git a/openspec/plan/agent-codex-vscode-active-agents-canonical-source-pl-2026-04-22-17-59/executor/tasks.md b/openspec/plan/agent-codex-vscode-active-agents-canonical-source-pl-2026-04-22-17-59/executor/tasks.md
new file mode 100644
index 0000000..7e6a2c0
--- /dev/null
+++ b/openspec/plan/agent-codex-vscode-active-agents-canonical-source-pl-2026-04-22-17-59/executor/tasks.md
@@ -0,0 +1,44 @@
+# executor tasks
+
+## 1. Spec
+
+- [ ] 1.1 Map the approved canonical-source requirements to concrete implementation work items.
+- [ ] 1.2 Freeze the touched components/files before coding starts: managed-file resolution, scaffold/doctor copy path, extension source tree, docs, and focused tests.
+
+## 2. Tests
+
+- [ ] 2.1 Define test additions/updates required to lock canonical-source behavior, setup/doctor asset copying, and install payload truthfulness.
+- [ ] 2.2 Validate the focused regression and smoke verification commands before coding.
+
+## 3. Implementation
+
+- [ ] 3.1 Move the authored extension source to one canonical tree and retire manual duplicate editing.
+- [ ] 3.2 Update setup/doctor/materialization so downstream repos still receive a working companion, including `icon.png`.
+- [ ] 3.3 Replace duplicate-tree parity plumbing with focused docs/tests and keep runtime behavior unchanged.
+
+## 4. Checkpoints
+
+- [ ] [E1] READY - Execution start checkpoint
+
+### E1 Acceptance Criteria
+
+- [ ] The execution lane starts on a fresh implementation branch from `main`, not on the planning branch.
+- [ ] The touched-file list is frozen before code edits begin.
+- [ ] Runtime/UI behavior remains out of scope unless the canonical-source migration proves a blocker.
+
+### E1 Verification Evidence
+
+- [ ] Executor notes record the frozen file list and branch choice.
+- [ ] `phases.md` is advanced to the execution phase when the fresh implementation lane begins.
+- [ ] The root handoff identifies the exact focused tests and finish command.
+
+## 5. Collaboration
+
+- [ ] 5.1 Owner recorded the fresh implementation lane before edits.
+- [ ] 5.2 Record joined agents / handoffs, or mark `N/A` when solo.
+
+## 6. Cleanup
+
+- [ ] 6.1 Finish the implementation branch with `gx branch finish --branch <implementation-branch> --base main --via-pr --wait-for-merge --cleanup`.
+- [ ] 6.2 Record PR URL + final `MERGED` state in the handoff.
+- [ ] 6.3 Confirm sandbox cleanup (`git worktree list`, `git branch -a`) or append `BLOCKED:` and stop.
diff --git a/openspec/plan/agent-codex-vscode-active-agents-canonical-source-pl-2026-04-22-17-59/phases.md b/openspec/plan/agent-codex-vscode-active-agents-canonical-source-pl-2026-04-22-17-59/phases.md
new file mode 100644
index 0000000..902f722
--- /dev/null
+++ b/openspec/plan/agent-codex-vscode-active-agents-canonical-source-pl-2026-04-22-17-59/phases.md
@@ -0,0 +1,35 @@
+# Plan Phases: agent-codex-vscode-active-agents-canonical-source-pl-2026-04-22-17-59
+
+One entry per phase. Checkbox marks map to: `x` = completed, `>` = in progress, space = pending.
+Indented sub-bullets are optional metadata consumed by the Plans UI:
+
+- `session`: which agent kind runs the phase (`codex` / `claude`).
+- `checkpoints`: comma-separated role checkpoint ids delivered within the phase.
+- `summary`: one short sentence rendered under the phase title.
+
+One phase is intended to fit into a single Codex or Claude session task.
+
+- [x] [PH01] Audit current Active Agents source-of-truth drift
+  - session: codex
+  - checkpoints: P1
+  - summary: Confirm current main already absorbed the stale runtime/icon follow-ups and isolate the real remaining gap: duplicated authored sources plus missing binary-safe asset propagation.
+
+- [x] [PH02] Choose canonical-source direction and migration boundaries
+  - session: codex
+  - checkpoints: A1, C1
+  - summary: Keep `vscode/guardex-active-agents/` as the authored source of truth and route setup/doctor/materialization through that source instead of manual twin-tree edits.
+
+- [ ] [PH03] Implement canonical-source migration
+  - session: codex
+  - checkpoints: E1
+  - summary: Update managed-file resolution, asset copying, and duplicate-tree handling without changing user-visible Active Agents behavior.
+
+- [ ] [PH04] Refresh docs and focused regression coverage
+  - session: codex
+  - checkpoints: W1, V1
+  - summary: Replace duplicate-tree parity proofs with canonical-source/install/setup checks and update operator guidance to match the new source path.
+
+- [ ] [PH05] Validate and finish the execution lane
+  - session: codex
+  - checkpoints: E1, V1
+  - summary: Run targeted tests plus OpenSpec validation, then finish the implementation branch via PR merge and cleanup.
diff --git a/openspec/plan/agent-codex-vscode-active-agents-canonical-source-pl-2026-04-22-17-59/planner/plan.md b/openspec/plan/agent-codex-vscode-active-agents-canonical-source-pl-2026-04-22-17-59/planner/plan.md
new file mode 100644
index 0000000..cc13e8a
--- /dev/null
+++ b/openspec/plan/agent-codex-vscode-active-agents-canonical-source-pl-2026-04-22-17-59/planner/plan.md
@@ -0,0 +1,129 @@
+# ExecPlan: agent-codex-vscode-active-agents-canonical-source-pl-2026-04-22-17-59
+
+This ExecPlan is a living document. Keep `Progress`, `Surprises & Discoveries`, `Decision Log`, and `Outcomes & Retrospective` current as work proceeds.
+
+Follow repository guidance in `AGENTS.md` and keep this plan workspace as the execution source of truth.
+
+## Purpose / Big Picture
+
+After this plan lands, the Active Agents companion has one authored source of truth. Operators still install the same companion and see the same Source Control behavior, but Guardex setup/doctor/install all pull from a single canonical extension surface, including bundled assets like `icon.png`, so future extension work stops paying a manual twin-tree sync tax.
+
+## Progress
+
+- [x] (2026-04-22 16:02Z) Audit current `main` and compare the latest Active Agents notes against shipped behavior.
+- [x] (2026-04-22 16:04Z) Draft architecture/tradeoff plan for canonical-source migration and downstream asset propagation.
+- [x] (2026-04-22 16:06Z) Publish an execution-ready continuation board with planner/architect/critic checkpoints closed.
+
+## Surprises & Discoveries
+
+- Observation: The recent icon-size and bugfix notes are stale against `main`; stop-session routing, diff opening, versioning, and inspect/runtime work already shipped.
+  Evidence: `vscode/guardex-active-agents/extension.js`, `vscode/guardex-active-agents/package.json`, `test/vscode-active-agents-session-state.test.js`
+- Observation: The install helper already treats `vscode/guardex-active-agents/` as the primary source, while setup/doctor still materialize managed files from `templates/vscode/guardex-active-agents/*`.
+  Evidence: `scripts/install-vscode-active-agents-extension.js`, `src/context.js`
+- Observation: The managed-file copy path is text-only today, which is fine for JS/JSON/Markdown but incorrect for `icon.png`.
+  Evidence: `src/scaffold/index.js`, `src/context.js`
+- Observation: Current parity tests prevent drift by requiring live/template JS equality instead of removing the duplicated authored surface.
+  Evidence: `test/metadata.test.js`
+
+## Decision Log
+
+- Decision: Use OpenSpec plan workspace as source of truth for this planning cycle.
+  Rationale: Keeps planning artifacts in-repo and reviewable.
+  Date/Author: 2026-04-22 / codex
+- Decision: Keep `vscode/guardex-active-agents/` as the authored canonical source.
+  Rationale: The local install helper, focused tests, README references, and runtime imports already anchor on `vscode/`, so moving the canonical source elsewhere would widen churn without fixing the real drift.
+  Date/Author: 2026-04-22 / codex
+- Decision: Treat setup/doctor materialization as the migration seam, not the runtime/UI layer.
+  Rationale: The remaining defect is source-of-truth and asset propagation drift, not missing Active Agents behavior.
+  Date/Author: 2026-04-22 / codex
+- Decision: Execute the actual migration on a fresh implementation branch from `main`.
+  Rationale: This branch is reserved for planning artifacts; keeping code edits on a separate execution lane preserves a clean handoff and truthful cleanup evidence.
+  Date/Author: 2026-04-22 / codex
+
+## Outcomes & Retrospective
+
+Planning now isolates one real next step: canonicalize the authored extension surface and make downstream materialization truthful. The plan deliberately rejects another runtime/UI feature pass until a concrete missing behavior is proven.
+
+## Completion Criteria For This Plan
+
+- `summary.md`, `phases.md`, `checkpoints.md`, and the role `tasks.md` files agree on the same canonical-source scope.
+- The execution lane names the concrete files/contracts that must move together.
+- The acceptance criteria are testable without repo-wide noise.
+
+## Context and Orientation
+
+- `vscode/guardex-active-agents/`: current live companion source used by the install script, README references, and focused tests.
+- `templates/vscode/guardex-active-agents/`: duplicate source tree still used by Guardex managed-repo scaffolding and parity tests.
+- `scripts/install-vscode-active-agents-extension.js`: local install helper; currently resolves `vscode/` first and only falls back to `templates/`.
+- `src/context.js`: declares the managed template file list for setup/doctor and currently lists only the text Active Agents files, not `icon.png`.
+- `src/scaffold/index.js`: copies managed files from `TEMPLATE_ROOT` using UTF-8 reads/writes today.
+- `src/doctor/index.js`: consumes the managed file contract and therefore must stay aligned with any source-path changes.
+- `test/vscode-active-agents-session-state.test.js`: focused regression surface for install payload, manifest/version rules, runtime wiring, and extension activation.
+- `test/metadata.test.js`: currently enforces direct equality between the live/template JS sources.
+
+## Plan of Work
+
+1. Audit every place that still assumes the Active Agents template copy is authored directly.
+   Freeze the source-of-truth map across installer, setup/doctor contracts, metadata tests, and README/OpenSpec guidance before code edits.
+2. Introduce a canonical-source materialization path.
+   Prefer a small explicit mapping layer that lets setup/doctor copy the managed companion from `vscode/guardex-active-agents/` into downstream repos, including binary assets, instead of hardcoding `TEMPLATE_ROOT` for this surface.
+3. Remove or demote manual duplicate authorship.
+   Either delete `templates/vscode/guardex-active-agents/*` or convert it into a generated/materialized mirror that is never the primary edit surface.
+4. Update docs and focused proofs.
+   Replace live/template parity policing with checks that the canonical source, managed repo copy, and installed payload remain aligned.
+5. Validate on a fresh execution lane and finish there.
+   The implementation branch should run focused Node tests plus OpenSpec validation, then close with `gx branch finish --via-pr --wait-for-merge --cleanup`.
+
+## Concrete Steps
+
+List exact commands with working directory and short expected outcomes.
+
+    cd /home/deadpool/Documents/recodee/gitguardex/.omx/agent-worktrees/<fresh-implementation-worktree>
+    rg -n "guardex-active-agents|icon.png|TEMPLATE_FILES|copyTemplateFile|resolveExtensionSource" src scripts test vscode templates
+    # Freeze every source-of-truth touchpoint before editing.
+
+    cd /home/deadpool/Documents/recodee/gitguardex/.omx/agent-worktrees/<fresh-implementation-worktree>
+    node --test test/vscode-active-agents-session-state.test.js test/metadata.test.js
+    # Focused extension/install/setup proof surface.
+
+    cd /home/deadpool/Documents/recodee/gitguardex/.omx/agent-worktrees/<fresh-implementation-worktree>
+    openspec validate agent-codex-vscode-active-agents-canonical-source-pl-2026-04-22-17-59 --type change --strict
+    openspec validate --specs
+    # Validate the change artifacts and repo specs.
+
+    cd /home/deadpool/Documents/recodee/gitguardex/.omx/agent-worktrees/<fresh-implementation-worktree>
+    gx branch finish --branch <implementation-branch> --base main --via-pr --wait-for-merge --cleanup
+    # Finalize the implementation branch after focused verification.
+
+## Validation and Acceptance
+
+- The Active Agents authored files live in one canonical source tree.
+- `gx setup` / `gx doctor` still materialize a working `vscode/guardex-active-agents/` folder in downstream repos, including `icon.png`.
+- The local install helper still produces a valid installed payload with the existing commands, activation events, and runtime behavior.
+- Focused tests prove the canonical source and downstream materialization stay aligned without depending on long-lived manual live/template duplication.
+
+## Idempotence and Recovery
+
+- Re-running setup/doctor after the migration should deterministically rewrite the managed companion from the same canonical source.
+- If a full duplicate-tree removal is too risky in one cut, keep a generated/materialized mirror for one lane only, but do not leave both trees as manually edited peers.
+- If binary asset copying destabilizes setup/doctor, pause and restore a minimal derived mirror rather than reintroducing silent manual drift.
+
+## Artifacts and Notes
+
+- Evidence pointers:
+  - `scripts/install-vscode-active-agents-extension.js` resolves `vscode/guardex-active-agents/` before `templates/vscode/guardex-active-agents/`.
+  - `src/context.js` still defines the managed template contract around text Active Agents files.
+  - `src/scaffold/index.js` copies managed files with UTF-8 reads/writes.
+  - `test/metadata.test.js` currently enforces live/template JS equality.
+  - `test/vscode-active-agents-session-state.test.js` imports the live `vscode/` extension files and validates the installed payload from there.
+
+## Interfaces and Dependencies
+
+- `resolveExtensionSource(repoRoot)` in `scripts/install-vscode-active-agents-extension.js` must keep returning an installable extension directory.
+- `TEMPLATE_FILES` / managed-file destinations in `src/context.js` define what setup/doctor expect to materialize.
+- `copyTemplateFile()` and related scaffold helpers in `src/scaffold/index.js` currently assume UTF-8 text content and therefore need an asset-safe path for `icon.png`.
+- `test/vscode-active-agents-session-state.test.js` and `test/metadata.test.js` are the minimal regression surface for this change.
+
+## Revision Note
+
+- 2026-04-22 16:06Z: Replaced the scaffold with an execution-ready continuation plan for canonicalizing the Active Agents authored source and downstream asset materialization.
diff --git a/openspec/plan/agent-codex-vscode-active-agents-canonical-source-pl-2026-04-22-17-59/planner/tasks.md b/openspec/plan/agent-codex-vscode-active-agents-canonical-source-pl-2026-04-22-17-59/planner/tasks.md
new file mode 100644
index 0000000..8e75fb1
--- /dev/null
+++ b/openspec/plan/agent-codex-vscode-active-agents-canonical-source-pl-2026-04-22-17-59/planner/tasks.md
@@ -0,0 +1,44 @@
+# planner tasks
+
+## 1. Spec
+
+- [x] 1.1 Define planning principles, decision drivers, and viable options for `agent-codex-vscode-active-agents-canonical-source-pl-2026-04-22-17-59`.
+- [x] 1.2 Capture the stale-note audit, canonical-source scope, and acceptance criteria in `summary.md`, `planner/plan.md`, and the change spec.
+
+## 2. Tests
+
+- [x] 2.1 Define the focused planning proof surface: strict change validation, artifact-consistency checks, and the future execution proof surface around `test/vscode-active-agents-session-state.test.js` and `test/metadata.test.js`.
+- [x] 2.2 Validate that this branch stays planning-only and leaves runtime/setup verification for the fresh implementation lane.
+
+## 3. Implementation
+
+- [x] 3.1 Publish the initial stale-note audit and freeze the real remaining issue: duplicate authored extension sources plus text-only managed-file copying.
+- [x] 3.2 Integrate Architect/Critic conclusions into the canonical-source direction and execution boundaries.
+- [x] 3.3 Publish the final execution-ready continuation board for the canonical-source migration.
+
+## 4. Checkpoints
+
+- [x] [P1] READY - Canonical-source planning checkpoint
+
+### P1 Acceptance Criteria
+
+- [x] The plan rejects stale runtime/icon follow-ups in favor of the real source-of-truth debt.
+- [x] The canonical authored source is fixed to `vscode/guardex-active-agents/`.
+- [x] The plan names the concrete migration seams and focused proof surface.
+
+### P1 Verification Evidence
+
+- [x] `summary.md`, `phases.md`, and `planner/plan.md` isolate the same canonical-source scope.
+- [x] The root change proposal/spec/tasks reflect the same boundaries.
+- [x] `checkpoints.md` records the planner checkpoint and downstream implementation handoff.
+
+## 5. Collaboration
+
+- [x] 5.1 Owner recorded this lane before edits.
+- [x] 5.2 N/A - solo planning lane.
+
+## 6. Cleanup
+
+- [ ] 6.1 Finish the planning branch with `gx branch finish --branch agent/codex/continue-vscode-extension-collab-plan-2026-04-22-17-59 --base main --via-pr --wait-for-merge --cleanup`.
+- [ ] 6.2 Record PR URL + final `MERGED` state in the handoff.
+- [ ] 6.3 Confirm sandbox cleanup (`git worktree list`, `git branch -a`) or append `BLOCKED:` and stop.
diff --git a/openspec/plan/agent-codex-vscode-active-agents-canonical-source-pl-2026-04-22-17-59/summary.md b/openspec/plan/agent-codex-vscode-active-agents-canonical-source-pl-2026-04-22-17-59/summary.md
new file mode 100644
index 0000000..1bbb768
--- /dev/null
+++ b/openspec/plan/agent-codex-vscode-active-agents-canonical-source-pl-2026-04-22-17-59/summary.md
@@ -0,0 +1,29 @@
+# Plan Summary: agent-codex-vscode-active-agents-canonical-source-pl-2026-04-22-17-59
+
+- **Mode:** ralplan
+- **Status:** planned; `P1`, `A1`, and `C1` are ready, execution pending
+
+## Context
+
+- User asked to continue the VS Code extension plan rather than reopen implementation blindly.
+- Current `main` already contains the recent Active Agents follow-ups: version `0.0.6`, inspect/session context, `gx`-driven stop flow, git-native diff opens, and focused tests that read the live `vscode/` source tree.
+- The remaining durable issue is source-of-truth drift. The install helper resolves `vscode/guardex-active-agents/` first, but setup/doctor still depend on `templates/vscode/guardex-active-agents/*`, and the managed-file pipeline is text-only even though the extension now ships `icon.png`.
+
+## Desired Outcome
+
+- Publish one execution-ready continuation board that collapses manual dual editing, makes asset propagation truthful, and keeps runtime behavior unchanged.
+
+## Scope Boundaries
+
+- In scope: canonical-source decision, setup/doctor/scaffold source-path changes, binary-safe asset copying, duplicate-tree retirement or derivation, focused docs/tests, and finish-flow planning.
+- Out of scope: new Active Agents commands, new tree grouping/inspect/runtime features, another icon redesign pass, or broad repo-wide cleanup unrelated to the extension source tree.
+
+## Planning Evidence
+
+- Audit closed the stale follow-up notes before planning: the icon-size and bugfix notes no longer represent real missing behavior on `main`.
+- Planning gates are closed for strategy only: `P1`, `A1`, and `C1` now point at one canonical-source migration rather than another runtime/UI lane.
+
+## Coordinator Disposition
+
+- Wave splitting is not needed yet. The next step is one bounded implementation lane on a fresh branch from `main`.
+- Preferred authored source is `vscode/guardex-active-agents/`; the duplicated template tree should be removed or reduced to a generated/materialized copy rather than manually maintained.
diff --git a/openspec/plan/agent-codex-vscode-active-agents-canonical-source-pl-2026-04-22-17-59/verifier/tasks.md b/openspec/plan/agent-codex-vscode-active-agents-canonical-source-pl-2026-04-22-17-59/verifier/tasks.md
new file mode 100644
index 0000000..c1ac1db
--- /dev/null
+++ b/openspec/plan/agent-codex-vscode-active-agents-canonical-source-pl-2026-04-22-17-59/verifier/tasks.md
@@ -0,0 +1,44 @@
+# verifier tasks
+
+## 1. Spec
+
+- [ ] 1.1 Define the end-to-end validation matrix for `agent-codex-vscode-active-agents-canonical-source-pl-2026-04-22-17-59`.
+- [ ] 1.2 Validate success/failure conditions and evidence requirements.
+
+## 2. Tests
+
+- [ ] 2.1 Execute the focused verification commands and collect outputs.
+- [ ] 2.2 Validate idempotency/re-run behavior for setup/doctor/install flows and any binary asset copy path touched by the change.
+
+## 3. Implementation
+
+- [ ] 3.1 Verify the completed work against the canonical-source acceptance criteria.
+- [ ] 3.2 Produce pass/fail findings with concrete evidence links.
+- [ ] 3.3 Publish the final verification sign-off or blocker report.
+
+## 4. Checkpoints
+
+- [ ] [V1] READY - Verification checkpoint
+
+### V1 Acceptance Criteria
+
+- [ ] Verification proves one authored source of truth plus correct downstream materialization of `icon.png`.
+- [ ] Focused tests cover install/setup/doctor truthfulness without widening into unrelated repo noise.
+- [ ] Final evidence is explicit for the implementation branch merge and cleanup.
+
+### V1 Verification Evidence
+
+- [ ] Verifier notes record targeted test output and any manual install/setup smoke evidence.
+- [ ] The final handoff includes PR URL, merge state, and cleanup proof for the implementation branch.
+- [ ] `planner/plan.md` is updated with the actual implementation evidence when execution finishes.
+
+## 5. Collaboration
+
+- [ ] 5.1 Owner recorded the verification lane before edits.
+- [ ] 5.2 Record joined agents / handoffs, or mark `N/A` when solo.
+
+## 6. Cleanup
+
+- [ ] 6.1 Finish the implementation branch with `gx branch finish --branch <implementation-branch> --base main --via-pr --wait-for-merge --cleanup`.
+- [ ] 6.2 Record PR URL + final `MERGED` state in the handoff.
+- [ ] 6.3 Confirm sandbox cleanup (`git worktree list`, `git branch -a`) or append `BLOCKED:` and stop.
diff --git a/openspec/plan/agent-codex-vscode-active-agents-canonical-source-pl-2026-04-22-17-59/writer/tasks.md b/openspec/plan/agent-codex-vscode-active-agents-canonical-source-pl-2026-04-22-17-59/writer/tasks.md
new file mode 100644
index 0000000..7be736b
--- /dev/null
+++ b/openspec/plan/agent-codex-vscode-active-agents-canonical-source-pl-2026-04-22-17-59/writer/tasks.md
@@ -0,0 +1,44 @@
+# writer tasks
+
+## 1. Spec
+
+- [ ] 1.1 Validate the docs audience: operators running `gx setup` / `gx doctor` and maintainers editing the Active Agents companion.
+- [ ] 1.2 Validate consistency between plan terminology, README guidance, and OpenSpec artifacts.
+
+## 2. Tests
+
+- [ ] 2.1 Define the documentation verification checklist for canonical-source behavior, setup/doctor guidance, and install expectations.
+- [ ] 2.2 Validate command/help text examples against actual workflow behavior after the migration.
+
+## 3. Implementation
+
+- [ ] 3.1 Update README/OpenSpec guidance so the canonical extension source and downstream materialization path are explicit.
+- [ ] 3.2 Add or refine operator expectations for setup, doctor repair, and local install after canonicalization.
+- [ ] 3.3 Publish the final docs change summary with references.
+
+## 4. Checkpoints
+
+- [ ] [W1] READY - Docs update checkpoint
+
+### W1 Acceptance Criteria
+
+- [ ] Docs describe one authored source of truth instead of manual live/template parity.
+- [ ] Setup/doctor/install examples reflect the actual file flow after canonicalization.
+- [ ] Docs do not imply new runtime/UI behavior that this lane does not ship.
+
+### W1 Verification Evidence
+
+- [ ] The updated README/OpenSpec copy matches the implementation result.
+- [ ] The docs surface references the same commands used in executor/verifier tasks.
+- [ ] Writer notes capture any downstream operator caveats.
+
+## 5. Collaboration
+
+- [ ] 5.1 Owner recorded the docs lane before edits.
+- [ ] 5.2 Record joined agents / handoffs, or mark `N/A` when solo.
+
+## 6. Cleanup
+
+- [ ] 6.1 Finish the implementation branch with `gx branch finish --branch <implementation-branch> --base main --via-pr --wait-for-merge --cleanup`.
+- [ ] 6.2 Record PR URL + final `MERGED` state in the handoff.
+- [ ] 6.3 Confirm sandbox cleanup (`git worktree list`, `git branch -a`) or append `BLOCKED:` and stop.