Skip to content

Plan v1: milestones M1–M8, decisions D11–D18, central server - #65

Open
djm56 wants to merge 27 commits into
mainfrom
plan-v1
Open

Plan v1: milestones M1–M8, decisions D11–D18, central server#65
djm56 wants to merge 27 commits into
mainfrom
plan-v1

Conversation

@djm56

@djm56 djm56 commented Oct 30, 2026 •
edited
Loading

Copy link
Copy Markdown
Owner

Plan v1 replaces the phase list with milestones M1 to M8 and Later, records decisions D11 to D18, and moves Cairn to one central server. This PR changes documents, data files and two shell scripts. It changes no Go product code.

Changes by file group

  • Status and marker. The README, PLAN and DESIGN status lines name M1 (Server-mode MCP) as current. <!-- cairn-milestone: M1 --> in README and PLAN replaces cairn-phase. scripts/check-docs.sh checks the milestone marker. CONTRIBUTING and the PR template follow.
  • Plan (docs/PLAN.md). §3 is the milestone table, M1 to M8 and Later, with cairn hook session-start in M1 and the directive cap and review_by in M2. §4, §5.1 and §7 use milestones; reviewer verdicts become review events in M6. §9 states the milestone rule.
  • Design (docs/DESIGN.md). cairn mcp requires server or CAIRN_SERVER. Every unbuilt command names its milestone. internal/mcp reaches the server through internal/client. Session-start is planned for M1. The reviews and notes tables are marked as cut from the v1 agent surface. §5.3 describes the server alone.
  • Contract (docs/CONTRACT.md). Phase references become milestones. Rule text is unchanged. The status line states the contract's own state, so it names no milestone.
  • README. Category line per D18. One server per D11, and server is required in the .cairn.toml example. The rename is noted as planned, not done.
  • Wiki. Roadmap is rewritten from the milestone table, with exit checks. Decisions adds D11 to D18 and marks D2, D8 and D10 superseded. Architecture, Home, Getting-Started, How-We-Work and Glossary follow.
  • CHANGELOG. One entry under Unreleased.
  • GitHub data (.github/labels.json, .github/roadmap.json). Labels m1 to m8 and later; the phase labels are marked historical. Roadmap entries for M1 to M8 and Later, with exit checks copied from the table. Existing roadmap issues keep their keys and markers. The Plan v1 issue list adds 34 issues.
  • scripts/github/bootstrap.sh. It no longer creates a Milestone board field, since GitHub's built-in Milestone field is used. Phase options are read from labels.json. The script stays fill-only.

Defaults pending operator veto

Rulings adopted for this PR, each open to veto:

  • CONTRACT status note only, with removals in M1 and the directive cap in M2.
  • Milestones renamed in place rather than recreated.
  • Phase labels kept as history.
  • Phase field kept on the board. The Milestone field added in the first draft is withdrawn; see ruling 11.
  • Milestone marker <!-- cairn-milestone: M --> in README and PLAN.
  • Open questions become decision issues on the milestone they affect, or on Later.
  • 13 tools plus recall and search.
  • Rule 2 allows cairn init in an error string.
  • Session-start in M1.
  • D11 to D18 adopted 2026-10-30.
  • No custom Milestone field. The project board uses GitHub's built-in Milestone field, and the "Group by Milestone" view instruction refers to it. bootstrap.sh creates and sets no Milestone field.

GitHub changes happen after merge

This PR changes no GitHub milestone, label, project or issue. Those are changed after merge, from a reviewed dry run of scripts/github/bootstrap.sh. Existing issues are retitled, relabelled and moved to milestones by hand before --apply, because the script fills only what is missing and never edits an existing issue, label or milestone.

Checks

  • make build and go test -count=1 ./... pass.
  • scripts/check-docs.sh passes; a mismatched or missing milestone marker fails it.
  • .github/labels.json and .github/roadmap.json parse.
  • scripts/github/bootstrap.sh dry run (labels, milestones, issues, project) writes nothing.
  • shellcheck is not installed on the machine that ran these checks.

Follow-ups

  • Repo CLAUDE.md still describes phase order and the cairn-phase marker (lines 8–10, 24, 51); the operator edits agent-instruction files.
  • Go comments naming phases (cmd/cairn/main.go, internal/conformance, internal/core/doc.go) change with the next code PR.

No issues are closed by this PR, and it uses no closing keywords.

🤖 Generated with Claude Code

Donovan Maidens and others added 27 commits October 30, 2026 10:26
Donovan Maidens @claude
docs(plan): Plan v1 milestones, decisions D11-D18, scope and open que…
5f4687e 
…stions

