diff --git a/.oat/projects/shared/project-completion/design.md b/.oat/projects/shared/project-completion/design.md
new file mode 100644
index 000000000..5a40f8359
--- /dev/null
+++ b/.oat/projects/shared/project-completion/design.md
@@ -0,0 +1,313 @@
+---
+oat_status: in_progress
+oat_ready_for: null
+oat_blockers: []
+oat_last_updated: 2026-03-27
+oat_generated: false
+---
+
+# Design: project-completion
+
+## Overview
+
+{2-3 paragraph summary of the technical approach, including key architectural decisions and rationale}
+
+## Architecture
+
+### System Context
+
+{How this fits into the broader system architecture}
+
+**Key Components:**
+
+- **{Component 1}:** {Purpose and responsibilities}
+- **{Component 2}:** {Purpose and responsibilities}
+
+### Component Diagram
+
+```
+{ASCII diagram or description of component relationships}
+```
+
+### Data Flow
+
+{Description of how data moves through the system}
+
+```
+{Sequence diagram or step-by-step flow}
+```
+
+## Component Design
+
+### {Component Name}
+
+**Purpose:** {What this component does}
+
+**Responsibilities:**
+
+- {Responsibility 1}
+- {Responsibility 2}
+
+**Interfaces:**
+
+```typescript
+// Key interfaces, classes, or function signatures
+```
+
+**Dependencies:**
+
+- {Internal dependency 1}
+- {External dependency 1}
+
+**Design Decisions:**
+
+- {Decision 1 and rationale}
+
+## Data Models
+
+### {Model Name}
+
+**Purpose:** {What this represents}
+
+**Schema:**
+
+```typescript
+interface ModelName {
+  // Field definitions with types
+}
+```
+
+**Validation Rules:**
+
+- {Rule 1}
+- {Rule 2}
+
+**Storage:**
+
+- **Location:** {Database, file system, memory}
+- **Persistence:** {How/when data is persisted}
+
+## API Design
+
+### {Endpoint/Interface Name}
+
+**Method:** GET / POST / PUT / DELETE
+**Path:** `/api/v1/{resource}`
+
+**Request:**
+
+```typescript
+interface Request {
+  // Request schema
+}
+```
+
+**Response:**
+
+```typescript
+interface Response {
+  // Response schema
+}
+```
+
+**Error Handling:**
+
+- {Error code}: {Description}
+
+**Authorization:** {Auth requirements}
+
+## Security Considerations
+
+### Authentication
+
+{How users/services authenticate}
+
+### Authorization
+
+{How permissions are enforced}
+
+### Data Protection
+
+- **Encryption:** {At rest, in transit}
+- **PII Handling:** {How sensitive data is protected}
+- **Input Validation:** {Where and how inputs are validated}
+
+### Threat Mitigation
+
+- **{Threat 1}:** {Mitigation strategy}
+- **{Threat 2}:** {Mitigation strategy}
+
+## Performance Considerations
+
+### Scalability
+
+{How the design scales with load}
+
+### Caching
+
+- **Layer:** {Where caching occurs}
+- **Strategy:** {Cache invalidation approach}
+- **TTL:** {Time-to-live values}
+
+### Database Optimization
+
+- **Indexes:** {Key indexes to create}
+- **Query Optimization:** {Query patterns to optimize}
+
+### Resource Limits
+
+- **Memory:** {Expected usage}
+- **CPU:** {Expected usage}
+- **Network:** {Expected bandwidth}
+
+## Error Handling
+
+### Error Categories
+
+- **User Errors:** {How handled}
+- **System Errors:** {How handled}
+- **External Service Errors:** {How handled}
+
+### Retry Logic
+
+{When and how retries are performed}
+
+### Logging
+
+- **Info:** {What to log at info level}
+- **Warn:** {What to log at warn level}
+- **Error:** {What to log at error level}
+
+## Testing Strategy
+
+### Requirement-to-Test Mapping
+
+{Maps spec requirements to test levels and key scenarios — ensures every requirement has a verification plan}
+
+| ID   | Verification                       | Key Scenarios              |
+| ---- | ---------------------------------- | -------------------------- |
+| FR1  | {unit/integration/e2e/manual/perf} | {Scenario 1}, {Scenario 2} |
+| FR2  | {unit/integration/e2e/manual/perf} | {Scenario 1}               |
+| NFR1 | {unit/integration/e2e/manual/perf} | {Scenario 1}               |
+
+**Notes:**
+
+- Pull ID from spec.md Requirement Index
+- Copy the **method** (left side of `method: pointer`) into Verification
+- Use the **pointer** (right side) to seed Key Scenarios, then expand based on design
+- Multiple test levels are valid (e.g., "unit + integration")
+
+### Unit Tests
+
+- **Scope:** {What gets unit tested}
+- **Coverage Target:** {N}%
+- **Key Test Cases:**
+  - {Test case 1}
+  - {Test case 2}
+
+### Integration Tests
+
+- **Scope:** {What gets integration tested}
+- **Test Environment:** {How environment is set up}
+- **Key Test Cases:**
+  - {Test case 1}
+  - {Test case 2}
+
+### End-to-End Tests
+
+- **Scope:** {What gets E2E tested}
+- **Test Scenarios:**
+  - {Scenario 1}
+  - {Scenario 2}
+
+## Deployment Strategy
+
+### Build Process
+
+{How the application is built}
+
+### Deployment Steps
+
+1. {Step 1}
+2. {Step 2}
+
+### Rollback Plan
+
+{How to rollback if deployment fails}
+
+### Configuration
+
+- **Environment Variables:** {List with descriptions}
+- **Feature Flags:** {Any feature flags needed}
+
+### Monitoring
+
+- **Metrics:** {Key metrics to track}
+- **Alerts:** {Alert conditions}
+- **Dashboards:** {What to monitor}
+
+## Migration Plan
+
+{If this involves database migrations, data migrations, or breaking changes}
+
+### Migration Steps
+
+1. {Step 1}
+2. {Step 2}
+
+### Rollback Strategy
+
+{How to rollback migrations}
+
+### Data Validation
+
+{How to verify migration success}
+
+## Open Questions
+
+- **{Question Category}:** {Question needing resolution}
+- **{Question Category}:** {Question needing resolution}
+
+## Implementation Phases
+
+### Phase 1: {Phase Name}
+
+**Goal:** {What this phase achieves}
+
+**Tasks:**
+
+- {Task 1}
+- {Task 2}
+
+**Verification:** {How to verify phase completion}
+
+### Phase 2: {Phase Name}
+
+{Similar structure}
+
+## Dependencies
+
+### External Dependencies
+
+- **{Service/Library}:** {Why needed, version constraints}
+
+### Internal Dependencies
+
+- **{Component/Service}:** {Why needed, coupling points}
+
+### Development Dependencies
+
+- **{Tool}:** {Why needed}
+
+## Risks and Mitigation
+
+- **{Risk 1}:** {Probability: Low/Medium/High} | {Impact: Low/Medium/High}
+  - **Mitigation:** {How to reduce risk}
+  - **Contingency:** {What to do if risk occurs}
+
+## References
+
+- Specification: `spec.md`
+- Knowledge Base: `.oat/repo/knowledge/project-index.md`
+- Architecture Docs: `.oat/repo/knowledge/architecture.md`
+- Conventions: `.oat/repo/knowledge/conventions.md`
diff --git a/.oat/projects/shared/project-completion/discovery.md b/.oat/projects/shared/project-completion/discovery.md
new file mode 100644
index 000000000..36a696eb4
--- /dev/null
+++ b/.oat/projects/shared/project-completion/discovery.md
@@ -0,0 +1,203 @@
+---
+oat_status: complete
+oat_ready_for: oat-project-spec
+oat_blockers: []
+oat_last_updated: 2026-03-27
+oat_generated: false
+---
+
+# Discovery: project-completion
+
+## Phase Guardrails (Discovery)
+
+Discovery is for requirements and decisions, not implementation details.
+
+- Prefer outcomes and constraints over concrete deliverables (no specific scripts, file paths, or function names).
+- If an implementation detail comes up, capture it as an **Open Question** for design (or a constraint), not as a deliverable list.
+
+## Initial Request
+
+Improve the OAT project completion flow with three interconnected changes:
+
+1. **`summary.md`** — A new first-class project artifact that serves as institutional memory, generated at project closeout. More reflective and extensive than the PR description's summary section. Serves as the artifact posted back to Linear issues on closeout, and as the source for portfolio-level rollups across completed projects.
+
+2. **Post-PR revision workflow** — Fix the "dead zone" after `oat-project-pr-final` where the project looks complete to agents but is still awaiting human review. Introduce a `pr_open` phase status and a `oat-project-revise` skill that enables clean re-entry for human feedback without starting a new project.
+
+3. **Completion flow improvements** — Better guidance and state transitions across the final stretch of the project lifecycle (post-implementation through archive), including how summary, document, update-repo-reference, pr-final, revise, and complete interact.
+
+4. **Automatic subagent review at phase checkpoints** — Configurable option to automatically trigger a subagent code review when a plan phase checkpoint completes, instead of requiring the user to manually invoke review-provide. Scopes the review to all phases since the last checkpoint (e.g., if checkpoints are p02 and p05, completing p02 triggers review for p01-p02, completing p05 triggers review for p03-p05). If it's the final phase, triggers `code final` review. Keeps sequential implementation but removes the manual review-triggering step.
+
+## Clarifying Questions
+
+### Question 1: Summary vs PR description distinction
+
+**Q:** Should `summary.md` feed into the PR description, or are they independent artifacts?
+**A:** They serve different audiences. `summary.md` is institutional memory (future you, future agents, portfolio rollups, Linear closeout). The PR description is reviewer-oriented (enough to review the PR). `pr-final` should draw from `summary.md` for its Summary section rather than synthesizing independently from raw artifacts.
+**Decision:** Two distinct artifacts. PR description pulls from summary.md as a primary source but is thinner and more actionable.
+
+### Question 2: Summary sections
+
+**Q:** What sections should `summary.md` contain?
+**A:** Based on brainstorming:
+
+1. Overview — 2-3 sentences on what the project was and why
+2. What was implemented — capability-level, narrative
+3. Key decisions — design choices with rationale
+4. Design deltas — where final result diverged from original design and why
+5. Notable challenges — what was harder than expected, resolution
+6. Tradeoffs made — explicit tradeoffs with reasoning
+7. Integration notes — things other projects/developers need to know
+8. Revision history — if revisions happened post-PR, what changed and why
+9. Follow-up items — deferred work, known limitations, spawned backlog items with refs
+10. Associated issues — which backlog items / Linear issues this project satisfied
+    **Decision:** These 10 sections form the summary template. Several sections may be omitted if not applicable (e.g., revision history for projects with no revisions).
+
+### Question 3: When should summary be generated?
+
+**Q:** What triggers summary generation?
+**A:** Multiple valid triggers:
+
+- `oat-project-summary` can be run independently at any time after implementation has meaningful progress
+- `oat-project-pr-final` triggers summary generation if not yet done (summary feeds the PR description)
+- `oat-project-complete` generates summary if not yet done
+- Summary is re-runnable — can be updated after revisions
+  **Decision:** Summary is an independent, re-runnable skill. Both pr-final and complete invoke it if summary.md doesn't exist. After revisions, summary should be updated (not fully rewritten — update relevant sections).
+
+### Question 4: How does summary know what's new on re-run?
+
+**Q:** When summary is re-run after revisions, how does it know what changed?
+**A:** Track in summary.md frontmatter what the summary has "seen":
+
+- `oat_summary_last_task` — last task ID when summary was generated
+- `oat_summary_revision_count` — how many revision phases existed at generation time
+- `oat_summary_includes_revisions` — which revision phases are reflected
+  On re-run, check for new tasks or revision phases since the tracked point and update relevant sections.
+  **Decision:** Frontmatter-based tracking of summary state enables incremental updates.
+
+### Question 5: Post-PR phase status
+
+**Q:** What should the project state be after pr-final but before human approval?
+**A:** A new phase status `pr_open` that signals "PR is open, human reviewing, revisions may come." This is NOT a blocker — `oat-project-complete` should still work from `pr_open`. The user may review inline (not on GitHub) and just want to close out directly.
+**Decision:** `pr_open` is guidance, not a gate. Complete is permissive from any status.
+
+### Question 6: How does the revision skill work?
+
+**Q:** What is the entry point for post-PR revisions?
+**A:** `oat-project-revise` accepts feedback from multiple sources:
+
+- Inline conversation (user describes changes needed)
+- GitHub PR comments (delegates to `review-receive-remote`)
+- A review artifact (delegates to `review-receive`)
+  For inline feedback, it's simpler than review-receive — no severity classification, no triage ceremony. Just "here are the things I want changed" → tasks → implement.
+  **Decision:** `oat-project-revise` is a unified re-entry point that routes to the right handler based on feedback source.
+
+### Question 8: Automatic subagent review at checkpoints
+
+**Q:** Should phase checkpoint completion automatically trigger a code review?
+**A:** Yes, as a configurable option. When enabled, completing a plan phase checkpoint automatically spawns a subagent review scoped to all phases since the last reviewed checkpoint. This keeps sequential implementation (not switching to subagent-driven execution mode) but removes the manual step of invoking review-provide at every checkpoint. Configuration could live in oat config (global default), local config (per-repo override), or per-project (state.md or plan.md frontmatter override).
+**Decision:** Add a configuration option for auto-review at checkpoints. The review scope is derived from checkpoint boundaries. Final phase checkpoint triggers `code final`. This is opt-in, not default behavior.
+
+### Question 9: Should OAT manage Linear status transitions?
+
+**Q:** When a project completes, should OAT move the Linear issue to Done?
+**A:** No. The GitHub integration handles status transitions automatically: branch push → In Progress, PR → In Review, merge → Done. OAT's responsibility is posting the summary as a comment/update, not managing status.
+**Decision:** OAT posts data to Linear (summary on closeout). Status lifecycle is GitHub integration's job.
+
+## Solution Space
+
+This project has a clear direction from extensive brainstorming. The solution involves three coordinated changes to existing skills plus two new skills/artifacts.
+
+### Chosen Direction
+
+**Approach:** Incremental extension of existing lifecycle skills with two new artifacts (summary.md, revision workflow)
+**Rationale:** The existing skill architecture (declarative frontmatter, phase-based lifecycle, review-receive pattern) already has the right seams. We're adding a missing artifact and fixing a state gap, not redesigning the lifecycle.
+**User validated:** Yes — confirmed through brainstorming session
+
+## Key Decisions
+
+1. **Summary.md is distinct from PR description:** Summary is institutional memory (deeper, more reflective). PR description is reviewer-oriented (thinner, actionable). PR description draws from summary.md as a source.
+
+2. **`pr_open` is not a gate:** It's a status signal. `oat-project-complete` works from `pr_open`, `complete`, or `in_progress`. The user controls when to close out, not the state machine.
+
+3. **Revision skill is a unified re-entry point:** `oat-project-revise` handles inline feedback directly and delegates to existing review-receive skills for structured feedback. It adds revision phases to plan.md and returns to `pr_open` after completion.
+
+4. **Summary is re-runnable with incremental updates:** Frontmatter tracks what the summary has seen. Re-runs after revisions update relevant sections rather than full rewrites.
+
+5. **No Linear status management from OAT:** GitHub integration owns status transitions. OAT posts summary content to Linear issues on closeout.
+
+6. **Complete is permissive:** Completion gates (final review, docs sync, summary) remain as warnings, not hard blocks. The user can always force completion.
+
+7. **Auto-review at checkpoints is opt-in:** Configurable at global, repo, or project level. When enabled, phase checkpoint completion spawns a subagent review covering all phases since the last checkpoint. Keeps sequential execution mode — this is about automating the review trigger, not changing how implementation runs.
+
+## Constraints
+
+- Must not break any existing project lifecycle workflow
+- Must not require summary.md for projects that don't want it (existing projects should still complete normally)
+- `pr_open` must be backward-compatible — agents reading older state.md files without this status should not break
+- Summary generation must work from any state (mid-implementation, post-implementation, post-revision)
+- The revision workflow must be compatible with both inline review (no GitHub PR) and GitHub PR review paths
+- Skills must follow existing OAT skill conventions (frontmatter, progress indicators, mode assertion, allowed-tools)
+
+## Success Criteria
+
+- `summary.md` is generated as a first-class project artifact with the defined section structure
+- `summary.md` is re-runnable and tracks what it has seen via frontmatter
+- `pr-final` uses summary.md as a source for its Summary section
+- `oat-project-complete` generates summary if not done, uses it as archive cover page
+- After pr-final, state.md reflects `pr_open` status with clear next-step guidance (revise or complete)
+- `oat-project-revise` cleanly re-enters implementation for inline feedback without triggering new project creation
+- `oat-project-revise` creates revision phases in plan.md and returns to `pr_open` on completion
+- `oat-project-complete` works from any phase status without blocking on `pr_open`
+- Agents in new sessions reading state.md correctly understand the project is "awaiting human review / open for revisions" rather than "done, start a new project"
+- Auto-review at checkpoints can be enabled via configuration and correctly scopes reviews to phases since the last checkpoint
+- Final phase checkpoint with auto-review triggers `code final` review
+
+## Out of Scope
+
+- Linear integration (handled by separate `remote-project-management` project)
+- Backlog promotion skill (`oat-pjm-promote-to-project`) — related but separate
+- Deferred work capture skill (`oat-pjm-capture-deferred`) — related but separate
+- Changes to `oat-project-document` or `oat-pjm-update-repo-reference` skills — these continue to work as-is
+- Portfolio rollup skill that reads summary.md across projects — future work
+
+## Deferred Ideas
+
+- **Portfolio rollup from summaries** — A skill that reads `summary.md` from recent completed projects to synthesize a status report. Valuable but depends on having completed projects with summaries first.
+- **Summary as Linear project update** — Beyond posting to individual issues, summary content could feed into Linear project-level updates with health/progress. Depends on Linear integration project.
+- **Auto-generation of decision-record entries from summary** — Summary's "key decisions" section overlaps with the repo decision record. Could auto-promote decisions to the decision record during update-repo-reference.
+- **Summary diff view** — Show what changed between summary versions when re-run after revisions.
+
+## Open Questions
+
+- **Revision phase naming:** Should revision phases use `p-rev1`, `p-rev2` naming or extend the existing phase numbering (e.g., if last phase was p03, revision becomes p04)?
+- **Summary template location:** Should the summary template live in `.oat/templates/summary.md` alongside other templates?
+- **Complete flow ordering:** Exact ordering of summary generation, document, update-repo-reference, and archive within `oat-project-complete`. Currently complete generates PR description then archives — where does summary fit relative to those?
+- **Auto-review config location:** Where does the auto-review setting live? Options: `oat config` (global default), `.oat/config.local.json` (per-repo), `state.md` or `plan.md` frontmatter (per-project). Could support cascading (project overrides repo overrides global).
+- **Auto-review + review-receive flow:** After auto-review completes, should it automatically invoke review-receive to process findings, or pause for the user to run it manually? Automatic would be more seamless but removes a human decision point.
+
+## Assumptions
+
+- Projects that were completed before this change (without summary.md) will not be retroactively updated
+- The `pr_open` status will be understood by agents that read state.md next-milestone guidance text, even without explicit code changes in the agent
+- Inline revision feedback (not from GitHub) will be conversational — the user describes what they want changed, the agent creates tasks
+
+## Risks
+
+- **State complexity:** Adding `pr_open` and revision loops increases the number of possible state transitions. Risk of edge cases where state gets inconsistent.
+  - **Likelihood:** Medium
+  - **Impact:** Medium
+  - **Mitigation Ideas:** Keep `pr_open` as guidance only, not a gate. Complete always works. Revision always returns to `pr_open`.
+
+- **Summary bloat:** Summary.md could become too long for large projects with many revisions, reducing its value as a quick-read artifact.
+  - **Likelihood:** Low
+  - **Impact:** Medium
+  - **Mitigation Ideas:** Keep sections concise. Revision history is additive but brief. Cap revision detail at 2-3 sentences per round.
+
+- **Skill interaction complexity:** Five skills need coordinated changes (implement, pr-final, complete, plus two new). Risk of inconsistent behavior across skills.
+  - **Likelihood:** Medium
+  - **Impact:** High
+  - **Mitigation Ideas:** Design the state transitions clearly in spec. Test the full lifecycle flow end-to-end.
+
+## Next Steps
+
+Spec-driven mode: continue to `oat-project-spec` (after HiLL approval if configured).
diff --git a/.oat/projects/shared/project-completion/implementation.md b/.oat/projects/shared/project-completion/implementation.md
new file mode 100644
index 000000000..657025d15
--- /dev/null
+++ b/.oat/projects/shared/project-completion/implementation.md
@@ -0,0 +1,205 @@
+---
+oat_status: in_progress
+oat_ready_for: null
+oat_blockers: []
+oat_last_updated: 2026-03-27
+oat_current_task_id: p01-t01
+oat_generated: false
+---
+
+# Implementation: project-completion
+
+**Started:** 2026-03-27
+**Last Updated:** 2026-03-27
+
+> This document is used to resume interrupted implementation sessions.
+>
+> Conventions:
+>
+> - `oat_current_task_id` always points at the **next plan task to do** (not the last completed task).
+> - When all plan tasks are complete, set `oat_current_task_id: null`.
+> - Reviews are **not** plan tasks. Track review status in `plan.md` under `## Reviews` (e.g., `| final | code | passed | ... |`).
+> - Keep phase/task statuses consistent with the Progress Overview table so restarts resume correctly.
+> - Before running the `oat-project-pr-final` skill, ensure `## Final Summary (for PR/docs)` is filled with what was actually implemented.
+
+## Progress Overview
+
+| Phase   | Status      | Tasks | Completed |
+| ------- | ----------- | ----- | --------- |
+| Phase 1 | in_progress | N     | 0/N       |
+| Phase 2 | pending     | N     | 0/N       |
+
+**Total:** 0/{N} tasks completed
+
+---
+
+## Phase 1: {Phase Name}
+
+**Status:** in_progress
+**Started:** 2026-03-27
+
+### Phase Summary (fill when phase is complete)
+
+**Outcome (what changed):**
+
+- {2-5 bullets describing user-visible / behavior-level changes delivered in this phase}
+
+**Key files touched:**
+
+- `{path}` - {why}
+
+**Verification:**
+
+- Run: `{command(s)}`
+- Result: {pass/fail + notes}
+
+**Notes / Decisions:**
+
+- {trade-offs or deviations discovered during implementation}
+
+### Task p01-t01: {Task Name}
+
+**Status:** completed / in_progress / pending / blocked
+**Commit:** {sha} (if completed)
+
+**Outcome (required when completed):**
+
+- {what materially changed (not “did task”, but “system now does X”)}
+
+**Files changed:**
+
+- `{path}` - {why}
+
+**Verification:**
+
+- Run: `{command(s)}`
+- Result: {pass/fail + notes}
+
+**Notes / Decisions:**
+
+- {gotchas, trade-offs, design deltas, important context for future sessions}
+
+**Issues Encountered:**
+
+- {Issue and resolution}
+
+---
+
+### Task p01-t02: {Task Name}
+
+**Status:** pending
+**Commit:** -
+
+**Notes:**
+
+- {Notes will be added during implementation}
+
+---
+
+## Phase 2: {Phase Name}
+
+**Status:** pending
+**Started:** -
+
+### Task p02-t01: {Task Name}
+
+**Status:** pending
+**Commit:** -
+
+---
+
+## Orchestration Runs
+
+> This section is used by `oat-project-subagent-implement` to log parallel execution runs.
+> Each run appends a new subsection — never overwrite prior entries.
+> For single-thread execution (via `oat-project-implement`), this section remains empty.
+
+<!-- orchestration-runs-start -->
+<!-- orchestration-runs-end -->
+
+---
+
+## Implementation Log
+
+Chronological log of implementation progress.
+
+### 2026-03-27
+
+**Session Start:** {time}
+
+- [x] p01-t01: {Task name} - {commit sha}
+- [ ] p01-t02: {Task name} - in progress
+
+**What changed (high level):**
+
+- {short bullets suitable for PR/docs}
+
+**Decisions:**
+
+- {Decision made and rationale}
+
+**Follow-ups / TODO:**
+
+- {anything discovered during implementation that should be captured for later}
+
+**Blockers:**
+
+- {Blocker description} - {status: resolved/pending}
+
+**Session End:** {time}
+
+---
+
+### 2026-03-27
+
+**Session Start:** {time}
+
+{Continue log...}
+
+---
+
+## Deviations from Plan
+
+Document any deviations from the original plan.
+
+| Task | Planned | Actual | Reason |
+| ---- | ------- | ------ | ------ |
+| -    | -       | -      | -      |
+
+## Test Results
+
+Track test execution during implementation.
+
+| Phase | Tests Run | Passed | Failed | Coverage |
+| ----- | --------- | ------ | ------ | -------- |
+| 1     | -         | -      | -      | -        |
+| 2     | -         | -      | -      | -        |
+
+## Final Summary (for PR/docs)
+
+**What shipped:**
+
+- {capability 1}
+- {capability 2}
+
+**Behavioral changes (user-facing):**
+
+- {bullet}
+
+**Key files / modules:**
+
+- `{path}` - {purpose}
+
+**Verification performed:**
+
+- {tests/lint/typecheck/build/manual steps}
+
+**Design deltas (if any):**
+
+- {what changed vs design.md and why}
+
+## References
+
+- Plan: `plan.md`
+- Design: `design.md`
+- Spec: `spec.md`
diff --git a/.oat/projects/shared/project-completion/plan.md b/.oat/projects/shared/project-completion/plan.md
new file mode 100644
index 000000000..b0220c5d0
--- /dev/null
+++ b/.oat/projects/shared/project-completion/plan.md
@@ -0,0 +1,169 @@
+---
+oat_status: in_progress
+oat_ready_for: null
+oat_blockers: []
+oat_last_updated: 2026-03-27
+oat_phase: plan
+oat_phase_status: in_progress
+oat_plan_hill_phases: [] # phases to pause AFTER completing (empty = every phase)
+oat_plan_source: spec-driven # spec-driven | quick | imported
+oat_import_reference: null # e.g., references/imported-plan.md
+oat_import_source_path: null # original source path provided by user
+oat_import_provider: null # codex | cursor | claude | null
+oat_generated: false
+---
+
+# Implementation Plan: project-completion
+
+> Execute this plan using `oat-project-implement` (sequential) or `oat-project-subagent-implement` (parallel), with phase checkpoints and review gates.
+
+**Goal:** {Brief goal statement from spec}
+
+**Architecture:** {1-2 sentence architecture summary from design}
+
+**Tech Stack:** {Key technologies from design}
+
+**Commit Convention:** `{type}({scope}): {description}` - e.g., `feat(p01-t01): add user auth endpoint`
+
+## Planning Checklist
+
+- [ ] Confirmed HiLL checkpoints with user
+- [ ] Set `oat_plan_hill_phases` in frontmatter
+
+---
+
+## Phase 1: {Phase Name}
+
+### Task p01-t01: {Task Name}
+
+**Files:**
+
+- Create: `{path/to/file.ts}`
+- Modify: `{path/to/existing.ts}`
+
+**Step 1: Write test (RED)**
+
+```typescript
+// {path/to/file.test.ts}
+describe('{feature}', () => {
+  it('{test case}', () => {
+    // Test implementation
+  });
+});
+```
+
+Run: `pnpm test {path/to/file.test.ts}`
+Expected: Test fails (RED)
+
+**Step 2: Implement (GREEN)**
+
+```typescript
+// {path/to/file.ts}
+// Implementation code or interface signatures
+```
+
+Run: `pnpm test {path/to/file.test.ts}`
+Expected: Test passes (GREEN)
+
+**Step 3: Refactor**
+
+{Any cleanup or improvements while tests stay green}
+
+**Step 4: Verify**
+
+Run: `pnpm lint && pnpm type-check`
+Expected: No errors
+
+**Step 5: Commit**
+
+```bash
+git add {files}
+git commit -m "feat(p01-t01): {description}"
+```
+
+---
+
+### Task p01-t02: {Task Name}
+
+**Files:**
+
+- {File list}
+
+**Step 1: Write test (RED)**
+
+{Test code}
+
+**Step 2: Implement (GREEN)**
+
+{Implementation code or signatures}
+
+**Step 3: Refactor**
+
+{Optional cleanup}
+
+**Step 4: Verify**
+
+Run: `{verification command}`
+Expected: {output}
+
+**Step 5: Commit**
+
+```bash
+git add {files}
+git commit -m "feat(p01-t02): {description}"
+```
+
+---
+
+## Phase 2: {Phase Name}
+
+### Task p02-t01: {Task Name}
+
+{Continue TDD pattern...}
+
+---
+
+## Reviews
+
+{Track reviews here after running the oat-project-review-provide and oat-project-review-receive skills.}
+
+{Keep both code + artifact rows below. Add additional code rows (p03, p04, etc.) as needed, but do not delete `spec`/`design`.}
+
+| Scope  | Type     | Status  | Date | Artifact |
+| ------ | -------- | ------- | ---- | -------- |
+| p01    | code     | pending | -    | -        |
+| p02    | code     | pending | -    | -        |
+| final  | code     | pending | -    | -        |
+| spec   | artifact | pending | -    | -        |
+| design | artifact | pending | -    | -        |
+
+**Status values:** `pending` → `received` → `fixes_added` → `fixes_completed` → `passed`
+
+**Meaning:**
+
+- `received`: review artifact exists (not yet converted into fix tasks)
+- `fixes_added`: fix tasks were added to the plan (work queued)
+- `fixes_completed`: fix tasks implemented, awaiting re-review
+- `passed`: re-review run and recorded as passing (no Critical/Important)
+
+---
+
+## Implementation Complete
+
+**Summary:**
+
+- Phase 1: {N} tasks - {Description}
+- Phase 2: {N} tasks - {Description}
+
+**Total: {N} tasks**
+
+Ready for code review and merge.
+
+---
+
+## References
+
+- Design: `design.md` (required in spec-driven mode; optional in quick/import mode)
+- Spec: `spec.md` (required in spec-driven mode; optional in quick/import mode)
+- Discovery: `discovery.md`
+- Imported Source: `references/imported-plan.md` (when `oat_plan_source: imported`)
diff --git a/.oat/projects/shared/project-completion/spec.md b/.oat/projects/shared/project-completion/spec.md
new file mode 100644
index 000000000..4f8dcc933
--- /dev/null
+++ b/.oat/projects/shared/project-completion/spec.md
@@ -0,0 +1,288 @@
+---
+oat_status: complete
+oat_ready_for: oat-project-design
+oat_blockers: []
+oat_last_updated: 2026-03-27
+oat_generated: false
+---
+
+# Specification: project-completion
+
+## Phase Guardrails (Specification)
+
+Specification is for requirements and acceptance criteria, not design/implementation details.
+
+- Avoid concrete deliverables (specific scripts, file paths, function names).
+- Keep the "High-Level Design" section to architecture shape and component boundaries only.
+- If a design detail comes up, record it under **Open Questions** for `oat-project-design`.
+
+## Problem Statement
+
+The OAT project lifecycle has a gap between implementation completion and project closure. Three problems converge:
+
+1. **No institutional memory artifact.** When a project completes, there is no single document that captures what was built, why decisions were made, what tradeoffs occurred, and what follow-up work was identified. The PR description serves reviewers, not future developers or agents. The `implementation.md` Final Summary is buried in a large file and formatted for PR use, not for knowledge retention or external system feedback (e.g., Linear issue closeout).
+
+2. **No post-PR revision path.** After `oat-project-pr-final` runs, the project state signals "ready for complete" — but the PR hasn't been human-reviewed yet. When a human returns with feedback, the agent interprets the project as done and tries to start a new one instead of continuing revisions in the existing project. There is no state representing "PR is open, awaiting human review, revisions may come" and no clean skill for re-entering implementation with feedback.
+
+3. **Manual review triggering at every checkpoint.** During sequential implementation, the user must manually invoke `oat-project-review-provide` at every plan phase checkpoint. This is repetitive and always follows the same pattern — the review should optionally be auto-triggered when a checkpoint phase completes.
+
+## Goals
+
+### Primary Goals
+
+- Produce a durable project summary artifact (`summary.md`) that serves as institutional memory, external system feedback payload, and portfolio rollup source
+- Eliminate the "dead zone" after PR creation where agents misinterpret project state and start new projects instead of accepting revisions
+- Provide a clean re-entry path for post-PR human feedback that creates revision tasks and returns to the PR-open state
+- Enable automatic subagent review triggering at plan phase checkpoints without switching to subagent-driven execution mode
+
+### Secondary Goals
+
+- Make PR description generation higher quality by grounding it in `summary.md` rather than raw artifact synthesis
+- Improve the overall clarity of the post-implementation lifecycle for both agents and humans
+- Reduce the number of manual skill invocations in the completion flow
+
+## Non-Goals
+
+- Linear or external PM tool integration (separate project: `remote-project-management`)
+- Backlog item promotion to project workflow
+- Deferred work capture during implementation
+- Changes to `oat-project-document` or `oat-pjm-update-repo-reference` skills
+- Portfolio-level rollup across multiple project summaries
+- Retroactive summary generation for already-completed projects
+
+## Requirements
+
+### Functional Requirements
+
+**FR1: Summary Artifact Generation**
+
+- **Description:** A new skill generates a `summary.md` artifact in the project directory that distills institutional knowledge from project artifacts into a structured, human-readable document.
+- **Acceptance Criteria:**
+  - Summary contains defined sections: overview, what was implemented, key decisions, design deltas, notable challenges, tradeoffs, integration notes, revision history, follow-up items, associated issues
+  - Summary is generated by reading discovery, design, plan, and implementation artifacts — not by asking the user to write it
+  - Sections that are not applicable (e.g., revision history when no revisions occurred) are omitted rather than left as empty placeholders
+  - Summary is grounded in what actually happened (implementation.md outcomes, design deltas, deviations table) rather than what was planned
+- **Priority:** P0
+
+**FR2: Summary Re-runnability**
+
+- **Description:** The summary skill can be re-run after revisions to update rather than replace the summary, using frontmatter to track what has already been captured.
+- **Acceptance Criteria:**
+  - Summary frontmatter tracks the last task ID, revision count, and which revision phases have been captured
+  - Re-running the skill when new tasks or revision phases exist updates relevant sections rather than overwriting the entire document
+  - Re-running the skill when nothing has changed since the last run produces no modifications
+- **Priority:** P0
+
+**FR3: Summary Integration with PR Final**
+
+- **Description:** When `oat-project-pr-final` runs, it checks for `summary.md` and generates it if missing, then uses it as the primary source for the PR description's Summary section.
+- **Acceptance Criteria:**
+  - If `summary.md` does not exist when pr-final runs, the summary skill is invoked first
+  - If `summary.md` exists and is current, pr-final reads it for the Summary section instead of synthesizing from raw artifacts
+  - PR description remains its own artifact — summary.md is a source, not a replacement
+- **Priority:** P1
+
+**FR4: Summary Integration with Complete**
+
+- **Description:** When `oat-project-complete` runs, it checks for `summary.md` and generates it if missing, using it as the archive cover page.
+- **Acceptance Criteria:**
+  - If `summary.md` does not exist when complete runs, the summary skill is invoked first
+  - Complete does not block on missing summary — it warns and proceeds if the user wants to skip
+  - Summary.md is preserved in the archived project directory
+- **Priority:** P1
+
+**FR5: Post-PR Phase Status (`pr_open`)**
+
+- **Description:** After `oat-project-pr-final` runs, the project state transitions to a new `pr_open` phase status that signals "awaiting human review" rather than "ready for complete."
+- **Acceptance Criteria:**
+  - After pr-final, `state.md` frontmatter shows `oat_phase_status: pr_open`
+  - Next milestone guidance references both `oat-project-revise` (for feedback) and `oat-project-complete` (when approved)
+  - Agents reading state.md in a new session correctly interpret the project as "open for revisions" rather than "done"
+  - `oat-project-complete` accepts `pr_open` as a valid starting status without additional confirmation beyond existing gates
+- **Priority:** P0
+
+**FR6: Revision Skill (`oat-project-revise`)**
+
+- **Description:** A new skill accepts post-PR human feedback and creates revision tasks in the plan, re-entering implementation without starting a new project.
+- **Acceptance Criteria:**
+  - Accepts inline conversational feedback (user describes what they want changed) and creates plan tasks directly without severity classification or triage ceremony
+  - Accepts GitHub PR feedback by delegating to `review-receive-remote`
+  - Accepts review artifact feedback by delegating to `review-receive`
+  - Creates revision phases in plan.md with a clear naming convention
+  - Sets state back to `oat_phase_status: in_progress` and `oat_current_task` to the first revision task
+  - Routes to `oat-project-implement` for execution
+  - After revision tasks complete, returns to `pr_open` status (not `complete`)
+- **Priority:** P0
+
+**FR7: Complete Permissiveness**
+
+- **Description:** `oat-project-complete` works from any phase status without hard-blocking on `pr_open` or any other intermediate state.
+- **Acceptance Criteria:**
+  - Complete accepts `in_progress`, `complete`, and `pr_open` as valid starting states
+  - Existing completion gates (final review, docs sync) remain as warnings, not hard blocks
+  - Summary generation gate follows the same warning pattern — suggest but don't block
+- **Priority:** P0
+
+**FR8: Automatic Subagent Review at Checkpoints**
+
+- **Description:** A configurable option causes plan phase checkpoint completion to automatically spawn a subagent code review, scoped to all phases since the last reviewed checkpoint.
+- **Acceptance Criteria:**
+  - Configuration option exists that can be set at global, repo, or per-project level
+  - When enabled, completing a checkpoint phase spawns a subagent review without manual user invocation
+  - Review scope covers phases since the last reviewed checkpoint (e.g., checkpoints at p02 and p05: completing p02 reviews p01-p02, completing p05 reviews p03-p05)
+  - Final phase checkpoint triggers `code final` scope
+  - When disabled (default), behavior is unchanged from current manual review triggering
+  - The feature works with sequential (single-thread) execution mode — it does not require or switch to subagent-driven mode
+- **Priority:** P1
+
+**FR9: Updated Implement Skill Guidance**
+
+- **Description:** `oat-project-implement` post-completion guidance correctly reflects the new lifecycle states and available next steps.
+- **Acceptance Criteria:**
+  - After final review passes, next-step guidance mentions summary generation, document, and pr-final — not just "create PR"
+  - The implement skill does not set state to "ready for complete" directly — it routes through pr-final which sets `pr_open`
+  - Implement skill correctly handles re-entry from revise (picks up revision tasks, doesn't re-run completed original tasks)
+- **Priority:** P1
+
+### Non-Functional Requirements
+
+**NFR1: Backward Compatibility**
+
+- **Description:** All changes must be backward-compatible with existing projects and workflows.
+- **Acceptance Criteria:**
+  - Projects without `summary.md` complete normally via existing `oat-project-complete` flow
+  - State.md files without `pr_open` status are handled gracefully by all updated skills
+  - Skills that don't know about `pr_open` (e.g., older agent sessions) don't break when encountering it
+- **Priority:** P0
+
+**NFR2: Skill Convention Compliance**
+
+- **Description:** New and modified skills follow existing OAT skill authoring conventions.
+- **Acceptance Criteria:**
+  - New skills have correct frontmatter (name, version, description, disable-model-invocation, user-invocable, allowed-tools)
+  - Progress indicators follow the banner + step indicator pattern
+  - Mode assertion, blocked/allowed activities, and self-correction protocol sections are present
+  - Skills use project resolution and config patterns consistent with existing skills
+- **Priority:** P0
+
+**NFR3: Summary Conciseness**
+
+- **Description:** Summary.md must remain a quick-read artifact even for large projects with multiple revisions.
+- **Acceptance Criteria:**
+  - Revision history section is brief (2-3 sentences per revision round)
+  - Overall summary targets under 200 lines for typical projects
+  - Sections that add no value for a specific project are omitted entirely
+- **Priority:** P1
+
+## Constraints
+
+- Must not break any existing project lifecycle workflow
+- Must not require summary.md for projects that don't want it
+- `pr_open` must be backward-compatible with older state.md files
+- Summary generation must work from any implementation state
+- Revision workflow must work with both inline (no GitHub PR) and GitHub PR review paths
+- Skills must follow existing OAT skill conventions
+- Auto-review must work within the sequential execution model — subagent is for review only, not implementation
+- No new CLI commands required — all changes are at the skill level plus configuration
+
+## Dependencies
+
+- Existing skills: `oat-project-implement`, `oat-project-pr-final`, `oat-project-complete`, `oat-project-review-provide`, `oat-project-review-receive`, `oat-project-review-receive-remote`
+- OAT template system (`.oat/templates/`)
+- OAT configuration system (`oat config get/set`)
+- Project state management (`state.md` frontmatter conventions)
+- Plan task ID conventions (`pNN-tNN` format)
+
+## High-Level Design (Proposed)
+
+The changes extend the existing lifecycle skill chain rather than introducing new architectural patterns. Two new skills are added (`oat-project-summary`, `oat-project-revise`), one new artifact type is introduced (`summary.md`), one new phase status is added (`pr_open`), and three existing skills receive targeted updates (`implement`, `pr-final`, `complete`).
+
+The summary skill reads project artifacts (discovery, design, plan, implementation) and synthesizes a structured summary document. It tracks its own generation state via frontmatter so it can be incrementally updated. PR-final and complete invoke it as a prerequisite when summary.md is missing.
+
+The revision skill is a lightweight router: for inline feedback it creates plan tasks directly; for structured feedback it delegates to the existing review-receive skills. It manages the `pr_open` ↔ `in_progress` state transition and ensures revision phases integrate cleanly with the existing plan structure.
+
+Auto-review at checkpoints is a behavior change in the implement skill gated by a configuration flag. When enabled, the checkpoint pause point spawns a subagent review before presenting results to the user, rather than requiring the user to manually trigger it.
+
+**Key Components:**
+
+- Summary generator — reads artifacts, synthesizes summary, manages frontmatter state
+- Revision router — accepts feedback from multiple sources, creates revision tasks, manages state transitions
+- Phase status extension — `pr_open` as a new valid value for `oat_phase_status`
+- Auto-review trigger — checkpoint behavior in implement skill gated by config
+- Skill updates — targeted changes to implement, pr-final, complete for new state and artifact awareness
+
+**Alternatives Considered:**
+
+- Building summary into `oat-project-complete` directly rather than as a standalone skill — rejected because summary is useful before complete (e.g., for PR description, for posting to Linear) and should be re-runnable independently
+- Using a new `revision` phase instead of `pr_open` status — rejected because revisions are still implementation work, not a separate lifecycle phase; adding a full phase would complicate the state machine unnecessarily
+
+_Design-related open questions are tracked in the [Open Questions](#open-questions) section below._
+
+## Success Metrics
+
+- Summary.md is generated for all new projects that complete through the standard lifecycle
+- Zero instances of agents misinterpreting `pr_open` as "done, start a new project"
+- Post-PR revisions use the revise skill rather than creating new projects or ad-hoc plan modifications
+- Users who enable auto-review report fewer manual review-provide invocations at checkpoints
+- PR descriptions generated after summary.md exists are at least as good as those generated without it
+
+## Requirement Index
+
+| ID   | Description                                           | Priority | Verification                                          | Planned Tasks |
+| ---- | ----------------------------------------------------- | -------- | ----------------------------------------------------- | ------------- |
+| FR1  | Summary artifact generation with 10-section structure | P0       | manual: end-to-end project lifecycle                  | TBD           |
+| FR2  | Summary re-runnability with frontmatter tracking      | P0       | manual: generate, revise, re-generate                 | TBD           |
+| FR3  | PR-final invokes summary if missing, uses as source   | P1       | manual: pr-final with/without existing summary        | TBD           |
+| FR4  | Complete invokes summary if missing, uses as cover    | P1       | manual: complete with/without existing summary        | TBD           |
+| FR5  | `pr_open` phase status after pr-final                 | P0       | manual: verify state.md after pr-final                | TBD           |
+| FR6  | Revision skill with multi-source feedback support     | P0       | manual: inline feedback → tasks → implement → pr_open | TBD           |
+| FR7  | Complete works from any phase status                  | P0       | manual: complete from in_progress, pr_open, complete  | TBD           |
+| FR8  | Auto subagent review at checkpoints                   | P1       | manual: enable config, verify review triggers         | TBD           |
+| FR9  | Updated implement skill guidance                      | P1       | manual: verify next-step routing after final phase    | TBD           |
+| NFR1 | Backward compatibility with existing projects         | P0       | manual: existing projects complete without summary    | TBD           |
+| NFR2 | Skill convention compliance                           | P0       | manual: review skill frontmatter and structure        | TBD           |
+| NFR3 | Summary conciseness under 200 lines                   | P1       | manual: verify summary length on real projects        | TBD           |
+
+## Open Questions
+
+- **Revision phase naming:** Should revision phases use `p-rev1`, `p-rev2` or extend existing numbering? Needs resolution in design — affects plan.md structure and task ID conventions.
+- **Summary template location:** Should `summary.md` template live in `.oat/templates/` or be generated entirely by the skill without a template?
+- **Complete flow ordering:** Where does summary generation sit relative to PR description generation and archive in the complete flow?
+- **Auto-review config key and schema:** Config key name, accepted values, and cascading behavior (global → repo → project).
+- **Auto-review + review-receive chaining:** Should auto-review automatically invoke review-receive after the subagent review, or pause for user decision?
+- **Summary frontmatter schema:** Exact field names and types for tracking summary state.
+
+## Assumptions
+
+- Projects completed before this change will not be retroactively updated with summary.md
+- `pr_open` will be understood by agents via state.md next-milestone text without requiring code changes in the agents themselves
+- Inline revision feedback is conversational — the user describes changes, the agent creates tasks
+- Subagent capability is available in the execution environment when auto-review is enabled
+
+## Risks
+
+- **State complexity:** Adding `pr_open` and revision loops increases possible state transitions.
+  - **Likelihood:** Medium
+  - **Impact:** Medium
+  - **Mitigation:** Keep `pr_open` as guidance only, not a gate. Complete always works. Design clear state transition diagrams.
+
+- **Summary bloat:** Large projects with many revisions could produce overly long summaries.
+  - **Likelihood:** Low
+  - **Impact:** Medium
+  - **Mitigation:** Keep sections concise. Cap revision history at 2-3 sentences per round. Omit empty sections.
+
+- **Skill interaction complexity:** Six skills need coordinated changes.
+  - **Likelihood:** Medium
+  - **Impact:** High
+  - **Mitigation:** Design state transitions clearly. Implement and test skills in dependency order. Verify full lifecycle end-to-end.
+
+- **Auto-review environment dependency:** Requires subagent spawning which may not be available everywhere.
+  - **Likelihood:** Low
+  - **Impact:** Low
+  - **Mitigation:** Opt-in, disabled by default. Falls back to manual review prompt if unavailable.
+
+## References
+
+- Discovery: `discovery.md`
+- Knowledge Base: `.oat/repo/knowledge/project-index.md`
+- Existing skills: `oat-project-implement`, `oat-project-pr-final`, `oat-project-complete`, `oat-project-review-provide`, `oat-project-review-receive`, `oat-project-review-receive-remote`
diff --git a/.oat/projects/shared/project-completion/state.md b/.oat/projects/shared/project-completion/state.md
new file mode 100644
index 000000000..3b414f9bf
--- /dev/null
+++ b/.oat/projects/shared/project-completion/state.md
@@ -0,0 +1,50 @@
+---
+oat_current_task: null
+oat_last_commit: null
+oat_blockers: []
+associated_issues: [] # [{type: backlog|project|jira|linear, ref: "identifier"}]
+oat_hill_checkpoints: ['discovery', 'spec', 'design'] # Configured: which phases require human-in-the-loop lifecycle approval
+oat_hill_completed: ['discovery'] # Progress: which HiLL checkpoints have been completed
+oat_parallel_execution: false
+oat_phase: design # Current phase: discovery | spec | design | plan | implement
+oat_phase_status: in_progress # Status: in_progress | complete
+oat_execution_mode: single-thread # single-thread | subagent-driven
+oat_workflow_mode: spec-driven # spec-driven | quick | import
+oat_workflow_origin: native # native | imported
+oat_docs_updated: null # null | skipped | complete — documentation sync status
+oat_project_created: '2026-03-27T13:22:02.887Z' # ISO 8601 UTC timestamp — set once at project creation
+oat_project_completed: null # ISO 8601 UTC timestamp — set when project is completed/archived
+oat_project_state_updated: '2026-03-27T14:00:00Z' # ISO 8601 UTC timestamp — updated on every state.md mutation
+oat_generated: false
+---
+
+# Project State: project-completion
+
+**Status:** Discovery
+**Started:** 2026-03-27
+**Last Updated:** 2026-03-27
+
+## Current Phase
+
+Specification - Defining formal requirements and acceptance criteria
+
+## Artifacts
+
+- **Discovery:** `discovery.md` (complete)
+- **Spec:** `spec.md` (in_progress)
+- **Design:** Not yet created
+- **Plan:** Not yet created
+- **Implementation:** Not yet created
+
+## Progress
+
+- ✓ Discovery complete
+- ⧗ Specification in progress
+
+## Blockers
+
+None
+
+## Next Milestone
+
+Complete specification and move to design phase
diff --git a/.oat/projects/shared/remote-project-management/linear-integration-discovery-handover.md b/.oat/projects/shared/remote-project-management/linear-integration-discovery-handover.md
new file mode 100644
index 000000000..d4fb6cdf1
--- /dev/null
+++ b/.oat/projects/shared/remote-project-management/linear-integration-discovery-handover.md
@@ -0,0 +1,285 @@
+# Linear Integration Discovery Handover
+
+This document captures the complete context from a brainstorming session about integrating OAT with Linear. It should be fed directly into the existing `remote-project-management` project's discovery phase to resolve open questions and advance toward spec.
+
+---
+
+## Context
+
+The `remote-project-management` project already exists at `.oat/projects/shared/remote-project-management/` with an in-progress discovery. The discovery has open questions about source of truth, auth, sync granularity, and sync triggers. This handover provides answers to those questions and significant additional design thinking that emerged from brainstorming.
+
+The brainstorming session also produced a separate project scope for `summary.md` and post-PR revision workflow improvements. **Those are being handled in a separate project.** This handover covers only the Linear/remote-PM integration concerns.
+
+---
+
+## Answers to Existing Discovery Questions
+
+### Question 1: Source of truth model
+
+**Answer: (d) with nuance — dual system of record.**
+
+- **Linear** is the system of record for: intent, ownership, approvals, status, and portfolio reporting.
+- **OAT** is the system of record for: deeper artifacts and execution traces (discovery.md, spec.md, design.md, plan.md, implementation.md, summary.md).
+- Mirror concise summaries and links back into Linear issue/project docs and updates rather than duplicating full specs in both places.
+- Status transitions in Linear should be driven by **GitHub integration** (branch activity, PR state, merge), not by OAT directly. OAT does not manage Linear status.
+
+### Question 2: Authentication and configuration
+
+**Answer: Use the official Linear MCP server as the primary access layer.**
+
+- The official MCP endpoint is `https://mcp.linear.app/mcp` (not `/sse`, which is deprecated as of Feb 2026).
+- Linear's MCP server supports Claude, Claude Code, Cursor, VS Code, Windsurf, Zed, Codex, v0, and others natively.
+- For authentication, defer to whatever the MCP server requires (typically Linear API key or OAuth token configured in the agent's MCP settings).
+- Credentials managed via MCP config, not stored in OAT files.
+- For supplemental CLI use (human developer ergonomics, not agent-critical), consider `schpet/linear-cli` for its issue→branch→PR loop, or `Finesssee/linear-cli` for broader automation. But the CLI choice is secondary — MCP covers the agent path.
+
+### Question 3: Sync granularity
+
+**Answer: Backlog items ↔ Linear issues, with project-level summary feedback. No plan task sync.**
+
+- **Backlog items ↔ Linear issues**: Bidirectional. A Linear issue can create a backlog item. A backlog item can create a Linear issue.
+- **Project status**: OAT does NOT sync phase transitions to Linear. Linear gets status from GitHub integration (branch push = in progress, PR = in review, merge = done).
+- **Plan tasks → Linear sub-issues**: No. Plan tasks are implementation-granularity (agent work), not ticket-worthy. If someone wants decomposition in Linear, they create sub-issues manually at the feature level.
+- **Summary feedback**: When a project completes, `summary.md` content is posted back to the associated Linear issue(s) as a comment/update. This is the primary "evidence of completion" payload.
+- **Exception**: If a plan phase maps to a meaningful deliverable milestone, that could optionally become a Linear project milestone. But individual tasks within phases should not.
+
+### Question 4: Sync direction and trigger
+
+**Answer: Primarily manual/skill-driven, not event-driven.**
+
+- **Backlog → Linear**: On-demand (`oat-pjm-publish-to-linear` or similar) + on promotion (when a backlog item is promoted to a project, create the Linear issue if one doesn't exist). Not every backlog item should auto-create a Linear issue — some are internal notes or "maybe someday" items.
+- **Linear → Backlog**: Manual intake skill (`oat-linear-intake`) that creates a backlog item from a Linear issue.
+- **Summary → Linear**: Triggered by `oat-project-complete` or a dedicated closeout skill — posts summary.md content to the Linear issue(s).
+- **No webhooks or event-driven bridge** for v1. Agent sessions are ephemeral; a running webhook service is overkill.
+- **No automatic sync on every mutation**. Sync happens at intentional lifecycle moments: intake, promotion, closeout.
+
+---
+
+## Cardinality Model
+
+The relationship between Linear issues, backlog items, and OAT projects is NOT 1:1:1:
+
+- **Linear issue : backlog item** → 1:1 (the intake link; `associated_issues` handles this)
+- **Backlog items : OAT project** → many:1 (multiple related backlog items can be grouped into a single project)
+- **OAT project : Linear issues** → 1:many (one project satisfies multiple Linear issues; completion should close/update all of them)
+
+The `associated_issues` array on both `backlog-item.md` and `state.md` already supports multiple refs. The key change is making those links **do work** — currently they're inert metadata.
+
+---
+
+## Bidirectional Backlog ↔ Linear Issue Sync
+
+### Linear → Backlog (intake)
+
+- A skill (`oat-linear-intake` or similar) reads a Linear issue via MCP and creates a backlog item.
+- Sets `associated_issues: [{type: linear, ref: "TEAM-123"}]` on the backlog item.
+- Populates description and acceptance criteria from the Linear issue content.
+- Runs `oat backlog regenerate-index` after creation.
+
+### Backlog → Linear (publish)
+
+- Not automatic for every item. Triggered:
+  - On-demand via a publish skill
+  - On promotion to project (if no Linear issue exists yet)
+- Creates a Linear issue from the backlog item's title, description, and acceptance criteria.
+- Updates the backlog item's `associated_issues` with the new Linear ref.
+- Should check for duplicates before creating (Linear issue may already exist).
+
+### Provenance tracking
+
+The backlog item template needs a new field to track where items originate:
+
+```yaml
+origin: null  # manual | project:<name> | linear:<id> | intake
+```
+
+This prevents re-creating a Linear issue for something that originated from Linear, and enables tracing the pipeline (this item was spawned during project X, or came in from Linear issue Y).
+
+---
+
+## Deferred Work Capture
+
+During project execution, deferred work is currently captured as free-text in `implementation.md` follow-up sections, then retroactively extracted by `oat-pjm-update-repo-reference`. This should become first-class:
+
+### `oat-pjm-capture-deferred` (lightweight, mid-implementation)
+
+- Takes a one-liner description + optional context
+- Creates a backlog item with sensible defaults (`scope: task`, `priority: medium`)
+- Sets `associated_issues: [{type: project, ref: "current-project-name"}]`
+- Sets `origin: project:<current-project-name>`
+- Logs the capture in `implementation.md` under the current task's follow-ups
+- Returns immediately so implementation continues (no interactive triage ceremony)
+- Optionally publishes to Linear if configured
+
+Then `oat-pjm-update-repo-reference` at closeout becomes a **review and enrich** pass over already-captured items rather than the primary extraction step.
+
+---
+
+## Branch Naming and Linear GitHub Integration
+
+Linear's GitHub integration automatically links branches/PRs to issues when the branch name contains the issue identifier (format: `TEAM-NUMBER`, e.g., `ENG-42`).
+
+Key details:
+- Issue ID can appear **anywhere** in the branch name (case-insensitive)
+- Linear's "Copy git branch name" produces: `username/team-number-slugified-title` (configurable in settings)
+- Multiple identifiers in one branch name are supported
+- Automatic status transitions: branch created → In Progress, PR opened → In Review, PR merged → Done
+
+**Integration point**: When `oat-pjm-promote-to-project` creates a project branch, it should incorporate the Linear issue ID if the backlog item has an associated Linear issue. This gives the GitHub integration everything it needs — no OAT-side status management required.
+
+---
+
+## What OAT Should NOT Do (Let GitHub/Linear Handle)
+
+- **Status transitions**: Don't move Linear issues between states from OAT. GitHub integration handles: branch push → In Progress, PR → In Review, merge → Done.
+- **Plan task decomposition to Linear**: Don't create Linear sub-issues from plan tasks. Plan tasks are agent-granularity work, not team-visible tickets.
+- **Phase-level status updates**: Don't sync OAT phases to Linear. Start without it. If after using it you find you need "in design" vs "in implementation" visibility, it's easy to add later.
+
+---
+
+## What OAT SHOULD Do
+
+1. **Bidirectional backlog ↔ issue sync** — the core data bridge
+2. **Branch naming with Linear issue IDs** — makes GitHub integration work for free
+3. **Summary posted as comment on closeout** — the evidence trail back to Linear
+4. **Deferred work capture** — first-class backlog item creation during implementation
+5. **Provenance tracking** — `origin` field on backlog items to prevent duplicate creation and enable pipeline tracing
+
+---
+
+## Proposed Skill Suite
+
+Listed in recommended build order:
+
+1. **`oat-pjm-promote-to-project`** (no Linear dependency — purely local)
+   - Takes backlog item ID(s) — supports grouping multiple items
+   - Asks which workflow mode (spec-driven / quick / import)
+   - Runs `oat project new` under the hood
+   - Seeds `discovery.md` from backlog item description + acceptance criteria
+   - Sets `associated_issues` on `state.md` (backlog refs + any Linear refs from the items)
+   - Flips backlog item(s) to `in_progress`
+   - Creates branch with Linear issue ID in name if available
+   - Regenerates backlog index
+
+2. **`oat-pjm-capture-deferred`** (no Linear dependency — purely local)
+   - Lightweight mid-implementation deferred work capture
+   - Creates backlog item with defaults + project provenance
+   - Logs in implementation.md
+   - Returns immediately
+
+3. **`oat-linear-intake`** (first Linear touchpoint)
+   - Reads Linear issue via MCP
+   - Creates backlog item with `associated_issues: [{type: linear, ref: "TEAM-123"}]`
+   - Sets `origin: linear:TEAM-123`
+
+4. **`oat-linear-publish`** (backlog → Linear)
+   - Creates Linear issue from backlog item
+   - Updates backlog item with Linear ref
+   - Duplicate detection before creation
+
+5. **`oat-linear-post-summary`** (closeout feedback)
+   - Reads `summary.md` from completed project
+   - Posts structured comment to associated Linear issue(s)
+   - Does NOT change Linear issue status (merge handles that)
+
+6. **`oat-linear-link`** (manual association)
+   - Links an existing backlog item to an existing Linear issue (or vice versa)
+   - Updates `associated_issues` on the backlog item
+   - Bidirectional — can start from either side
+
+---
+
+## Linear-Specific Context for Discovery
+
+### Linear's Current AI/MCP Surface (as of March 2026)
+
+- **Feb 5, 2026**: MCP expanded to initiatives, project milestones, project updates, project labels, URL/image loading. Deprecated `/sse` in favor of `/mcp`.
+- **Feb 26, 2026**: Added direct deeplinks from issues into coding tools with customizable prompt templates.
+- **Mar 24, 2026**: Launched Linear Agent with reusable skills and automations.
+- Linear's MCP also improved documentation and reduced token usage in Feb 2026.
+
+**Implication**: Don't build custom CRUD. The official MCP covers the access layer. OAT's custom skills should encode workflow rules (discovery-before-creation, artifact mapping, delegation readiness, progress reporting, closeout) — not replace basic Linear operations.
+
+### Linear Data Model Notes (for mapping design)
+
+- Issue identifiers: `TEAM-NUMBER` format (e.g., `ENG-42`)
+- Issues belong to exactly one team
+- Issues can belong to at most one project at a time
+- Sub-issues inherit project/cycle context from parent
+- Projects support milestones, docs, updates (health/progress)
+- Initiatives group multiple projects under one objective
+- Custom views are filter-based, shareable, support list/board layouts
+- Triage is the intake buffer — supports Triage Intelligence for auto-routing
+- Agent guidance can be set at workspace and team level
+
+### Status Mapping (for Open Question in existing discovery)
+
+| OAT backlog status | Linear status category |
+|---|---|
+| `open` | Backlog or Triage (unstarted) |
+| `in_progress` | Started (In Progress) |
+| `closed` | Completed (Done) |
+| `wont_do` | Canceled |
+
+Linear has 5 categories: Triage, Backlog, Unstarted, Started, Completed, Canceled. OAT's 4 statuses map cleanly. The nuance is Triage vs Backlog vs Unstarted — all three are "not started yet" from OAT's perspective (`open`).
+
+### Priority Mapping
+
+| OAT priority | Linear priority |
+|---|---|
+| `urgent` | 1 (Urgent) |
+| `high` | 2 (High) |
+| `medium` | 3 (Medium) |
+| `low` | 4 (Low) |
+| `none` | 0 (No priority) |
+
+---
+
+## Relationship to Other In-Progress Work
+
+### Summary.md Project (separate, being handled independently)
+
+A separate project is handling:
+- `summary.md` as a new first-class project artifact
+- `oat-project-summary` skill (standalone, re-runnable)
+- `oat-project-revise` skill (post-PR revision workflow)
+- `pr_open` phase status
+- Integration of summary into pr-final and complete
+
+**The Linear integration depends on summary.md existing** — `oat-linear-post-summary` reads summary.md to post back to Linear. So the summary project should complete first or in parallel.
+
+### Backlog Promote to Project (shared dependency)
+
+`oat-pjm-promote-to-project` is needed by both the summary/revision project (as a general workflow improvement) and the Linear integration (for Linear-aware branch naming). It should be built as part of whichever project starts first.
+
+---
+
+## Constraints (Updated from Existing Discovery)
+
+- Must not break existing local PM workflows
+- Credentials managed via MCP config, not stored in OAT files
+- Agent sessions are ephemeral — no long-running processes or webhooks for v1
+- Should accommodate future providers beyond Linear (GitHub Issues, Jira, Notion) via the existing polymorphic `associated_issues` model
+- Linear MCP is the access layer — don't build custom GraphQL/REST clients for v1
+- Status transitions owned by GitHub integration, not OAT
+- Branch naming must include Linear issue ID for GitHub integration to work
+
+---
+
+## Risks (Updated)
+
+- **MCP surface may not cover all needed operations**: The official MCP is broad but may lack specific operations (e.g., posting a structured comment with specific formatting). Mitigation: test the MCP surface early in implementation; fall back to a thin SDK wrapper only if needed.
+- **Bidirectional sync complexity**: Even with manual triggers, syncing backlog items ↔ Linear issues can produce conflicts if both are edited independently. Mitigation: start with clear ownership (intake = Linear wins, publish = OAT wins) and add conflict detection later.
+- **Branch naming convention enforcement**: If users don't use promote-to-project, branches won't have Linear IDs. Mitigation: make it the recommended path, but don't hard-enforce it.
+
+---
+
+## Recommended Next Steps for Discovery
+
+1. Resolve the existing discovery questions using the answers above
+2. Validate the cardinality model (many backlog items : 1 project : many Linear issues)
+3. Validate the "no plan task sync" decision
+4. Validate the "no status management from OAT" decision
+5. Design the `associated_issues` extensions needed (provenance/origin field)
+6. Design the branch naming convention for promote-to-project
+7. Move to spec once discovery questions are resolved