TrackCTL Roadmap Alignment

Review checkpoint for repairing the task pipeline before `tasks/roadmap.md` or `tasks/todo.md` are changed. The proposed change is to turn the existing alignment-upgrade handoff into a numbered roadmap phase that `$plan-phase` can decompose.

Generated: 2026-06-01 Alignment page: alignment/roadmap-trackctl.html Project type: business-app Execution state: pre-approval

Decision Summary

The task pipeline is blocked because `tasks/todo.md` contains an unchecked `Upgrade Alignment Pages` execution handoff, but `tasks/roadmap.md` has no numbered roadmap phase for that work. `$plan-phase` requires a `## Phase N: ...` roadmap entry with Goal, Scope, and Acceptance Criteria before it can generate implementation steps.

Recommended verdict Approve a narrow task-doc repair: append Phase 3 to the roadmap and queue `$plan-phase 3`.
Source of truth Use the existing handoff in `tasks/todo.md` from commit `001a413` as the phase source.
Non-goal Do not upgrade alignment HTML files in this roadmap run; that remains `$exec` work after planning.

Pipeline Evidence

Artifact Observed State Evidence
`tasks/roadmap.md` Present but not executable for current work Last modified 2026-05-27 15:35:08. Contains completed `Customer And User Stories From ICP` and `Ship Agent Workflow Config` sections, but no `## Phase N:` alignment-upgrade phase.
`tasks/todo.md` Contains unchecked work absent from roadmap Last modified 2026-06-01 10:10:16. Contains `## Phase: Upgrade Alignment Pages` with seven unchecked checklist items and acceptance criteria.
Manual, record, recurring queues Absent No `tasks/manual-todo.md`, `tasks/record-todo.md`, or `tasks/recurring-todo.md` files exist in the active task directory.
`tasks/history.md` Absent Completed task work exists, but no history file is present. This is lower priority than unblocking the current phase.
Git state Clean `git status --short` produced no output. Latest commit is `c4bb629 Add roadmap alignment review page` on `main` and `origin/main`.

Research And Spec Coverage

Available research context

  • `research/concept-brief.md` and interview notes exist.
  • `research/icp.md` and search log exist.
  • `research/competitive-analysis.md` and search log exist.
  • `research/value-prop.md` and search log exist.
  • `research/customer-user-stories.md` exists and reflects the latest founder corrections.

Missing or alternate planning artifacts

  • No active `specs/` directory or `spec.md` exists in the fresh TrackCTL root.
  • No `research/journey-map.md` file exists, but `alignment/journey-map-trackctl.html` exists.
  • The alignment-upgrade task does not require product feature specs; it is maintenance on generated review pages.

Confidence is high for repairing the task pipeline because the needed phase details are already in `tasks/todo.md`. Confidence is lower for broader product roadmapping because no current implementation specs are present outside the archived old codebase.

Candidate Fix

Verdict

Append a new roadmap phase named `Phase 3: Upgrade Alignment Pages`. This preserves the completed roadmap sections, gives `$plan-phase` the structure it requires, and keeps all implementation detail out of the roadmap until the phase is decomposed.

Why not run the upgrade directly?

`$upgrade-alignment-pages --apply` already produced a batch-mode handoff because six pages need upgrades. The next safe step is not editing the pages directly; it is giving the handoff a canonical roadmap phase and then decomposing it.

Manual task classification

No human-only external prerequisites are identified. Archiving, rewriting generated HTML, checking content preservation, and running the central alignment compile are agent-executable repository work.

Proposed File Changes

`tasks/roadmap.md`

Append this phase after the two completed sections. Preserve existing completed roadmap content exactly.

## Phase 3: Upgrade Alignment Pages

**Goal**: Upgrade the six existing `alignment/*.html` review pages to the current alignment-page standard without losing page-specific research, decisions, questions, gates, or review context.

