@ktpartners/dgs-platform 3.0.4 → 3.3.0

package/deliver-great-systems/templates/package-scan-report.md

@@ -0,0 +1,108 @@
+# Package Scan Report Template
+
+> Reference: the output format `/dgs:package-scan` produces.
+> This file is documentation — the emitter composes programmatically, not via template substitution.
+
+## Frontmatter + Body Skeleton
+
+```markdown
+---
+type: package-scan
+date: {{YYYY-MM-DD}}
+tool: {{snyk|osv-scanner|npm-audit|pip-audit|govulncheck|bundler-audit|mixed|none}}
+repos_scanned: {{N}}
+critical: {{N}}
+high: {{N}}
+medium: {{N}}
+low: {{N}}
+duration: {{seconds}}
+findings:
+  - id: "pkg-001"
+    test_source: "package-scan"
+    gap_type: "dependency-security"
+    severity: "critical"
+    resource_id: "{{package}}@{{version}}"
+    repo: "{{repo-name}}"
+    manifest_path: "{{manifest-path-or-null}}"
+    title: "{{title}}"
+    description: "{{description-or-null}}"
+    remediation: "{{remediation-or-null}}"
+    reference: "{{reference-url-or-null}}"
+    cve: "{{CVE-id-or-null}}"
+    cvss: {{score-or-null}}
+    dependency_chain:
+      - "{{dep1}}"
+      - "{{dep2}}"
+    chain_available: true
+    direct_or_transitive: "{{direct-or-transitive}}"
+    tool: "{{scanner-tool}}"
+---
+
+# Package Scan Report
+
+## Summary
+
+| Repo | Ecosystem | Tool | Critical | High | Medium | Low | Status |
+|------|-----------|------|----------|------|--------|-----|--------|
+| {{repo}} | {{node|python|go|ruby|java|yarn}} | {{tool}} | {{N}} | {{N}} | {{N}} | {{N}} | ok |
+| {{repo}} | {{ecosystem}} | — | — | — | — | — | skipped (no manifests) |
+
+## Critical
+
+### {{repo}}: {{package}}@{{version}} — {{title}}
+- **CVE:** {{CVE-id-or-'unavailable'}}
+- **CVSS:** {{score-or-'unavailable'}}
+- **Tool:** {{scanner-tool}}
+- **Manifest:** `{{manifest-path}}` (or `repo root`)
+- **Direct/Transitive:** {{direct-or-transitive-or-'unknown'}}
+- **Dependency chain:** {{a → b → c}} (or `unavailable (chain_available: false — recommend Snyk for full chain analysis)`)
+- **Fix:** {{remediation-or-'no upgrade path available — manual review required'}}
+- **Reference:** {{URL-or-'unavailable'}}
+
+> {{description-blockquote-if-present}}
+
+## High
+(per-finding format same as Critical)
+
+## Medium
+(per-finding format same as Critical)
+
+## Low
+(per-finding format same as Critical)
+
+## Diagnostics
+(present only when runResult.diagnostics is non-empty)
+- {{diagnostic.kind}}: {{diagnostic.message-or-hint}}
+```
+
+## Field reference
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `id` | string | `pkg-NNN` (zero-padded, assigned by orchestrator at merge time) |
+| `test_source` | string | Always `"package-scan"` (constant) |
+| `gap_type` | string | `"dependency-security"` or `"dependency-licence"` (Phase 153 extends to licence) |
+| `severity` | string | `critical|high|medium|low` (null/unknown collapses to `medium` — conservative bias) |
+| `resource_id` | string | `{{package_name}}@{{installed_version}}` (omit `@` if version empty) |
+| `repo` | string | Repo name from REPOS.md (or `_product_root`) |
+| `manifest_path` | string\|null | Relative POSIX path of manifest that produced the finding (null when scanning repo root) |
+| `title` | string | Vulnerability title from scanner |
+| `description` | string\|null | Vulnerability description (may be multi-line) |
+| `remediation` | string\|null | Fix command from scanner |
+| `reference` | string\|null | Advisory URL |
+| `cve` | string\|null | CVE identifier |
+| `cvss` | number\|null | CVSS score (v3 preferred) |
+| `dependency_chain` | array\|null | e.g., `[your-app, auth-lib, lodash]` |
+| `chain_available` | boolean | `false` when the scanner didn't provide a chain (OSV / native) |
+| `direct_or_transitive` | string\|null | `direct` or `transitive` |
+| `tool` | string | Scanner that produced this finding (for disambiguation when frontmatter `tool` is `mixed`) |
+
+## Placement cascade
+
+1. Active phase → `{phase-dir}/{phase-number}-PACKAGE-SCAN.md`
+2. Active milestone → `{planning-root}/milestones/v{X}.{Y}-PACKAGE-SCAN.md`
+3. No active context → `{planning-root}/PACKAGE-SCAN-{YYYY-MM-DD-HHmm}.md`
+
+## Related
+- `deliver-great-systems/references/package-scan-config.md` — config reference
+- `specs/spec-package-dependency-scanning.md` — the source spec