Replace the phase list in PLAN.md §2 and §3 with the eight milestones
(M1-M8) and Later, keeping phases 0-2 as done history. Cut-over (§5.3)
moves to M8. Record D11-D18 in §8 and mark D2 and D8 as superseded.
Add Scope of v1, After v1 and Open questions.

The status line and the cairn-phase marker are unchanged; they move
with README, the wiki and the CI check when the milestone exit passes.

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
Donovan Maidens @claude
docs(design): central server, review_by, 13-tool surface, hooks and CLI
77d344c 
Per Plan v1: §1.1 becomes "One server"; §2.1 requires `server` in
.cairn.toml; §3.4 adds review_by (planned, M2); §4 tool table names the
planned surface and the CLI, and lists the three hooks (§4.1); §5
diagram drops the local backend, §5.1 adds internal/cli, §5.2 adds
enable, backup and restore; §6.1 and §6.2 cover the hooks and the CLI
route; §8 adds the viewer scope.

Built-today behaviour is kept and labelled as such. Planned work is
marked with its milestone.

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
Donovan Maidens @claude
docs(contract): note the Plan v1 surface changes planned for M1
5ca5df6 
Status note only. The planned removals (note_put, note_get,
review_record, event_list), the task_get events section and the
directive cap land in M1 with core and conformance. No rule text
changes here.

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
Donovan Maidens @claude
docs(contributing): add the Plan v1 engineering rules
489ef7d 
Ten rules from Plan v1 under the existing Engineering rules heading,
so the heading anchor stays the same.

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
Donovan Maidens @claude
docs(plan): correct the milestone-to-phase mapping
b18efa9 
M4 is new, not a phase 3-7 carry-over, so phases 3-7 map to M1, M2,
M3, M5 and M6 only. Fixes the Phase 3 intro and the Milestones lead-in.

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
Donovan Maidens @claude
docs: correct built-state claims and Plan v1 review warnings
ff5a734 
Fix round 1 of the step-3 review. DESIGN.md called the local MCP backend,
the session-start hook and the .cairn.toml server switch built. None is:
the local backend was designed (D2) and cut by D11 before it was built,
and session-start is designed with no milestone work row yet. Each site
now says so.

- CONTRACT: split the status note: tool removals and section=events in
  M1; directive cap and review_by in M2.
- PLAN §8: mark D10 superseded by the M1-M8 order; adoption line for
  D11-D18.
- CONTRIBUTING rule 2: CI test names --force, rm, reset, and any init
  other than cairn init, so it agrees with rule 7.
- One count phrasing everywhere: 13 tools plus the read tools recall and
  search (15 names). Open count question removed.
- PLAN: neutral wording for the local bishop-memory checkout; open
  question on M1's exit check against cairn serve.