**Scope**:
- Archive each original alignment page under `docs/history/archive/YYYY-MM-DD/HHMMSS/alignment/`.
- Rewrite `alignment/concept-exploration-trackctl.html` to the current dark-mode alignment-page standard.
- Rewrite `alignment/icp-trackctl.html` to the current dark-mode alignment-page standard.
- Rewrite `alignment/competitive-analysis-trackctl.html` to the current dark-mode alignment-page standard.
- Rewrite `alignment/value-prop-canvas-trackctl.html` to the current dark-mode alignment-page standard.
- Rewrite `alignment/journey-map-trackctl.html` to the current dark-mode alignment-page standard.
- Rewrite `alignment/customer-user-stories-trackctl.html` to the current dark-mode alignment-page standard.
- Run central alignment compilation after page upgrades; do not edit `alignment/index.html` by hand.

**Acceptance Criteria:**
- [ ] Each upgraded page uses the current dark-mode alignment-page standard with responsive layout and an in-flow top Table of Contents.
- [ ] Each page preserves its page-specific title, meta/context, findings, matrices, assumptions, decisions, open questions, review notes, proposed next steps, and existing diff/change context.
- [ ] Every major section has section feedback controls with local feedback-only YAML generation.
- [ ] Each applicable approval gate has required inline radio questions with `Other / None of the above`, `Need clarification`, optional notes, and unanswered-question handling.
- [ ] The bottom compile section provides separate feedback-only YAML and final answer YAML flows, copy status, explicit copy buttons, and clipboard fallback behavior.
- [ ] Research-oriented pages include evidence coverage, confidence/assumption handling, source coverage gaps, alternatives or lower-confidence findings where relevant, and downstream decision impact.
- [ ] Each original page is archived under `docs/history/archive/YYYY-MM-DD/HHMMSS/alignment/<filename>.html` before replacement.
- [ ] `alignment/index.html` is regenerated only through the central alignment compile workflow, not edited by hand.

**Parallelization:** serial
**Coordination Notes:** The six pages share the same generated-page standard, archive path, and index regeneration dependency. Keep serial to reduce content-loss risk and avoid conflicting archive/index state.

`tasks/todo.md`

Insert or replace a top-level `## Priority Task Queue` before the current handoff. The first unresolved task should route to phase decomposition after the roadmap phase exists.

## Priority Task Queue

- [ ] `$plan-phase 3` - decompose `Phase 3: Upgrade Alignment Pages` because `tasks/todo.md` contains an unchecked alignment-upgrade handoff, but `$exec` needs roadmap-backed implementation steps before it can run.

Files intentionally not changed in this step

  • `alignment/*.html` pages remain unchanged until `$exec` executes the planned phase.
  • `alignment/index.html` remains untouched; central regeneration is a later phase step.
  • No `tasks/manual-todo.md`, `tasks/record-todo.md`, or `tasks/recurring-todo.md` is needed for this phase.

Assumptions And Risks

Assumption

The existing `Upgrade Alignment Pages` handoff is approved work and should become the next canonical roadmap phase. This is inferred from commit `001a413 Plan alignment page upgrades` and the user invoking `$exec`, `$plan-phase`, then `$roadmap` to unblock it.

Risk if not repaired

`$exec` will continue to stop because the phase has acceptance criteria but no roadmap-backed implementation detail. `$plan-phase` will continue to stop because the phase is missing from `tasks/roadmap.md`.

Deferred findings

  • `tasks/history.md` is absent. This should be recorded during the later shipping step, not used to block the roadmap repair.
  • No active implementation specs exist in `specs/`; broader product-phase discovery should happen after the current alignment-maintenance phase is unblocked or explicitly parked.

Approval Gates

Evidence sufficient?
Assumptions and confidence acceptable?
Sequencing and manual-task classification acceptable?
Proposed canonical file changes approved?
Keep downstream execution blocked until these task docs are approved?

Compile Review YAML

Use feedback YAML for concerns or clarification before final approval. Use final answers only when all required gate questions are answered.

Approved file changes represented in final YAML

  • `tasks/roadmap.md`: append `Phase 3: Upgrade Alignment Pages`.
  • `tasks/todo.md`: add `## Priority Task Queue` with `$plan-phase 3` as the first unresolved item.