[MAJOR] §10: No roadmap or project plan for outstanding work

[mvillmow]

Evidence

.github/ (no ROADMAP.md, no GitHub Projects), CHANGELOG.md:15

Description

Major outstanding work is mentioned in passing — NATS subscriber implementation and state backend for status/list/cancel commands — but neither is tracked in any planning artifact. There is no ROADMAP.md, no milestone, and no labeled issues visible in the repo artifacts. Future contributors have no visibility into planned direction.

Part of #92

[mvillmow]

Implementation Plan

Confirmed: remote is HomericIntelligence/ProjectTelemachy; ## Planned Features is at CLAUDE.md:179; ### Key Components at CLAUDE.md:53; ## Quick Links is the first H2 in CONTRIBUTING.md at line 11.

Implementation Plan

Objective

Issue #167 (MAJOR, §10) flags that ProjectTelemachy ships no roadmap artifact: the two large outstanding work items — the NATS subscriber (#92) and the persistent state backend for status/list/cancel — are referenced only in prose in CLAUDE.md:179-185 and README.md:35, with no ROADMAP.md, no GitHub Milestones (gh api repos/:owner/:repo/milestones → []), and no roadmap-aligned labels (gh label list → no roadmap/nats-subscriber/state-backend). This plan creates docs/ROADMAP.md as the canonical planning artifact, records the decision in ADR-003, opens milestones (v0.1.0, v0.2.0, v1.0.0) and three roadmap labels, wires discoverability links from README.md, CLAUDE.md, CONTRIBUTING.md, docs/adr/README.md, the PR template, and CHANGELOG.md, and adds tests/test_roadmap.py to pin structure and link integrity so the artifact cannot silently rot.

Approach

Decision 1 — docs/ROADMAP.md (not top-level), markdown, four fixed sections. Planning artefacts already live under docs/ (docs/adr/, docs/backwards-compat.md, docs/definition-of-done.md, docs/RELEASING.md, docs/license-audit.md). The PR template at .github/pull_request_template.md:21 already references docs/ROADMAP.md ("see docs/ROADMAP.md if present"). Sections are fixed (Current Release, Next Release, Future, Known Limitations) so the regression test can assert structure.

Decision 2 — issue URLs use the verified canonical remote HomericIntelligence/ProjectTelemachy. Verified via git remote -v → https://github.com/HomericIntelligence/ProjectTelemachy.git and gh repo view --json nameWithOwner → HomericIntelligence/ProjectTelemachy. Every embedded link in docs/ROADMAP.md uses https://github.com/HomericIntelligence/ProjectTelemachy/issues/NNN. (This addresses the prior review's Critical finding #1.)

Decision 3 — milestones drive the roadmap, not labels alone. gh api repos/:owner/:repo/milestones returned []. Milestones are the GitHub-native release-bucketing object and give contributors a filter URL out of the box. Labels (roadmap, nats-subscriber, state-backend) complement them for cross-cutting filtering; gh label list confirms none of these three exist yet.

Decision 4 — bind each roadmap row to an issue or ADR. The roadmap must not become a parallel narrative that drifts from issues. Each row links to a tracking issue (or notes "no issue yet") and to an ADR when one exists. ADR-001 (HTTP polling) is currently Proposed per docs/adr/README.md; the roadmap entry for the NATS subscriber will note that landing #92 supersedes ADR-001.

Decision 5 — re-use the existing ADR template & index conventions. docs/adr/template.md defines a Status / Date / Deciders / Context tags header. ADR-003 is created from that template and added to the index table in docs/adr/README.md so the "why roadmap lives at docs/ROADMAP.md" decision is discoverable alongside ADR-001/002.

Decision 6 — pin structure with a regression test. tests/test_release_workflow.py is the precedent (REPO_ROOT = Path(__file__).resolve().parents[1], function-per-invariant, parse a top-level artifact and assert required invariants). tests/test_roadmap.py follows the same shape — parse docs/ROADMAP.md, assert required H2 sections, assert ADR link integrity, assert ADR-003 exists and is Accepted.

Decision 7 — edit-targets cite section headings, not line numbers, for narrative files that rot. Verified headings via grep -nE "^##|^###" CLAUDE.md CONTRIBUTING.md README.md: ## Planned Features is at CLAUDE.md:179, ### Key Components at CLAUDE.md:53, ## Quick Links at CONTRIBUTING.md:11, ## Development Setup at CONTRIBUTING.md:20, ## Quick Start at README.md:16. Each modification below cites the exact heading anchor + verified line so the implementer cannot land in the wrong block. (This addresses the prior review's Major finding #2.)

Decision 8 — no CLI / source changes. Issue #167 is a planning-artefact gap (§10 = roadmap/planning); src/telemachy/ is out of scope. Touching it would violate KISS/YAGNI per the audit-remediation principles already in memory.

Files to Create

docs/ROADMAP.md

Canonical roadmap, four required H2 sections, every external issue link uses https://github.com/HomericIntelligence/ProjectTelemachy/issues/NNN.

# ProjectTelemachy Roadmap

This roadmap is the authoritative planning artefact for ProjectTelemachy.
It captures **what is shipping now, what is shipping next, and what we
know is not yet built**. Every row links to an issue, an ADR, or both.

Conventions:
- Release lines follow `docs/backwards-compat.md` (SemVer; v0.x is pre-1.0).
- Each row links to a tracking issue (or notes _no issue yet_) and to
  any relevant ADR under `docs/adr/`.