package/deliver-great-systems/templates/project.md

@@ -1,186 +1,22 @@
 # PROJECT.md Template
 
-Template for `PROJECT.md` (in planning root) — the living project context document.
-
-> **Layout-agnostic:** Workflows access PROJECT.md via `${project_path}` from init output. Works in both standard and root layouts.
+Thin skeleton for `PROJECT.md` (in `${project_path}`). Projects are holders —
+product-level vision lives in `docs/product/PRODUCT-SUMMARY.md` (Tier 1), and
+product architecture lives in `docs/product/ARCHITECTURE.md` (Tier 2).
 
 <template>
 
 ```markdown
 # [Project Name]
 
-## What This Is
-
-[Current accurate description — 2-3 sentences. What does this product do and who is it for?
-Use the user's language and framing. Update whenever reality drifts from this description.]
-
-## Core Value
-
-[The ONE thing that matters most. If everything else fails, this must work.
-One sentence that drives prioritization when tradeoffs arise.]
-
-## Requirements
-
-### Validated
-
-<!-- Shipped and confirmed valuable. -->
-
-(None yet — ship to validate)
-
-### Active
-
-<!-- Current scope. Building toward these. -->
-
-- [ ] [Requirement 1]
-- [ ] [Requirement 2]
-- [ ] [Requirement 3]
-
-### Out of Scope
-
-<!-- Explicit boundaries. Includes reasoning to prevent re-adding. -->
-
-- [Exclusion 1] — [why]
-- [Exclusion 2] — [why]
-
-## Context
-
-[Background information that informs implementation:
-- Technical environment or ecosystem
-- Relevant prior work or experience
-- User research or feedback themes
-- Known issues to address]
-
-## Constraints
-
-- **[Type]**: [What] — [Why]
-- **[Type]**: [What] — [Why]
-
-Common types: Tech stack, Timeline, Budget, Dependencies, Compatibility, Performance, Security
-
-## Key Decisions
-
-<!-- Decisions that constrain future work. Add throughout project lifecycle. -->
-
-| Decision | Rationale | Outcome |
-|----------|-----------|---------|
-| [Choice] | [Why] | [✓ Good / ⚠️ Revisit / — Pending] |
-
----
-*Last updated: [date] after [trigger]*
+<One-line purpose — fill in to anchor this project.>
 ```
 
 </template>
 
