recodeee · NagyVikt · Apr 22, 2026 · Apr 22, 2026
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-04-22
@@ -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.
@@ -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.
@@ -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).
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -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.