feat(P03): multi-project support, NFR milestone versioning, phase context reset, install scripts (v0.3.0)

2026-05-29 15:13:45 +00:00
parent e4bb3a9970
commit ddf04792c7
57 changed files with 1748 additions and 59 deletions
@@ -18,6 +18,13 @@ If the prompt contains a `<files_to_read>` block, you MUST use the Read tool to
 </role>

 <project_context>
+If .ci/config.json has projects[] with length > 0, you are in multi-project mode.
+- Read active_project from .ci/config.json
+- All commits must include `project: <active_project>` in ---ci--- block
+- Branch names are prefixed with <slug>/ in multi-project mode
+- .ci/ files are in .ci/<slug>/ subdirectories
+If single-project mode (projects[] empty or absent), use existing conventions.
+
 Before challenging, load context from git first:

 1. Run `git log --max-count=30` for recent decisions and project history
@@ -19,6 +19,13 @@ If the prompt contains a `<files_to_read>` block, you MUST use the Read tool to
 </role>

 <project_context>
+If .ci/config.json has projects[] with length > 0, you are in multi-project mode.
+- Read active_project from .ci/config.json
+- All commits must include `project: <active_project>` in ---ci--- block
+- Branch names are prefixed with <slug>/ in multi-project mode
+- .ci/ files are in .ci/<slug>/ subdirectories
+If single-project mode (projects[] empty or absent), use existing conventions.
+
 Before reviewing, load context from git first:

 1. Run `git log --max-count=10` for recent changes
@@ -20,6 +20,13 @@ If the prompt contains a `<files_to_read>` block, you MUST use the Read tool to
 </role>

 <project_context>
+If .ci/config.json has projects[] with length > 0, you are in multi-project mode.
+- Read active_project from .ci/config.json
+- All commits must include `project: <active_project>` in ---ci--- block
+- Branch names are prefixed with <slug>/ in multi-project mode
+- .ci/ files are in .ci/<slug>/ subdirectories
+If single-project mode (projects[] empty or absent), use existing conventions.
+
 Before debugging, load context from git first:

 1. Run `git log --max-count=20` for recent changes that may have caused the bug
@@ -18,6 +18,13 @@ If the prompt contains a `<files_to_read>` block, you MUST use the Read tool to
 </role>

 <project_context>
+If .ci/config.json has projects[] with length > 0, you are in multi-project mode.
+- Read active_project from .ci/config.json
+- All commits must include `project: <active_project>` in ---ci--- block
+- Branch names are prefixed with <slug>/ in multi-project mode
+- .ci/ files are in .ci/<slug>/ subdirectories
+If single-project mode (projects[] empty or absent), use existing conventions.
+
 Before verifying, load context from git first:

 1. Run `git diff HEAD~10` to see recent code changes
@@ -20,6 +20,13 @@ If the prompt contains a `<files_to_read>` block, you MUST use the Read tool to
 </role>

 <project_context>
+If .ci/config.json has projects[] with length > 0, you are in multi-project mode.
+- Read active_project from .ci/config.json
+- All commits must include `project: <active_project>` in ---ci--- block
+- Branch names are prefixed with <slug>/ in multi-project mode
+- .ci/ files are in .ci/<slug>/ subdirectories
+If single-project mode (projects[] empty or absent), use existing conventions.
+
 Before writing, load context from git first:

 1. Run `git log --max-count=20` for recent changes that affect docs
@@ -20,6 +20,13 @@ If the prompt contains a `<files_to_read>` block, you MUST use the Read tool to
 </role>

 <project_context>
+If .ci/config.json has projects[] with length > 0, you are in multi-project mode.
+- Read active_project from .ci/config.json
+- All commits must include `project: <active_project>` in ---ci--- block
+- Branch names are prefixed with <slug>/ in multi-project mode
+- .ci/ files are in .ci/<slug>/ subdirectories
+If single-project mode (projects[] empty or absent), use existing conventions.
+
 Before executing, load context from git first:

 1. Run `git log --max-count=20` for recent project history
@@ -18,6 +18,13 @@ If the prompt contains a `<files_to_read>` block, you MUST use the Read tool to
 </role>

 <project_context>
