@pdlc-os/pdlc 0.1.0

package/templates/STATE.md

@@ -0,0 +1,113 @@
+# State
+<!-- This file is the live operational state of the PDLC workflow.
+     It is written by PDLC hooks and commands — do not edit manually unless recovering from an error.
+     Claude reads this file at the start of every session to auto-resume from the last checkpoint.
+     If this file is missing or empty, PDLC will prompt you to run /pdlc init. -->
+
+**Last updated:** <!-- YYYY-MM-DDTHH:MM:SSZ — set automatically by hooks -->
+
+---
+
+## Current Phase
+
+<!-- Valid values: Initialization | Inception | Construction | Operation -->
+
+Initialization
+
+---
+
+## Current Feature
+
+<!-- The name of the feature currently being worked on.
+     Matches the [feature-name] slug used in file paths under docs/pdlc/.
+     Example: user-auth | billing-integration | onboarding-flow
+     Set to "none" when between features. -->
+
+none
+
+---
+
+## Active Beads Task
+
+<!-- The Beads task currently claimed by Claude.
+     Format: [task-id] — [task title]
+     Example: bd-a1b2 — Add OAuth2 login with GitHub
+     Set to "none" when no task is active. -->
+
+none
+
+---
+
+## Current Sub-phase
+
+<!-- The specific sub-phase within the current phase.
+     Inception sub-phases: Discover | Define | Design | Plan
+     Construction sub-phases: Build | Review | Test
+     Operation sub-phases: Ship | Verify | Reflect
+     Set to "none" during Initialization or between phases. -->
+
+none
+
+---
+
+## Last Checkpoint
+
+<!-- The most recent point where state was explicitly saved.
+     Format: [Phase] / [Sub-phase] / [YYYY-MM-DDTHH:MM:SSZ]
+     Example: Construction / Build / 2026-04-03T14:32:00Z
+     Updated: (a) at every phase/sub-phase transition, (b) on context CRITICAL warning,
+     (c) after every Beads task completes. -->
+
+Initialization / — / <!-- timestamp -->
+
+---
+
+## Active Blockers
+
+<!-- List anything currently preventing forward progress.
+     Each blocker should have: what it is, when it was logged, and who/what needs to resolve it.
+     Format: - [YYYY-MM-DD] [description] — waiting on: [person/system]
+     Example:
+       - [2026-04-03] Supabase project not provisioned — waiting on: human (needs account setup)
+       - [2026-04-03] bd-c3d4 has unresolved merge conflict — waiting on: Claude (will resolve next session)
+     Clear this list as blockers are resolved. -->
+
+<!-- none -->
+
+---
+
+## Context Checkpoint
+
+<!-- Auto-populated by the context monitor hook when context hits CRITICAL (≤25% remaining).
+     Records exactly where Claude was so the next session can resume cleanly.
+     Do not edit manually.
+
+     Fields written by hook:
+       - active_task: Beads task ID and title at time of save
+       - sub_phase: sub-phase in progress
+       - work_in_progress: one-sentence summary of what was being done
+       - next_action: the exact next step Claude should take on resume
+       - files_open: list of files that were being edited
+-->
+
+```json
+{
+  "triggered_at": null,
+  "active_task": null,
+  "sub_phase": null,
+  "work_in_progress": null,
+  "next_action": null,
+  "files_open": []
+}
+```
+
+---
+
+## Phase History
+
+<!-- Append a row every time the phase or sub-phase changes.
+     Written automatically by hooks. Do not edit manually. -->
+
+| Timestamp | Event | Phase | Sub-phase | Feature |
+|-----------|-------|-------|-----------|---------|
+| <!-- YYYY-MM-DDTHH:MM:SSZ --> | init | Initialization | — | none |

package/templates/episode.md

