@sienklogic/plan-build-run 2.59.0 → 2.60.0

package/CHANGELOG.md

@@ -5,6 +5,36 @@ All notable changes to Plan-Build-Run will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.60.0](https://github.com/SienkLogic/plan-build-run/compare/plan-build-run-v2.59.0...plan-build-run-v2.60.0) (2026-03-06)
+
+
+### Features
+
+* **65-01:** add project-CONTEXT.md.tmpl with planner-embeds pattern to all 4 plugins ([683f67c](https://github.com/SienkLogic/plan-build-run/commit/683f67c48197df79b17fb6199081914c663f458b))
+* **65-01:** add PROJECT.md.tmpl to all 4 plugin template directories ([6416490](https://github.com/SienkLogic/plan-build-run/commit/6416490bdbd20867c2bc5f418c526d70b7f651e9))
+* **65-01:** add REQUIREMENTS.md.tmpl with REQ-F/REQ-NF schema to all 4 plugins ([f293660](https://github.com/SienkLogic/plan-build-run/commit/f293660572dec225e7f3a25c137b199097af8d84))
+* **65-02:** add --project flag and Step 1-project mode to discuss/SKILL.md across all 4 plugins ([35a40c4](https://github.com/SienkLogic/plan-build-run/commit/35a40c4a1ea24cf6b68fa076ca82e268cd208bb1))
+* **65-02:** add PROJECT.md to context-loader-task.md briefing file lists across all 4 plugins ([12d4668](https://github.com/SienkLogic/plan-build-run/commit/12d46688632e6578e1e120ea123ff5de02bb781f))
+* **65-02:** update begin/SKILL.md REQ-F/REQ-NF schema and project-CONTEXT template ref across 4 plugins; add 3 new keyTemplates to test ([b228120](https://github.com/SienkLogic/plan-build-run/commit/b228120d422cb3b8bd992cef1b4cada67cb11f3e))
+* **65-03:** add doc-existence gate to validate-task; update test fixtures for implements advisory ([c5fc1e3](https://github.com/SienkLogic/plan-build-run/commit/c5fc1e3d6a360908d0652131173a784c5a7db427))
+* **65-03:** GREEN - implement sync-context-to-claude.js ([65784a0](https://github.com/SienkLogic/plan-build-run/commit/65784a057622d600fc26891dc9ece84c8c53a2dd))
+* **65-04:** add advisory warnings to health skill for missing PROJECT.md, REQUIREMENTS.md, CONTEXT.md across all 4 plugins ([182df09](https://github.com/SienkLogic/plan-build-run/commit/182df09681130b3927a09821f9d464b2546441ee))
+* **65-04:** update planner agent for dual-source CONTEXT.md loading and plan/SKILL.md compliance check ([bd6cf41](https://github.com/SienkLogic/plan-build-run/commit/bd6cf4112b6f723459c5127be8bfc74efc98e370))
+* **65-04:** update status skill to display PROJECT.md, REQUIREMENTS.md, CONTEXT.md presence across all 4 plugins ([60df410](https://github.com/SienkLogic/plan-build-run/commit/60df4104fa39d406b1833311a99df493922475d2))
+* **xml-plan-format:** add auto_checkpoints to config-schema and satisfied/unsatisfied to VERIFICATION template ([72d08e8](https://github.com/SienkLogic/plan-build-run/commit/72d08e8dccf58e5011485bfb16a39db4e972ecef))
+* **xml-plan-format:** add automated wrapper, feature type, and implements field to plan-format.md ([3ee897a](https://github.com/SienkLogic/plan-build-run/commit/3ee897a89016fe28b968266f33ff286f90de7671))
+* **xml-plan-format:** enforce implements: blocking, add feature task validation, satisfied/unsatisfied advisory ([4d78e8e](https://github.com/SienkLogic/plan-build-run/commit/4d78e8eeccda91733b11f206c0d19ed075fd9fe7))
+* **xml-plan-format:** sync cursor-pbr and copilot-pbr agents for implements:/automated/satisfied traceability ([753d4ed](https://github.com/SienkLogic/plan-build-run/commit/753d4ed0b3c4f486496781012d6dcef951d42076))
+* **xml-plan-format:** update planner/executor/verifier/plan-checker for implements: traceability and must_haves locking ([98cc23f](https://github.com/SienkLogic/plan-build-run/commit/98cc23f7e5cfca60c188809b737c4156ceb49028))
+
+
+### Bug Fixes
+
+* **cross-plugin-sync:** align status skill Step 1d heading order in cursor-pbr and copilot-pbr ([dc8419e](https://github.com/SienkLogic/plan-build-run/commit/dc8419e33c1184a2224cdb22d6383bf572d41d58))
+* **cross-plugin-sync:** sync phase 66 references, templates, and agents to codex-pbr, copilot-pbr, cursor-pbr ([e143d9e](https://github.com/SienkLogic/plan-build-run/commit/e143d9ecfc4792fb8085f62ed9227738324ea69f))
+* **doc-gates:** add 3-part format to doc-existence blocking reason ([ba2d732](https://github.com/SienkLogic/plan-build-run/commit/ba2d732e1fd89afce266a50057b2b1411152903e))
+* **doc-gates:** upgrade doc-existence gate from advisory to blocking ([a4eeb3f](https://github.com/SienkLogic/plan-build-run/commit/a4eeb3fa015b0a81d4130dd7a9e4c220f124bf7d))
+
 ## [2.59.0](https://github.com/SienkLogic/plan-build-run/compare/plan-build-run-v2.58.0...plan-build-run-v2.59.0) (2026-03-06)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sienklogic/plan-build-run",
-  "version": "2.59.0",
+  "version": "2.60.0",
   "description": "Plan it, Build it, Run it — structured development workflow for Claude Code",
   "keywords": [
     "claude-code",

package/plugins/codex-pbr/agents/executor.md

@@ -35,6 +35,9 @@ You are **executor**, the code execution agent for Plan-Build-Run. You receive v
    a. Read task XML
    b. Execute <action> steps
    c. Run <verify> commands
+      - If <verify> contains an <automated> child element, extract and run the command inside it
+      - If <verify> is plain text (no <automated> child), run it as before (backward compat)
+      - Both forms produce the same result — <automated> is machine-parseable, plain text is human-readable
    d. If verify passes: commit
    e. If verify fails: apply deviation rules
    f. If checkpoint: STOP and return
@@ -196,6 +199,11 @@ When a task has a checkpoint type, **STOP execution** and return a structured re
 | `decision` | Before executing | Decision needed, options, context |
 | `human-action` | Before executing | What user must do, step-by-step |
 
+**auto_checkpoints config**: After loading plan frontmatter, read `gates.auto_checkpoints` from config.json (default false):
+- Load with: `node pbr-tools.js config-get gates.auto_checkpoints`
+- When `auto_checkpoints` is true AND task type is `checkpoint:human-verify`: run the automated verify command. If it passes, auto-approve and continue. If it fails, still STOP and return the checkpoint response.
+- `checkpoint:decision` and `checkpoint:human-action` always require human input regardless of `auto_checkpoints`.
+
 **Automation-first**: Complete all automatable pre-work before any checkpoint. Only checkpoint for genuinely human-required actions (API keys needing account login, architectural choices, destructive approvals).
 
 All responses use: `CHECKPOINT: {TYPE}` header, task info, type-specific fields, completed tasks table, remaining tasks list.

package/plugins/codex-pbr/agents/plan-checker.md

@@ -157,14 +157,16 @@ Plans declare `provides`/`consumes`; all consumed items must have providers.
 | Missing provides/consumes for exports | INFO |
 
 ### D9: Requirement Traceability
-Plans declare `requirement_ids` with bidirectional coverage. Forward: IDs trace to REQUIREMENTS.md (or ROADMAP.md goals). Backward: every requirement covered by at least one plan.
+Plans declare `implements` with bidirectional coverage. Forward: IDs trace to REQUIREMENTS.md (or ROADMAP.md goals). Backward: every requirement covered by at least one plan.
+
+> **Note:** `requirement_ids:` is a deprecated alias for `implements:` — treat as equivalent during transition.
 
 | Condition | Severity |
 |-----------|----------|
-| requirement_id references nonexistent requirement | BLOCKER |
+| implements: ID references nonexistent requirement | BLOCKER |
 | Requirement not covered by any plan | WARNING |
 | ROADMAP goal not covered (no REQUIREMENTS.md) | WARNING |
-| Plan missing requirement_ids entirely | INFO |
+| Plan missing implements: entirely | WARNING |
 
 ### D10: Test Plan Coverage
 Code-producing tasks should include test expectations. Check that tasks creating or modifying source code have corresponding test references in `<files>`, `<action>`, or `<verify>`. Test files should appear in `<files>`, test commands in `<verify>`, and test outcomes in `<done>`.

package/plugins/codex-pbr/agents/planner.md

@@ -9,7 +9,7 @@ you MUST Read every listed file BEFORE any other action.
 Skipping this causes hallucinated context and broken output.
 </files_to_read>
 
-> Default files: CONTEXT.md, ROADMAP.md, research documents, existing plan files
+> Default files: PROJECT.md (if exists), CONTEXT.md (project-level, if exists), phase CONTEXT.md (if exists), ROADMAP.md, research documents, existing plan files
 
 # Plan-Build-Run Planner
 
@@ -20,7 +20,7 @@ You are **planner**, the planning agent for the Plan-Build-Run development syste
 
 ## Core Principle: Context Fidelity
 
-**Locked decisions from CONTEXT.md are NON-NEGOTIABLE.** You never substitute, reinterpret, or work around locked decisions. If CONTEXT.md says "Use PostgreSQL", the plan uses PostgreSQL. Period.
+**Locked decisions from BOTH `.planning/CONTEXT.md` (project-level) AND `.planning/phases/{NN}-{slug}/CONTEXT.md` (phase-level) are NON-NEGOTIABLE.** Phase-level overrides project-level for the same decision area. You never substitute, reinterpret, or work around locked decisions. If CONTEXT.md says "Use PostgreSQL", the plan uses PostgreSQL. Period.
 
 **Deferred ideas from CONTEXT.md MUST NOT appear in plans.** If something is marked as deferred, it does not exist for planning purposes. Do not plan for it, do not create hooks for it, do not "prepare" for it.
 </role>
@@ -192,7 +192,13 @@ Two plans CONFLICT if their `files_modified` lists overlap. Conflicting plans MU
 <execution_flow>
 ## Planning Process
 
-1. **Load Context**: Read CONTEXT.md (locked decisions + deferred ideas), phase goal, and any research documents.
+1. **Load Context**: Read locked decisions, phase goal, and any research documents.
+   - Read `.planning/PROJECT.md` (if exists) — project scope/out-of-scope constraints
+   - Read `.planning/CONTEXT.md` (project-level, if exists) — cross-cutting locked decisions
+   - Read `.planning/phases/{NN}-{slug}/CONTEXT.md` (phase-level, if exists) — phase-specific decisions
+   - Phase-level CONTEXT.md overrides project-level for conflicting decision areas
+   - **For each locked decision found**: embed it directly into the relevant task's `<action>` block.
+     Executors NEVER read CONTEXT.md — PLAN.md task actions must be self-contained.
 
 ### Handling [NEEDS DECISION] Items
 When CONTEXT.md or RESEARCH-SUMMARY.md contains `[NEEDS DECISION]` flags from the synthesizer:
@@ -202,7 +208,7 @@ When CONTEXT.md or RESEARCH-SUMMARY.md contains `[NEEDS DECISION]` flags from th
 2. **Derive Must-Haves**: Apply goal-backward methodology — state the phase goal as a user-observable outcome, derive truths, artifacts, and key links.
 3. **Break Down Tasks**: For each must-have, determine code changes, files involved, verification method, and observable done condition. Group related work into tasks (2-3 per plan).
 4. **Assign Waves and Dependencies**: Identify independent tasks (Wave 1), map dependencies, assign wave numbers, check for circular deps and file conflicts within same wave.
-5. **Write Plan Files**: Complete YAML frontmatter (include `requirement_ids` from REQUIREMENTS.md or ROADMAP.md goal IDs for traceability), XML tasks with all 5 elements, clear action instructions, executable verify commands, observable done conditions. Append a `## Summary` section per `references/plan-format.md` (under 500 tokens): plan ID, numbered task list, key files, must-haves, provides/consumes.
+5. **Write Plan Files**: Complete YAML frontmatter (include `implements` field with REQ-IDs from REQUIREMENTS.md or ROADMAP.md for traceability; `requirement_ids` is a deprecated alias — use `implements` as the primary field), XML tasks with all 5 elements, clear action instructions, executable verify commands, observable done conditions. Append a `## Summary` section per `references/plan-format.md` (under 500 tokens): plan ID, numbered task list, key files, must-haves, provides/consumes.
 6. **Self-Check** before writing:
 
 **CRITICAL — Run the self-check. Plans missing must-have coverage or incomplete tasks cause executor failures.**
@@ -240,7 +246,7 @@ When receiving checker feedback:
 
 ## Context Optimization
 
-**Context Fidelity Self-Check**: Before writing plans, verify: (1) every locked decision in CONTEXT.md has a corresponding task, (2) no task implements a deferred idea, (3) each "Claude's Discretion" item is addressed in at least one task. Report: "CONTEXT.md compliance: {M}/{N} locked decisions mapped."
+**Context Fidelity Self-Check**: Before writing plans, verify: (1) every locked decision in BOTH `.planning/CONTEXT.md` (project-level) AND `.planning/phases/{NN}-{slug}/CONTEXT.md` (phase-level) has a corresponding task (deduplicate identical decisions across both files), (2) no task implements a deferred idea, (3) each "Claude's Discretion" item is addressed in at least one task. Report: "CONTEXT.md compliance: {M}/{N} locked decisions mapped."
 
 **Frontmatter-First Assembly**: When prior plans exist, read SUMMARY.md frontmatter only (not full body) — 10 frontmatters ~500 tokens vs 10 full SUMMARYs ~5000 tokens. Extract: `provides`, `requires`, `key_files`, `key_decisions`, `patterns`. Only read full body when a specific detail is needed.
 
@@ -256,7 +262,7 @@ When receiving checker feedback:
 - [ ] Tasks grouped into plans by wave
 - [ ] PLAN files exist with XML task structure
 - [ ] Each plan: frontmatter complete (depends_on, files_modified, must_haves)
-- [ ] Each plan: requirement_ids field populated (MUST NOT be empty)
+- [ ] Each plan: implements: field populated (list REQ-IDs; use [] only if phase has no REQUIREMENTS.md)
 - [ ] Each task: all 5 elements (name, files, action, verify, done)
 - [ ] Wave structure maximizes parallelism
 - [ ] Every REQ-ID from ROADMAP/REQUIREMENTS appears in at least one plan
@@ -336,7 +342,7 @@ One-line task descriptions in `<name>`. File paths in `<files>`, not explanation
 11. DO NOT leave done conditions vague — they must be observable
 12. DO NOT specify literal `undefined` for parameters that have a known source in the calling context — use data contracts to map sources
 13. DO NOT use Bash heredoc for file creation — ALWAYS use the Write tool
-14. DO NOT leave requirement_ids empty in PLAN frontmatter — every plan must trace to requirements
+14. DO NOT leave implements: empty in PLAN frontmatter — use implements: as the primary traceability field (requirement_ids: is deprecated)
 
 </anti_patterns>
 

package/plugins/codex-pbr/agents/verifier.md

@@ -74,7 +74,8 @@ Stop and report error if pbr-tools CLI is unavailable. Also read CONTEXT.md for
 - `artifacts`: Files/exports that must exist, be substantive, and not be stubs
 - `key_links`: Connections that must be wired between components
 
-If plans lack explicit must-haves, derive them goal-backward from ROADMAP.md: what must be TRUE → what must EXIST → what must be CONNECTED.
+Must-haves in plan frontmatter are canonical — use exactly what mustHavesCollect returns.
+Only fall back to goal-backward derivation from ROADMAP.md if ALL plans in the phase have completely empty must_haves sections. Do NOT supplement or re-derive when must_haves are present.
 
 Output: A numbered list of every must-have to verify.
 
@@ -159,6 +160,14 @@ Cross-reference all must-haves against verification results in a table:
 
 L4 column shows `-` when no automated verification is available. Only artifacts with test commands or build verification get L4 checks.
 
+### Step 7b: Write REQ-ID Traceability (Always)
+
+After verifying all must-haves, collect `implements:[]` from all plan frontmatters in the phase.
+
+- For each REQ-ID: if all must-haves for that plan passed → add to `satisfied:[]`
+- If any must-have for that plan failed → add to `unsatisfied:[]`
+- Write `satisfied:[]` and `unsatisfied:[]` to the VERIFICATION.md frontmatter
+
 ### Step 8: Scan for Anti-Patterns (Full Verification Only)
 
 Scan for: dead code/unused imports, console.log in production code, hardcoded secrets, TODO/FIXME comments (should be in deferred), disabled/skipped tests, empty catch blocks, committed .env files. Report blockers only.

package/plugins/codex-pbr/references/plan-format.md

@@ -43,9 +43,9 @@ provides:
   - "requireAuth() middleware"
 consumes:
   - "Database connection (from plan 01-01)"
-requirement_ids:
-  - "P02-G1"
-  - "P02-G2"
+implements:
+  - "REQ-F-001"
+  - "REQ-F-002"
 closes_issues:
   - 42
   - 57
@@ -71,7 +71,8 @@ closes_issues:
 | `must_haves.key_links` | YES | array | Connections between components. Append `: grep command` for verification. |
 | `provides` | NO | array | What this plan exports for other plans to consume (classes, endpoints, modules) |
 | `consumes` | NO | array | What this plan needs from prior plans. Format: `"Thing (from plan XX-YY)"` |
-| `requirement_ids` | NO | array | Requirement IDs from REQUIREMENTS.md or ROADMAP.md goal IDs that this plan addresses. Enables bidirectional traceability between plans and requirements/goals. |
+| `implements` | NO (WARNING if absent) | array | REQ-IDs from REQUIREMENTS.md this plan addresses. Primary traceability field. |
+| `requirement_ids` | NO | array | DEPRECATED — use `implements:` instead. Kept for backward compat. |
 | `dependency_fingerprints` | NO | object | Hashes of dependency phase SUMMARY.md files at plan-creation time. Used to detect stale plans. |
 | `data_contracts` | NO | array | Cross-boundary parameter mappings for calls where arguments originate from external boundaries. Format: `"param: source (context) [fallback]"` |
 | `closes_issues` | NO | number[] | GitHub issue numbers to close when this plan's final commit lands. Default: `[]` |
@@ -162,14 +163,20 @@ The Summary section is generated by the planner agent at plan creation time. It
        DISCORD_REDIRECT_URI=http://localhost:3000/auth/callback
   </action>
   <verify>
-    npx tsc --noEmit
-    ls src/auth/discord.ts
-    ls src/auth/types.ts
+    <automated>
+      npx tsc --noEmit
+      ls src/auth/discord.ts
+      ls src/auth/types.ts
+    </automated>
   </verify>
   <done>Discord OAuth client module exists and compiles without errors</done>
 </task>
 ```
 
+> **Verify block forms**: The `<automated>` wrapper (Option A) is preferred — it enables machine-parsing
+> for `auto_checkpoints` mode. Plain-text verify commands without the wrapper (Option B) remain valid
+> for backward compatibility. Both forms are supported by the executor.
+
 ### TDD Task
 
 ```xml
@@ -204,6 +211,33 @@ The Summary section is generated by the planner agent at plan creation time. It
 </task>
 ```
 
+### Feature Task (TDD Variant)
+
+Feature tasks add a `<feature>` element for structured TDD planning. The element contains two required children:
+
+- **`<behavior>`** — the observable outcome from the user's perspective. Maps directly to a `must_haves.truths` entry.
+- **`<implementation>`** — the technical approach at a high level (which files, patterns, or algorithms to use).
+
+Prose structure (illustrative — not a live task block to avoid validator false-positives):
+
+```
+task id="02-01-T3" type="auto" tdd="true" complexity="medium"
+  name: Implement rate limiter for OAuth endpoint
+  files: src/middleware/rate-limit.ts / tests/middleware/rate-limit.test.ts
+  feature:
+    behavior: OAuth endpoint rejects more than 5 requests per minute per IP with HTTP 429
+    implementation: Token-bucket algorithm; Redis-backed counter with TTL; express-rate-limit wrapper
+  action:
+    RED: Write failing tests for 429 response at >5 req/min
+    GREEN: Implement token-bucket middleware using Redis
+    REFACTOR: Extract counter logic to RateLimitStore class
+  verify:
+    automated: npm test -- --grep "rate limiter"
+  done: Rate limiter rejects excessive OAuth requests with 429
+```
+
+The `<feature>` element is optional — standard TDD tasks without it are still valid. Use `<feature>` when the planner wants to record the behavior/implementation split explicitly for traceability.
+
 ### Checkpoint: Human Verify
 
 ```xml
@@ -291,9 +325,13 @@ Every task MUST have ALL 5. No exceptions.
 | `<name>` | What the task does | Imperative verb phrase. Short. |
 | `<files>` | Files touched | One per line. Actual file paths. |
 | `<action>` | How to do it | Numbered steps. Specific. Code snippets for complex work. |
-| `<verify>` | How to check | Executable shell commands. Or checkpoint format. |
+| `<verify>` | How to check | Executable shell commands (plain-text or wrapped in `<automated>`). Or checkpoint format. |
 | `<done>` | How to know it worked | Observable user/system behavior. Maps to a must-have. |
 
+> **Optional `<feature>` element**: Feature tasks (TDD variant) may add a `<feature>` element with
+> `<behavior>` and `<implementation>` children for structured TDD planning. The 5 standard elements
+> above are still required.
+
 ---
 
 ## Task ID Format

package/plugins/codex-pbr/skills/begin/SKILL.md

@@ -546,11 +546,10 @@ For each category, present the features and ask the user to classify each:
 - **Out of scope** — Will NOT be built
 
 **7d. Assign REQ-IDs:**
-For each committed requirement, assign an ID in the format `{CATEGORY}-{NN}`:
-- `AUTH-01`: User can log in with Discord OAuth
-- `AUTH-02`: Protected routes redirect to login
-- `UI-01`: Dashboard shows player statistics
-- `UI-02`: Mobile-responsive layout
+For each committed requirement, assign an ID using the REQ-F/REQ-NF schema:
+- Functional requirements: `REQ-F-xxx` numbered sequentially within each category (REQ-F-001, REQ-F-002, ...)
+- Non-functional requirements: `REQ-NF-xxx` numbered sequentially across all NFR categories (REQ-NF-001, REQ-NF-002, ...)
+- Examples: `REQ-F-001: User can log in with Discord OAuth`, `REQ-NF-001: Page loads in <2s on 4G`
 
 Each requirement must be:
 - **User-centric** — describes a capability from the user's perspective
@@ -663,28 +662,13 @@ Write the project state files from templates:
 **CRITICAL (no hook): Write CONTEXT.md NOW. Do NOT skip this step.**
 
 **9c. Write CONTEXT.md:**
-Create `.planning/CONTEXT.md` from information gathered during questioning:
-
-```markdown
-# Project Context
-
-## Locked Decisions
-{Technology choices, architecture decisions, and constraints that are NON-NEGOTIABLE}
-
-| Decision | Rationale | Locked By |
-|----------|-----------|-----------|
-| {e.g., "Use TypeScript"} | {User preference, team skill} | User |
-
-## User Constraints
-{Budget, timeline, skill level, hosting, team size}
-
-## Deferred Ideas
-{Features explicitly moved to v2 or out-of-scope}
-
-| Idea | Reason Deferred |
-|------|----------------|
-| {feature} | {reason} |
-```
+1. Read `${CLAUDE_SKILL_DIR}/templates/project-CONTEXT.md.tmpl`
+2. Fill in from the questioning conversation:
+   - Locked Decisions: all technology choices and architecture decisions from Step 2
+   - User Constraints: budget, timeline, skill level, hosting, team
+   - Deferred Ideas: out-of-scope items identified in Step 7c scoping
+   - Claude's Discretion: any areas where user said "you decide"
+3. Write to `.planning/CONTEXT.md`
 
 **CRITICAL (no hook): Write HISTORY.md NOW. Do NOT skip this step.**
 

package/plugins/codex-pbr/skills/discuss/SKILL.md

@@ -35,9 +35,12 @@ This skill runs **inline** (no Task delegation).
 
 ### Step 1: Parse Phase Number and Check for Existing Plans
 
-Parse `$ARGUMENTS` to get the phase number.
+Parse `$ARGUMENTS`:
+- If argument is `--project`: enter PROJECT mode (see Step 1-project below). Skip Steps 2-8.
+- If argument is a phase number: enter PHASE mode (existing flow — continue with Step 1 as-is).
+- If no argument: existing logic applies (read STATE.md for current phase).
 
-**Validation:**
+**Validation (PHASE mode):**
 - Must be a valid phase number (integer or decimal like `3.1`)
 - If no argument provided, read STATE.md to get the current phase
 - If no current phase and no argument: "Which phase do you want to discuss? Run `$pbr-status` to see available phases."
@@ -63,6 +66,53 @@ Phase {N} not found.
    - Warn: "Phase {N} already has plans. Decisions from this discussion won't retroactively change them. Consider re-planning with `$pbr-plan {N}` after."
    - This is a **warning only** — do not block the discussion
 
+### Step 1-project: Project Discussion Mode (--project)
+
+When invoked with `--project`, discuss project-level cross-cutting decisions.
+This mode writes to `.planning/CONTEXT.md` (project-level), NOT a phase directory.
+
+**Check for existing project CONTEXT.md:**
+1. Use Glob to check if `.planning/CONTEXT.md` exists.
+2. If it exists, ask the user (using the context-handling pattern from
+   `skills/shared/gate-prompts.md`):
+   question: "Project CONTEXT.md already exists. How should we handle it?"
+   options: Overwrite | Append | Cancel
+3. If Cancel: stop and display the existing CONTEXT.md path.
+
+**Load project context:**
+- Read `.planning/PROJECT.md` (if exists) — project vision and scope
+- Read `.planning/REQUIREMENTS.md` (if exists) — requirements for constraint awareness
+- Read `.planning/CONTEXT.md` (if exists) — current locked decisions (for Append mode)
+
+**Run gray areas for project-level decisions (Steps 2.5-5 pattern):**
+- Identify 3-4 cross-cutting architectural decisions across ALL phases
+- Focus on: technology stack choices, infrastructure, security posture,
+  observability approach, deployment strategy, data storage decisions
+- Follow the same Steps 3-5 pattern (gray areas → options → follow-ups)
+
+**Write project CONTEXT.md:**
+1. Read `${CLAUDE_SKILL_DIR}/templates/project-CONTEXT.md.tmpl`
+2. Fill in from discussion decisions:
+   - Locked Decisions table: all decisions the user made (not "Let Claude decide")
+   - User Constraints: budget, team, timeline, hosting from the conversation
+   - Deferred Ideas: anything explicitly ruled out for this project
+   - Claude's Discretion: decisions marked "Let Claude decide"
+3. If Append mode: merge new decisions with existing CONTEXT.md content
+4. Write to `.planning/CONTEXT.md`
+
+**Update STATE.md pointer:**
+Add under Accumulated Context:
+```
+Project context: .planning/CONTEXT.md ({N} locked decisions, {N} deferred, {N} discretion)
+```
+
+**After writing:** Auto-sync to CLAUDE.md is handled by the post-write-dispatch hook.
+Display: `✓ Project CONTEXT.md written — locked decisions will auto-sync to CLAUDE.md`
+
+Skip to Cleanup step. Do NOT run Steps 2-8 of the phase flow.
+
+---
+
 ### Step 2: Load Phase Context
 
 Read the following files to understand what this phase needs to accomplish:

package/plugins/codex-pbr/skills/health/SKILL.md

@@ -61,6 +61,19 @@ Stop all further checks.
 - PASS: All three required files exist
 - FAIL: List each missing file — "Run `$pbr-begin` to re-initialize, or create the file manually."
 
+**Advisory checks — WARN if missing, do not FAIL:**
+
+- `.planning/PROJECT.md`
+  If missing: `⚠ PROJECT.md not found. Run $pbr-begin to generate it, or create from plugins/pbr/templates/PROJECT.md.tmpl.`
+
+- `.planning/REQUIREMENTS.md`
+  If missing: `⚠ REQUIREMENTS.md not found. Run $pbr-begin to generate it, or create from plugins/pbr/templates/REQUIREMENTS.md.tmpl.`
+
+- `.planning/CONTEXT.md` (project-level)
+  If missing: `⚠ CONTEXT.md not found. Run $pbr-discuss --project to capture locked decisions.`
+
+These files are generated by $pbr-begin. Absence is expected on projects created before v2.15.
+
 ### Check 2: Config Validity
 
 Parse `.planning/config.json` as JSON. Check required fields: `version`, `depth`. Check recommended fields: `features`, `models`.

package/plugins/codex-pbr/skills/plan/SKILL.md

@@ -484,7 +484,17 @@ Use AskUserQuestion (pattern: approve-revise-abort from `skills/shared/gate-prom
 - Or make small inline edits to plan files directly
 
 **If user selects 'Approve':**
-- **CONTEXT.md compliance reporting**: If `.planning/CONTEXT.md` exists, compare all locked decisions against the generated plans. Print: "CONTEXT.md compliance: {M}/{N} locked decisions mapped to tasks" where M = locked decisions that are reflected in at least one task, N = total locked decisions. If any locked decisions are unmapped, list them as warnings.
+- **CONTEXT.md compliance reporting**: Check locked decisions from BOTH sources:
+  a. Project-level: `.planning/CONTEXT.md` (if exists) — cross-cutting decisions for all phases
+  b. Phase-level: `.planning/phases/{NN}-{slug}/CONTEXT.md` (if exists) — phase-specific decisions
+     Phase-level decisions override project-level for the same decision area.
+
+  Collect ALL locked decisions from both files (deduplicate identical decision text).
+  Compare against the generated plan tasks. Print:
+  `CONTEXT.md compliance: {M}/{N} locked decisions mapped to tasks`
+  where M = locked decisions reflected in at least one task action, N = total unique locked decisions.
+  If any locked decisions are unmapped, list them as warnings.
+  If neither CONTEXT.md exists: skip this check silently.
 - **Dependency fingerprinting**: For each dependency phase (phases that this phase depends on, per ROADMAP.md):
   1. Find all SUMMARY.md files in the dependency phase directory
   2. Compute a fingerprint string for each: `"len:{bytes}-mod:{mtime}"` and add as a `dependency_fingerprints` map in each plan's YAML frontmatter — this allows the build skill to detect stale plans if dependencies were rebuilt.

package/plugins/codex-pbr/skills/shared/context-loader-task.md

@@ -28,6 +28,7 @@ Task({
     - .planning/STATE.md
     - .planning/ROADMAP.md
     - .planning/REQUIREMENTS.md
+    - .planning/PROJECT.md (if exists — project vision and scope)
     - .planning/CONTEXT.md
     - Any .planning/phases/*/CONTEXT.md files
     - .planning/research/SUMMARY.md (if exists)
@@ -65,6 +66,7 @@ Task({
     - .planning/STATE.md
     - .planning/ROADMAP.md
     - .planning/REQUIREMENTS.md
+    - .planning/PROJECT.md (if exists — project vision and scope)
     - .planning/CONTEXT.md
     - Any .planning/phases/*/CONTEXT.md files
     - .planning/HISTORY.md (if exists — scan for decisions relevant to '{topic}' only, do NOT summarize all history)

package/plugins/codex-pbr/skills/status/SKILL.md

@@ -111,6 +111,16 @@ Parse the JSON response. Capture:
 
 Store these for use in Step 4 display and Step 5 routing.
 
+6. **`.planning/CONTEXT.md`** (project-level, if exists)
+   - Note: project-level locked decisions file
+
+### Step 1d: Check Project Documents
+
+Check existence of the three project-level documents and record their status for Step 4 display:
+- `.planning/PROJECT.md` — exists or not
+- `.planning/REQUIREMENTS.md` — exists or not
+- `.planning/CONTEXT.md` — exists or not
+
 ### Step 2: Scan Phase Directories
 
 For each phase listed in ROADMAP.md:
@@ -221,6 +231,13 @@ Phase Status:
 | 2. {name} | {status indicator} {status text} | {completed}/{total} | {percentage}% |
 | ...
 
+**Project documents:**
+| File | Status |
+|------|--------|
+| PROJECT.md | {exists / not found — run $pbr-begin} |
+| REQUIREMENTS.md | {exists / not found — run $pbr-begin} |
+| CONTEXT.md | {exists / not found — run $pbr-discuss --project} |
+
 {If context tier is DEGRADING, POOR, or CRITICAL:}
 ⚠ Context: {percentage}% used ({tier}) — {recommendation_text}
   Run `/compact` to reclaim context before spawning more agents.

package/plugins/codex-pbr/templates/PROJECT.md.tmpl

@@ -0,0 +1,41 @@
+# {project_name}
+
+> {ONE sentence core value statement}
+
+## Vision
+
+{2-3 sentences describing the product and problem it solves. Who is it for? What does it replace or improve?}
+
+## Scope
+
+### In Scope (v1)
+
+{Bulleted list of features and capabilities committed for this project.}
+
+- {Feature area}: {brief description}
+
+### Out of Scope
+
+{Features explicitly excluded from this project.}
+
+- {Feature}: {brief reason why excluded}
+
+## Success Criteria
+
+{Observable conditions that define project success. Each must be testable.}
+
+- {Criterion 1 — specific and measurable}
+- {Criterion 2 — specific and measurable}
+- {Criterion 3 — specific and measurable}
+
+## Stakeholders
+
+{Who cares about this project and why.}
+
+- **Primary user**: {description}
+- **Team**: {description}
+
+## Milestones
+
+{project_name} planned in {phase_count} phases across {milestone_count} milestone(s).
+See `.planning/ROADMAP.md` for phase details.

package/plugins/codex-pbr/templates/REQUIREMENTS.md.tmpl

@@ -0,0 +1,52 @@
+# Requirements
+
+> Living document. Generated by `/pbr:begin`, updated via `/pbr:discuss`.
+> All requirements flow from here into plans via `implements:[]` in PLAN.md frontmatter.
+
+## Functional Requirements
+
+Capabilities the system must provide from the user's perspective.
+
+### {Category} (e.g., Authentication, API, UI)
+
+| ID | Requirement | Priority | Status |
+|----|-------------|----------|--------|
+| REQ-F-001 | {User-centric, testable statement of capability} | Must | Open |
+| REQ-F-002 | {User-centric, testable statement of capability} | Should | Open |
+
+### {Category 2}
+
+| ID | Requirement | Priority | Status |
+|----|-------------|----------|--------|
+| REQ-F-010 | {User-centric, testable statement of capability} | Must | Open |
+
+## Non-Functional Requirements
+
+Quality attributes and constraints the system must satisfy.
+
+| ID | Requirement | Category | Priority |
+|----|-------------|----------|----------|
+| REQ-NF-001 | {Observable quality statement — e.g., "Page loads in <2s on 4G"} | Performance | Must |
+| REQ-NF-002 | {Observable quality statement} | Security | Must |
+| REQ-NF-003 | {Observable quality statement} | Reliability | Should |
+
+## Deferred Requirements (v2+)
+
+Requirements explicitly out of scope for v1.
+
+| ID | Requirement | Deferred Reason |
+|----|-------------|----------------|
+| REQ-F-099 | {requirement} | {reason — e.g., "Phase 2 priority"} |
+
+## Out of Scope
+
+Features explicitly excluded. These must NOT appear in any plan.
+
+- {Feature}: {brief rationale}
+
+## Traceability
+
+| REQ-ID | Implemented In | Verified In |
+|--------|---------------|------------|
+| REQ-F-001 | Phase 01 PLAN-01 | Phase 01 VERIFICATION.md |
+| REQ-F-002 | — | — |

package/plugins/codex-pbr/templates/VERIFICATION-DETAIL.md.tmpl

@@ -23,6 +23,11 @@ anti_patterns:
   console_logs: {count}
   skipped_tests: {count}
   hardcoded_secrets: {count}
+# populated by verifier from implements:[] in plan frontmatter
+satisfied:
+  - "REQ-F-001"    # REQ-IDs confirmed verified in this phase
+unsatisfied:
+  - "REQ-F-002"    # REQ-IDs that failed verification
 ---
 
 # Phase Verification: {phase_name}

package/plugins/codex-pbr/templates/project-CONTEXT.md.tmpl

@@ -0,0 +1,43 @@
+# Project Context
+
+> Cross-cutting decisions that ALL phases must honor.
+> Updated via `/pbr:discuss --project`. Auto-synced to CLAUDE.md on write.
+> Phase-level CONTEXT.md (in phase directories) overrides project-level for that phase.
+>
+> PLANNER NOTE: Embed each locked decision directly into the relevant task's action block.
+> Executors NEVER read this file — PLAN.md is self-contained.
+
+## Locked Decisions
+
+Technology choices, architecture decisions, and constraints that are NON-NEGOTIABLE across ALL phases.
+The planner embeds these into PLAN.md task actions. Executors never read this file directly.
+
+| Decision | Rationale | Locked By |
+|----------|-----------|-----------|
+| {e.g., "Use TypeScript strict mode"} | {User preference, team skill} | User |
+| {e.g., "PostgreSQL via Supabase"} | {Existing infrastructure} | User |
+
+## User Constraints
+
+Budget, timeline, skill level, hosting, team size — factors that shape ALL planning decisions.
+
+- {e.g., "Solo developer, no team"}
+- {e.g., "Deploy to Hetzner VPS"}
+- {e.g., "Must work offline"}
+
+## Deferred Ideas
+
+Ideas explicitly moved to v2 or ruled out. Plans at ANY phase MUST NOT include these.
+
+| Idea | Reason Deferred |
+|------|----------------|
+| {feature} | {reason — e.g., "Post-launch priority"} |
+
+## Claude's Discretion Areas
+
+Areas where planners can make implementation choices without asking the user.
+Document the choice made and rationale when exercised.
+
+| Area | Choice Made | Rationale |
+|------|------------|-----------|
+| {e.g., "Logging library"} | {e.g., "pino"} | {e.g., "Lightweight, structured output"} |