pi-dev-team 0.2.0

package/skills/gherkin-public/SKILL.md

@@ -0,0 +1,266 @@
+---
+name: gherkin-public
+description: >-
+  Author Gherkin scenarios for the entire public interface of a repository
+  — every API endpoint, UI screen, batch-job entry point, library export,
+  and event type — at the observable boundary, not internal steps. The
+  scenarios become the executable specification of intended behavior before
+  any test or production-code change lands. After the operator approves the
+  scenarios at the Phase-2 gate, this skill also creates the Phase-4 and
+  Phase-5 `[Component tests]` Stories that will bind their test code to
+  specific scenario names — so the component tests are written from the
+  approved Gherkin, not from the assessment.
+argument-hint: "<repo-path> [--repo-slug <slug>] [--parent <issue-url>] [--create-stories]"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash, Write
+---
+
+# Gherkin Public
+
+Role: worker. Standalone Gherkin authoring skill. Reads the component map produced by `/cd-test-architecture` and writes `.feature` files at the **public boundary** of each component — the surface an external caller actually depends on. Internal steps are out of scope here; scenarios describe observable outputs.
+
+You have been invoked with the `/gherkin-public` command.
+
+## Parse Arguments
+
+Arguments: $ARGUMENTS
+
+- Positional: `<repo-path>` — the repo under modernization.
+- `--repo-slug <slug>` — namespace under `.claude/memory/<workflow>/`. Defaults to the last path segment of `<repo-path>`.
+
+If `<repo-path>` is absent, ask the operator.
+
+## Steps
+
+### 1. Load the component map
+
+Read `.claude/memory/<workflow>/<slug>/phase-1.md` for the components & patterns table. If it's missing, tell the operator Phase 1 has not run and stop.
+
+### 2. Pick the output directory
+
+- Prefer `features/<workflow>/` if `<repo>/features/` already exists (matches the repo's existing Gherkin layout).
+- Otherwise write to `<repo>/specs/<workflow>/`.
+- Create the directory if missing.
+
+### 3. Author scenarios per public surface
+
+For each component in the map, generate one `.feature` file per public surface using the pattern's template. Every scenario MUST cover at least one success and one failure path. Every scenario MUST be observable at the boundary — no scenario describes an internal call.
+
+**Grounding scenarios in real behavior.** The component map names each surface but not its actual branches or error-handling depth. Prefer CodeGraph/Repowise over raw `Grep` to inspect a surface's real failure conditions before writing its failure scenario, rather than inferring one from the surface name alone — see [`knowledge/codegraph-vs-graphify.md`](../../knowledge/codegraph-vs-graphify.md) for tool selection and the fallback contract.
+
+**Titles must be specific enough to identify the surface without relying on the `Feature:` header for context (issue #1526).** A `Scenario:` title read in isolation — in a CI report, a BDD runner's scenario list, or a coverage dashboard — must be recognizable as belonging to its specific surface, not a generic category label that could describe any endpoint (e.g. `returns error for invalid input`, `handles success case`). Prefer wording that names the concrete condition or resource involved (e.g. `rejects the request when the id path parameter is non-numeric`, `returns the created order with a 201 and Location header`) over a bare category name. A title that is merely a paraphrase of the surface name (the same words as the `Feature:` line, reworded) fails this rule.
+
+**API Provider** (one `.feature` per endpoint):
+
+```gherkin
+Feature: <method> <path>
+  As an external API consumer
+  I want <documented behavior>
+  So that <user value>
+
+  Scenario: <success-path-summary>
+    Given <request shape + auth context>
+    When the client calls <method> <path>
+    Then the response status is <code>
+    And the body conforms to <schema reference>
+
+  Scenario: <failure-mode-summary, per the assessment's failure-modes list>
+    Given <invalid request>
+    When the client calls <method> <path>
+    Then the response status is <code>
+    And the error body includes <field>
+```
+
+**User Interface** (one `.feature` per user-facing flow):
+
+```gherkin
+Feature: <flow name>
+  As a <user role>
+  I want <task>
+  So that <outcome>
+
+  Scenario: <happy path>
+    Given <starting screen + preconditions>
+    When the user <observable action sequence>
+    Then the user sees <observable outcome>
+    And the URL is <route> (or app state is <state>)
+
+  Scenario: <validation / error path>
+    Given <invalid input>
+    When the user submits
+    Then the user sees <error message>
+    And no destructive change has occurred
+```
+
+**Batch / Scheduled Job** (one `.feature` per job; the entry point is the surface):
+
+```gherkin
+Feature: <job name> — scheduled entry point
+
+  Scenario: <success path — full input → expected outputs>
+    Given the input source contains <fixture rows / messages>
+    When the job is triggered at its scheduled entry point
+    Then the job exits with code 0
+    And the output sink contains <expected rows / files / events>
+    And the run-metrics show <count> processed
+
+  Scenario: <partial-failure path>
+    Given the input source contains <N valid + M invalid rows>
+    When the job is triggered
+    Then the job exits with code <non-zero per the contract, or 0 with reported errors>
+    And the dead-letter sink contains the M invalid rows
+    And no valid row was dropped
+```
+
+**CLI / Library** (one `.feature` per command or exported function):
+
+```gherkin
+Feature: <command-or-function>
+
+  Scenario: <documented success>
+    Given <preconditions / stdin / args>
+    When the caller invokes <cmd-or-fn> with <args>
+    Then the exit code is <n> (or the return value is <shape>)
+    And stdout contains <pattern>
+
+  Scenario: <documented error>
+    Given <invalid input>
+    When the caller invokes <cmd-or-fn>
+    Then the exit code is <non-zero>
+    And stderr contains <message>
+```
+
+**API / Event Consumer** (one `.feature` per outbound call or emitted event):
+
+```gherkin
+Feature: <component> emits <event-type>
+
+  Scenario: <triggering input → expected emission>
+    Given <inbound trigger>
+    When the component processes it
+    Then an event of type <type> is emitted to <sink>
+    And the event body matches <schema>
+```
+
+**Event Producer / Stateful Service** — combine the API Provider and Event Consumer templates as appropriate.
+
+### 4. Cite the assessment
+
+In every `.feature` file's header, include:
+
+```
+# Source: .claude/memory/<workflow>/<slug>/phase-1.md
+# Component: <name>
+# Pattern: <pattern>
+# Public surface: <surface-id>
+```
+
+This lets the operator trace each scenario back to a component row at the Phase-2 human sign-off (Step 6), and lets `/feature-file-validation` — which `/code-review` invokes automatically whenever `.feature` or step-definition files are in the changeset — verify each scenario has matching test automation once the bound Stories are built.
+
+### 4b. Adversarial Gherkin Quality Review
+
+Dispatch the adversarial review against Step 3's authored `.feature` files
+unconditionally — this skill has no `none` mode, so every completed Step 3
+authors at least one `.feature` file, and no operator opt-in is required.
+This runs **before** Step 5 (Persist phase-2 progress) and before the Step 6
+human sign-off, so the operator sees the dual-agent findings alongside the
+scenario inventory at the sign-off decision point.
+
+Follow `knowledge/gherkin-quality-review-dispatch.md` for the shared dispatch,
+aggregation, failure-handling, and zero-findings mechanics — this step states
+only what's specific to `/gherkin-public`: each of the two
+`gherkin-quality-critic` instances receives, for every surface reviewed, that
+surface's `.feature` file content plus its Step 4 header (`# Source:`,
+`# Component:`, `# Pattern:`, `# Public surface:`). The resulting
+`agreed`/`single-source` buckets feed Step 8's two new report sections.
+
+### 5. Persist phase-2 progress
+
+Write `.claude/memory/<workflow>/<slug>/phase-2.md` with:
+
+- Number of `.feature` files written + their paths.
+- Surface coverage per component (one row per component: surfaces touched / surfaces total).
+- Any components for which the operator must hand-author scenarios (e.g. heavy UI flows the worker could not derive from the map alone) — call these out explicitly.
+- The scenario inventory: per component, the full list of `<feature-file>::<scenario-name>` pairs.
+
+### 6. STOP for human sign-off
+
+This is the Gherkin-review human gate the calling orchestrator (when one is used) enforces. Print the scenario inventory and wait. Do NOT proceed to Step 7 (Story creation) until the operator signs off on the scenarios. The Gherkin is the executable spec — Stories that bind to it must not be created from un-reviewed scenarios.
+
+### 7. Create `[Component tests]` Stories bound to the approved scenarios
+
+Once the operator has approved the scenarios (orchestrator passes `--create-stories` or `/gherkin-public` is re-invoked after approval), create one `[Component tests]` Story per (component, surface) pair via the resolved tracker CLI from Phase 0:
+
+- **Title:** `[Component tests] <component> · <surface-id>` (e.g. `[Component tests] orders-api · POST /orders`).
+- **Phase tag:** `Phase-4` when the surface is fully reachable at existing seams (per the seam-reachability table in `phase-1.md`); `Phase-5` when one or more scenarios require a `[Refactor-for-testability]` Story.
+- **Predecessor links:**
+  - `[Baseline]` for the same component (from Phase 1) — baseline before tests.
+  - For Phase-5 Stories, also the matching `[Refactor-for-testability]` Story for any scenario that requires the refactor.
+- **Body — Acceptance Criteria (this is the binding):**
+
+  ```markdown
+  ## Approved Gherkin scenarios (binding contract)
+
+  All scenarios below MUST have a passing test in this Story. Each test:
+  - cites the source `.feature` file + scenario name in its name or a leading comment;
+  - exercises the scenario via the public surface (no internal-step assertions);
+  - runs deterministically with no off-machine dependencies (airplane test);
+  - lands at the **component** layer per the MinimumCD taxonomy.
+
+  Source: `features/<workflow>/<surface>.feature`
+
+  - [ ] `Scenario: <success-path-summary>`
+  - [ ] `Scenario: <failure-mode-summary>`
+  - [ ] `Scenario: <…>`
+
+  ## Testing approach
+
+  Binding mode: `<bdd-runner | xunit-with-annotations>` (from Phase 0).
+
+  - `bdd-runner` — generate step definitions for the scenarios above using the project's BDD runner (cucumber-js / pytest-bdd / behave / cucumber-jvm / SpecFlow / godog). Step definitions go under the project's existing step-defs directory.
+  - `xunit-with-annotations` — write one xUnit-style test method per scenario. The test method name SHALL mirror the scenario name (e.g. `Scenario: rejects invalid total` → `test_rejects_invalid_total()` / `RejectsInvalidTotal()` / etc.). The Given / When / Then become structured comments at the top of each test body, citing the feature file path.
+
+  ## Doubles
+
+  <In-memory doubles for third-party dependencies + local containers / loopback for team-owned infrastructure. No off-machine calls.>
+  ```
+
+Record the **scenario → Story-id** map in `.claude/memory/<workflow>/<slug>/gherkin-bindings.json`:
+
+```json
+{
+  "features/<workflow>/orders-post.feature::accepts valid order": 311,
+  "features/<workflow>/orders-post.feature::rejects invalid total": 311,
+  "features/<workflow>/orders-get.feature::returns existing order": 312,
+  …
+}
+```
+
+Append the Story creations to `phase-2.md` (one row per Story: title, phase tag, scenario count, tracker-id, predecessors). The map lets the operator confirm at the Phase-2 human sign-off that every Scenario has a Story citing it, and lets `/quality-targets-converge` check for an existing binding before proposing a new component-test Story for a coverage gap it finds later.
+
+### 8. Report
+
+Print:
+
+- Output directory used.
+- N `.feature` files written.
+- Any components flagged for hand-authoring.
+- N `[Component tests]` Stories created with scenario-binding count per Story.
+- The phase-2 progress file path and the `gherkin-bindings.json` path.
+
+**Print Step 4b's two Gherkin quality sections — "Agreed Gherkin quality
+findings" and "Single-source (unconfirmed) Gherkin quality findings" —
+distinct from the hand-authoring-flagged-components callout above:** follow
+`knowledge/gherkin-quality-review-dispatch.md`'s Report section format for the
+exact per-finding line format, the zero-findings sentence, and the
+failure-handling wording.
+
+## Notes
+
+- This skill runs in **two passes**, separated by the Phase-2 human gate:
+  1. First pass (Steps 1–6) authors the `.feature` files and stops for sign-off.
+  2. Second pass (Step 7), invoked by the orchestrator with `--create-stories` after the operator approves, creates the `[Component tests]` Stories bound to the approved scenarios. Splitting the passes ensures the Stories never reference un-reviewed scenarios.
+- The Stories produced here become the binding contract `/build` consumes in Phase 4 and Phase 5. Each Story's body cites the exact scenarios its tests must satisfy — the component tests are written **from the approved Gherkin**, not from the assessment.
+- `gherkin-bindings.json` is the inverse map (scenario → Story). The operator uses it at the Phase-2 human sign-off to confirm every Scenario in every `.feature` has a Story citing it; `/quality-targets-converge` consults it before proposing a new component-test Story for a coverage gap (see its "Gherkin binding for proposed component tests" step); and `/feature-file-validation` — run automatically by `/code-review` whenever `.feature` files are in the changeset — verifies each `[Component tests]` Story's submitted test code actually references its bound scenarios.
+- For UI patterns where the worker cannot infer the flow from the assessment alone, emit a stub `.feature` with the required header and a `# TODO: hand-author scenarios here` block — better to surface the gap than to invent steps. Stub `.feature` files do NOT generate Stories until the operator fills them in.
+- **Depth-audit finding (issue #1450): no behavior change here.** `/gherkin-derive` was made to mandatorily analyze controllers, handlers, services, domain logic, workflows, validation rules, error handling, and business processes in depth, because it derives scenarios directly from code with no prior analysis pass. This skill does not: Step 1 reads a pre-built component map (`/cd-test-architecture` Phase 1) rather than discovering surfaces itself, so the in-depth analysis this skill's scenarios rely on already happened upstream, in Phase 1 — transplanting `/gherkin-derive`'s directive here would either duplicate that upstream work or silently mask a gap that actually belongs to `/cd-test-architecture`'s own analysis depth (out of this issue's scope; flagged as a possible follow-up for a human to open separately).

package/skills/governance-compliance/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: governance-compliance
+description: Audit logging, quality gates, and ethics procedures for the agent team. Use for periodic compliance reviews, when logging task completion events, or when an ethical concern arises that requires human escalation.
+role: worker
+user-invocable: true
+---
+
+# Governance & Compliance
+
+## Overview
+
+Requirements and procedures for audit logging, multi-layer quality assurance, and ethical operation of the agent team. Ensures all agent activity is traceable, quality is validated at multiple levels, and ethical principles are maintained.
+
+## Constraints
+
+- The audit changelog is append-only; never modify or delete existing entries
+- Never log credentials, API keys, or PII in `.claude/metrics/` or `.claude/memory/` files
+- All agent decisions must be explainable on request — no black-box outputs
+- Ethical concerns are never auto-resolved; always escalate to the human
+
+## Audit & Transparency
+
+### What Must Be Logged
+
+| Event | Log Location | Retention |
+| --- | --- | --- |
+| Task start/completion | `.claude/metrics/{date}-task-log.jsonl` | 90 days |
+| Configuration change | `.claude/metrics/config-changelog.jsonl` | Indefinite |
+| Human approval/override | `.claude/metrics/config-changelog.jsonl` — `proposed`/`evidence_shown`/`risks_surfaced` required (schema: [human-oversight-protocol § Audit trail](../human-oversight-protocol/SKILL.md#audit-trail)) | Indefinite |
+| Hallucination detection | Task log entry (`hallucination_detected` flag) | 90 days |
+| Context summarization | `.claude/memory/{date}-{task-slug}.md` | 90 days (30 active + 60 archive) |
+
+### Audit Trail Principles
+
+- **Append-only**: Log entries are never modified or deleted
+- **Timestamped**: Every entry has an ISO 8601 timestamp
+- **Attributed**: Every entry identifies which agent acted and who approved
+- **Complete**: No decision-making gap should exist between log entries
+- **Reconstructable**: For every `approval`/`override` gate-decision entry, the
+  decision, the proposal, the evidence, and the surfaced risks must all be
+  recoverable from the entry alone — see [human-oversight-protocol § Audit trail](../human-oversight-protocol/SKILL.md#audit-trail)
+  for the field schema. Entries predating this schema (no `proposed`/`evidence_shown`/
+  `risks_surfaced`) remain valid — never migrated — and are not reconstructable
+  to this standard; treat them as historical, not as a compliance gap.
+
+### Compliance Queries
+
+To answer "why did the system do X?", trace through:
+
+1. Task log: which agents were involved
+2. Config changelog: what configuration was active at the time
+3. Memory summaries: what context the agents were working with
+
+For a gate decision specifically ("what was this approval/override based on?"),
+also check gate-record completeness: does the `approval`/`override` entry carry
+`proposed`, `evidence_shown`, and `risks_surfaced`? An entry missing all three is
+either a pre-schema entry (acceptable) or a write site that skipped the schema
+(a gap — see human-oversight-protocol's Audit trail for the required write
+sites).
+
+## Quality Assurance
+
+### Multi-Layer Validation
+
+Quality is enforced at four progressive layers:
+
+#### Layer 1: Agent Self-Validation
+
+- Every agent applies the [Quality Gate Pipeline](../quality-gate-pipeline/SKILL.md) before delivering output
+- Confidence scoring on all major claims
+- Tool-based verification for factual claims (file paths, APIs, data)
+
+#### Layer 2: QA Agent Validation
+
+When applicable (code generation, data analysis, architecture changes):
+
+- QA agent reviews output against acceptance criteria
+- Automated test generation and execution for code
+- Consistency checks against existing codebase
+
+#### Layer 3: Human Spot-Check
+
+- User reviews delivered output
+- Feedback captured via accept/reject/amend
+- Patterns in rejections feed back through [Feedback & Learning](../feedback-learning/SKILL.md)
+
+#### Layer 4: Post-Hoc Monitoring
+
+- Orchestrator reviews task metrics during learning loop
+- Identifies trends: rising rework rate, hallucination frequency, cost outliers
+- Triggers configuration amendments when patterns emerge (minimum 3 occurrences)
+
+### Quality Gates
+
+No task output is delivered until it passes applicable quality gates:
+
+| Task Type | Required Gates |
+| --- | --- |
+| Code implementation | Self-validation + QA review (if available) |
+| Architecture design | Self-validation + human approval |
+| Documentation | Self-validation + terminology consistency check |
+| Bug fix | Self-validation + regression test |
+| Data analysis | Self-validation + statistical validation |
+
+## Ethics & Responsibility
+
+### Core Principles
+
+1. **Human accountability**: Humans are ultimately responsible for all outputs. Agents assist and recommend; humans decide and own.
+2. **Explainability**: Every agent decision must be explainable. No "black box" outputs. When asked why, the agent must provide rationale.
+3. **Bias awareness**: Agents must flag when their output may be influenced by training biases, especially in:
+   - Technology recommendations (may favor popular over appropriate)
+   - Estimation (may anchor to common patterns)
+   - Design decisions (may default to familiar architectures)
+4. **Privacy**: Agents must not log, store, or transmit sensitive data (credentials, PII, API keys) in metrics or memory files.
+5. **Proportionality**: Agent autonomy should match the risk level of the task. Higher risk = more human oversight.
+
+### Sensitive Data Handling
+
+| Data Type | Rule |
+| --- | --- |
+| Credentials, API keys | Never log, never store in .claude/memory/ or .claude/metrics/ |
+| PII (names, emails, etc.) | Do not include in metrics entries or summaries |
+| Business-sensitive data | Minimize in summaries; use references to source files instead |
+| Source code | May be included in summaries when relevant to task continuity |
+
+### When Ethical Concerns Arise
+
+1. Agent identifies the concern and pauses
+2. Flags to Orchestrator with: what the concern is, why it matters, what the options are
+3. Orchestrator escalates to human (always - ethical concerns are never auto-resolved)
+4. Human decides
+5. Decision is logged with full rationale
+
+## Output
+
+Compliance checklist results (pass/fail per item) and/or new audit log entries written to `.claude/metrics/`. Be concise — report failures and entries written; omit passing items.
+
+## Compliance Checklist
+
+For periodic review (monthly recommended):
+
+- [ ] All tasks in the review period have corresponding log entries
+- [ ] No gaps in the config changelog
+- [ ] Gate-record completeness: `approval`/`override` entries from this period carry `proposed`/`evidence_shown`/`risks_surfaced` (pre-schema entries are exempt, not counted as gaps)
+- [ ] Memory summaries exist for long-running tasks
+- [ ] No sensitive data present in .claude/metrics/ or .claude/memory/ files
+- [ ] Hallucination rate reviewed qualitatively (no sensor yet — see CLAUDE.md "Claims discipline")
+- [ ] Rework rate trend is stable or improving
+- [ ] All human overrides have been reviewed for systemic issues

package/skills/guard/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: guard
+description: >-
+  Activate both careful mode and freeze mode together. Blocks destructive
+  commands and scope-locks editing to the specified pattern. Use for
+  production-critical debugging sessions.
+argument-hint: "<glob-pattern>"
+user-invocable: true
+allowed-tools: Write, Read
+---
+
+# Guard
+
+Role: worker. Combined safety mode: careful + freeze.
+
+You have been invoked with the `/guard` command.
+
+## Worker constraints
+
+1. Compose /careful + /freeze; introduce no new blocking behavior.
+2. Do not edit source.
+3. **Be concise.** Confirm both modes in one line each.
+
+## Parse Arguments
+
+Arguments: $ARGUMENTS
+
+- Positional: `<glob-pattern>` (required) — glob pattern for files that ARE allowed to be edited
+
+If no pattern is provided, display usage and exit:
+> Usage: `/guard <glob-pattern>`
+> Example: `/guard src/auth/**` — blocks destructive commands AND limits edits to `src/auth/`.
+> Use `/careful off` and `/unfreeze` separately to disable, or pass `off` to disable both.
+
+If argument is `off`:
+
+1. Remove `.claude/hooks/careful-state.json` and `.claude/hooks/freeze-state.json`
+2. Display: "Guard mode OFF. All safety restrictions lifted."
+
+## Steps
+
+### 1. Enable careful mode
+
+Write to `.claude/hooks/careful-state.json` (repo-scoped — see the `/careful`
+skill's Notes for why this is not `hooks/careful-state.json`; issue #1900):
+
+```json
+{
+  "active": true,
+  "enabled_at": "<ISO timestamp>"
+}
+```
+
+### 2. Enable freeze mode
+
+Write to `.claude/hooks/freeze-state.json` (repo-scoped — see the `/freeze`
+skill's Notes for why this is not `hooks/freeze-state.json`; issue #1890):
+
+```json
+{
+  "active": true,
+  "allowed_patterns": ["<glob-pattern>"],
+  "frozen_at": "<ISO timestamp>"
+}
+```
+
+### 3. Confirm
+
+Display:
+> Guard mode ON.
+>
+> - Destructive commands: BLOCKED
+> - File editing: Locked to `<pattern>`
+>
+> Use `/guard off` to disable both, or `/careful off` / `/unfreeze` individually.

package/skills/handoff/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: handoff
+description: Compress or split off context for another session to pick up. Use to compress conversation history when context utilization approaches 40% (continue mode), or to split off a distinguishable out-of-scope side-task to an independent session (fork mode) — write a structured artifact for the other session and free the current one.
+role: orchestrator
+user-invocable: true
+---
+
+# Handoff
+
+One skill, two modes, for getting structured context to another session instead of replaying history:
+
+- **Continue mode** — compress *this* task's history so the *same* task can keep going past the context ceiling, in a fresh window.
+- **Fork mode** — split off a distinguishable, out-of-scope side-task into an *independent* session (a parallel sibling, or a child that later hands learnings back), without diluting or compacting the current session's context.
+
+Both modes apply the same Three Gates (below) to decide what to keep, compress, and discard — that logic is written once and shared by both modes.
+
+## Mode Selection
+
+Keyed off whether a **stated purpose** exists for an independent/fresh session:
+
+| Signal | Mode |
+| --- | --- |
+| No stated purpose — continuing the current task past the ceiling | **Continue** (default, unchanged behavior) |
+| A stated purpose for a distinguishable, out-of-scope side-task | **Fork** |
+| Ambiguous — unclear whether this is the same task or a split-off | Ask: "Continue this task in a fresh window, or split off unrelated work to an independent session?" |
+
+## Constraints
+
+- Summaries/handoff artifacts replace conversation history; never reload prior turns
+- Never include credentials, PII, or other sensitive data in written output — see Redaction below
+- Output must be sufficient for the receiving session to start without replaying history
+
+## The Three Gates
+
+Apply in order to all context older than the last 3-5 turns, in both modes:
+
+### 1. Forget Gate -- Discard
+
+- Exploratory dead ends and rejected approaches
+- Verbose tool outputs where only the conclusion matters
+- Superseded decisions
+- Debugging steps for resolved issues
+
+### 2. Input Gate -- Preserve
+
+- Current task definition and acceptance criteria
+- Active architectural decisions and rationale
+- Unresolved questions or blockers
+- File paths and line numbers being worked on
+- User preferences and feedback from this session
+
+### 3. Output Gate -- Keep Verbatim
+
+- Last 3-5 conversation turns
+- Code actively being modified
+- Error messages being debugged
+- Current agent persona and skill guidelines (if loaded)
+
+## Redaction
+
+Before writing any output in either mode, redact secrets, API keys, tokens, and PII from the content. Fork-mode output leaves the repo-adjacent trust boundary (an OS temp dir another session reads), so redaction is mandatory there. Continue-mode output stays under `.claude/memory/` inside the repo, but apply the same redaction pass for consistency — a secret that shouldn't be in conversation history shouldn't be in a committed-adjacent file either.
+
+## Continue Mode
+
+Compress conversation history to keep context utilization below 40% while continuing the *same* task in a fresh window.
+
+### When to Summarize
+
+`/handoff` is manual: nothing forces or blocks on it. Reach for it when a
+deliberate, structured summary beats the harness's generic compaction:
+
+- before a long phase ends, so the next phase starts from a reviewable
+  `.claude/memory/` file rather than replayed history;
+- when you notice the session is heavy (many file reads accumulated, turn
+  count above about 40, degraded output quality) and want to choose what
+  survives;
+- before a planned break in the work.
+
+The harness compacts on its own at the percentage `/dev-team:setup` configures
+(default 40%); a `/handoff` summary written first is the structured
+alternative to that generic summary.
+
+**Measuring utilization**: `utilization = (input + cache_read + cache_creation) / model_context_window`, from the most recent assistant-message usage in the session transcript.
+
+**Why 40%, not a higher number**: see [Context Loading Protocol → Why 40%](../context-loading-protocol/SKILL.md#why-40).
+
+### Writing Summaries
+
+- **Destination**: `.claude/memory/{date}-{task-slug}.md`
+- **Scope**: full relevant history for the task
+- **Requires**: nothing extra — the task is already known
+
+Write the summary using the Task Summary template in `references/summary-templates.md`.
+
+### Phase Progress Files
+
+Each phase produces a progress file that onboards the next phase's agent without replaying history. Write the progress file using the appropriate phase template (Research, Plan, or Implementation) from `references/summary-templates.md`.
+
+### Using Summaries in New Conversations
+
+1. Read the most recent summary from `.claude/memory/`
+2. Load only **Key Context for Continuation** into active context
+3. Load referenced files on demand, not upfront
+4. Do NOT reload full conversation history -- the summary replaces it
+
+### Cleanup (Time-Based)
+
+1. Archive summaries older than 30 days to `.claude/memory/archive/`
+2. Delete archived summaries older than 90 days
+3. Consolidate multiple summaries for the same task into one
+
+## Fork Mode
+
+Split off a distinguishable, out-of-scope side-task into an independent session — a sibling running in parallel, or a child (e.g. a prototype session) that later hands learnings back — without diluting or compacting the current session.
+
+### Requires a Stated Purpose
+
+Fork mode always needs a one-line purpose describing the side-task. If the user hasn't stated one, ask for it before writing anything — an unpurposed fork artifact can't be scoped correctly by the Forget/Input/Output gates above.
+
+### Writing the Fork Artifact
+
+- **Destination**: the OS temp dir (e.g. `$TMPDIR` or the platform default), never `.claude/memory/` — the artifact is disposable and not part of the repo's durable history
+- **Scope**: just the slice of context relevant to the stated purpose, not the full session history
+- **Naming**: `{tmpdir}/handoff-{purpose-slug}-{date}.md`
+
+Use the **Fork Handoff** template in `references/summary-templates.md`, which adds these sections beyond the Task Summary:
+
+- **Suggested Skills** — skills the receiving session likely needs loaded for the stated purpose, so it doesn't have to rediscover them.
+- **Pointers, not duplication** — link to or cite content that already exists in other artifacts (files, prior summaries, design docs) instead of copying it into the fork doc. The fork doc should compose with existing artifacts, not fork a second copy of them.
+- **Hand-back** (when the fork will report results back to this session) — what the parent session needs from the child when it's done: a short result summary and pointers to what changed, in a shape the parent can merge without replaying the child's history.
+
+### Cleanup (Event-Based, Never Time-Based)
+
+Fork-mode artifacts are deleted **on consumption**, not on a schedule:
+
+- The receiving session merges its result back into the parent — delete the fork artifact once the merge is confirmed.
+- The parent session reads a hand-back doc from a completed child — delete the hand-back doc once it has been read.
+
+Never apply the continue-mode 30/90-day time-based cleanup to fork-mode output — an unconsumed fork artifact should persist until it's actually picked up, and a consumed one should not linger waiting for a sweep.