-<guidelines>
-
-**What This Is:**
-- Current accurate description of the product
-- 2-3 sentences capturing what it does and who it's for
-- Use the user's words and framing
-- Update when the product evolves beyond this description
-
-**Core Value:**
-- The single most important thing
-- Everything else can fail; this cannot
-- Drives prioritization when tradeoffs arise
-- Rarely changes; if it does, it's a significant pivot
-
-**Requirements — Validated:**
-- Requirements that shipped and proved valuable
-- Format: `- ✓ [Requirement] — [version/phase]`
-- These are locked — changing them requires explicit discussion
-
-**Requirements — Active:**
-- Current scope being built toward
-- These are hypotheses until shipped and validated
-- Move to Validated when shipped, Out of Scope if invalidated
-
-**Requirements — Out of Scope:**
-- Explicit boundaries on what we're not building
-- Always include reasoning (prevents re-adding later)
-- Includes: considered and rejected, deferred to future, explicitly excluded
-
-**Context:**
-- Background that informs implementation decisions
-- Technical environment, prior work, user feedback
-- Known issues or technical debt to address
-- Update as new context emerges
-
-**Constraints:**
-- Hard limits on implementation choices
-- Tech stack, timeline, budget, compatibility, dependencies
-- Include the "why" — constraints without rationale get questioned
-
-**Key Decisions:**
-- Significant choices that affect future work
-- Add decisions as they're made throughout the project
-- Track outcome when known:
-  - ✓ Good — decision proved correct
-  - ⚠️ Revisit — decision may need reconsideration
-  - — Pending — too early to evaluate
-
-**Last Updated:**
-- Always note when and why the document was updated
-- Format: `after Phase 2` or `after v1.0 milestone`
-- Triggers review of whether content is still accurate
-
-</guidelines>
-
-<evolution>
-
-PROJECT.md evolves throughout the project lifecycle.
-
-**After each phase transition:**
-1. Requirements invalidated? → Move to Out of Scope with reason
-2. Requirements validated? → Move to Validated with phase reference
-3. New requirements emerged? → Add to Active
-4. Decisions to log? → Add to Key Decisions
-5. "What This Is" still accurate? → Update if drifted
-
-**After each milestone:**
-1. Full review of all sections
-2. Core Value check — still the right priority?
-3. Audit Out of Scope — reasons still valid?
-4. Update Context with current state (users, feedback, metrics)
-
-</evolution>
-
-<brownfield>
-
-For existing codebases:
-
-1. **Map codebase first** via `/dgs:map-codebase`
-
-2. **Infer Validated requirements** from existing code:
-   - What does the codebase actually do?
-   - What patterns are established?
-   - What's clearly working and relied upon?
-
-3. **Gather Active requirements** from user:
-   - Present inferred current state
-   - Ask what they want to build next
-
-4. **Initialize:**
-   - Validated = inferred from existing code
-   - Active = user's goals for this work
-   - Out of Scope = boundaries user specifies
-   - Context = includes current codebase state
-
-</brownfield>
-
 <state_reference>
 
-STATE.md references PROJECT.md:
-
-```markdown
-## Project Reference
-
-See: PROJECT.md (updated [date])
-
-**Core value:** [One-liner from Core Value section]
-**Current focus:** [Current phase name]
-```
-
-This ensures Claude reads current PROJECT.md context.
+STATE.md references PROJECT.md by path; the thin skeleton still satisfies
+`dgs-tools health` Check 2 (file exists + top-level heading).
 
 </state_reference>

package/deliver-great-systems/templates/summary.md

@@ -40,7 +40,9 @@ patterns-established:
   - "Pattern 1: description"
   - "Pattern 2: description"
 
-requirements-completed: []  # REQUIRED — Copy ALL requirement IDs from this plan's `requirements` frontmatter field.
+requirements_completed: []  # MANDATORY — Copy ALL requirement IDs from this plan's `requirements` frontmatter field VERBATIM. Empty array allowed only when PLAN's `requirements:` is also empty. Pre-commit precondition (REL-08) aborts the executor with `summary-frontmatter-mismatch` if non-empty PLAN paired with empty `requirements_completed`.
+# Canonical key: `requirements_completed` (underscore — pinned by Phase 157 / 157-Q2-FINDINGS.md).
+# The legacy hyphen variant is still readable by `cmdSummaryExtract` for backwards-compat with archived v23.1 SUMMARYs (REL-10 dual-read), but MUST NOT be used for new SUMMARYs.
 
 # Metrics
 duration: Xmin

