@pdlc-os/pdlc 0.1.0

package/.claude/commands/ship.md

@@ -0,0 +1,349 @@
+---
+description: Run the Operation phase (Ship → Verify → Reflect) for the current feature
+---
+
+You are running the Operation phase. Follow every step in order. Do not skip steps.
+
+---
+
+## Pre-flight: Load state and context
+
+### Step 1 — Read STATE.md
+
+Read `docs/pdlc/memory/STATE.md` completely.
+
+Extract:
+- **Current Phase**: must be `Construction Complete — Ready for /pdlc ship`
+- **Current Feature**: the `[feature-name]` slug
+- **Episode file path**: look in `docs/pdlc/memory/episodes/` for a draft file matching `[NNN]_[feature-name]_[YYYY-MM-DD].md`
+
+If the phase is not `Construction Complete — Ready for /pdlc ship`, warn the user:
+
+> "STATE.md shows the current phase is `[phase]`, not `Construction Complete`. Running `/pdlc ship` before Construction is complete may cause issues.
+>
+> Continue anyway? (yes/no)"
+
+Wait for confirmation before proceeding.
+
+### Step 2 — Verify test gates
+
+Read `docs/pdlc/memory/CONSTITUTION.md` §7 (Test Gates).
+
+Read the episode file draft at `docs/pdlc/memory/episodes/[NNN]_[feature-name]_[YYYY-MM-DD].md`.
+
+Check the Test Summary table in the episode file against the required gates in CONSTITUTION.md.
+
+If any required gate shows `fail` in the episode file, warn the user:
+
+> "Required test gate `[layer]` shows as failed in the episode file. Shipping with failing required gates is a Tier 3 logged warning.
+>
+> Proceed anyway? (yes/no)"
+
+Log the response in STATE.md as a Tier 3 event if the user proceeds with a failed gate.
+
+Update `docs/pdlc/memory/STATE.md`:
+- **Current Phase**: `Operation`
+- **Current Sub-phase**: `Ship`
+- **Last Checkpoint**: `Operation / Ship / [now ISO 8601]`
+
+---
+
+## SHIP
+
+### Step 3 — Merge approval gate
+
+Tell the user:
+
+> "Ready to merge and deploy `[feature-name]` to main.
+>
+> Feature branch: `feature/[feature-name]`
+> Episode: `[NNN]_[feature-name]_[YYYY-MM-DD].md`
+>
+> **Confirm merge commit to main?** (yes/no)"
+
+Wait for explicit `yes`. Do not merge without it.
+
+If the user says `no`: stop and tell them to resolve whatever is blocking before re-running `/pdlc ship`.
+
+### Step 4 — Merge to main
+
+Switch to main and merge:
+```bash
+git checkout main
+git merge --no-ff feature/[feature-name] -m "feat([feature-name]): [one-line feature description from the PRD Overview section]"
+```
+
+**TIER 1 HARD BLOCK**: Do not force-push to main under any circumstances. If a merge conflict arises, stop and tell the user:
+
+> "Merge conflict detected. Please resolve the conflicts manually, then re-run `/pdlc ship`."
+
+### Step 5 — Generate release notes and CHANGELOG entry
+
+Jarvis role: read all commits on the feature branch since it diverged from main:
+```bash
+git log main..[feature branch before merge] --oneline
+```
+
+Generate a CHANGELOG entry in Conventional Changelog format. Draft it as:
+
+```markdown
+## v[X.Y.Z] — [today's date]
+
+### Added
+- [bullet for each new feature or capability]
+
+### Changed
+- [bullet for each modified behavior]
+
+### Fixed
+- [bullet for each bug fixed, if any]
+
+### Breaking Changes
+- [only if applicable — feature or API that is not backward compatible]
+```
+
+Prepend this entry to `docs/pdlc/memory/CHANGELOG.md`.
+
+### Step 6 — Determine semantic version
+
+Read the current latest tag:
+```bash
+git describe --tags --abbrev=0
+```
+
+If no tags exist, the next version is `v0.1.0`.
+
+Analyze the commits on the feature branch:
+- Any commit message contains `BREAKING CHANGE` or a `!` after the type (e.g. `feat(api)!:`) → **major** bump
+- Any commit message starts with `feat` → **minor** bump
+- All commits are `fix`, `docs`, `chore`, `test`, `refactor`, `perf`, or `ci` only → **patch** bump
+
+If the bump type is ambiguous (e.g. mix of `feat` and `fix` with no breaking changes), default to **minor**.
+
+If you are unsure, ask the user:
+
+> "Commits on this branch include features and fixes. Is this a **minor** release (new feature, backward-compatible) or a **patch** release (fixes only)? Type `minor` or `patch`:"
+
+Increment the version accordingly. Example: `v1.2.3` → minor bump → `v1.3.0`.
+
+### Step 7 — Tag the commit
+
+```bash
+git tag v[X.Y.Z] -m "[feature-name] — [one-line description from PRD Overview]"
+```
+
+### Step 8 — Push to origin
+
+```bash
+git push origin main
+git push origin v[X.Y.Z]
+```
+
+**TIER 1 HARD BLOCK**: Do not use `--force` on `git push origin main`. If the push is rejected (non-fast-forward), stop and tell the user:
+
+> "Push rejected — main has diverged. Please pull and resolve manually:
+> `git pull --rebase origin main`
+> Then re-run `/pdlc ship`."
+
+Do not attempt to force-push.
+
+### Step 9 — Trigger CI/CD (Pulse coordinates)
+
+Pulse role: detect the CI/CD setup in this order:
+
+1. Check for `npm run deploy` in `package.json` → if found, run `npm run deploy`
+2. Check for `make deploy` in `Makefile` → if found, run `make deploy`
+3. Check for `.github/workflows/` → if deploy workflows exist, trigger via:
+   ```bash
+   gh workflow run [workflow-filename] --ref main
+   ```
+   (requires GitHub CLI `gh` to be authenticated)
+4. If none of the above are found, tell the user:
+   > "No CI/CD deployment command detected. Please trigger your deployment manually and confirm when the deployment is complete."
+   > Wait for user confirmation before proceeding to Verify.
+
+Update `docs/pdlc/memory/STATE.md`:
+- **Current Sub-phase**: `Verify`
+- **Last Checkpoint**: `Operation / Verify / [now ISO 8601]`
+
+---
+
+## VERIFY
+
+### Step 10 — Get the deployment URL
+
+Check `docs/pdlc/memory/CONSTITUTION.md` for a deployment URL (look in §1 Hosting/Deploy row or §9 Additional Rules).
+
+If not found, ask the user:
+
+> "What is the URL of the deployed environment? (e.g. `https://your-app.fly.dev`)"
+
+Store as `[deploy-url]`.
+
+### Step 11 — Run smoke tests
+
+Run basic health checks against `[deploy-url]`:
+
+**11a. HTTP health check:**
+Fetch the root URL and key routes. Check for HTTP 200 responses. Run:
+```bash
+curl -s -o /dev/null -w "%{http_code}" [deploy-url]
+curl -s -o /dev/null -w "%{http_code}" [deploy-url]/[key-route-from-PRD]
+```
+
+Report the results. Flag any non-200 response.
+
+**11b. Critical user journey:**
+Read the PRD at `docs/pdlc/prds/PRD_[feature-name]_[YYYY-MM-DD].md`. Identify the primary acceptance criterion (AC-1).
+
+Describe the manual steps the user should take to verify the primary user journey works in production. Example:
+
+> "Please verify AC-1 manually: [Given/When/Then steps from the BDD user story]. Confirm the behavior matches the acceptance criterion."
+
+Wait for the user to perform the check and report back.
+
+**11c. Auth flow (if applicable):**
+If the feature includes authentication (check PRD and design docs for `auth`, `login`, `OAuth`), ask the user to verify the auth flow works end-to-end in the deployed environment.
+
+### Step 12 — Smoke test approval gate
+
+Present a summary of smoke test results:
+
+> "Smoke test results:
+>
+> - HTTP health check: [pass/fail — [N] routes checked]
+> - Primary user journey (AC-1): [pass/fail — user-reported]
+> - Auth flow: [pass/fail / N/A]
+>
+> **Manual sign-off required. Does the deployment look correct?** (yes/no)"
+
+Wait for explicit `yes`. If the user says `no`: help them diagnose the issue. Do not proceed to Reflect until the user confirms the deployment is good.
+
+Update `docs/pdlc/memory/STATE.md`:
+- **Current Sub-phase**: `Reflect`
+- **Last Checkpoint**: `Operation / Reflect / [now ISO 8601]`
+
+---
+
+## REFLECT
+
+### Step 13 — Generate the retro
+
+Following the gstack-style retrospective approach, generate a Reflect Notes section for the episode file. Cover:
+
+**Per-agent contributions** (list which agents participated and what they contributed):
+- Neo: [architectural work done]
+- Echo: [test strategy and coverage work]
+- Phantom: [security checks performed, issues found/resolved]
+- Jarvis: [docs written, CHANGELOG authored]
+- [Auto-selected agents]: [their contributions]
+
+**What went well:**
+Analyze the Construction phase: tasks completed without issue, tests that passed cleanly, design decisions that worked out, agent collaboration that was effective. List 3–5 specific observations.
+
+**What broke or slowed us down:**
+Review the STATE.md Phase History and episode file: how many auto-fix attempts were needed, which tests failed initially, which review findings required fixing. List 2–4 specific observations.
+
+**What to improve next time:**
+Based on the above, list 2–3 actionable improvements for the next feature cycle.
+
+**Metrics snapshot:**
+- Cycle time: calculate from first Inception entry in Phase History to today's date
+- Test pass rate: calculate from the episode file Test Summary (total passed / total run × 100%)
+- Tasks completed: count from Beads
+- Review findings: count from the review file (Important / Recommended / Advisory)
+
+### Step 14 — Update the episode file
+
+Open `docs/pdlc/memory/episodes/[NNN]_[feature-name]_[YYYY-MM-DD].md`.
+
+Append the Reflect Notes section with all content from Step 13.
+
+Update:
+- **Date delivered**: today's date (the actual merge date)
+- **Status**: keep as `Draft` — it becomes `Approved` after human sign-off below
+- **Links → PR**: fill in the PR link if one was created (check `gh pr list` or ask the user)
+
+### Step 15 — Episode file approval gate
+
+Tell the user:
+
+> "Episode file is complete at `docs/pdlc/memory/episodes/[NNN]_[feature-name]_[YYYY-MM-DD].md`
+>
+> Please review the full episode file — the What Was Built summary, decisions, test results, tech debt, and retro notes.
+>
+> **Approve to commit this episode to the repository?** (approve / request changes)"
+
+Wait for explicit approval. If the user requests changes: make them, re-save the file, and re-present.
+
+When approved: update the **Approval** section in the episode file with the approver's name and today's date. Set **Status** to `Approved`.
+
+### Step 16 — Commit the episode and update memory files
+
+After approval, run these commands sequentially:
+
+**16a. Update the episodes index:**
+
+Append a row to `docs/pdlc/memory/episodes/index.md`:
+```
+| [NNN] | [Feature Name] | [today's date] | [[NNN]_[feature-name]_[date].md]([NNN]_[feature-name]_[date].md) | [#PR or —] | Shipped |
+```
+
+**16b. Update OVERVIEW.md:**
+
+Read `docs/pdlc/memory/OVERVIEW.md`. Update:
+- **Active Functionality**: add a bullet for the new capability shipped (e.g. "Users can now [feature description]")
+- **Shipped Features table**: add a row for this feature with episode and PR links
+- **Architecture Summary**: update if this feature changed the architecture meaningfully (new service, new DB table, new integration)
+- **Known Tech Debt**: append any tech debt items recorded in the episode file
+- **Last updated**: today's date
+
+**16c. Commit everything:**
+
+```bash
+git add docs/pdlc/memory/episodes/[NNN]_[feature-name]_[YYYY-MM-DD].md
+git add docs/pdlc/memory/episodes/index.md
+git add docs/pdlc/memory/OVERVIEW.md
+git add docs/pdlc/memory/CHANGELOG.md
+git commit -m "docs(pdlc): add episode [NNN] — [feature-name]"
+git push origin main
+```
+
+**TIER 2 action**: this is a direct push to main (not a PR). Since this is a docs-only commit (episode file), it is acceptable — but confirm with the user if their workflow requires a PR even for docs.
+
+### Step 17 — Final STATE.md update
+
+Update `docs/pdlc/memory/STATE.md`:
+- **Current Phase**: `Idle — Ready for next /pdlc brainstorm`
+- **Current Feature**: `none`
+- **Active Beads Task**: `none`
+- **Current Sub-phase**: `none`
+- **Last Checkpoint**: `Operation / Complete / [now ISO 8601]`
+
+Append to Phase History:
+```
+| [now] | operation_complete | Idle | — | none |
+```
+
+### Step 18 — Print completion message
+
+> "[feature-name] shipped. Episode [NNN] committed.
+>
+> - Version: v[X.Y.Z]
+> - Episode: docs/pdlc/memory/episodes/[NNN]_[feature-name]_[YYYY-MM-DD].md
+> - CHANGELOG updated: docs/pdlc/memory/CHANGELOG.md
+> - OVERVIEW updated: docs/pdlc/memory/OVERVIEW.md
+>
+> Ready for the next feature — run `/pdlc brainstorm [next-feature]` to start."
+
+---
+
+## Rules
+
+- Never force-push to `main`. This is a Tier 1 hard block with no override.
+- Never push PR comments or tags without human approval at the ship gate (Step 3).
+- Never proceed to Reflect without human sign-off on smoke tests (Step 12).
+- Never commit the episode file without human approval (Step 15).
+- If the deployment URL is unknown, ask — do not guess or skip smoke tests.
+- The merge strategy is always `--no-ff` (merge commit). Do not squash or rebase feature branches.
+- If any step fails due to an external service (GitHub, CI, deploy target), describe the failure clearly and give the user the manual steps to resolve it. Do not silently skip.