+If .ci/config.json has projects[] with length > 0, you are in multi-project mode.
+- Read active_project from .ci/config.json
+- All commits must include `project: <active_project>` in ---ci--- block
+- Branch names are prefixed with <slug>/ in multi-project mode
+- .ci/ files are in .ci/<slug>/ subdirectories
+If single-project mode (projects[] empty or absent), use existing conventions.
+
 Before ideating, load context from git first:

 1. Run `git log --max-count=50` for full project history
@@ -22,6 +22,13 @@ If the prompt contains a `<files_to_read>` block, you MUST use the Read tool to
 </role>

 <project_context>
+If .ci/config.json has projects[] with length > 0, you are in multi-project mode.
+- Read active_project from .ci/config.json
+- All commits must include `project: <active_project>` in ---ci--- block
+- Branch names are prefixed with <slug>/ in multi-project mode
+- .ci/ files are in .ci/<slug>/ subdirectories
+If single-project mode (projects[] empty or absent), use existing conventions.
+
 Before any operation, load project context from git first:

 1. Run `git log --max-count=20` and `git branch -a` to discover project structure
@@ -18,6 +18,13 @@ If the prompt contains a `<files_to_read>` block, you MUST use the Read tool to
 </role>

 <project_context>
+If .ci/config.json has projects[] with length > 0, you are in multi-project mode.
+- Read active_project from .ci/config.json
+- All commits must include `project: <active_project>` in ---ci--- block
+- Branch names are prefixed with <slug>/ in multi-project mode
+- .ci/ files are in .ci/<slug>/ subdirectories
+If single-project mode (projects[] empty or absent), use existing conventions.
+
 Before researching, load context from git first:

 1. Run `git log --max-count=50` for full project history
@@ -18,6 +18,13 @@ If the prompt contains a `<files_to_read>` block, you MUST use the Read tool to
 </role>

 <project_context>
+If .ci/config.json has projects[] with length > 0, you are in multi-project mode.
+- Read active_project from .ci/config.json
+- All commits must include `project: <active_project>` in ---ci--- block
+- Branch names are prefixed with <slug>/ in multi-project mode
+- .ci/ files are in .ci/<slug>/ subdirectories
+If single-project mode (projects[] empty or absent), use existing conventions.
+
 Before checking, load context from git first:

 1. Run `git log --max-count=20` for recent decisions affecting this phase
@@ -19,6 +19,13 @@ If the prompt contains a `<files_to_read>` block, you MUST use the Read tool to
 </role>

 <project_context>
+If .ci/config.json has projects[] with length > 0, you are in multi-project mode.
+- Read active_project from .ci/config.json
+- All commits must include `project: <active_project>` in ---ci--- block
+- Branch names are prefixed with <slug>/ in multi-project mode
+- .ci/ files are in .ci/<slug>/ subdirectories
+If single-project mode (projects[] empty or absent), use existing conventions.
+
 Before planning, load context from git first:

 1. Run `git log --max-count=50` to see recent decisions and project history
@@ -18,6 +18,13 @@ If the prompt contains a `<files_to_read>` block, you MUST use the Read tool to
 </role>

 <project_context>
+If .ci/config.json has projects[] with length > 0, you are in multi-project mode.
+- Read active_project from .ci/config.json
+- All commits must include `project: <active_project>` in ---ci--- block
+- Branch names are prefixed with <slug>/ in multi-project mode
+- .ci/ files are in .ci/<slug>/ subdirectories
+If single-project mode (projects[] empty or absent), use existing conventions.
+
 Before researching, load context from git first:

 1. Run `git log --max-count=20` for any prior project history
@@ -18,6 +18,13 @@ If the prompt contains a `<files_to_read>` block, you MUST use the Read tool to
 </role>

 <project_context>
+If .ci/config.json has projects[] with length > 0, you are in multi-project mode.
+- Read active_project from .ci/config.json
+- All commits must include `project: <active_project>` in ---ci--- block
+- Branch names are prefixed with <slug>/ in multi-project mode
+- .ci/ files are in .ci/<slug>/ subdirectories
+If single-project mode (projects[] empty or absent), use existing conventions.
+
 Before synthesizing, load context from git first:

 1. Run `git log --grep="research" --max-count=20` for prior research commits
@@ -18,6 +18,13 @@ If the prompt contains a `<files_to_read>` block, you MUST use the Read tool to
 </role>

 <project_context>