package/deliver-great-systems/workflows/add-phase.md

@@ -76,6 +76,11 @@ Update STATE.md to reflect the new phase:
    ```
 
 If "Roadmap Evolution" section doesn't exist, create it.
+
+3. Commit both ROADMAP.md and STATE.md:
+   ```bash
+   node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" commit "docs: add phase {N} to roadmap" --push --files ${roadmap_path} ${state_path}
+   ```
 </step>
 
 <step name="completion">

package/deliver-great-systems/workflows/audit-milestone.md

@@ -45,6 +45,19 @@ node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" phases list
 - Extract milestone definition of done from ROADMAP.md
 - Extract requirements mapped to this milestone from REQUIREMENTS.md
 
+### Parse `--strict-audit` flag (REL-10)
+
+```bash
+STRICT_AUDIT=$(echo "$ARGUMENTS" | grep -oE -- '--strict-audit' | head -1)
+if [ -n "$STRICT_AUDIT" ]; then
+  STRICT_AUDIT=true
+else
+  STRICT_AUDIT=false
+fi
+```
+
+When `STRICT_AUDIT=true`, the cross-reference matrix in Section 5d preserves the OLD strict behaviour: empty `requirements_completed` → `partial` regardless of VERIFICATION state. When `STRICT_AUDIT=false` (default), Section 5d applies the soft-tolerance via `bin/lib/audit-tolerance.cjs::applyMatrix` and logs the `summary-frontmatter-empty-but-verified` warning under a separate channel (`soft_warnings`) — distinct from real partials.
+
 ## 2. Read All Phase Verifications
 
 For each phase directory, read the VERIFICATION.md:
@@ -143,21 +156,30 @@ done
 
 ### 5d. Status Determination Matrix
 
-For each REQ-ID, determine status using all three sources:
+For each REQ-ID, determine status using all three sources, routed through `bin/lib/audit-tolerance.cjs::applyMatrix(input)` (REL-10):
+
+| VERIFICATION.md Status | SUMMARY Frontmatter | requirements_claimed in VERIFICATION | --strict-audit | → Final Status |
+|------------------------|---------------------|--------------------------------------|----------------|----------------|
+| passed                 | listed              | any                                  | any            | **satisfied** |
+| passed                 | empty               | lists ID                             | false (default) | **satisfied** + soft-warning `summary-frontmatter-empty-but-verified` |
+| passed                 | empty               | lists ID                             | true            | **partial** (preserves old strict behaviour; opt-in via `--strict-audit`) |
+| passed                 | empty               | does NOT list ID                     | any            | **partial** (real partial — tolerance must NOT mask this) |
+| gaps_found             | any                 | any                                  | any            | **unsatisfied** |
+| missing                | listed              | any                                  | any            | **partial** (verification gap) |
+| missing                | missing             | any                                  | any            | **unsatisfied** |
+
+**Soft-warning channel:** Entries with status `satisfied` AND `softWarning: 'summary-frontmatter-empty-but-verified'` are collected in a SEPARATE list under `soft_warnings.summary_frontmatter_empty_but_verified` in the audit JSON output. They are NOT included under `gaps.requirements` — that channel is reserved for real `unsatisfied` and real `partial`. The soft-warning channel is shown as an info-level note in the markdown report.
 
-| VERIFICATION.md Status | SUMMARY Frontmatter | REQUIREMENTS.md | → Final Status |
-|------------------------|---------------------|-----------------|----------------|
-| passed                 | listed              | `[x]`           | **satisfied**  |
-| passed                 | listed              | `[ ]`           | **satisfied** (update checkbox) |
-| passed                 | missing             | any             | **partial** (verify manually) |
-| gaps_found             | any                 | any             | **unsatisfied** |
-| missing                | listed              | any             | **partial** (verification gap) |
-| missing                | missing             | any             | **unsatisfied** |
+**Implementation:** Section 5d invokes `applyMatrix({ verificationStatus, requirementsClaimed, summaryRequirementsCompleted, reqId, strictAudit })` for each REQ-ID. The output `{ status, softWarning }` populates the per-requirement row.
+
+**Removal trigger (REL-10 band-aid):** When 3 consecutive milestones ship with zero `summary-frontmatter-empty-but-verified` warnings, this row should be removed from the matrix and the strict behaviour restored as default.
 
 ### 5e. FAIL Gate and Orphan Detection
 
 **REQUIRED:** Any `unsatisfied` requirement MUST force `gaps_found` status on the milestone audit.
 
+**Soft-warning entries (`softWarning: 'summary-frontmatter-empty-but-verified'`) MUST NOT force `gaps_found`** — they are `satisfied` with a recoverable provenance gap. They surface in `soft_warnings.summary_frontmatter_empty_but_verified` and in the markdown info-level notes only.
+
 **Orphan detection:** Requirements present in REQUIREMENTS.md traceability table but absent from ALL phase VERIFICATION.md files MUST be flagged as orphaned. Orphaned requirements are treated as `unsatisfied` — they were assigned but never verified by any phase.
 
 ## 5.5. Nyquist Compliance Discovery
@@ -207,6 +229,11 @@ gaps:  # Critical blockers
       completed_by_plans: ["{plan files whose SUMMARY marks it complete}"]
       verification_status: "passed | gaps_found | missing | orphaned"
       evidence: "{specific evidence or lack thereof}"
+soft_warnings:  # REL-10: recoverable provenance issues — NOT blockers
+  summary_frontmatter_empty_but_verified:
+    - id: "{REQ-ID}"
+      phase: "{phase}"
+      reason: "VERIFICATION.md status: passed and requirements_claimed lists ID; SUMMARY.md requirements_completed is empty"
   integration: [...]
   flows: [...]
 tech_debt:  # Non-critical, deferred
@@ -227,7 +254,35 @@ Plus full markdown report with tables for requirements, phases, integration, tec
 - `gaps_found` — critical blockers exist
 - `tech_debt` — no blockers but accumulated deferred items need review
 
-## 7. Present Results
+## 7. Generate REVIEW.md
+
+After audit scoring completes, generate the milestone review report so it is available before reviewers run complete-milestone.
+
+```bash
+# Generate REVIEW.md using the CLI command — always regenerates even if prior version exists
+REVIEW_RESULT=$(node "$HOME/.claude/deliver-great-systems/bin/dgs-tools.cjs" jobs generate-review "${milestone_version}" --raw 2>&1)
+REVIEW_EXIT=$?
+```
+
+**If generation succeeds** (`REVIEW_EXIT` is 0):
+
+Parse the JSON output to get the file path:
+```bash
+REVIEW_PATH=$(echo "$REVIEW_RESULT" | node -e "const d=require('fs').readFileSync('/dev/stdin','utf-8');try{const j=JSON.parse(d);console.log(j.relativePath||'')}catch{console.log('')}")
+```
+
+Display: `Review report: ${REVIEW_PATH}`
+
+**If generation fails** (`REVIEW_EXIT` is non-zero):
+
+Log warning and continue — do NOT block the audit:
+```
+Warning: Review generation failed: ${REVIEW_RESULT}
+```
+
+The audit report is complete regardless of review generation status. The review report is supplementary context for four-eyes reviewers.
+
+## 8. Present Results
 
 Route by status (see `<offer_next>`).
 
@@ -360,5 +415,6 @@ All requirements met. No critical blockers. Accumulated tech debt needs review.
 - [ ] FAIL gate enforced — any unsatisfied requirement forces gaps_found status
 - [ ] Nyquist compliance scanned for all milestone phases (if enabled)
 - [ ] Missing VALIDATION.md phases flagged with validate-phase suggestion
+- [ ] REVIEW.md generated as final step (or warning logged on failure)
 - [ ] Results presented with actionable next steps
 </success_criteria>

package/deliver-great-systems/workflows/cancel-job.md

@@ -65,7 +65,7 @@ Display the result based on the response:
 
 **If `cancelled: true`:**
 ```