@@ -0,0 +1,182 @@
+# Episode [ID]: [Feature Name]
+<!-- Replace [ID] with the zero-padded episode number (e.g. 001) and [Feature Name] with the feature title.
+     File naming convention: [ID]_[feature-slug]_[YYYY-MM-DD].md
+     This file lives at: docs/pdlc/memory/episodes/[ID]_[feature-slug]_[YYYY-MM-DD].md
+     Claude drafts this file at the end of Construction. Human reviews and approves before it is committed.
+     After commit, PDLC updates docs/pdlc/memory/OVERVIEW.md and docs/pdlc/memory/episodes/index.md. -->
+
+**Episode ID:** <!-- e.g. 001 -->
+**Feature name:** <!-- Human-readable feature name, e.g. "User Auth — GitHub OAuth" -->
+**Feature slug:** <!-- kebab-case slug used in file paths, e.g. user-auth-github-oauth -->
+**Date delivered:** <!-- YYYY-MM-DD — date of merge to main -->
+**Phase delivered in:** Construction
+**Status:** Draft <!-- Change to "Approved" after human sign-off -->
+
+---
+
+## What Was Built
+
+<!-- A paragraph (3–6 sentences) summarising what was designed, built, and shipped.
+     Written by Claude; reviewed and edited by human before commit.
+     Should be readable by someone coming to the codebase fresh.
+     Example:
+       This episode delivered GitHub OAuth login as an alternative authentication method.
+       Users can now click "Sign in with GitHub" on the login page, authorize the app via
+       the standard OAuth 2.0 PKCE flow, and be redirected to their dashboard — all in under
+       3 seconds. New accounts are created automatically on first login; if the GitHub email
+       matches an existing account the identities are linked. The implementation uses the
+       existing auth session infrastructure from ep-001 and adds a new oauth_accounts join
+       table to support multiple identity providers in future episodes. -->
+
+<!-- Auto-drafted by Claude at end of Construction. Review and edit as needed. -->
+
+---
+
+## Links
+
+- **PRD:** <!-- [PRD_feature-name_YYYY-MM-DD.md](../../prds/PRD_feature-name_YYYY-MM-DD.md) -->
+- **PR:** <!-- [#42](https://github.com/org/repo/pull/42) -->
+- **Review file:** <!-- [REVIEW_bd-a1b2_YYYY-MM-DD.md](../../reviews/REVIEW_bd-a1b2_YYYY-MM-DD.md) -->
+- **Design docs:** <!-- [ARCHITECTURE.md](../../design/feature-name/ARCHITECTURE.md) | [data-model.md](../../design/feature-name/data-model.md) -->
+
+---
+
+## Key Decisions & Rationale
+
+<!-- Numbered list of significant decisions made during this feature's lifecycle.
+     Each entry should explain: what was decided, why, and what was rejected/considered.
+     These feed into docs/pdlc/memory/DECISIONS.md (ADR log).
+     Example:
+       1. Used PKCE flow instead of implicit flow for OAuth — PKCE is the current best practice
+          for public clients; implicit flow is deprecated in OAuth 2.1. Rejected server-side
+          flow because it adds complexity without benefit at current scale.
+       2. Stored OAuth access tokens encrypted at rest, not in plaintext — Phantom flagged
+          plaintext storage as a Tier 1 security risk. AES-256-GCM encryption added with
+          key managed via environment variable.
+       3. Did not implement account unlinking in this episode — out of scope per PRD.
+          Deferred to ep-004. Tech debt ticket: td-007.
+-->
+
+1.
+2.
+3.
+
+---
+
+## Files Created
+
+<!-- List every new file added in this feature's branch that was merged.
+     Format: - `path/from/project/root` — one-line description of the file's purpose
+     Example:
+       - `src/lib/auth/github-oauth.ts` — GitHub OAuth PKCE flow implementation
+       - `src/app/api/auth/github/route.ts` — API route handler for OAuth callback
+       - `src/app/api/auth/github/callback/route.ts` — redirect target after GitHub authorization
+       - `db/migrations/0003_add_oauth_accounts.sql` — adds oauth_accounts table
+       - `src/components/auth/GitHubLoginButton.tsx` — "Sign in with GitHub" button component
+       - `tests/unit/auth/github-oauth.test.ts` — unit tests for OAuth flow helpers
+       - `tests/e2e/auth/github-login.spec.ts` — E2E test for full OAuth login journey
+-->
+
+-
+
+---
+
+## Files Modified
+
+<!-- List every pre-existing file changed in this feature's branch.
+     Format: - `path/from/project/root` — one-line description of what changed and why
+     Example:
+       - `src/lib/auth/session.ts` — extended session type to include oauth_provider field
+       - `src/app/(auth)/login/page.tsx` — added GitHub login button below email form
+       - `src/middleware.ts` — added /auth/github/* to public routes list
+       - `db/schema.ts` — added oauth_accounts table definition to Drizzle schema
+       - `docs/pdlc/memory/OVERVIEW.md` — updated active functionality and shipped features
+-->
+
+-
+
+---
+
+## Test Summary
+
+<!-- Filled in by Claude from the Test sub-phase results. Edit if numbers are wrong. -->
+
+| Layer | Status | Passed | Failed | Skipped | Notes |
+|-------|--------|--------|--------|---------|-------|
+| Unit | <!-- pass / fail / skip --> | <!-- n --> | <!-- n --> | <!-- n --> | <!-- e.g. all core logic covered --> |
+| Integration | <!-- pass / fail / skip --> | <!-- n --> | <!-- n --> | <!-- n --> | <!-- e.g. DB interactions verified --> |
+| E2E | <!-- pass / fail / skip --> | <!-- n --> | <!-- n --> | <!-- n --> | <!-- e.g. full login journey via Chromium --> |
+| Performance | <!-- pass / fail / skip --> | <!-- — --> | <!-- — --> | <!-- — --> | <!-- e.g. OAuth round-trip p95 = 1.2s --> |
+| Accessibility | <!-- pass / fail / skip --> | <!-- — --> | <!-- — --> | <!-- — --> | <!-- e.g. WCAG 2.1 AA — 0 violations --> |
+| Visual Regression | <!-- pass / fail / skip --> | <!-- — --> | <!-- — --> | <!-- — --> | <!-- e.g. login page diff approved --> |
+
+**Constitution gates:** <!-- All required gates passed / [list any that failed and how resolved] -->
+
+---
+
+## Known Tradeoffs & Tech Debt Introduced
+
+<!-- Honest record of shortcuts taken, things deferred, or imperfections knowingly accepted.
+     Each item will be tracked in docs/pdlc/memory/OVERVIEW.md under "Known Tech Debt".
+     Format: - [TD-nnn] Description — why accepted — planned resolution (if known)
+     Example:
+       - [TD-012] Access tokens encrypted with a single app-wide key instead of per-user keys
+         — accepted for v1 simplicity; move to per-user key derivation before SOC 2 audit
+       - [TD-013] No rate limiting on /api/auth/github/callback — deferred until after launch;
+         add before scaling past 1k users
+       - [TD-014] GitHub avatar URL stored as-is (external URL) — should proxy/cache before launch
+         to avoid broken images if GitHub changes URL structure
+-->
+
+<!-- None. -->
+
+---
+
+## Agent Team
+
+<!-- List all agents that participated in this feature's delivery.
+     Always-on agents are pre-filled. Remove any that did not participate.
+     Add auto-selected agents (Bolt, Friday, Muse, Oracle, Pulse) that were activated. -->
+
+**Always-on:**
+- **Neo** (Architect) — architecture review and PRD conformance
+- **Echo** (QA Engineer) — test strategy and coverage review
+- **Phantom** (Security Reviewer) — OWASP and auth security review
+- **Jarvis** (Tech Writer) — inline docs, API docs, episode draft
+
+**Auto-selected for this feature:**
+- <!-- **Bolt** (Backend Engineer) — API routes, business logic, DB migrations -->
+- <!-- **Friday** (Frontend Engineer) — UI components, state management -->
+- <!-- **Muse** (UX Designer) — interaction design, accessibility -->
+- <!-- **Oracle** (PM) — requirements clarity, acceptance criteria -->
+- <!-- **Pulse** (DevOps) — CI/CD, deployment, environment config -->
+
+---
+
+## Reflect Notes
+
+<!-- Retro observations generated by Claude during the Reflect sub-phase.
+     Covers: what went well, what broke, what to improve, and metrics snapshot.
+     Auto-drafted by Claude; human edits before commit. -->
+
+**What went well:**
+<!-- Auto-drafted by Claude -->
+
+**What broke or slowed us down:**
+<!-- Auto-drafted by Claude -->
+
+**What to improve next time:**
+<!-- Auto-drafted by Claude -->
+
+**Cycle time:** <!-- e.g. Inception to merge: 3 days -->
+**Test pass rate:** <!-- e.g. 94% (48/51 tests passed; 3 skipped) -->
+
+---
+
+## Approval
+
+<!-- Do not commit this episode file until a human has reviewed and approved it. -->
+
+**Reviewed by:** <!-- Name / initials -->
+**Date approved:** <!-- YYYY-MM-DD -->
+**Notes:** <!-- Any edits made or observations about this episode -->

package/templates/review.md

@@ -0,0 +1,215 @@
+# Review: [Task ID] — [Task Title]
+<!-- Replace [Task ID] and [Task Title] with the Beads task being reviewed.
+     File naming convention: REVIEW_[task-id]_[YYYY-MM-DD].md
+     This file lives at: docs/pdlc/reviews/REVIEW_[task-id]_[YYYY-MM-DD].md
+     Claude generates this file during the Review sub-phase after all tests pass.
+     Human reviews the findings and makes the final call before PDLC posts PR comments.
+     All reviewer findings are soft warnings only — human decides: fix, accept, or defer. -->
+
+**Task ID:** <!-- e.g. bd-a1b2 -->
+**Task title:** <!-- Full task title from Beads -->
+**Date reviewed:** <!-- YYYY-MM-DD -->
+**Feature:** <!-- Feature name / slug -->
+**Feature branch:** <!-- e.g. feature/user-auth-github-oauth -->
+**Episode:** <!-- e.g. ep-003 (assigned after delivery) -->
+**PRD:** <!-- [PRD_feature-name_YYYY-MM-DD.md](../prds/PRD_feature-name_YYYY-MM-DD.md) -->
+
+---
+
+## Reviewers
+
+<!-- Always-on reviewers are pre-filled. Add builder agent(s) who worked on this task. -->
+
+| Reviewer | Role | Present |
+|----------|------|---------|
+| Neo | Architect | yes |
+| Echo | QA Engineer | yes |
+| Phantom | Security Reviewer | yes |
+| Jarvis | Tech Writer | yes |
+| <!-- Bolt / Friday / Muse / Oracle / Pulse --> | <!-- Role --> | <!-- yes --> |
+
+---
+
+## Neo's Findings — Architecture & PRD Conformance
+
+<!-- Neo checks: does the implementation match the design docs and PRD?
+     Are there architectural concerns (coupling, abstraction, tech debt, scalability)?
+     Does this introduce cross-cutting concerns that affect other parts of the system?
+     Severity: BLOCKER | MAJOR | MINOR | INFO
+     A BLOCKER from Neo means the architecture must be corrected before shipping.
+     All other severities are recommendations; human decides. -->
+
+**PRD conformance:** <!-- Fully conformant / Partially conformant / Non-conformant -->
+**Design doc adherence:** <!-- Followed / Minor deviations / Significant deviations -->
+
+### Findings
+
+<!-- Format: [SEVERITY] [Finding title]
+     Description of the issue and Neo's recommended action.
+     Example:
+       [MAJOR] Business logic leaking into route handler
+       The GitHub token exchange logic in `/api/auth/github/route.ts` (lines 34–67) mixes
+       HTTP concerns with OAuth business logic. Per the architectural constraint in CONSTITUTION.md
+       (§3), business logic must live in the service layer. Recommend extracting to
+       `src/lib/auth/github-oauth.ts`.
+
+       [INFO] oauth_accounts table will support future providers cleanly
+       The schema design correctly anticipates multi-provider OAuth. No action needed.
+-->
+
+<!-- Auto-generated by Claude (Neo role). Review and supplement as needed. -->
+
+---
+
+## Phantom's Findings — Security
+
+<!-- Phantom checks against OWASP Top 10, auth best practices, input validation, and
+     any security requirements defined in CONSTITUTION.md §4.
+     Severity: CRITICAL | HIGH | MEDIUM | LOW | INFO
+     CRITICAL means the feature MUST NOT ship without resolution (Tier 1 guardrail).
+     All other severities are recommendations; human decides.
+     Reference: https://owasp.org/www-project-top-ten/ -->
+
+**OWASP Top 10 sweep:** <!-- Pass / Issues found (see below) -->
+**Auth & session security:** <!-- Pass / Issues found (see below) -->
+**Input validation:** <!-- Pass / Issues found (see below) -->
+**Secrets & credential handling:** <!-- Pass / Issues found (see below) -->
+
+### Findings
+
+<!-- Format: [SEVERITY] [Finding title]
+     Description, location (file + line), and Phantom's recommended fix.
+     Example:
+       [HIGH] OAuth state parameter not validated on callback
+       The /api/auth/github/callback/route.ts handler (line 18) does not verify that the
+       `state` parameter in the callback matches the value stored in the session before
+       exchanging the code for a token. This allows CSRF attacks against the OAuth flow.
+       OWASP A01:2021 (Broken Access Control). Fix: compare state before proceeding.
+
+       [LOW] GitHub access token logged at debug level
+       `src/lib/auth/github-oauth.ts` line 89 logs `token` at debug level. Tokens must
+       not appear in logs per CONSTITUTION.md §4. Remove the log statement.
+-->
+
+<!-- Auto-generated by Claude (Phantom role). Review and supplement as needed. -->
+
+---
+
+## Echo's Findings — Test Coverage & Quality
+
+<!-- Echo checks: are all acceptance criteria from the PRD covered by tests?
+     Are edge cases and error paths tested? Is test quality high (clear, isolated, deterministic)?
+     Severity: BLOCKER | HIGH | MEDIUM | LOW | INFO
+     BLOCKER means a critical path has zero test coverage — human must decide before shipping. -->
+
+**Acceptance criteria coverage:** <!-- All covered / Partial (see below) / None -->
+**Unit test coverage:** <!-- Adequate / Gaps found (see below) -->
+**Integration test coverage:** <!-- Adequate / Gaps found (see below) -->
+**E2E test coverage:** <!-- Adequate / Gaps found (see below) -->
+**Edge cases tested:** <!-- Yes / Partial / No -->
+
+### Findings
+
+<!-- Format: [SEVERITY] [Finding title]
+     Description of the coverage gap, which AC it affects, and recommended test to add.
+     Example:
+       [HIGH] AC-3 (account linking) has no integration test
+       The acceptance criterion "if GitHub email matches an existing account, link the identities"
+       is only tested via E2E. There is no integration test verifying the database state after
+       linking — if the E2E test is skipped, this path is completely untested.
+       Recommend: add `tests/integration/auth/account-linking.test.ts`.
+
+       [MEDIUM] No test for GitHub OAuth service unavailability
+       There is no test covering the graceful degradation path (NFR item: "degrade gracefully
+       if GitHub OAuth is unavailable"). Recommend mocking GitHub to return a 503 and asserting
+       the user sees the fallback error message.
+
+       [INFO] Unit tests for github-oauth.ts are thorough — 12 cases, all edge paths covered.
+-->
+
+<!-- Auto-generated by Claude (Echo role). Review and supplement as needed. -->
+
+---
+
+## Jarvis's Findings — Documentation Completeness
+
+<!-- Jarvis checks: are all public functions/methods documented? Is the API contract documented?
+     Are there inline comments on non-obvious logic? Is the CHANGELOG entry ready?
+     Severity: MAJOR | MINOR | INFO
+     All findings are recommendations; human decides. -->
+
+**Inline code documentation:** <!-- Complete / Gaps (see below) -->
+**API documentation:** <!-- Complete / Gaps (see below) -->
+**CHANGELOG entry drafted:** <!-- Yes / No -->
+**README updated (if needed):** <!-- Yes / N/A -->
+
+### Findings
+
+<!-- Format: [SEVERITY] [Finding title]
+     Description and location of the documentation gap.
+     Example:
+       [MINOR] exchangeCodeForToken() missing JSDoc
+       `src/lib/auth/github-oauth.ts` lines 34–67 — the main token exchange function has no
+       JSDoc comment. Per CONSTITUTION.md §2, all public functions must have JSDoc.
+       Recommend adding a JSDoc block with @param, @returns, and @throws annotations.
+
+       [INFO] CHANGELOG entry drafted and ready for Jarvis to commit
+       See the staged CHANGELOG.md update — no changes needed.
+-->
+
+<!-- Auto-generated by Claude (Jarvis role). Review and supplement as needed. -->
+
+---
+
+## Builder's Notes
+
+<!-- The agent(s) who built this task add context here: decisions made during Build,
+     anything the reviewers should know, known limitations, or questions for the human.
+     Written by the builder agent; reviewed as part of this file. -->
+
+<!-- Auto-drafted by the builder agent. Review and supplement as needed. -->
+
+---
+
+## Summary & Overall Recommendation
+
+<!-- Claude's overall read after all four reviewer findings are considered.
+     Options: Approve | Approve with conditions | Revise -->
+
+**Overall recommendation:** <!-- Approve | Approve with conditions | Revise -->
+
+**Blocking issues (must fix before shipping):**
+<!-- List any BLOCKER / CRITICAL findings. If none, write "None." -->
+
+**Recommended fixes (strong advice):**
+<!-- List HIGH / MAJOR findings that reviewers recommend addressing before ship. -->
+
+**Deferred items (accepted for now):**
+<!-- List MEDIUM / LOW findings that can be addressed in a follow-up episode. -->
+
+---
+
+## Human Decision
+
+<!-- This section is completed by the human after reviewing the findings above.
+     PDLC will not post PR comments until this section is filled in. -->
+
+**Decision:** <!-- Approve | Fix | Accept warning | Defer -->
+<!-- Approve — ship as-is; post PR comments
+     Fix — pause; Claude addresses the listed issues then generates an updated review
+     Accept warning — ship despite warnings; Phantom/Echo findings logged as Tier 3 events in STATE.md
+     Defer — do not ship yet; item moved to next episode or tech debt log -->
+
+**Conditions / notes from human:**
+<!-- Any instructions, caveats, or context the human wants recorded here -->
+
+**Reviewed by:** <!-- Name / initials -->
+**Date of decision:** <!-- YYYY-MM-DD -->
+
+---
+
+## PR Comments
+
+**Pushed to PR:** <!-- yes / no -->
+**Date pushed:** <!-- YYYY-MM-DD — set by PDLC after human approves and comments are posted -->
+**PR link:** <!-- https://github.com/org/repo/pull/N -->