+If .ci/config.json has projects[] with length > 0, you are in multi-project mode.
+- Read active_project from .ci/config.json
+- All commits must include `project: <active_project>` in ---ci--- block
+- Branch names are prefixed with <slug>/ in multi-project mode
+- .ci/ files are in .ci/<slug>/ subdirectories
+If single-project mode (projects[] empty or absent), use existing conventions.
+
 Before researching, load context from git first:

 1. Run `git log --max-count=50` for project history and prior research
@@ -19,6 +19,13 @@ If the prompt contains a `<files_to_read>` block, you MUST use the Read tool to
 </role>

 <project_context>
+If .ci/config.json has projects[] with length > 0, you are in multi-project mode.
+- Read active_project from .ci/config.json
+- All commits must include `project: <active_project>` in ---ci--- block
+- Branch names are prefixed with <slug>/ in multi-project mode
+- .ci/ files are in .ci/<slug>/ subdirectories
+If single-project mode (projects[] empty or absent), use existing conventions.
+
 Before roadmapping, load context from git first:

 1. Run `git log --max-count=30` for project history
@@ -20,6 +20,13 @@ If the prompt contains a `<files_to_read>` block, you MUST use the Read tool to
 </role>

 <project_context>
+If .ci/config.json has projects[] with length > 0, you are in multi-project mode.
+- Read active_project from .ci/config.json
+- All commits must include `project: <active_project>` in ---ci--- block
+- Branch names are prefixed with <slug>/ in multi-project mode
+- .ci/ files are in .ci/<slug>/ subdirectories
+If single-project mode (projects[] empty or absent), use existing conventions.
+
 Before auditing, load context from git first:

 1. Run `git log --grep="security" --max-count=20` for prior security decisions
@@ -19,6 +19,13 @@ If the prompt contains a `<files_to_read>` block, you MUST use the Read tool to
 </role>

 <project_context>
+If .ci/config.json has projects[] with length > 0, you are in multi-project mode.
+- Read active_project from .ci/config.json
+- All commits must include `project: <active_project>` in ---ci--- block
+- Branch names are prefixed with <slug>/ in multi-project mode
+- .ci/ files are in .ci/<slug>/ subdirectories
+If single-project mode (projects[] empty or absent), use existing conventions.
+
 Before analyzing, load context from git first:

 1. Run `git log --max-count=20` for recent problem-solving history
@@ -18,6 +18,13 @@ If the prompt contains a `<files_to_read>` block, you MUST use the Read tool to
 </role>

 <project_context>
+If .ci/config.json has projects[] with length > 0, you are in multi-project mode.
+- Read active_project from .ci/config.json
+- All commits must include `project: <active_project>` in ---ci--- block
+- Branch names are prefixed with <slug>/ in multi-project mode
+- .ci/ files are in .ci/<slug>/ subdirectories
+If single-project mode (projects[] empty or absent), use existing conventions.
+
 Before verifying, load context from git first:

 1. Run `git log --grep="P##" --max-count=50` for all phase commits
@@ -1 +1 @@
-0.2.0
+0.3.0
@@ -4,6 +4,18 @@ Agent output guidance for CI dev mode. Loaded when the orchestrator operates in

 ---

+## Multi-Project and NFR Versioning
+
+When in multi-project mode (`.ci/config.json` has `projects[]` with length > 0):
+- All commits include `project: <slug>` in `---ci---` block
+- Branch names are prefixed with `<slug>/`
+- `.ci/` files are in `.ci/<slug>/` subdirectories
+- Project scoping applies to all operations
+
+NFR milestone versioning:
+- NFR milestones (all phases are fix/chore/docs/perf/refactor/test): progressive patch versions only, no minor tag
+- Feature milestones (any feat phase): progressive patch versions + minor milestone tag
+
 ## Output Style

 - Concise, action-oriented responses
@@ -21,11 +21,13 @@ Agent output guidance for CI research mode. Loaded when the orchestrator operate

 ## Research Output

-Research commits update `.ci/` static files (ARCHITECTURE.md, PROJECT.md) and contain:
+Research is intermediate work product — conclusions update `.ci/<slug>/` static files (ARCHITECTURE.md, PROJECT.md) and contain:
 - Key findings in the commit body
 - Decisions in the `---ci---` block
 - Confidence levels for each recommendation

+In multi-project mode, research conclusions update files in `.ci/<slug>/` subdirectories, not the root `.ci/` directory.
+
 ## Verbosity

 High. Explain reasoning, show evidence, and document assumptions.
@@ -4,6 +4,14 @@ Agent output guidance for CI review mode. Loaded when the orchestrator operates

 ---