-Job {version} cancelled. {steps_reset} in-progress step(s) reset. Job moved to pending/ -- re-run with /dgs:run-job {version}
+Job {version} cancelled. {steps_reset} in-progress step(s) reset. Job status set to pending -- re-run with /dgs:run-job {version}
 ```
 
 **If `reason: 'not_found'`:**

package/deliver-great-systems/workflows/codereview.md

@@ -9,7 +9,10 @@ Multi-agent code review that runs 3 passes of 3 parallel agents each (9 total re
 - PLAN: plan number
 - PLAN_PATH: path to the PLAN.md file
 - PHASE_DIR: phase directory path
+- CODE_REPO_PATH: absolute path to the code repo where task commits live. All git commands in this workflow MUST run against this repo via `git -C "${CODE_REPO_PATH}"`, because the spawned subagent inherits the orchestrator's cwd (the planning repo), not the code repo.
 - DIFF_REF: git ref range for the code diff (from first task commit to HEAD)
+- PROJECT_ROOT: project root directory path (e.g., projects/gsd). Passed by execute-phase. Used to resolve project-scoped context files.
+- PLANNING_ROOT: planning root directory path (git repo root). Passed by execute-phase. Used as fallback for product-level context files.
 </inputs>
 
 <process>
@@ -18,7 +21,7 @@ Multi-agent code review that runs 3 passes of 3 parallel agents each (9 total re
 Compute the diff from the plan's task commits.
 
 ```bash