- DESIGN §4 re-wrapped; §6.2 registrations via cairn enable in M4;
  §8 scopes marked unbuilt and admin dropped.

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
Donovan Maidens @claude
docs: milestone marker and status lines name M1 as current
a5051ff 
check-docs.sh checks the cairn-milestone marker in README.md and
docs/PLAN.md, replacing the cairn-phase check. The status lines in
README, PLAN and DESIGN name M1 (Server-mode MCP) as current, and PLAN
§9 states the milestone rule.

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
Donovan Maidens @claude
docs(plan): milestones replace phases in §3 to §7
1460f8e 
Adds the cairn hook session-start work to M1 (issue #16). The directive
cap and review_by move to M2 in the M1 row, the M2 row and Scope of v1.
Phase references in §4, §5.1 and §7 become milestones; §5.1's reviewer
verdicts become review events in M6. The §3 heading becomes Milestones,
with the table under Milestone table, so anchors can point at it.

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
Donovan Maidens @claude
docs(design): central server, milestones and cut surface
53d54b1 
The cairn mcp row needs server or CAIRN_SERVER, and every unbuilt command
names its milestone. internal/mcp reaches the server through
internal/client. session-start is planned for M1 in §4.1 and §6.1. The
reviews and notes tables are marked as cut from the v1 agent surface,
and §5.3 describes the server alone.

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
Donovan Maidens @claude
docs(contract): milestone references replace phases
bfa2ef4 
The MCP adapter is M1, the web UI is M3, and the step-review rule
deferred from phase 8 moves to Later (#41). Rule text is unchanged.

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
Donovan Maidens @claude
docs(readme): operating record category, server required, rename planned
7127de4 
The category line follows D18. The README says one server is required
(D11) and that the .cairn.toml example carries server. The rename to
cairn is noted as planned, not done. CONTRIBUTING names milestones
where it named phases.

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
Donovan Maidens @claude
docs(wiki): milestones, decisions D11 to D18, one-server architecture
84f5a21 
Roadmap is rewritten from the PLAN §3 milestone table, with the exit
checks. Decisions adds D11 to D18 and marks D2, D8 and D10 superseded.
Architecture describes one server: clients open no database, so the
local backend and the local listener are gone. Status lines name M1 as
current, and the phase glossary entry becomes milestone.

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
Donovan Maidens @claude
github: milestone labels m1 to m8 and later; phase labels are history
3e0e97b 
Adds the labels m1 to m8 and later, with neutral descriptions. The phase
labels stay, and their descriptions say they are historical. The
bootstrap script never edits an existing label, so the new descriptions
reach a repository only when its labels are created. The CHANGELOG entry
for Plan v1 is added under Unreleased.

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
Donovan Maidens @claude
github: roadmap milestones M1 to M8 and Later, with issue mapping
c3fb79f 
Phase 3 to 10 milestone entries become M1 to M8 and Later, each with its
exit check from the PLAN §3 table. Phases 0 to 2 stay as history. Each
existing roadmap issue keeps its key and marker, so bootstrap matches it
by marker and creates nothing for it; the retitles and milestone moves
are made by hand after merge. The 33 new issues come from the Plan v1
issue list. Open questions become decision issues on the milestone they
affect, and the rename issue is deferred to Later.

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
Donovan Maidens @claude
github: bootstrap sets a Milestone board field and reads phases from …
b74e5e8 
…labels

Adds the Milestone single-select field, with options from the roadmap's
milestone keys, and fills it on each roadmap issue when empty. Phase
options come from the phase: labels, not a hard-coded range. A roadmap
issue with no phase, such as every Plan v1 issue, sets no Phase. Fill
only, as before: nothing existing is changed.

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
Donovan Maidens @claude
ci: comment names Later for release builds, not phase 10
829c1ae 
Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
Donovan Maidens @claude
CHANGELOG: link the Plan v1 entry to PR #65
27b8e9a 
Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
Donovan Maidens @claude
github: milestone is the built-in board field, not a custom one
884f5ef 
The project board already has GitHub's Milestone field, so bootstrap no
longer creates a single-select Milestone field, sets it per item, or reads
it. The table view groups by the built-in field. The wiki board section
says three fields of its own plus the built-in milestone.

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
Donovan Maidens @claude
issue forms: milestone dropdown, decisions D11 to D18, bug environment
cdc7e50 
The roadmap task form asks for the milestone (M1 to M8, Later) instead of
the phase. The decision form lists D1 to D18, marks D2, D8 and D10
superseded as PLAN §8 does, and says when each batch was adopted. The bug
form's environment prompt no longer names the local database, which
decision D11 removed. The How-We-Work task line matches the task form.

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
Donovan Maidens @claude
ci: docs job named for what it checks
b51f599 
The job checks the milestone markers and the changelog, so it is named
"milestone marker and changelog". The old name is not a required check on
main (build, vet, fmt, test is the only one), so renaming it is safe.

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
Donovan Maidens @claude
docs(wiki): area:server description matches labels.json
8ff21ce 
The wiki gave the area as "HTTP server, API keys and the remote backend".
labels.json says "HTTP server and API keys: cairn serve.", and the wiki now
says the same.

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
Donovan Maidens @claude
docs: category line is an operating record for coding agents
59ba89d 
Wiki Home and DESIGN §1 said "a memory for coding agents". Decision D18
sets the category line to "an operating record for coding agents".

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
Donovan Maidens @claude
docs(readme): serve, mcp and the CLI marked as planned with milestones
af0ab09 
The design-in-brief section described cairn serve, cairn mcp and the CLI as
if built. They are planned: serve in M2, mcp in M1, the CLI in M4.

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
Donovan Maidens @claude
docs(design): §5 intro points at §5.3 "The server"
ba67e7d 
The intro said the local backend in §5.3 was designed under D2. §5.3 now
describes the server and says D2 was cut by D11, so the intro names both
and points to that section.

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
Donovan Maidens @claude
docs(wiki): M4, M7 and M8 have no epic yet
677e12d 
Says so plainly in the milestones section, with the roadmap.json link for
their task issues, so a reader does not look for epics that do not exist.

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
Donovan Maidens @claude
github: roadmap decision on placing cairn export project
6803709 
cairn export project is in Scope of v1 but no milestone places it. One
decision issue, type:decision and needs-operator, sits in M1 until the
operator decides where it goes.

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
Donovan Maidens @claude
Roadmap: M1 children, stale comments for step 9
53d9d6a 
- roadmap.json: add m1-export-project-decision to the p3-epic children list.
- docs.yml: the header names the milestone marker, not phase markers.
- bootstrap.sh: the Phase comment names phase: null as the key for Plan v1 issues.

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@djm56