- This file is regression-tested by `tests/test_roadmap.py`.

## Current Release (v0.1.x — Unreleased)

| Work | Status | Issue | ADR |
| --- | --- | --- | --- |
| HTTP-polling task monitoring | Shipped (default) | — | [ADR-001](adr/001-http-polling-monitoring.md) |
| Agamemnon-exclusive backend | Shipped | — | [ADR-002](adr/002-decouple-from-maestro.md) |
| Secure TLS default (`REQUIRE_TLS=true`) | Shipped | [#158](https://github.com/HomericIntelligence/ProjectTelemachy/issues/158) | — |
| Release workflow (PyPI + GH Release) | Shipped | [#153](https://github.com/HomericIntelligence/ProjectTelemachy/issues/153) | — |
| 75% coverage gate | Shipped | [#152](https://github.com/HomericIntelligence/ProjectTelemachy/issues/152) | — |
| Strict-audit remediation epic | In progress | [#92](https://github.com/HomericIntelligence/ProjectTelemachy/issues/92) | — |

## Next Release (v0.2.0)

| Work | Status | Issue | ADR |
| --- | --- | --- | --- |
| NATS subscriber for task-lifecycle events (supersedes ADR-001) | Planned | [#92](https://github.com/HomericIntelligence/ProjectTelemachy/issues/92) | ADR-001 → to be superseded |
| Roadmap & milestones (this artefact) | In progress | [#167](https://github.com/HomericIntelligence/ProjectTelemachy/issues/167) | [ADR-003](adr/003-roadmap-artifact.md) |

## Future (v1.0.0 and beyond)

| Work | Status | Issue | ADR |
| --- | --- | --- | --- |
| Persistent workflow-state backend (enables `status`/`list`/`cancel`) | Design not started | _no issue yet — file before starting work_ | _ADR required at design time_ |
| Stabilise workflow YAML to `apiVersion: telemachy/v1` (drop pre-1.0 caveats) | Pending v0.2.0 | _no issue yet_ | — |

## Known Limitations

- `status`, `list`, and `cancel` CLI commands are not implemented; they
  require the state backend listed in Future. Until then, query
  ProjectAgamemnon directly. (`CLAUDE.md` §Planned Features, `README.md`.)
- Task-completion detection is HTTP polling, bounded by
  `MONITOR_TIMEOUT_SECONDS` / `MONITOR_MAX_POLLS`. Event-driven
  detection is gated on the NATS subscriber above.
- `NATS_URL` is parsed and TLS-validated but **not yet subscribed to**;
  it is reserved for the planned subscriber.

## How to propose a roadmap change

1. Open an issue with label `roadmap`.
2. If the change implies an architectural decision, draft an ADR under
   `docs/adr/` per `docs/adr/template.md`.
3. Reference the issue + ADR from the relevant row in this file.

docs/adr/003-roadmap-artifact.md

Records the decision; uses docs/adr/template.md exactly.

# ADR-003: `docs/ROADMAP.md` as the canonical planning artefact

- **Status:** Accepted
- **Date:** 2026-06-03
- **Deciders:** ProjectTelemachy maintainers
- **Context tags:** planning, governance, docs

## Context

Audit finding §10 (#167) observed that major outstanding work — the
NATS subscriber (#92) and the persistent state backend for `status` /
`list` / `cancel` — is referenced only in `CLAUDE.md` prose and a
`README.md` aside. There is no canonical planning artefact, no
milestones, and no roadmap labels. Future contributors have no
single place to read what is shipping, what is planned, and what is
not yet built.

## Decision

`docs/ROADMAP.md` is the canonical roadmap. It is:

1. Bound to GitHub Milestones (`v0.1.0`, `v0.2.0`, `v1.0.0`) so issues
   can be filtered by release line in the UI.
2. Tagged with the cross-cutting labels `roadmap`, `nats-subscriber`,
   and `state-backend`.
3. Regression-tested (`tests/test_roadmap.py`) for required H2
   sections and link integrity.
4. Linked from `README.md`, `CLAUDE.md`, `CONTRIBUTING.md`, and the
   PR template.

## Consequences

Positive:
- Single discoverable source for "what is planned".
- Drift surfaces as a CI failure rather than a stale prose snippet.
- ADRs and roadmap rows cross-reference each other.

Negative:
- Two places to update when planning changes: the roadmap row and the
  issue/ADR. Mitigated by the regression test, which fails if rows
  point at dead links.

## Alternatives considered

- **GitHub Projects only.** Rejected: not visible to anonymous readers,
  not version-controlled, not reviewable via PR.
- **Top-level `ROADMAP.md`.** Rejected: the PR template
  (`.github/pull_request_template.md:21`) already references
  `docs/ROADMAP.md`; planning artefacts already live under `docs/`.
- **Embed roadmap in `README.md`.** Rejected: would dilute the
  README's role as a quickstart and make the regression test brittle.

## References

- Issue #167, #92
- ADR-001, ADR-002
- `docs/backwards-compat.md`

tests/test_roadmap.py

Mirrors tests/test_release_workflow.py:1-40 style. Five named test functions, each pinning one invariant. The ADR-link regex matches both inline [text](adr/file.md) and table-cell [ADR-001](adr/001-http-polling-monitoring.md) forms (markdown link syntax is identical in both contexts, so \[[^\]]+\]\(adr/([^)\s]+\.md)\) covers both).

import re
from pathlib import Path

REPO_ROOT = Path(__file__).resolve().parents[1]
ROADMAP = REPO_ROOT / "docs" / "ROADMAP.md"
ADR_DIR = REPO_ROOT / "docs" / "adr"

REQUIRED_SECTIONS = (
    "Current Release",
    "Next Release",
    "Future",
    "Known Limitations",
)

# Matches any markdown link whose target starts with `adr/` and ends with `.md`,
# regardless of whether the link sits in a paragraph or a table cell.
ADR_LINK_RE = re.compile(r"\[[^\]]+\]\(adr/([^)\s]+\.md)\)")


def _read() -> str:
    assert ROADMAP.is_file(), "docs/ROADMAP.md is missing (issue #167)"
    return ROADMAP.read_text(encoding="utf-8")


def test_roadmap_exists() -> None:
    _read()


def test_roadmap_has_required_sections() -> None:
    text = _read()
    for heading in REQUIRED_SECTIONS:
        assert re.search(rf"^##\s+{re.escape(heading)}\b", text, re.MULTILINE), (
            f"docs/ROADMAP.md missing required `## {heading}` section"
        )


def test_roadmap_references_outstanding_work_items() -> None:
    # Issue #167 specifically calls out NATS subscriber and state backend.
    text = _read().lower()
    assert "nats subscriber" in text
    assert "state backend" in text
    assert "#92" in text  # parent epic
    assert "#167" in text  # this finding


def test_roadmap_uses_canonical_remote_url() -> None:
    # Guard against the fork-URL defect seen in the prior plan iteration.
    text = _read()
    bad = re.findall(r"https://github\.com/(?!HomericIntelligence/ProjectTelemachy)[^/\s)]+/ProjectTelemachy", text)
    assert not bad, f"docs/ROADMAP.md links to non-canonical repo URLs: {bad}"


def test_roadmap_adr_links_resolve() -> None:
    text = _read()
    targets = ADR_LINK_RE.findall(text)
    assert targets, "docs/ROADMAP.md has no ADR links — at least ADR-001/002/003 must be referenced"
    for rel in targets:
        assert (ADR_DIR / rel).is_file(), f"docs/ROADMAP.md links to missing ADR: {rel}"


def test_adr_003_present_and_accepted() -> None:
    adr = ADR_DIR / "003-roadmap-artifact.md"
    assert adr.is_file(), "ADR-003 (roadmap artefact) is missing"
    body = adr.read_text(encoding="utf-8")
    assert "**Status:** Accepted" in body

Files to Modify

README.md

Insert a new ## Roadmap H2 immediately after ## Quick Start (verified at README.md:16, before ## Workflow Schema at README.md:38). The README currently has a single prose line at README.md:35 mentioning the state backend; this new section supersedes that aside.

## Roadmap

See [`docs/ROADMAP.md`](docs/ROADMAP.md) for the canonical roadmap —
current, next, and future releases plus known limitations. Outstanding
work (NATS subscriber, state backend for `status`/`list`/`cancel`) is
tracked under epic [#92](https://github.com/HomericIntelligence/ProjectTelemachy/issues/92).

CLAUDE.md

Two edits, both cited by verified heading + line:

(a) At the end of the ## Planned Features block (heading at CLAUDE.md:179, block runs to CLAUDE.md:185), append a pointer.

For the full planning picture — including release-line bucketing and
known limitations — see `docs/ROADMAP.md`. Roadmap drift is regression-
tested (`tests/test_roadmap.py`).

(b) In the ### Key Components block (heading at CLAUDE.md:53), append a final bullet pointing at the roadmap so the architecture-index entry surfaces it.

- `docs/ROADMAP.md` — canonical roadmap for outstanding work (NATS
  subscriber under #92, state backend under v1.0.0). See ADR-003.

CONTRIBUTING.md

Insert a new H2 ## Where to find the roadmap immediately before ## Development Setup (verified at CONTRIBUTING.md:20), placing it right after ## Quick Links (verified at CONTRIBUTING.md:11). This puts the roadmap pointer in the orientation block where new contributors land first.

## Where to find the roadmap

Planning lives in [`docs/ROADMAP.md`](docs/ROADMAP.md). Cross-cutting
work is bucketed into milestones (`v0.1.0`, `v0.2.0`, `v1.0.0`) and
tagged with the `roadmap`, `nats-subscriber`, or `state-backend`
labels. Open an issue with label `roadmap` to propose a change before
sending a PR that alters planned scope.

docs/adr/README.md

Append ADR-003 to the Index table.

| 003 | `docs/ROADMAP.md` as the canonical planning artefact | Accepted |

.github/pull_request_template.md

At .github/pull_request_template.md:21 the template currently reads Suggested milestone: v0.x.y (see docs/ROADMAP.md if present). Drop "if present" now that the file exists.

Suggested milestone:     v0.x.y  (see docs/ROADMAP.md)

CHANGELOG.md

Add a bullet under ## [Unreleased] → ### Added (block starts at CHANGELOG.md:11, current first bullet at CHANGELOG.md:13-19).

- `docs/ROADMAP.md`, ADR-003, and `v0.1.0`/`v0.2.0`/`v1.0.0` GitHub
  milestones establishing the canonical planning artefact for
  ProjectTelemachy. Regression-tested by `tests/test_roadmap.py`.
  Closes #167; part of #92.

Implementation Order

1. Create docs/ROADMAP.md with the four required H2 sections and the issue/ADR links shown above (all URLs using HomericIntelligence/ProjectTelemachy).
2. Create docs/adr/003-roadmap-artifact.md copied from docs/adr/template.md, status Accepted.
3. Append ADR-003 row to the Index table in docs/adr/README.md.
4. Create tests/test_roadmap.py and run pixi run pytest tests/test_roadmap.py -v locally; iterate on the roadmap text until all six tests pass (the new canonical-URL guard included).
5. Apply discoverability edits:
   • README.md — insert ## Roadmap after ## Quick Start (README.md:16).
   • CLAUDE.md — append pointer at end of ## Planned Features (CLAUDE.md:179); add roadmap bullet at end of ### Key Components (CLAUDE.md:53).
   • CONTRIBUTING.md — insert ## Where to find the roadmap before ## Development Setup (CONTRIBUTING.md:20).
   • .github/pull_request_template.md — drop "if present" at line 21.
   • CHANGELOG.md — add ### Added bullet under [Unreleased].
6. Run the full suite & lint: just test && just lint.
7. Create milestones and labels via gh (idempotent):

   gh api repos/:owner/:repo/milestones -f title='v0.1.0' -f description='Current release line — see docs/ROADMAP.md'
   gh api repos/:owner/:repo/milestones -f title='v0.2.0' -f description='NATS subscriber + roadmap (see docs/ROADMAP.md)'
   gh api repos/:owner/:repo/milestones -f title='v1.0.0' -f description='State backend + stable workflow API (see docs/ROADMAP.md)'
   gh label create roadmap         --color '0075ca' --description 'Roadmap-tracked work (see docs/ROADMAP.md)' || true
   gh label create nats-subscriber --color '5319e7' --description 'NATS subscriber implementation (#92)'        || true
   gh label create state-backend   --color '5319e7' --description 'Persistent workflow-state backend'           || true

   :owner/:repo resolves to HomericIntelligence/ProjectTelemachy from the local git remote.
8. Attach Epic: Strict audit 2026-04-28 — ProjectTelemachy #92, [MAJOR] §10: No roadmap or project plan for outstanding work #167, [MINOR] §6: No coverage minimum threshold in CI #152, [MINOR] §6: No release or deployment workflow #153, [MINOR] §8: require_tls defaults to False — insecure configuration is path of least resistance #158 to their milestones via gh issue edit <N> --milestone <name>. Apply the roadmap label to [MAJOR] §10: No roadmap or project plan for outstanding work #167.
9. Open PR following CONTRIBUTING.md: Closes #167; part of #92. Tick "Documentation only" in the PR template type-of-change list.

Verification

# Criterion: ROADMAP.md exists (issue evidence: ".github/ (no ROADMAP.md ...)")
pixi run pytest tests/test_roadmap.py::test_roadmap_exists -v

# Criterion: required H2 sections present so the artefact cannot drift to prose-only
pixi run pytest tests/test_roadmap.py::test_roadmap_has_required_sections -v

# Criterion: NATS subscriber + state backend (the two work items called out in #167) are explicitly named
pixi run pytest tests/test_roadmap.py::test_roadmap_references_outstanding_work_items -v

# Criterion: every issue link uses the canonical HomericIntelligence/ProjectTelemachy remote (guards against fork-URL defect)
pixi run pytest tests/test_roadmap.py::test_roadmap_uses_canonical_remote_url -v

# Criterion: every ADR link in the roadmap resolves (no dead pointers)
pixi run pytest tests/test_roadmap.py::test_roadmap_adr_links_resolve -v

# Criterion: ADR-003 (roadmap-as-artefact decision) exists and is Accepted
pixi run pytest tests/test_roadmap.py::test_adr_003_present_and_accepted -v

# Criterion: full suite still green under the 75% coverage gate (CLAUDE.md Development Guidelines)
pixi run pytest --cov=src/telemachy --cov-fail-under=75

# Criterion: milestones exist on the repo (GitHub Projects/Milestones gap called out by #167)
gh api repos/:owner/:repo/milestones --jq '.[].title' | grep -E '^v(0\.1\.0|0\.2\.0|1\.0\.0)$' | wc -l   # expect 3

# Criterion: roadmap labels exist (label-based filtering gap called out by #167)
gh label list | grep -E '^(roadmap|nats-subscriber|state-backend)\b' | wc -l   # expect 3

# Criterion: lint clean (project guardrail per CLAUDE.md)
just lint

Skills Used

• planning (Hephaestus): structured TASK/PLAN/REVIEW output, section ordering, line-cited handoff.
• graph-query / docs-search (read-only grep-and-read): grounded decisions in docs/adr/, .github/pull_request_template.md, CHANGELOG.md, tests/test_release_workflow.py, and the canonical git remote.
• documentation-strict-audit-remediation-workflow (team knowledge base, per the audit-remediation-plan memory): Wave 2 documentation remediation — pair docs artefact with ADR plus regression test.
• code-quality-audit-principles (team knowledge base, per the audit-remediation-plan memory): KISS/YAGNI applied — no src/telemachy/ changes; the gap is a planning-artefact gap.
• hephaestus:advise / hephaestus:learn: ADR-driven decision-recording pattern reused from ADR-001/002.
• hephaestus:verification: pre-NOGO-fix verification of canonical remote (git remote -v + gh repo view) and section line numbers (grep -nE "^##|^###").

Changes from review

Every concrete finding in the prior review is addressed below. No finding is merely acknowledged.

1. Critical fix: ecosystem audit — migrate config to pydantic-settings #1 (wrong GitHub URL throughout primary deliverable). Verified the canonical remote with git remote -v (→ https://github.com/HomericIntelligence/ProjectTelemachy.git) and gh repo view --json nameWithOwner (→ HomericIntelligence/ProjectTelemachy). Every issue link in the embedded docs/ROADMAP.md content (rows for Epic: Strict audit 2026-04-28 — ProjectTelemachy #92, [MINOR] §6: No coverage minimum threshold in CI #152, [MINOR] §6: No release or deployment workflow #153, [MINOR] §8: require_tls defaults to False — insecure configuration is path of least resistance #158, [MAJOR] §10: No roadmap or project plan for outstanding work #167 and the Roadmap pointer in README.md) now uses https://github.com/HomericIntelligence/ProjectTelemachy/issues/NNN. Added a sixth regression test, test_roadmap_uses_canonical_remote_url, that fails CI if any future edit reintroduces a non-canonical URL pattern (HomericIntelligence/ProjectTelemachy is the only allowed /ProjectTelemachy URL).

2. Major Remove backlog from _DONE_STATUSES — it is an initial state, not terminal #2 (CLAUDE.md edit targets underspecified). Ran grep -nE "^##|^###" CLAUDE.md and pinned exact headings + verified lines: ## Planned Features at CLAUDE.md:179 (block runs to CLAUDE.md:185), ### Key Components at CLAUDE.md:53. The ## Files to Modify → CLAUDE.md section now cites both heading anchors and verified line numbers, and the implementation order names the headings as the primary insertion anchors so future line drift cannot land the edit in the wrong block. Applied the same fix to CONTRIBUTING.md (## Quick Links at CONTRIBUTING.md:11, ## Development Setup at CONTRIBUTING.md:20 — explicit "insert before ## Development Setup") and README.md (## Quick Start at README.md:16, ## Workflow Schema at README.md:38 — explicit "insert after ## Quick Start").

3. Minor Implement NATS event-driven monitoring instead of polling #3 (ADR-link regex brittleness). Replaced \(adr/([^)\s]+\.md)\) with \[[^\]]+\]\(adr/([^)\s]+\.md)\), which is the full markdown-link production and matches both inline and table-cell uses identically. Also added an assertion that at least one ADR link exists (assert targets, …), so an empty/stripped roadmap fails loudly rather than passing vacuously.

4. Minor Add tests for executor error paths (partial failures, cancellation) #4 (CONTRIBUTING.md insertion point vague). Replaced "near the top, before the contribution-flow steps" with the precise anchor "insert immediately before ## Development Setup (CONTRIBUTING.md:20), placing it right after ## Quick Links (CONTRIBUTING.md:11)" in both ## Files to Modify and ## Implementation Order.

---

Final review verdict (from strict review loop)

Good. Now I have the concrete facts needed to evaluate the R1 plan. Let me conduct the systematic review.

---

R1 Review: Implementation Plan for Issue #167

Prior Iteration Findings — Resolution Check

The R0 review had two critical/major findings and two minor ones:

Critical #1 (wrong GitHub URL — villmow instead of HomericIntelligence):

The plan's "Changes from review" section states this is resolved. Examining the current plan text in docs/ROADMAP.md content: every embedded issue URL uses https://github.com/HomericIntelligence/ProjectTelemachy/issues/NNN (rows for #92, #152, #153, #158, #167). The README.md insert also uses HomericIntelligence/ProjectTelemachy/issues/92. A sixth regression test test_roadmap_uses_canonical_remote_url has been added that fails if any URL contains a non-canonical owner. The remote is confirmed as HomericIntelligence/ProjectTelemachy.

Resolution: CONFIRMED FIXED.

Major #2 (CLAUDE.md line numbers underspecified, implementer must re-derive):

The plan now explicitly states: "## Planned Features is at CLAUDE.md:179" and "### Key Components at CLAUDE.md:53". The "Files to Modify → CLAUDE.md" section says "(a) At the end of the ## Planned Features block (heading at CLAUDE.md:179, block runs to CLAUDE.md:185)" and "(b) In the ### Key Components block (heading at CLAUDE.md:53)". The implementation order also cites these as primary insertion anchors. Verified against the repo: ## Planned Features is at line 179, ### Key Components is at line 53. Both correct.

The same treatment is applied to CONTRIBUTING.md ("## Quick Links at CONTRIBUTING.md:11, ## Development Setup at CONTRIBUTING.md:20" — verified correct) and README.md ("## Quick Start at README.md:16, ## Workflow Schema at README.md:38" — verified correct).

Resolution: CONFIRMED FIXED.

Minor #3 (ADR-link regex brittleness):

The plan replaces \(adr/([^)\s]+\.md)\) with \[[^\]]+\]\(adr/([^)\s]+\.md)\) and adds assert targets, … so an empty result fails loudly. The test file in the plan now uses this improved regex. This matches both inline and table-cell forms.

Resolution: CONFIRMED FIXED.

Minor #4 (CONTRIBUTING.md insertion point vague):

The plan now says "insert immediately before ## Development Setup (CONTRIBUTING.md:20), placing it right after ## Quick Links (CONTRIBUTING.md:11)". Verified both headings at those exact lines.

Resolution: CONFIRMED FIXED.

---

Dimension 1: Requirements Alignment

Issue #167 cites: no ROADMAP.md, no milestone, no labeled issues, two specific outstanding work items (NATS subscriber, state backend).

• ROADMAP.md: plan creates it ✓
• Milestones: plan creates v0.1.0, v0.2.0, v1.0.0 ✓
• Labels: roadmap, nats-subscriber, state-backend ✓
• NATS subscriber tracked: in docs/ROADMAP.md "Next Release" under Epic: Strict audit 2026-04-28 — ProjectTelemachy #92 ✓
• State backend tracked: in "Future (v1.0.0 and beyond)" ✓
• Part of Epic: Strict audit 2026-04-28 — ProjectTelemachy #92: plan links back ✓

All stated criteria addressed. No silently dropped requirements.

Dimension 2: Plan Completeness

Design decisions (Decision 1–8) ✓, implementation in ordered steps 1–9 ✓, tests with named functions ✓, verification with 9 concrete commands ✓. Rollback consideration: docs-only PR is trivially reversible; plan notes "Documentation only" PR type. No hard-to-reverse operations.

Finding: Complete.

Dimension 3: Concreteness

Every file to create or modify is named by path. Every test function is named. gh commands are given verbatim. CLAUDE.md, CONTRIBUTING.md, and README.md insertion anchors cite both heading name and verified line number. The inline content for each file modification is provided in the plan.

One residual concern: The plan says docs/backwards-compat.md defines "SemVer; v0.x is pre-1.0" — this is now verifiable and correct (the file does cover SemVer and explicitly has a pre-1.0 caveat). The Learnings section correctly flags this as an assumption, but it's verified by the Explore agent's findings. Not a plan defect.

Finding: Highly concrete; no underspecified edit targets remain.

Dimension 4: Risk Surface

Documentation-only. No source changes, no schema changes, no migrations. GitHub gh api milestone creation is additive. Label creation uses || true for idempotency. Issue attachment via gh issue edit is reversible. No destructive operations. The plan explicitly states Decision 8 ("no CLI / source changes").

The Learnings section notes that || true on gh label create may silently overwrite existing labels if they already exist with different colors. This is a mild concern but not a blocking defect — label metadata drift is easily corrected and doesn't affect the shipped artifact.

Finding: Risk is appropriately low for docs-only work.

Dimension 5: Verification Plan

Nine concrete verification commands, one per acceptance criterion:

1. test_roadmap_exists — ROADMAP.md presence
2. test_roadmap_has_required_sections — H2 structure
3. test_roadmap_references_outstanding_work_items — NATS + state backend content
4. test_roadmap_uses_canonical_remote_url — URL correctness (new in R1)
5. test_roadmap_adr_links_resolve — no dead ADR pointers
6. test_adr_003_present_and_accepted — ADR-003 created
7. Full suite with coverage gate — pixi run pytest --cov-fail-under=75
8. Milestones count check via gh api
9. Labels count check via gh label list
10. Lint via just lint

All acceptance criteria have concrete checks. The Learnings section's concern about regex edge cases (headings in code blocks) is acknowledged and remains minor — the regex pattern ^##\s+{re.escape(heading)}\b with re.MULTILINE could match a heading inside a fenced code block. However since ROADMAP.md is a new file the plan defines, the implementer controls its format and no headings will appear inside code blocks.

Finding: Verification is solid.

Dimension 6: Stage Handoff

The plan provides sufficient artifacts: exact file content (ROADMAP.md, ADR-003, test file), specific insertion points with verified line numbers and heading anchors, verbatim gh commands, ordered steps, and verification commands. An implementer can execute step-by-step without re-deriving design decisions.

Finding: Clean handoff.

Software Engineering Principles

P1 (KISS): Docs-only change, no unnecessary abstractions. Regression test proportional to artifact. Single ROADMAP.md file, not a complex system. ✓

P2 (YAGNI): Every step maps to #167's stated requirements. No opportunistic scope additions. Decision 8 explicitly excludes src/telemachy/. ✓

P3 (TDD): Step 4 mandates running the tests before proceeding to step 5. Tests define the acceptance criteria. The docs artifact is built to satisfy the tests, not vice versa. ✓

P4 (DRY): Cross-linking across README, CLAUDE.md, CONTRIBUTING.md is appropriate discoverability — not duplication. No single source of truth is duplicated; each file gets one pointer to docs/ROADMAP.md. ✓

P5 (SOLID): Not strongly applicable to documentation. No finding.

P6 (Modularity): Follows existing docs/ convention. ADR-003 placed in docs/adr/ alongside ADR-001/002. Regression test follows tests/test_release_workflow.py pattern already established. ✓

P7 (POLA): PR template change from "if present" to direct reference is exactly right. The || true on label creation is idempotent and predictable. The roadmap's "How to propose a roadmap change" section makes the workflow explicit. ✓

---

Residual Concerns (below NOGO threshold)

1. Learnings section unresolved assumption about docs/backwards-compat.md: Now verifiable — the file exists and does cover SemVer with a pre-1.0 caveat. Not a plan defect; the assumption is correct.

2. Issue validation (step 8): Plan assumes Epic: Strict audit 2026-04-28 — ProjectTelemachy #92, [MINOR] §6: No coverage minimum threshold in CI #152, [MINOR] §6: No release or deployment workflow #153, [MINOR] §8: require_tls defaults to False — insecure configuration is path of least resistance #158, [MAJOR] §10: No roadmap or project plan for outstanding work #167 are open and editable. Reasonable assumption for a live repo; gh issue edit will fail gracefully if any are closed. Not a blocking concern for the plan itself.

3. ADR-001 internal status vs. index: Verified — ADR-001's internal status field is "Proposed" (line 3: - **Status:** Proposed), matching the index. The roadmap's assertion that landing Epic: Strict audit 2026-04-28 — ProjectTelemachy #92 "supersedes ADR-001" is accurate. ✓

4. Regex for section matching: ^##\s+{re.escape(heading)}\b with re.MULTILINE could match a heading inside a fenced code block in theory, but the plan defines ROADMAP.md's content and no H2 headings appear inside code fences in the specified content. Acceptable.

---

Verdict Reasoning

All four prior-iteration findings (Critical #1, Major #2, Minor #3, Minor #4) are concretely resolved in the plan text — not merely acknowledged. The prior Critical finding (wrong URL) is fixed with verified canonical URLs and a new regression test. The prior Major finding (underspecified edit targets) is fixed with verified heading names and line numbers. Both minor findings are addressed. No new critical or major findings emerge on fresh analysis. The plan is concrete, verifiable, and produces clean handoff artifacts. All P1–P7 principles pass.

Grade: B
Verdict: GO

---

Generated by Claude Code Planner (strict review loop)

[mvillmow]

🔍 Plan Review

Good. Now I have the concrete facts needed to evaluate the R1 plan. Let me conduct the systematic review.

---

R1 Review: Implementation Plan for Issue #167

Prior Iteration Findings — Resolution Check

The R0 review had two critical/major findings and two minor ones:

Critical #1 (wrong GitHub URL — villmow instead of HomericIntelligence):

The plan's "Changes from review" section states this is resolved. Examining the current plan text in docs/ROADMAP.md content: every embedded issue URL uses https://github.com/HomericIntelligence/ProjectTelemachy/issues/NNN (rows for #92, #152, #153, #158, #167). The README.md insert also uses HomericIntelligence/ProjectTelemachy/issues/92. A sixth regression test test_roadmap_uses_canonical_remote_url has been added that fails if any URL contains a non-canonical owner. The remote is confirmed as HomericIntelligence/ProjectTelemachy.

Resolution: CONFIRMED FIXED.

Major #2 (CLAUDE.md line numbers underspecified, implementer must re-derive):

The plan now explicitly states: "## Planned Features is at CLAUDE.md:179" and "### Key Components at CLAUDE.md:53". The "Files to Modify → CLAUDE.md" section says "(a) At the end of the ## Planned Features block (heading at CLAUDE.md:179, block runs to CLAUDE.md:185)" and "(b) In the ### Key Components block (heading at CLAUDE.md:53)". The implementation order also cites these as primary insertion anchors. Verified against the repo: ## Planned Features is at line 179, ### Key Components is at line 53. Both correct.

The same treatment is applied to CONTRIBUTING.md ("## Quick Links at CONTRIBUTING.md:11, ## Development Setup at CONTRIBUTING.md:20" — verified correct) and README.md ("## Quick Start at README.md:16, ## Workflow Schema at README.md:38" — verified correct).

Resolution: CONFIRMED FIXED.

Minor #3 (ADR-link regex brittleness):

The plan replaces \(adr/([^)\s]+\.md)\) with \[[^\]]+\]\(adr/([^)\s]+\.md)\) and adds assert targets, … so an empty result fails loudly. The test file in the plan now uses this improved regex. This matches both inline and table-cell forms.

Resolution: CONFIRMED FIXED.

Minor #4 (CONTRIBUTING.md insertion point vague):

The plan now says "insert immediately before ## Development Setup (CONTRIBUTING.md:20), placing it right after ## Quick Links (CONTRIBUTING.md:11)". Verified both headings at those exact lines.

Resolution: CONFIRMED FIXED.

---

Dimension 1: Requirements Alignment

Issue #167 cites: no ROADMAP.md, no milestone, no labeled issues, two specific outstanding work items (NATS subscriber, state backend).

• ROADMAP.md: plan creates it ✓
• Milestones: plan creates v0.1.0, v0.2.0, v1.0.0 ✓
• Labels: roadmap, nats-subscriber, state-backend ✓
• NATS subscriber tracked: in docs/ROADMAP.md "Next Release" under Epic: Strict audit 2026-04-28 — ProjectTelemachy #92 ✓
• State backend tracked: in "Future (v1.0.0 and beyond)" ✓
• Part of Epic: Strict audit 2026-04-28 — ProjectTelemachy #92: plan links back ✓

All stated criteria addressed. No silently dropped requirements.

Dimension 2: Plan Completeness

Design decisions (Decision 1–8) ✓, implementation in ordered steps 1–9 ✓, tests with named functions ✓, verification with 9 concrete commands ✓. Rollback consideration: docs-only PR is trivially reversible; plan notes "Documentation only" PR type. No hard-to-reverse operations.

Finding: Complete.

Dimension 3: Concreteness

Every file to create or modify is named by path. Every test function is named. gh commands are given verbatim. CLAUDE.md, CONTRIBUTING.md, and README.md insertion anchors cite both heading name and verified line number. The inline content for each file modification is provided in the plan.

One residual concern: The plan says docs/backwards-compat.md defines "SemVer; v0.x is pre-1.0" — this is now verifiable and correct (the file does cover SemVer and explicitly has a pre-1.0 caveat). The Learnings section correctly flags this as an assumption, but it's verified by the Explore agent's findings. Not a plan defect.

Finding: Highly concrete; no underspecified edit targets remain.

Dimension 4: Risk Surface

Documentation-only. No source changes, no schema changes, no migrations. GitHub gh api milestone creation is additive. Label creation uses || true for idempotency. Issue attachment via gh issue edit is reversible. No destructive operations. The plan explicitly states Decision 8 ("no CLI / source changes").

The Learnings section notes that || true on gh label create may silently overwrite existing labels if they already exist with different colors. This is a mild concern but not a blocking defect — label metadata drift is easily corrected and doesn't affect the shipped artifact.

Finding: Risk is appropriately low for docs-only work.

Dimension 5: Verification Plan

Nine concrete verification commands, one per acceptance criterion:

1. test_roadmap_exists — ROADMAP.md presence
2. test_roadmap_has_required_sections — H2 structure
3. test_roadmap_references_outstanding_work_items — NATS + state backend content
4. test_roadmap_uses_canonical_remote_url — URL correctness (new in R1)
5. test_roadmap_adr_links_resolve — no dead ADR pointers
6. test_adr_003_present_and_accepted — ADR-003 created
7. Full suite with coverage gate — pixi run pytest --cov-fail-under=75
8. Milestones count check via gh api
9. Labels count check via gh label list
10. Lint via just lint

All acceptance criteria have concrete checks. The Learnings section's concern about regex edge cases (headings in code blocks) is acknowledged and remains minor — the regex pattern ^##\s+{re.escape(heading)}\b with re.MULTILINE could match a heading inside a fenced code block. However since ROADMAP.md is a new file the plan defines, the implementer controls its format and no headings will appear inside code blocks.

Finding: Verification is solid.

Dimension 6: Stage Handoff

The plan provides sufficient artifacts: exact file content (ROADMAP.md, ADR-003, test file), specific insertion points with verified line numbers and heading anchors, verbatim gh commands, ordered steps, and verification commands. An implementer can execute step-by-step without re-deriving design decisions.

Finding: Clean handoff.

Software Engineering Principles

P1 (KISS): Docs-only change, no unnecessary abstractions. Regression test proportional to artifact. Single ROADMAP.md file, not a complex system. ✓

P2 (YAGNI): Every step maps to #167's stated requirements. No opportunistic scope additions. Decision 8 explicitly excludes src/telemachy/. ✓

P3 (TDD): Step 4 mandates running the tests before proceeding to step 5. Tests define the acceptance criteria. The docs artifact is built to satisfy the tests, not vice versa. ✓

P4 (DRY): Cross-linking across README, CLAUDE.md, CONTRIBUTING.md is appropriate discoverability — not duplication. No single source of truth is duplicated; each file gets one pointer to docs/ROADMAP.md. ✓

P5 (SOLID): Not strongly applicable to documentation. No finding.

P6 (Modularity): Follows existing docs/ convention. ADR-003 placed in docs/adr/ alongside ADR-001/002. Regression test follows tests/test_release_workflow.py pattern already established. ✓

P7 (POLA): PR template change from "if present" to direct reference is exactly right. The || true on label creation is idempotent and predictable. The roadmap's "How to propose a roadmap change" section makes the workflow explicit. ✓

---

Residual Concerns (below NOGO threshold)

1. Learnings section unresolved assumption about docs/backwards-compat.md: Now verifiable — the file exists and does cover SemVer with a pre-1.0 caveat. Not a plan defect; the assumption is correct.

2. Issue validation (step 8): Plan assumes Epic: Strict audit 2026-04-28 — ProjectTelemachy #92, [MINOR] §6: No coverage minimum threshold in CI #152, [MINOR] §6: No release or deployment workflow #153, [MINOR] §8: require_tls defaults to False — insecure configuration is path of least resistance #158, [MAJOR] §10: No roadmap or project plan for outstanding work #167 are open and editable. Reasonable assumption for a live repo; gh issue edit will fail gracefully if any are closed. Not a blocking concern for the plan itself.

3. ADR-001 internal status vs. index: Verified — ADR-001's internal status field is "Proposed" (line 3: - **Status:** Proposed), matching the index. The roadmap's assertion that landing Epic: Strict audit 2026-04-28 — ProjectTelemachy #92 "supersedes ADR-001" is accurate. ✓

4. Regex for section matching: ^##\s+{re.escape(heading)}\b with re.MULTILINE could match a heading inside a fenced code block in theory, but the plan defines ROADMAP.md's content and no H2 headings appear inside code fences in the specified content. Acceptable.

---

Verdict Reasoning

All four prior-iteration findings (Critical #1, Major #2, Minor #3, Minor #4) are concretely resolved in the plan text — not merely acknowledged. The prior Critical finding (wrong URL) is fixed with verified canonical URLs and a new regression test. The prior Major finding (underspecified edit targets) is fixed with verified heading names and line numbers. Both minor findings are addressed. No new critical or major findings emerge on fresh analysis. The plan is concrete, verifiable, and produces clean handoff artifacts. All P1–P7 principles pass.

Grade: B
Verdict: GO