-FIRST_TASK_COMMIT=$(git log --oneline --grep="feat(${PHASE}-${PLAN}):" --grep="fix(${PHASE}-${PLAN}):" --grep="test(${PHASE}-${PLAN}):" --grep="refactor(${PHASE}-${PLAN}):" --reverse | head -1 | cut -d' ' -f1)
+FIRST_TASK_COMMIT=$(git -C "${CODE_REPO_PATH}" log --oneline --grep="feat(${PHASE}-${PLAN}):" --grep="fix(${PHASE}-${PLAN}):" --grep="test(${PHASE}-${PLAN}):" --grep="refactor(${PHASE}-${PLAN}):" --reverse | head -1 | cut -d' ' -f1)
 ```
 
 If FIRST_TASK_COMMIT is empty, exit with message: "No task commits found for ${PHASE}-${PLAN}, skipping code review."
@@ -26,13 +29,13 @@ If FIRST_TASK_COMMIT is empty, exit with message: "No task commits found for ${P
 Otherwise, compute the full diff:
 
 ```bash
-REVIEW_DIFF=$(git diff ${FIRST_TASK_COMMIT}^..HEAD)
+REVIEW_DIFF=$(git -C "${CODE_REPO_PATH}" diff ${FIRST_TASK_COMMIT}^..HEAD)
 ```
 
 Store REVIEW_DIFF for use by all review agents. Also store the file list:
 
 ```bash
-CHANGED_FILES=$(git diff --name-only ${FIRST_TASK_COMMIT}^..HEAD)
+CHANGED_FILES=$(git -C "${CODE_REPO_PATH}" diff --name-only ${FIRST_TASK_COMMIT}^..HEAD)
 ```
 
 Display:
@@ -43,11 +46,77 @@ Reviewing ${PHASE}-${PLAN} changes:
 ```
 </step>
 