+## Multi-Project Awareness
+
+When in multi-project mode (`.ci/config.json` has `projects[]` with length > 0):
+- All reviews are scoped to the active project
+- Commits include `project: <slug>` in `---ci---` blocks
+- Branch names are prefixed with `<slug>/`
+- Review findings reference project-scoped paths
+
 ## Output Style

 - Critical, detail-focused responses that prioritize correctness
@@ -115,6 +115,33 @@ git push origin main --tags

 When the project undergoes a schema-breaking change (e.g., switching from file-based to git-native architecture), bump the major version. Major releases follow the same merge → tag → release flow.

+## NFR Milestone Versioning
+
+NFR milestones and feature milestones follow different versioning rules:
+
+**NFR milestones** — all phases are `fix`, `chore`, `docs`, `perf`, `refactor`, or `test`:
+- Each phase gets a progressive patch version (v0.1.1, v0.1.2, v0.1.3)
+- No separate milestone tag — the milestone is implicit from the patch sequence
+- Example: milestone v0.1 with phases P01 (chore), P02 (test), P03 (perf) → v0.1.1, v0.1.2, v0.1.3
+
+**Feature milestones** — any phase is `feat`:
+- Each phase gets a progressive patch version
+- On milestone completion, tag a minor version (e.g., v0.2.0)
+- Example: milestone v0.2 with phases P01 (feat), P02 (feat), P03 (fix) → v0.2.1, v0.2.2, v0.2.3 + milestone tag v0.3.0
+
+Determine milestone type by checking `isNfrMilestone()` which inspects all phase commit types within the milestone.
+
+## Multi-Project Branch Naming
+
+When operating in multi-project mode (`.ci/config.json` has `projects[]` with length > 0):
+
+| Branch Type | Format | Example |
+|-------------|--------|---------|
+| Phase | `<slug>/phase/NN-slug` | `auth/phase/01-jwt-setup` |
+| Milestone | `<slug>/milestone/vX.X-slug` | `auth/milestone/v0.2-login` |
+
+Single-project mode keeps the existing `phase/NN-slug` and `milestone/vX.X-slug` conventions (no slug prefix).
+
 ## Phase Discovery

 ```typescript
@@ -4,15 +4,33 @@ How CI manages the `.ci/` directory — long-lived reference documents only. Dyn

 ---

+## Multi-Project Directory Structure
+
+In multi-project mode, `.ci/` uses subdirectories per project:
+
+```
+.ci/
+  config.json          # Registry with projects[] and active_project
+  <project-slug>/
+    PROJECT.md
+    ARCHITECTURE.md
+    ROADMAP.md
+    REQUIREMENTS.md
+```
+
+`.ci/config.json` serves as the registry with `projects[]` (array of project entries) and `active_project` (slug of the currently active project).
+
+**Backward compatibility:** if `.ci/` has flat files (PROJECT.md, ARCHITECTURE.md, etc.) and no project subdirectories, auto-migrate by creating `<default-slug>/` and moving files into it, then updating `config.json` with a single `projects[]` entry.
+
 ## What Lives in `.ci/`

 | File | Purpose | Update Frequency |
 |------|---------|-------------------|
-| `config.json` | Project-level CI configuration | Rare (initialization, setting changes) |
-| `PROJECT.md` | Vision, core value, requirements, constraints, key decisions | Low (phase boundaries) |
-| `ARCHITECTURE.md` | System architecture, component boundaries, data flow | Low (major refactors) |
-| `ROADMAP.md` | Phase breakdown, milestone mapping, success criteria | Low (phase transitions) |
-| `REQUIREMENTS.md` | v1/v2 requirements with REQ-IDs, out of scope, traceability | Low (requirement changes) |
+| `config.json` | Project registry with `projects[]` and `active_project` | Rare (initialization, project changes) |
+| `<slug>/PROJECT.md` | Vision, core value, requirements, constraints, key decisions per project | Low (phase boundaries) |
+| `<slug>/ARCHITECTURE.md` | System architecture, component boundaries, data flow per project | Low (major refactors) |
+| `<slug>/ROADMAP.md` | Phase breakdown, milestone mapping, success criteria per project | Low (phase transitions) |
+| `<slug>/REQUIREMENTS.md` | v1/v2 requirements with REQ-IDs, out of scope, traceability per project | Low (requirement changes) |

 ## What Does NOT Live in `.ci/`

@@ -137,6 +155,15 @@ interface ArchitectureMd {
 }
 ```

