@pdlc-os/pdlc 0.1.0

package/skills/reflect.md

@@ -0,0 +1,189 @@
+# Retrospective Protocol
+
+## When this skill activates
+
+Activate at the start of the **Reflect sub-phase** of Operation, after the Verify sub-phase is complete and the human has signed off on smoke tests. This skill generates the full retrospective for the completed feature cycle — from Inception through Ship.
+
+Before starting, gather all required inputs:
+- The active episode file: `docs/pdlc/memory/episodes/[episode-id].md`
+- The episode index: `docs/pdlc/memory/episodes/index.md`
+- The PRD: `docs/pdlc/prds/PRD_[feature-name]_[YYYY-MM-DD].md`
+- All review files generated during Construction: `docs/pdlc/reviews/REVIEW_[task-id]_[YYYY-MM-DD].md`
+- `docs/pdlc/memory/STATE.md` — for guardrail event log and loop-breaker escalation count
+- `docs/pdlc/memory/DECISIONS.md` — for any tech debt deferred this cycle
+
+---
+
+## Protocol
+
+### Step 1 — Per-agent contributions
+
+List every agent that participated in this feature cycle. For each agent, record:
+- Their role name and display name (e.g. "Neo — Architect")
+- What they contributed: specific tasks, findings surfaced, decisions influenced
+- Any notable findings they raised (e.g. a Phantom security finding that led to a code change, an Echo coverage gap that revealed a missing test)
+
+Pull this information from: the review files, the episode file, STATE.md history, and the Beads task records (`bd show [task-id]` for each completed task).
+
+Agents to check: Neo, Echo, Phantom, Jarvis (always-on), plus any auto-selected agents (Bolt, Friday, Muse, Oracle, Pulse) that participated based on task labels.
+
+### Step 2 — Shipping streak
+
+1. Read `docs/pdlc/memory/episodes/index.md`.
+2. Count consecutive successfully delivered features ending with the current episode (i.e. episodes where the Ship sub-phase completed without a rollback or abandon).
+3. A streak is broken by: a rollback, an explicitly abandoned feature, or a feature that did not reach Ship.
+4. Record the current streak count.
+
+Display format: "Shipping streak: X consecutive features delivered"
+
+### Step 3 — Metrics snapshot
+
+Collect the following metrics from the episode file, review files, and STATE.md:
+
+**Test pass rate by layer:**
+Read from the Test Summary in the episode file. For each layer, record: passed / total. Compute pass rate percentage.
+
+**Cycle time:**
+- Start date: the date the Inception phase began for this feature (read from the PRD file date or STATE.md history)
+- End date: the date the Ship sub-phase completed (today's date or the Ship timestamp in STATE.md)
+- Cycle time = end date − start date, in calendar days
+
+**Review rounds:**
+Count the number of times the Review sub-phase was run for this feature (i.e. how many times a review file was written or regenerated). Read from the review files — check multiple files for the same task-id if they exist.
+
+**Guardrail triggers by tier:**
+Read `docs/pdlc/memory/STATE.md` for logged guardrail events.
+- Tier 1 events: hard blocks that required double-RED confirmation
+- Tier 2 events: pause-and-confirm events
+- Tier 3 events: logged warnings (skipped layers, accepted warnings, overrides)
+- Count each tier separately.
+
+**Loop-breaker escalations:**
+Count the number of times the 3-attempt auto-fix limit was hit and the human was asked to intervene. Read from STATE.md and the episode file.
+
+### Step 4 — What went well
+
+Write 3–5 bullet points drawn from the episode's actual history. Be specific — reference actual events, not generic platitudes.
+
+Inputs to draw from:
+- Beads tasks completed without blockers or loop-breakers → "Task [X] was implemented cleanly in one TDD cycle"
+- Review findings that led to measurable improvements → "Phantom surfaced an injection risk in [module] that was fixed before ship"
+- Test layers that caught regressions early → "Integration tests caught a broken contract between [service A] and [service B]"
+- A smooth human approval gate → "PRD and design docs approved in one round without revisions"
+- CI/CD or tooling that worked well → "Playwright E2E suite ran against Chromium with zero flakes"
+
+### Step 5 — What broke or was harder than expected
+
+Write 3–5 bullet points. Be specific and honest. Reference actual incidents from the episode.
+
+Inputs to draw from:
+- Loop-breaker escalations (3-attempt limit hits) → what the root cause turned out to be
+- Approval rounds that required multiple revisions → what caused the back-and-forth
+- Test layers that had failures → what the failures were
+- Guardrail Tier 1 or Tier 2 events → what triggered them and how they were resolved
+- Merge conflicts or CI/CD failures during Ship
+- Scope that expanded beyond the PRD → what crept in and why
+
+### Step 6 — What to improve next time
+
+Write 2–3 actionable improvement suggestions. These must be concrete and implementable in the next cycle.
+
+Each suggestion should follow the format:
+- **What**: the specific change to make
+- **Why**: what problem it solves (trace back to this cycle's friction)
+- **How**: a concrete first step to implement it
+
+Examples of the kind of specificity required:
+- "Add a perf benchmark for [endpoint] to the E2E suite before next iteration, so Layer 4 has automated coverage rather than manual timing"
+- "Pre-populate the CONSTITUTION.md test gates section during Init — it was left blank this cycle, which caused ambiguity during the Test sub-phase"
+- "Establish a baseline visual regression screenshot set before the next frontend task, to make Layer 6 actionable rather than advisory"
+
+### Step 7 — Tech debt log
+
+Read `docs/pdlc/memory/DECISIONS.md` for any tech debt deferred during this cycle. Also check review files for findings marked "Defer to tech debt."
+
+For each item:
+- Name the component or module affected
+- Describe the debt (what was cut, why it was deferred)
+- Propose a concrete remediation approach and a suggested future episode to address it
+
+If no tech debt was introduced this cycle, state that explicitly: "No tech debt introduced this cycle."
+
+### Step 8 — Write the retrospective into the episode file
+
+Append the retrospective to the active episode file at `docs/pdlc/memory/episodes/[episode-id].md` under a "Reflect Notes" section.
+
+The section must contain all seven elements from Steps 1–7:
+- Per-agent contributions
+- Shipping streak
+- Metrics snapshot
+- What went well
+- What broke / was harder than expected
+- What to improve next time
+- Tech debt log
+
+### Step 9 — Update OVERVIEW.md
+
+Read `docs/pdlc/memory/OVERVIEW.md`. This is the aggregated view of all functionality delivered across every iteration.
+
+Add an entry for this feature cycle:
+- Feature name and episode ID
+- What was built (2–3 sentence summary)
+- Key decisions made
+- Version tag shipped (v[X.Y.Z])
+- Links to the episode file and PRD
+
+Do not overwrite previous entries. Append only.
+
+### Step 10 — Present for human approval
+
+Present the human with:
+1. The path to the updated episode file: `docs/pdlc/memory/episodes/[episode-id].md`
+2. The path to the updated OVERVIEW.md: `docs/pdlc/memory/OVERVIEW.md`
+3. A brief summary: shipping streak, cycle time, total tests passed, and the top "what to improve" item.
+
+State: "Retrospective complete. Please review the episode file and OVERVIEW.md. Approve to close the episode and commit the final state."
+
+Wait for human approval. Do not commit until the human approves.
+
+### Step 11 — Commit and close
+
+After human approval:
+
+1. Stage and commit the episode file and OVERVIEW.md:
+```bash
+git add docs/pdlc/memory/episodes/[episode-id].md
+git add docs/pdlc/memory/OVERVIEW.md
+git commit -m "reflect: [feature-name] episode [episode-id] retrospective"
+```
+
+2. Push to main.
+
+3. Update `docs/pdlc/memory/STATE.md`:
+   - Phase: Initialization (ready for next `/pdlc brainstorm`)
+   - Last completed episode: [episode-id]
+   - Active feature: none
+
+4. Report to human: "Episode [episode-id] closed. Ready for the next feature. Run `/pdlc brainstorm` to begin."
+
+---
+
+## Rules
+
+- The retrospective must be grounded in actual events from the episode — not generic observations. Every bullet point in "what went well" and "what broke" must be traceable to a specific event in the episode file, review files, or STATE.md.
+- Shipping streak must be calculated from the full episode index, not estimated.
+- Cycle time is calculated from Inception start to Ship completion — not from the first commit.
+- Tech debt must be explicitly stated as either present (with specifics) or absent ("no tech debt introduced this cycle"). Silence is not acceptable.
+- Do not commit the retrospective without explicit human approval.
+- OVERVIEW.md is append-only. Never modify or remove previous entries.
+- Improvement suggestions must be actionable: no "communicate better" or "be more careful." Each suggestion needs a concrete first step.
+
+---
+
+## Output
+
+- "Reflect Notes" section appended to `docs/pdlc/memory/episodes/[episode-id].md` covering all seven elements.
+- `docs/pdlc/memory/OVERVIEW.md` updated with a new entry for this feature cycle.
+- Episode file and OVERVIEW.md committed to main after human approval.
+- `docs/pdlc/memory/STATE.md` updated: phase reset to Initialization, active feature cleared.
+- Human informed the feature cycle is closed and the system is ready for the next `/pdlc brainstorm`.

package/skills/repo-scan.md

@@ -0,0 +1,266 @@
+# Repo Scan — Brownfield Initialization
+
+## When this skill activates
+
+During `/pdlc init` when the repository contains existing source code (brownfield project). The goal is to deeply review the existing codebase and produce pre-populated drafts of all memory bank files, so initialization reflects reality rather than starting from blank templates.
+
+---
+
+## Protocol
+
+Execute every step below in order. Do not skip any step. Collect all findings before writing any memory files.
+
+---
+
+### Step 1 — Map the repository structure
+
+Run the following to understand the top-level layout:
+
+```bash
+git ls-files | head -200
+```
+
+Also run:
+```bash
+find . -maxdepth 3 \
+  -not -path './.git/*' \
+  -not -path './node_modules/*' \
+  -not -path './.beads/*' \
+  -not -path './docs/pdlc/*' \
+  -not -name '.DS_Store' \
+  | sort
+```
+
+From this output, identify:
+- Primary language(s) (file extensions)
+- Framework indicators (`package.json`, `Gemfile`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `pom.xml`, etc.)
+- Entry points (`main.*`, `index.*`, `app.*`, `server.*`, `cmd/`)
+- Test directories (`__tests__/`, `spec/`, `test/`, `tests/`, `*.test.*`, `*.spec.*`)
+- Config files (`.env.example`, `docker-compose.yml`, `Dockerfile`, CI/CD configs)
+- Existing documentation (`README*`, `docs/` excluding `docs/pdlc/`)
+
+---
+
+### Step 2 — Read key manifest and config files
+
+Read every file from this list that exists:
+
+- `package.json` / `package-lock.json` — for Node.js projects
+- `Gemfile` — for Ruby projects
+- `pyproject.toml` / `requirements.txt` / `setup.py` — for Python projects
+- `go.mod` — for Go projects
+- `Cargo.toml` — for Rust projects
+- `pom.xml` / `build.gradle` — for Java/Kotlin projects
+- `docker-compose.yml` / `Dockerfile` — for containerised stacks
+- `.github/workflows/*.yml` — for CI/CD pipelines
+- `README.md` / `README.rst` / `README.txt` — for existing documentation
+- `.env.example` — for environment variable hints
+- Any existing `ARCHITECTURE.md`, `CONTRIBUTING.md`, `DECISIONS.md`, or `ADR/` directory
+
+Extract from these files:
+- **Tech stack**: languages, frameworks, databases, cloud providers, key libraries
+- **Scripts**: what `test`, `build`, `start`, `deploy` commands exist
+- **Dependencies**: categorise into frontend, backend, testing, dev tools
+- **Environment variables**: what external services are configured
+- **CI/CD pipeline**: what stages run on merge/push
+
+---
+
+### Step 3 — Read entry points and core source files
+
+Identify and read (or skim) up to 10 of the most important source files. Priority order:
+
+1. Main entry point (`index.js`, `main.py`, `app.rb`, `main.go`, `src/main.*`, etc.)
+2. Router or route definitions (`routes/`, `router.*`, `urls.py`, `routes.rb`)
+3. Core models or data layer (`models/`, `schema.*`, `prisma/schema.prisma`, `db/schema.rb`)
+4. Primary controllers or handlers (`controllers/`, `handlers/`, `views/`, `resolvers/`)
+5. Auth layer if present (`auth.*`, `middleware/auth.*`, `lib/auth/`)
+6. Existing API contract files (`openapi.yaml`, `swagger.json`, `graphql/schema.graphql`)
+
+From these files, identify:
+- **Core features**: what the application already does (be specific — list each distinct feature)
+- **Data model**: main entities and their relationships
+- **API surface**: existing endpoints or mutations
+- **Business logic patterns**: where decisions are made, how data flows
+- **Architectural style**: MVC, hexagonal, serverless functions, monolith, microservices
+
+---
+
+### Step 4 — Read existing tests
+
+Find and skim up to 10 test files across different test types:
+
+```bash
+git ls-files | grep -E '\.(test|spec)\.' | head -20
+git ls-files | grep -E '^(test|tests|spec|__tests__)/' | head -20
+```
+
+From test files, identify:
+- What features are already covered by tests
+- What testing libraries / frameworks are used
+- Approximate test coverage (many tests = good coverage, few = sparse)
+- Whether tests are unit, integration, or E2E style
+- Any test conventions (naming, file co-location, fixtures)
+
+---
+
+### Step 5 — Read git history
+
+Run the following to understand the project's timeline:
+
+```bash
+git log --oneline --no-merges -50
+```
+
+Also run:
+```bash
+git log --format="%ai %s" --no-merges -20
+```
+
+From the git log, identify:
+- When the project started (first commit date)
+- The main feature areas worked on (infer from commit messages)
+- Recent areas of activity (last 10 commits)
+- Any architectural pivots (e.g. "migrate to X", "replace Y with Z", "rewrite")
+- Recurring contributors (for the team context)
+
+---
+
+### Step 6 — Synthesise findings
+
+Before writing any file, compose a structured internal summary with these sections. You will use this summary to write all memory files:
+
+```
+REPO SCAN SUMMARY
+=================
+
+PROJECT
+  Name: [inferred from package.json/README/directory name]
+  Description: [1–2 sentence description of what it does]
+  Started: [date of first commit]
+  Primary language: [language]
+  Tech stack: [framework + DB + infra]
+
+EXISTING FEATURES (list each concrete feature the app currently has)
+  1. [Feature name] — [1-sentence description]
+  2. ...
+
+DATA MODEL (main entities)
+  - [Entity]: [fields / relationships in plain English]
+  - ...
+
+API SURFACE (if applicable)
+  - [METHOD /path] — [what it does]
+  - ...
+
+ARCHITECTURAL PATTERNS
+  - [Pattern observed, e.g. "MVC via Rails conventions", "Service objects for business logic"]
+
+TEST COVERAGE
+  - Frameworks: [list]
+  - Covered: [features with tests]
+  - Gaps: [features with little or no test coverage]
+
+CI/CD
+  - [What pipeline stages exist, what triggers them]
+
+KEY DECISIONS (inferred from code and git history)
+  1. [Decision inferred, e.g. "Chose PostgreSQL over MongoDB — evidenced by ActiveRecord schemas"]
+  2. ...
+
+TECH DEBT SIGNALS (code patterns suggesting debt)
+  - [e.g. "TODO/FIXME comments found in N files", "No tests for auth module", "Deprecated dep X"]
+
+RECENT ACTIVITY (last 10 commits summary)
+  - [Area of focus, date range]
+```
+
+Print this summary to the user before proceeding, and ask: **"Does this look accurate? Any corrections before I generate the memory files?"** Wait for the user's response. Incorporate any corrections.
+
+---
+
+### Step 7 — Generate memory files from scan findings
+
+Use the verified summary to write pre-populated versions of all memory files. Do not use blank template stubs — fill in real content wherever the scan produced findings.
+
+#### `CONSTITUTION.md`
+
+- **Tech Stack table**: fill in actual stack from scan
+- **Architectural Constraints**: list observed patterns as constraints (e.g. "Service layer separates business logic from controllers — maintain this separation")
+- **Coding Standards**: infer from code (e.g. linter config, consistent naming patterns found)
+- **Test Gates**: check layers that already have tests; suggest enabling them
+- Leave other sections as instructed defaults
+
+#### `INTENT.md`
+
+- **Project name**: from scan
+- **Problem statement**: infer from README + features list. Write 2–4 sentences describing what problem the app solves
+- **Target user**: infer from README or feature names. Mark clearly as "(inferred — please verify)"
+- **Core value proposition**: draft from features and problem statement. Mark as "(inferred)"
+- Leave success metrics and out-of-scope as placeholders — these need human input
+
+#### `OVERVIEW.md`
+
+This is the most important file to populate thoroughly:
+
+- **Project Summary**: 2–3 sentences about what the app does today
+- **Active Functionality**: list every feature identified in Step 3 as a bullet point with a 1-sentence description
+- **Architecture Summary**: describe the architectural style and key layers from Step 3
+- **Known Tech Debt**: list all tech debt signals from Step 6
+- **Shipped Features table**: leave empty (no PDLC episodes yet, but note "Pre-PDLC functionality documented above")
+
+#### `DECISIONS.md`
+
+- Record each key decision from Step 6 as a lightweight ADR entry:
+
+```markdown
+## ADR-001 — [Decision title] *(pre-PDLC, inferred)*
+
+**Date:** [inferred from git log or "unknown"]
+**Status:** Accepted
+
+**Decision:** [What was decided]
+
+**Context:** [Why this decision makes sense given the codebase]
+
+**Inferred from:** [git log / package.json / schema file / etc.]
+
+---
+```
+
+Mark all pre-PDLC entries as `*(pre-PDLC, inferred)*` so the team knows these were reverse-engineered.
+
+#### `CHANGELOG.md`
+
+- Add a single entry for the pre-PDLC state:
+
+```markdown
+## Pre-PDLC baseline — [first commit date] to [today]
+
+### Existing functionality
+[List the features from the scan as bullet points under "Added"]
+
+*Note: This entry documents the state of the repository before PDLC was introduced.
+       Future entries will be generated by Jarvis during each Ship sub-phase.*
+```
+
+#### `ROADMAP.md` and `STATE.md`
+
+- Populate with project name but leave feature planning sections as stubs
+- Set STATE.md to `Initialization Complete — Ready for /pdlc brainstorm`
+
+---
+
+## Rules
+
+- **Never invent functionality** that isn't evidenced in the code, README, or git history. If you're uncertain, mark findings with "(inferred — please verify)".
+- **Prefer specificity over generality**. "User authentication with JWT via Devise" is better than "authentication exists".
+- **Respect existing conventions**. If the codebase uses a specific naming convention or architecture, document it in CONSTITUTION.md as a constraint to preserve.
+- **Flag gaps explicitly**. If a feature exists but has no tests, say so. If there's no README, say so. If the git history is sparse, say so.
+- **Mark all inferred content clearly** so the team can verify and correct.
+
+---
+
+## Output
+
+Seven fully populated memory files under `docs/pdlc/memory/`, derived from real codebase analysis rather than blank templates.

package/skills/review.md

@@ -0,0 +1,156 @@
+# Multi-Agent Code Review
+
+## When this skill activates
+
+Activate at the start of the **Review sub-phase** of Construction, immediately after all tests for the active Beads task have passed. Do not run review before tests pass — this is a hard ordering constraint.
+
+This skill governs one full review cycle per task. If the human requests revisions after reading the review file, re-run only the affected reviewer domains (or all, if the change is broad), regenerate the review file, and re-present for approval.
+
+---
+
+## Protocol
+
+### Step 1 — Establish context
+
+Before any reviewer begins, load the following into context:
+
+1. The active Beads task: `bd show [task-id]` — read title, description, acceptance criteria.
+2. The PRD: `docs/pdlc/prds/PRD_[feature-name]_[YYYY-MM-DD].md` — check requirements, BDD stories, non-functional requirements, out-of-scope list.
+3. `docs/pdlc/memory/CONSTITUTION.md` — rules, standards, definition of done.
+4. `docs/pdlc/memory/DECISIONS.md` — architectural decisions already made; any deviation is a finding.
+5. The design docs at `docs/pdlc/design/[feature-name]/` — ARCHITECTURE.md, data-model.md, api-contracts.md.
+6. The full diff of all files changed in this task on the feature branch.
+
+### Step 2 — Independent reviewer passes
+
+Each reviewer operates independently within their domain. They do not wait for others. Run all four in parallel where possible. Each reviewer produces a list of findings — each finding has a title, description, affected file/line, and a severity note (Advisory / Recommended / Important — all are soft warnings; none are hard blocks).
+
+**Neo — Architecture & PRD conformance**
+
+Neo checks:
+- Does the implementation match the architecture described in `docs/pdlc/design/[feature-name]/ARCHITECTURE.md`? Flag any divergence.
+- Does the code implement what the PRD requires, and only what the PRD requires? Flag scope creep or missing requirements.
+- Are any decisions recorded in `docs/pdlc/memory/DECISIONS.md` being violated or ignored?
+- Is new tech debt being introduced? If so, is it intentional and documented?
+- Are cross-cutting concerns (logging, error handling, config, auth) handled consistently with the rest of the codebase?
+- Are module boundaries respected? Does new code reach across layers it should not?
+
+**Phantom — Security**
+
+Phantom checks against the OWASP Top 10 and general security hygiene:
+- Injection: Is all user input validated and sanitized before use in queries, shell commands, or rendered output?
+- Broken authentication: Are auth tokens validated correctly? Are session fixation, replay, and privilege escalation risks addressed?
+- Sensitive data exposure: Are secrets, tokens, or PII exposed in logs, error messages, or API responses?
+- Security misconfiguration: Are default credentials used? Are error pages leaking stack traces?
+- Broken access control: Does the code enforce authorization at every access point, not just at the route level?
+- Trust boundaries: Is data from external sources treated as untrusted until validated?
+- Dependency risk: Are any new packages introduced that have known CVEs or unusual permissions?
+- Are there any hardcoded secrets, API keys, or credentials anywhere in the diff?
+
+**Echo — Test coverage & quality**
+
+Echo checks:
+- Does every acceptance criterion from the Beads task have at least one test?
+- Are the Given/When/Then test names traceable to specific PRD user stories?
+- Are edge cases covered: empty inputs, null values, boundary conditions, concurrent access, network failures?
+- Are integration boundaries tested (not just mocked at every layer)?
+- What is the regression risk? Have changes to shared utilities, base classes, or middleware been tested for downstream effects?
+- Are there tests that are structurally present but not actually asserting meaningful behavior (i.e. tests that always pass regardless of implementation)?
+
+**Jarvis — Documentation & API contracts**
+
+Jarvis checks:
+- Are all new public functions, methods, components, and APIs documented with inline comments or JSDoc/docstrings?
+- If an API endpoint was added or changed: is `docs/pdlc/design/[feature-name]/api-contracts.md` up to date?
+- Is the CHANGELOG entry for this task ready to be written? (Jarvis prepares a draft entry.)
+- Are README or setup instructions impacted by this change? If so, are they updated?
+- Are type signatures, return values, and error states documented accurately?
+
+### Step 3 — Consolidate findings
+
+After all four reviewers complete their passes:
+
+1. Collect all findings into a single list.
+2. Group by reviewer (Neo / Phantom / Echo / Jarvis).
+3. Within each group, order by severity: Important → Recommended → Advisory.
+4. Include the builder agent(s) who implemented the task as a named participant. They do not generate separate findings but are listed as contributors for traceability.
+
+### Step 4 — Write the review file
+
+Write the review file to:
+```
+docs/pdlc/reviews/REVIEW_[task-id]_[YYYY-MM-DD].md
+```
+
+The file must contain:
+
+```
+# Review: [task-id] — [task title]
+Date: [YYYY-MM-DD]
+Feature: [feature-name]
+Reviewers: Neo, Phantom, Echo, Jarvis + [builder agent name(s)]
+
+## Summary
+[2–4 sentence summary of overall code quality and readiness]
+
+## Neo — Architecture & PRD Conformance
+[Findings, or "No findings."]
+
+## Phantom — Security
+[Findings, or "No findings."]
+
+## Echo — Test Coverage & Quality
+[Findings, or "No findings."]
+
+## Jarvis — Documentation & API Contracts
+[Findings, or "No findings." + draft CHANGELOG entry]
+
+## Consolidated Finding Count
+Important: X | Recommended: Y | Advisory: Z
+
+## Human Decision Required
+For each Important or Recommended finding, list:
+- Finding title
+- Proposed resolution
+- Options: [ ] Fix now  [ ] Accept and move on  [ ] Defer to tech debt
+```
+
+### Step 5 — Human approval gate
+
+Present the review file path to the human. State: "Review complete. Please read `docs/pdlc/reviews/REVIEW_[task-id]_[YYYY-MM-DD].md` and approve, or request changes."
+
+Wait. Do not proceed to the Test sub-phase or push PR comments until the human explicitly approves.
+
+If the human requests changes: address them, regenerate the review file, and re-present.
+
+### Step 6 — Post approval actions
+
+After human approval:
+
+1. If GitHub integration is active: push findings as PR comments via the GitHub integration. Only push findings the human has not marked "Accept and move on."
+2. For any finding marked "Defer to tech debt": add an entry to `docs/pdlc/memory/DECISIONS.md` under a "Tech Debt" section with the finding, the rationale for deferral, and a suggested remediation approach.
+3. Update `docs/pdlc/memory/STATE.md`: mark review as approved for this task.
+4. Proceed to the Test sub-phase.
+
+---
+
+## Rules
+
+- Review runs only after all tests pass. Never before.
+- All findings are soft warnings. No finding hard-blocks the build. Human decides: fix, accept, or defer.
+- Human must approve the review file before PR comments are pushed. Never push PR comments automatically without approval.
+- Severity labels — Important, Recommended, Advisory — are not severity scores for automation. They are signals to the human to help prioritize decisions.
+- The builder agent(s) are always listed in the review file as participants. This is for traceability, not blame.
+- Phantom security findings marked "Accept" must be logged as Tier 3 guardrail events in `docs/pdlc/memory/STATE.md`.
+- Echo test coverage gaps marked "Accept" must also be logged as Tier 3 guardrail events in `docs/pdlc/memory/STATE.md`.
+- Do not re-run the full review cycle for trivial fixes (e.g. a variable rename). Use judgment: re-run only the affected reviewer domain(s) when the human requests a change.
+
+---
+
+## Output
+
+- `docs/pdlc/reviews/REVIEW_[task-id]_[YYYY-MM-DD].md` — the full review file, approved by human.
+- PR comments pushed (if GitHub integration active) for non-accepted findings.
+- Any deferred tech debt recorded in `docs/pdlc/memory/DECISIONS.md`.
+- `docs/pdlc/memory/STATE.md` updated to reflect review approval.
+- Task ready to proceed to the Test sub-phase.