+<step name="load_context">
+Load project context files for domain-specific review. These files provide architecture rules, coding conventions, and design principles that the review agents use to catch project-specific violations alongside generic code quality issues.
+
+If PROJECT_ROOT is empty or not provided, skip the entire step silently (backward compatibility for codereview spawned without PROJECT_ROOT).
+
+**Context files (in truncation priority order -- first truncated = least valuable):**
+1. `codebase/ARCHITECTURE.md` -- auto-generated codebase structure overview
+2. `codebase/CONVENTIONS.md` -- auto-generated naming/import/error handling patterns
+3. `docs/product/ARCHITECTURE.md` -- hand-written target architecture and domain rules
+4. `docs/product/DESIGN-PRINCIPLES.md` -- hand-written design principles and lessons learned
+
+**Path resolution (dual-path fallback):**
+For each file, try two paths in order:
+1. `${PROJECT_ROOT}/<file>` (v2 project-scoped path)
+2. `${PLANNING_ROOT}/<file>` (v1 product-level / synthesized fallback)
+
+Use the Read tool to load each file. If Read returns an error (file not found), silently skip that file. Do NOT error or warn for individual missing files.
+
+**Build PROJECT_CONTEXT:**
+For each successfully loaded file, prepend a header line:
+```
+--- {filename} ({byte_count} bytes) ---
+{file_content}
+```
+
+Concatenate all loaded file contents into a single `PROJECT_CONTEXT` variable.
+
+**Size guard:**
+After loading all files, measure total byte length of PROJECT_CONTEXT.
+
+If total exceeds 51200 bytes (~50KB):
+- Truncate files in priority order (ARCHITECTURE.md from codebase/ first, then CONVENTIONS.md from codebase/, then docs/product/ARCHITECTURE.md, then docs/product/DESIGN-PRINCIPLES.md last)
+- For each truncated file, cut to fit within the remaining budget and append: `\n[Truncated from {original_bytes} bytes to {truncated_bytes} bytes]`
+- After truncation, log a warning:
+  ```
+  ⚠ Project context truncated to ~50KB:
+    {filename}: truncated from {original} to {truncated} bytes
+  ```
+
+**Logging:**
+Display which context files were loaded:
+
+When at least one file found:
+```
+Project context loaded:
+  codebase/ARCHITECTURE.md: {N} bytes
+  codebase/CONVENTIONS.md: {N} bytes (or "not found")
+  docs/product/ARCHITECTURE.md: {N} bytes (or "not found")
+  docs/product/DESIGN-PRINCIPLES.md: {N} bytes (or "not found")
+  Total: {N} bytes
+```
+
+When no files found:
+```
+Project context: no context files found (skipped)
+```
+</step>
+
 <step name="pass_1_foundational">
 **Pass 1: Foundational Review** -- Spawn 3 parallel Task() subagents.
 
 Each agent receives REVIEW_DIFF and CHANGED_FILES as input context.
 
+If PROJECT_CONTEXT is non-empty, also provide it to each agent wrapped in tags:
+
+<project_context>
+{PROJECT_CONTEXT}
+</project_context>
+
+If PROJECT_CONTEXT is empty (no context files found), omit the <project_context> block entirely -- agents receive the same prompt as before this feature was added.
+
 **Agent 1A: Correctness and Security**
 
 Review REVIEW_DIFF for:
@@ -57,6 +126,7 @@ Review REVIEW_DIFF for:
 - Auth bypass, missing authorization checks
 - Secret exposure (hardcoded keys, tokens, passwords)
 - Race conditions, deadlocks
+- Violations of domain-specific rules from PROJECT_CONTEXT (if provided): architecture constraints, module boundary contracts, security policies declared in project docs
 - Memory leaks, resource cleanup
 
 Output: Structured findings list with fields:
@@ -81,7 +151,7 @@ Review REVIEW_DIFF against the plan's `<context>` file patterns for:
 - Type safety (any usage, missing types, loose generics)
 - Consistency with existing codebase patterns
 
-If a codebase/ map exists at ${project_root}/codebase/, reference CONVENTIONS.md for established patterns.
+Reference the project conventions and patterns from PROJECT_CONTEXT (if provided) when evaluating naming, import patterns, error handling, and code organization. Flag deviations from the project's established conventions documented in PROJECT_CONTEXT.
 
 Output: Structured findings list with fields:
 - id: "1B-{N}"
@@ -113,6 +183,14 @@ Output: Structured findings list with fields:
 
 Each agent receives REVIEW_DIFF, CHANGED_FILES, and all Pass 1 findings as input context.
 