package/.claude/settings.json

@@ -0,0 +1,40 @@
+{
+  "statusLine": {
+    "type": "command",
+    "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/pdlc-statusline.js"
+  },
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/pdlc-context-monitor.js"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/pdlc-guardrails.js"
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/pdlc-session-start.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

package/CLAUDE.md

@@ -0,0 +1,179 @@
+# PDLC — Product Development Lifecycle
+
+You are operating within the PDLC (Product Development Lifecycle) framework, a structured Claude Code plugin designed for small startup teams (2–5 engineers). PDLC guides every feature from raw idea through shipping and retrospective across four phases: Initialization, Inception, Construction, and Operation. The framework combines methodology discipline (TDD, systematic debugging, subagent reviews), specialist agent roles, context-rot prevention, spec-driven execution, and file-based persistent memory. Every session begins by reading `docs/pdlc/memory/STATE.md` to determine where work left off, then resumes automatically from the last checkpoint. All rules, standards, and overrides live in `docs/pdlc/memory/CONSTITUTION.md` — the Constitution always wins.
+
+---
+
+## PDLC Flow Diagram
+
+```mermaid
+flowchart TD
+    START([Session Start]) --> RESUME{docs/pdlc/memory/\nSTATE.md exists?}
+    RESUME -->|No| INIT
+    RESUME -->|Yes| AUTOLOAD[Auto-resume from\nlast checkpoint]
+    AUTOLOAD --> PHASE_CHECK{Current phase?}
+    PHASE_CHECK -->|Inception| INCEPTION
+    PHASE_CHECK -->|Construction| CONSTRUCTION
+    PHASE_CHECK -->|Operation| OPERATION
+
+    %% PHASE 0 — INITIALIZATION
+    INIT["/pdlc init"] --> I1[Setup CONSTITUTION.md\nINTENT.md]
+    I1 --> I2[Create Memory Bank\nROADMAP · DECISIONS\nSTATE · CHANGELOG\nOVERVIEW]
+    I2 --> I3[bd init → .beads/\nin project root]
+    I3 --> I4([Initialization Complete\nReady for /pdlc brainstorm])
+
+    %% PHASE 1 — INCEPTION
+    INCEPTION["/pdlc brainstorm"] --> D1[Start Visual\nCompanion Server]
+    D1 --> D2[DISCOVER\nSocratic questioning\n+ external context ingestion]
+    D2 --> D3[Human approves\nvisual + conversation output]
+    D3 --> D4[DEFINE\nClaude auto-generates\nPRD draft — BDD stories]
+    D4 --> D5{Human approves\nPRD?}
+    D5 -->|Revise| D4
+    D5 -->|Approved| D6[DESIGN\nARCHITECTURE · data-model\napi-contracts — linked from PRD]
+    D6 --> D7{Human approves\ndesign docs?}
+    D7 -->|Revise| D6
+    D7 -->|Approved| D8[PLAN\nCreate Beads tasks with\nepic·story labels + dependencies]
+    D8 --> D9{Human approves\nBeads task list?}
+    D9 -->|Revise| D8
+    D9 -->|Approved| D10[Stop Visual Server\nUpdate docs/pdlc/memory/STATE.md]
+    D10 --> D11([Inception Complete\nReady for /pdlc build])
+
+    %% PHASE 2 — CONSTRUCTION
+    CONSTRUCTION["/pdlc build"] --> C1[bd ready → pick\nhighest-priority task]
+    C1 --> C2[bd update --claim\nUpdate docs/pdlc/memory/STATE.md]
+    C2 --> C3{Execution\nmode?}
+    C3 -->|Agent Teams| C4[Auto-select roles\nNeo·Echo·Phantom·Jarvis\n+ context roles]
+    C3 -->|Sub-Agent| C5[Single focused\nsubagent]
+    C4 & C5 --> C6[BUILD\nTDD enforced:\nfailing tests → implement → pass]
+    C6 --> C7{Tests pass?}
+    C7 -->|Fail — attempt ≤3| C6
+    C7 -->|Fail — attempt 3| C8{Human choice}
+    C8 -->|Continue| C6
+    C8 -->|Intervene| C9[Human suggests\ncourse of action]
+    C9 --> C6
+    C7 -->|Pass| C10[REVIEW\nNeo·Echo·Phantom·Jarvis\n+ builder]
+    C10 --> C11[Generate\nREVIEW_task_date.md]
+    C11 --> C12{Human approves\nreview?}
+    C12 -->|Revise| C10
+    C12 -->|Approved| C13[Push PR comments\nvia GitHub integration]
+    C13 --> C14[TEST\nUnit · Integration · E2E\nPerf · A11y · Visual Regression\nskip any layer via Constitution]
+    C14 --> C15{Constitution\ngates pass?}
+    C15 -->|Soft warnings| C16[Human: fix or accept?]
+    C16 --> C15
+    C15 -->|Pass| C17[bd done\nUpdate docs/pdlc/memory/STATE.md]
+    C17 --> C18{More tasks\nin bd ready?}
+    C18 -->|Yes| C1
+    C18 -->|No| C19[Claude drafts\nepisode file]
+    C19 --> C20([Construction Complete\nReady for /pdlc ship])
+
+    %% PHASE 3 — OPERATION
+    OPERATION["/pdlc ship"] --> O1[SHIP\nMerge PR — merge commit]
+    O1 --> O2[Trigger CI/CD\nvia Pulse]
+    O2 --> O3[Jarvis generates\nrelease notes + CHANGELOG]
+    O3 --> O4[PDLC auto-tags\nsemver commit]
+    O4 --> O5[VERIFY\nSmoke tests vs\ndeployed environment]
+    O5 --> O6{Human\nsign-off?}
+    O6 -->|No — issues found| O5
+    O6 -->|Approved| O7[REFLECT\ngstack-style retro:\nper-agent breakdown\nshipping streaks · metrics]
+    O7 --> O8[Human approves\nepisode file]
+    O8 --> O9[Commit episode\nUpdate docs/pdlc/memory/OVERVIEW.md\nUpdate docs/pdlc/memory/CHANGELOG.md]
+    O9 --> O10([Feature Delivered\nReady for next /pdlc brainstorm])
+
+    %% SAFETY GUARDRAILS
+    style C8 fill:#ff4444,color:#fff
+    style D5 fill:#f0a500,color:#fff
+    style D7 fill:#f0a500,color:#fff
+    style D9 fill:#f0a500,color:#fff
+    style C12 fill:#f0a500,color:#fff
+    style O6 fill:#f0a500,color:#fff
+```
+
+---
+
+## Phase Summary
+
+| Phase | Command | Description |
+|-------|---------|-------------|
+| **Phase 0 — Initialization** | `/pdlc init` | First-time setup: Constitution, Intent, Memory Bank, Beads (`bd init`) |
+| **Phase 1 — Inception** | `/pdlc brainstorm` | Discover → Define → Design → Plan for a feature; visual companion server active |
+| **Phase 2 — Construction** | `/pdlc build` | Build (TDD) → Review → Test for current feature; wave-based task execution via Beads |
+| **Phase 3 — Operation** | `/pdlc ship` | Ship (merge PR) → Verify (smoke tests) → Reflect (retro + episode file) |
+| *(resume)* | *(none)* | If no command given, read `docs/pdlc/memory/STATE.md` and resume from last checkpoint |
+
+---
+
+## Agent Roster
+
+**Always-on** — participate in every task regardless of scope:
+
+| Name | Role | Responsibility |
+|------|------|----------------|
+| **Neo** | Architect | High-level design, cross-cutting concerns, tech debt radar |
+| **Echo** | QA Engineer | Test strategy, edge cases, regression coverage |
+| **Phantom** | Security Reviewer | Auth, input validation, OWASP checks |
+| **Jarvis** | Tech Writer | Inline docs, API docs, changelogs |
+
+**Auto-selected** — PDLC picks based on task labels and scope:
+
+| Name | Role | Responsibility |
+|------|------|----------------|
+| **Bolt** | Backend Engineer | API, services, DB, business logic |
+| **Friday** | Frontend Engineer | UI components, state, UX implementation |
+| **Muse** | UX Designer | User experience, flows, interaction design |
+| **Oracle** | PM | Requirements clarity, scope, acceptance criteria |
+| **Pulse** | DevOps | CI/CD, infra, deployment, environment config |
+
+---
+
+## Approval Gates
+
+PDLC pauses and waits for explicit human approval at each of the following checkpoints:
+
+1. **End of Discover** — human approves the Socratic conversation output before PRD is drafted
+2. **End of Define** — human approves the auto-generated PRD draft before Design begins
+3. **End of Design** — human approves architecture, data-model, and API contract docs
+4. **End of Plan** — human approves the Beads task list before Construction begins
+5. **End of Review** — human approves the `REVIEW_[task-id]_[date].md` file before PR comments are posted
+6. **Ship** — human approves merge to main and deployment trigger
+7. **Verify** — human sign-off after smoke tests pass against the deployed environment
+8. **Reflect** — human reads and approves the episode file before it is committed
+
+---
+
+## 3-Strike Loop Breaker
+
+When Claude enters a bug-fix loop during Construction (build → test → fix → test → fix…):
+
+- Maximum **3 automatic fix attempts** per issue.
+- On the **3rd failed attempt**, PDLC pauses and presents the human with a choice:
+  - **(A) Continue automatically** — let Claude keep trying with a fresh approach.
+  - **(B) Human takes the wheel** — human reviews the error and suggests a course of action; Claude resumes with that guidance.
+
+---
+
+## Key Rules
+
+> **These rules are enforced by default. All can be overridden via `docs/pdlc/memory/CONSTITUTION.md`.**
+
+| Rule | Default Behavior |
+|------|-----------------|
+| **TDD enforced** | Claude must write failing tests before any implementation code. No implementation without a failing test. |
+| **Merge commit** | All PRs use merge commits (no squash, no rebase) to preserve full branch history. |
+| **Soft warnings only** | Security findings (Phantom) and test coverage gaps (Echo) are flagged but do not hard-block progress. Human decides: fix now, accept, or defer to tech debt. |
+| **Constitution overrides defaults** | Any rule in this document can be changed by editing `docs/pdlc/memory/CONSTITUTION.md`. The Constitution is the single source of truth for all project-specific rules. |
+| **Tier 1 hard blocks** | Force-push to `main`, dropping DB tables without a migration file, deleting files not created on the current branch, deploying with failing smoke tests — these require **double confirmation in red highlighted text** to override. |
+| **Tier 2 pause & confirm** | `rm -rf`, `git reset --hard`, production DB migrations, changes to `CONSTITUTION.md`, closing all Beads tasks at once, any external API call that writes/posts/sends — PDLC stops and waits for explicit yes. |
+| **Tier 3 logged warnings** | Skipping a test layer, overriding a Constitution rule, accepting a Phantom security warning without fixing, accepting an Echo coverage gap — PDLC proceeds and records the decision in `STATE.md`. |
+
+---
+
+## State & Configuration Pointers
+
+- **Current project state:** `docs/pdlc/memory/STATE.md`
+- **Constitution (rules, standards, overrides):** `docs/pdlc/memory/CONSTITUTION.md`
+- **Intent (problem statement, target user, value prop):** `docs/pdlc/memory/INTENT.md`
+- **Roadmap:** `docs/pdlc/memory/ROADMAP.md`
+- **Architectural decisions:** `docs/pdlc/memory/DECISIONS.md`
+- **Changelog:** `docs/pdlc/memory/CHANGELOG.md`
+- **Aggregated delivery overview:** `docs/pdlc/memory/OVERVIEW.md`
+- **Episode history:** `docs/pdlc/memory/episodes/index.md`