+## Research and .ci/ File Updates
+
+Research is intermediate work product. Conclusions from research update `.ci/` static files:
+- Key findings go in the commit body
+- Decisions go in `---ci---` blocks
+- Conclusions that change project structure update the appropriate `.ci/<slug>/` files (ARCHITECTURE.md, PROJECT.md, etc.)
+
+Research commits are not final artifacts — they feed into planning and roadmap updates.
+
 ## Anti-Patterns

 - Never write dynamic state (decisions, escalations, lessons) to `.ci/` files
@@ -145,5 +172,6 @@ interface ArchitectureMd {
 - Never commit `.ci/` changes without a `---ci---` block
 - Never create new files in `.ci/` without updating this reference document
 - Never store counters, timestamps, or session state in `.ci/` files
+- Never store research conclusions only in commits — update `.ci/<slug>/` static files with findings

 </ci_files_discipline>
@@ -10,6 +10,7 @@ Canonical `---ci---` YAML block schema for CI commits. Every CI-generated commit
 <type>(<scope>): <subject>

 ---ci---
+project: <slug>          # required in multi-project mode
 phase: <number>
 milestone: <string>
 plan: <string>           # optional
@@ -38,6 +39,23 @@ compound:                # optional
 ---/ci---
 ```

+The `project` field is required when in multi-project mode (`.ci/config.json` has `projects[]` with length > 0). In single-project mode, it is optional.
+
+Example with project field:
+
+```
+feat(P01-01-01): implement JWT auth
+
+---ci---
+project: auth-service
+phase: 1
+milestone: v0.2
+plan: 01-01
+task: 01-01-01
+status: execute
+---/ci---
+```
+
 ## Commit Types

 | Type | Purpose | Scope |
@@ -93,6 +93,10 @@ const phaseDecisions = gitContext.getDecisions(3);     // Phase 3 only
 const commitDecisions = gitContext.getDecisionsFromCommits(commits, 3);
 ```

+## Project-Scoped Decisions
+
+Decisions can be project-scoped via the `project` field in `---ci---` blocks. When in multi-project mode, include the project slug so that `GitContext.getDecisions()` can filter decisions by project. Project-scoped decisions only apply to the specified project and do not affect other projects in the same repository.
+
 ## Anti-Patterns

 - Never write decisions to a `.ci/audit/` file — commit them
@@ -76,6 +76,34 @@ interface ParsedCiCommit {

 Commits without `---ci---` blocks have `ci: null` — these are treated as non-CI commits (e.g., manual edits by the developer).

+## Phase Context Reset
+
+Between phases, all state is committed to git, then the next phase starts with fresh context from git log — not accumulated conversation history.
+
+**On opencode (subagent support):** spawn a fresh agent for the next phase. The new agent loads context from git log and `.ci/` files only.
+
+**On platforms without subagents:** simulated reset — re-read git context from scratch, ignore prior conversation history. Treat the phase boundary as a hard context boundary.
+
+**Checkpoint sequence:**
+1. Commit all work from the current phase
+2. Update `.ci/` files (ROADMAP.md phase status, REQUIREMENTS.md requirement statuses)
+3. Verify `GitContext.reconstructState()` matches expected state
+4. Reset context — next phase begins fresh
+
+The phase context reset ensures that each phase operates on verified git state, preventing context drift across long-running projects.
+
+## Multi-Project Context
+
+GitContext supports multi-project mode with optional project scoping:
+
+| Method | Returns | Purpose |
+|--------|---------|---------|
+| `GitContext(projectPath, projectSlug?)` | GitContext | Optional project slug for scoping |
+| `detectProjectFromCommit()` | string \| null | Detect project from latest commit's `project` field |
+| `isNfrMilestone()` | boolean | Check if current milestone is NFR-only (no feat phases) |
+
+In multi-project mode, `detectProjectFromCommit()` reads the `project` field from the latest `---ci---` block to determine which project context to load. `isNfrMilestone()` inspects phase commit types to determine versioning behavior.
+
 ## Context Budget Strategy

 When context is limited:
@@ -8,6 +8,18 @@ Audit the CI project for health issues. Verifies that git log state matches .ci/

 **Usage:** `ci-audit`

+## Step 0: Confirm Active Project
+
+Check `ci listProjects()` or read `.ci/config.json` to determine if multi-project mode is active.
+
+If `.ci/config.json` has `projects[]` with length > 0:
+- Confirm `active_project` is correct for this audit
+- If not, set it with `ci setActiveProject(<slug>)`
+- Scope audit queries to the active project
+- All commit messages must include `project: <slug>` in `---ci---` block
+
+If single-project mode: proceed with existing conventions.
+
 ## Step 1: Reconstruction Test

 Attempt to reconstruct the full project state from commit messages only:
@@ -8,6 +8,17 @@ Run the clarification phase for the current CI project. Generate questions about

 **Usage:** `ci-clarify [phase_number]`

+## Step 0: Confirm Active Project
+
+Check `ci listProjects()` or read `.ci/config.json` to determine if multi-project mode is active.
+
+If `.ci/config.json` has `projects[]` with length > 0:
+- Confirm `active_project` is correct for this clarification
+- If not, set it with `ci setActiveProject(<slug>)`
+- All commit messages must include `project: <slug>` in `---ci---` block
+
+If single-project mode: proceed with existing conventions.
+
 ## Step 1: Load Git Context

 ```bash
@@ -8,6 +8,18 @@ Systematic debugging workflow: triage → root cause diagnosis → auto-fix or e

 **Usage:** `ci-debug [description]`

+## Step 0: Confirm Active Project
+
+Check `ci listProjects()` or read `.ci/config.json` to determine if multi-project mode is active.
+
+If `.ci/config.json` has `projects[]` with length > 0:
+- Confirm `active_project` is correct for this debug session
+- If not, set it with `ci setActiveProject(<slug>)`
+- Scope debugging to the active project
+- All commit messages must include `project: <slug>` in `---ci---` block
+
+If single-project mode: proceed with existing conventions.
+
 ## Step 1: Load Git Context

 ```bash
@@ -8,6 +8,18 @@ Initialize a new CI project with specification parsing, clarification, and .ci/

 **Usage:** `ci-init [description]`

+## Step 0: Confirm Active Project
+
+Check `ci listProjects()` or read `.ci/config.json` to determine if multi-project mode is active.
+
+If `.ci/config.json` has `projects[]` with length > 0:
+- Confirm `active_project` is correct for this initialization
+- If not, set it with `ci setActiveProject(<slug>)`
+- All subsequent operations use `.ci/<slug>/` subdirectories
+- All commit messages must include `project: <slug>` in `---ci---` block
+
+If single-project mode: proceed with existing conventions.
+
 ## Step 1: Check Prerequisites

 Verify git is initialized:
@@ -51,11 +63,13 @@ Record decisions in the `---ci---` block of the init commit.

 Use CiFiles to create the project structure:

-1. `.ci/config.json` — default CI configuration with autonomy level
-2. `.ci/PROJECT.md` — vision, requirements, constraints, key decisions
-3. `.ci/ARCHITECTURE.md` — system architecture (initial, may be incomplete)
-4. `.ci/ROADMAP.md` — phase breakdown (to be refined by roadmapper)
-5. `.ci/REQUIREMENTS.md` — formal requirements with REQ-IDs
+1. `.ci/config.json` — registry with `projects[]` and `active_project`
+2. `.ci/<slug>/PROJECT.md` — vision, requirements, constraints, key decisions (or `.ci/PROJECT.md` in single-project mode)
+3. `.ci/<slug>/ARCHITECTURE.md` — system architecture (initial, may be incomplete)
+4. `.ci/<slug>/ROADMAP.md` — phase breakdown (to be refined by roadmapper)
+5. `.ci/<slug>/REQUIREMENTS.md` — formal requirements with REQ-IDs
+
+`initCI()` accepts `projectSlug` and `projectName` parameters for multi-project initialization.

 ## Step 5: Create Initial Branches

@@ -69,6 +83,7 @@ git checkout -b milestone/v1.0-initial
 docs(init): initialize [project-name] ([N] phases)

 ---ci---
+project: <slug>
 phase: 0
 milestone: v1.0
 status: specify
@@ -86,6 +101,8 @@ Constraints: [constraint1, ...]
 Out of scope: [item1, ...]
 ```

+Include `project: <slug>` in the `---ci---` block when in multi-project mode.
+
 ## Step 7: Done

 Report project initialized, .ci/ files created, initial branch created.
@@ -13,6 +13,17 @@ Execute small, ad-hoc tasks with CI guarantees: git context loading, `---ci---`
 - `--verify` — verify results after execution
 - `--full` — research + verify

+## Step 0: Confirm Active Project
+
+Check `ci listProjects()` or read `.ci/config.json` to determine if multi-project mode is active.
+
+If `.ci/config.json` has `projects[]` with length > 0:
+- Confirm `active_project` is correct
+- If not, set it with `ci setActiveProject(<slug>)`
+- All commit messages must include `project: <slug>` in `---ci---` block
+
+If single-project mode: proceed with existing conventions.
+
 ## Step 1: Get Task Description

 If provided as argument, use it. Otherwise ask: "What do you want to do?"
@@ -8,6 +8,17 @@ Multi-persona code review workflow. Reviews changes in the current phase, auto-a

 **Usage:** `ci-review [phase_number]`

+## Step 0: Confirm Active Project
+
+Check `ci listProjects()` or read `.ci/config.json` to determine if multi-project mode is active.
+
+If `.ci/config.json` has `projects[]` with length > 0:
+- Confirm `active_project` is correct for this review
+- If not, set it with `ci setActiveProject(<slug>)`
+- All commit messages must include `project: <slug>` in `---ci---` block
+
+If single-project mode: proceed with existing conventions.
+
 ## Step 1: Load Changes

 ```bash
@@ -10,6 +10,18 @@ Rollback a CI phase by reverting to the state before the phase started. Uses git

 If no phase specified, rolls back the current (most recent) phase.

+## Step 0: Confirm Active Project
+
+Check `ci listProjects()` or read `.ci/config.json` to determine if multi-project mode is active.
+
+If `.ci/config.json` has `projects[]` with length > 0:
+- Confirm `active_project` is correct for this rollback
+- If not, set it with `ci setActiveProject(<slug>)`
+- Identify project-scoped branches (prefixed with `<slug>/`)
+- All commit messages must include `project: <slug>` in `---ci---` block
+
+If single-project mode: proceed with existing conventions (branches without slug prefix).
+
 ## Step 1: Load Git Context

 ```bash
@@ -10,6 +10,17 @@ Execute the full CI pipeline from the current stage to completion. The orchestra

 If no phase number specified, continues from the current phase (detected from git log).

+## Step 0: Confirm Active Project
+
+Check `ci listProjects()` or read `.ci/config.json` to determine if multi-project mode is active.
+
+If `.ci/config.json` has `projects[]` with length > 0:
+- Confirm `active_project` is correct for this run
+- If not, set it with `ci setActiveProject(<slug>)`
+- All commit messages must include `project: <slug>` in `---ci---` block
+
+If single-project mode: proceed with existing conventions.
+
 ## Step 1: Load Git Context

 ```bash
@@ -76,6 +87,23 @@ For each stage in order (starting from current or from `specify`):

 Versioning: Major = project-level refactor/schema change, Minor = milestone completion, Patch = every phase.

+## Phase Boundary Checkpoint
+
+Between phases, perform a context reset:
+
+1. Commit all work from the current phase
+2. Update `.ci/` files (phase status, requirement statuses)
+3. Verify `GitContext.reconstructState()` matches expected state
+4. Reset context: spawn fresh agent (opencode) or re-read git context (platforms without subagents)
+5. Next phase begins with fresh context from git log only
+
+## NFR Versioning Logic
+
+Before tagging a phase completion, check `isNfrMilestone()`:
+
+- **NFR milestone** (all phases are fix/chore/docs/perf/refactor/test): apply progressive patch versions (v0.1.1, v0.1.2, v0.1.3). No separate milestone tag.
+- **Feature milestone** (any feat phase): apply progressive patch versions per phase, then tag minor milestone version on completion (e.g., v0.2.0).
+
 ## Step 4: Error Recovery

 On stage failure:
@@ -8,11 +8,27 @@ Ship a CI phase or milestone. Every ship creates a release — no exceptions.

 **Versioning rule:**
 - **Major** (X.0.0): Project-level refactor or schema changes
- **Minor** (0.X.0): Every milestone completion
+- **Minor** (0.X.0): Feature milestone completion only
 - **Patch** (0.0.X): Every phase completion

+**NFR versioning:**
+- NFR milestones (all phases are fix/chore/docs/perf/refactor/test): progressive patch versions only (v0.1.1, v0.1.2, v0.1.3). No minor milestone tag.
+- Feature milestones (any feat phase): progressive patch versions per phase + minor milestone tag on completion (e.g., v0.2.0).
+
 **Usage:** `ci-ship [phase_number|milestone]`

+## Step 0: Confirm Active Project
+
+Check `ci listProjects()` or read `.ci/config.json` to determine if multi-project mode is active.
+
+If `.ci/config.json` has `projects[]` with length > 0:
+- Confirm `active_project` is correct for this ship
+- If not, set it with `ci setActiveProject(<slug>)`
+- All commit messages must include `project: <slug>` in `---ci---` block
+- Branch names are prefixed with `<slug>/` in multi-project mode
+
+If single-project mode: proceed with existing conventions.
+
 ## Step 1: Pre-Flight

 ```bash
@@ -41,15 +57,17 @@ If any fail: iterate autonomously until tests pass. Do NOT ask the user for guid

 ## Step 3: Compute Version

-Determine the release version from what is being shipped:
+Determine the release version from what is being shipped. Check `isNfrMilestone()` for versioning behavior:

-| What's shipping | Version bump | Tag format | Example |
-|----------------|-------------|------------|---------|
-| Single phase | Patch | `vX.Y.Z` | `v0.2.3` (3rd phase in milestone v0.2) |
-| Milestone completion | Minor | `vX.Y.0` | `v0.3.0` (milestone v0.3 complete) |
-| Project refactor/schema change | Major | `vX.0.0` | `v1.0.0` (breaking schema) |
+| What's shipping | Milestone Type | Version bump | Tag format | Example |
+|----------------|---------------|-------------|------------|---------|
+| Single phase | NFR | Patch | `vX.Y.Z` | `v0.1.3` (3rd NFR phase in milestone v0.1) |
+| Single phase | Feature | Patch | `vX.Y.Z` | `v0.2.3` (3rd phase in feature milestone v0.2) |
+| Milestone completion | NFR | Patch (last phase) | `vX.Y.Z` | `v0.1.3` (no minor tag) |
+| Milestone completion | Feature | Minor | `vX.Y.0` | `v0.3.0` (feature milestone v0.3 complete) |
+| Project refactor/schema change | Any | Major | `vX.0.0` | `v1.0.0` (breaking schema) |

-Count completed phases in the current milestone to determine the patch number. If this is the last phase in the milestone, the version bumps to minor instead of patch.
+Count completed phases in the current milestone to determine the patch number.

 ## Step 4: Merge Branch

@@ -8,6 +8,18 @@ Display the current CI project status derived entirely from the git log and .ci/

 **Usage:** `ci-status`

+## Step 0: Confirm Active Project
+
+Check `ci listProjects()` or read `.ci/config.json` to determine if multi-project mode is active.
+
+If `.ci/config.json` has `projects[]` with length > 0:
+- Show project list with active project indicator
+- Confirm `active_project` is the project to show status for
+- If not, set it with `ci setActiveProject(<slug>)`
+- All commit messages must include `project: <slug>` in `---ci---` block
+
+If single-project mode: proceed with existing conventions.
+
 ## Step 1: Load Git Context

 ```bash
@@ -44,8 +56,9 @@ Read:
 CI ► STATUS
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

-Project: [name]
-Milestone: [current]
+Project: [name]  [If multi-project: (active)]
+[If multi-project: Other projects: [name1], [name2]]
+Milestone: [current] [NFR|Feature]
 Phase: [N] — [name]
 Stage: [current_stage]
 Autonomy: [level]
@@ -10,6 +10,20 @@ Run the CI verification pipeline against the current or specified phase. Four la

 If no phase specified, verifies the current phase.

+## Step 0: Confirm Active Project
+
+Check `ci listProjects()` or read `.ci/config.json` to determine if multi-project mode is active.
+
+If `.ci/config.json` has `projects[]` with length > 0:
+- Confirm `active_project` is correct for this verification
+- If not, set it with `ci setActiveProject(<slug>)`
+- Scope verification to the active project
+- All commit messages must include `project: <slug>` in `---ci---` block
+
+If single-project mode: proceed with existing conventions.
+
+**Phase Boundary Checkpoint:** Between phases, all state is committed to git, context is reset, and the next phase begins with fresh git log context. Verify that the current verification aligns with the reconstructed state.
+
 ## Step 1: Load Git Context

 ```bash
@@ -1 +1 @@
 .2.0
 .3.0