+If PROJECT_CONTEXT is non-empty, also provide it to each agent wrapped in tags:
+
+<project_context>
+{PROJECT_CONTEXT}
+</project_context>
+
+If PROJECT_CONTEXT is empty (no context files found), omit the <project_context> block entirely -- agents receive the same prompt as before this feature was added.
+
 **Agent 2A: Fix Verification**
 
 For each auto-fixable finding from Pass 1 (severity medium or low with a clear fix), propose a concrete code change.
@@ -174,6 +252,14 @@ Output: Structured findings list with fields:
 
 Each agent receives REVIEW_DIFF, CHANGED_FILES, and all findings from Pass 1 and Pass 2 as input context.
 
+If PROJECT_CONTEXT is non-empty, also provide it to each agent wrapped in tags:
+
+<project_context>
+{PROJECT_CONTEXT}
+</project_context>
+
+If PROJECT_CONTEXT is empty (no context files found), omit the <project_context> block entirely -- agents receive the same prompt as before this feature was added.
+
 **Agent 3A: Fresh Eyes**
 
 Re-read REVIEW_DIFF without bias from prior findings. Identify anything missed by the previous 6 agents. Focus on:
@@ -181,6 +267,7 @@ Re-read REVIEW_DIFF without bias from prior findings. Identify anything missed b
 - Edge cases in business logic
 - Assumptions that may not hold in production
 - Missing error messages or unhelpful error messages
+- Violations of design principles stated in PROJECT_CONTEXT (if provided) that previous agents may have missed — compare implementation choices against documented principles and architectural decisions
 
 Output: Net-new findings only (deduplicated against all prior findings). Use fields:
 - id: "3A-{N}"
@@ -367,8 +454,8 @@ Take the proposed fixes from Agent 2A.
 4. Stage all successful fixes and commit:
 
 ```bash
-git add [fixed files]
-git commit -m "fix(${PHASE}-${PLAN}): codereview auto-fixes
+git -C "${CODE_REPO_PATH}" add [fixed files]
+git -C "${CODE_REPO_PATH}" commit -m "fix(${PHASE}-${PLAN}): codereview auto-fixes
 
 - [list each fix applied, one per bullet]
 
@@ -409,15 +496,22 @@ No fixes qualified for auto-application (all findings were critical/high severit
 
 Update the frontmatter: set `stats.auto_fixed` to `{FIXES_APPLIED}`.
 
-Include CODEREVIEW.md in the auto-fix commit by adding it to the staged files:
+**Do NOT include CODEREVIEW.md in the auto-fix commit.** CODEREVIEW.md lives in the planning repo under `${PHASE_DIR}`, while the auto-fix commit lives in the code repo. `git -C "${CODE_REPO_PATH}" add ${CODEREVIEW_PATH}` would fail because `${CODEREVIEW_PATH}` is not inside `${CODE_REPO_PATH}`. CODEREVIEW.md will be picked up by the amend-metadata-commit at the bottom of the execute-phase codereview gate (which commits it in the planning repo).
+
+For the auto-fix commit, stage only the code-repo files:
 
-Change the existing `git add [fixed files]` to also include CODEREVIEW.md:
 ```bash
-git add [fixed files] ${CODEREVIEW_PATH}
+git -C "${CODE_REPO_PATH}" add [fixed files]
+git -C "${CODE_REPO_PATH}" commit -m "fix(${PHASE}-${PLAN}): codereview auto-fixes
+
+- [list each fix applied, one per bullet]
+
+Co-Authored-By: Claude Code Review <noreply@anthropic.com>"
 ```
 
 If no auto-fixes were applied (commit skipped), commit CODEREVIEW.md alone:
 ```bash
+# CODEREVIEW.md lives in the planning repo under ${PHASE_DIR}. This commit intentionally runs in the inherited (planning) cwd — do NOT use git -C "${CODE_REPO_PATH}" here.
 git add ${CODEREVIEW_PATH}
 git commit -m "docs(${PHASE}-${PLAN}): codereview report