hatch3r 1.8.0 → 2.0.0

package/commands/hatch3r-context-health.md

@@ -1,147 +0,0 @@
----
-id: hatch3r-context-health
-type: command
-orchestrator: false
-description: Monitor conversation context health, detect degradation, and auto-suggest fresh context or sub-agent delegation
-tags: [maintenance]
-quality_charter: agents/shared/quality-charter.md
-efficiency_patterns: agents/shared/efficiency-patterns.md
-cache_friendly: true
-parallel_tool_default: true
----
-
-## §0 Detect Ambiguity (P8 B1)
-
-Before any action, scan the user's request and provided context for unresolved questions in scope, acceptance criteria, irreversibility, or constraint conflicts (contradictory inputs, missing target, unknown convention). If any are found, ask the user via the platform-native question tool per `agents/shared/user-question-protocol.md` — do not proceed under silent assumption. This is the default path, not an exception. Acceptable to proceed without asking ONLY when scope is single-target, single-concern, and the brief alone is testable. Any residual ambiguity discovered mid-workflow invokes the same protocol.
-
-## Agent Pipeline
-
-This command monitors context health and recommends delegation. It does not spawn sub-agents directly — it recommends when the orchestrator should delegate to sub-agents due to context degradation.
-
-# Context Health — Conversation Context Monitoring
-
-Monitor and maintain healthy conversation context during long-running agent sessions. Detects context degradation before it impacts output quality and recommends corrective actions.
-
----
-
-## Context Health Indicators
-
-### Degradation Signals
-
-| Signal | Detection Method | Default Threshold |
-|--------|-----------------|-------------------|
-| Conversation depth | Count user/assistant turns | > 30 turns |
-| Token accumulation | Estimate total context tokens | > 80% of model context window |
-| Topic drift | Compare current task to original issue scope | Cosine similarity < 0.6 |
-| Repeated errors | Track consecutive failed attempts | > 2 failures on same task |
-| File staleness | Track time since last file re-read | > 20 turns since last read |
-| Tool failure rate | Track tool call success/failure ratio | > 30% failure rate |
-
-### Model-Aware Threshold Profiles
-
-Different models have different context window sizes and degradation characteristics. The default thresholds above assume a large-context model. When the active model is known, apply the matching profile to adjust thresholds dynamically.
-
-| Model Tier | Context Window | Token Warning | Turn Limit | File Staleness |
-|-----------|---------------|---------------|------------|----------------|
-| Small (< 32K) | ~32K tokens | > 60% of window | > 15 turns | > 10 turns |
-| Medium (32K--128K) | ~128K tokens | > 70% of window | > 25 turns | > 15 turns |
-| Large (128K--200K) | ~200K tokens | > 80% of window | > 30 turns | > 20 turns |
-| Extended (> 200K) | 200K+ tokens | > 85% of window | > 40 turns | > 25 turns |
-
-**Profile resolution:**
-
-1. Check `models` in `hatch.json` for the configured model. If a model name or tier is specified, use the matching profile.
-2. If no model is configured, default to the **Large** profile (backward-compatible with existing thresholds).
-3. When the runtime reports the model name (e.g., via API response headers or tool metadata), map it to the appropriate tier using known model context sizes.
-4. Log the active profile at the start of each health check: `"Context health using <tier> profile (<window_size> tokens)"`.
-
-**Custom thresholds:** If `hatch.json` includes a `contextHealth` section with explicit thresholds, those values override the model-aware profile. This allows teams to tune thresholds for their specific workflow patterns.
-
-### Health Levels
-
-| Level | Status | Action |
-|-------|--------|--------|
-| Green | Healthy (< 50% indicators triggered) | Continue normally |
-| Yellow | Degrading (50-70% indicators triggered) | Refresh key context, summarize progress |
-| Orange | At risk (70-90% indicators triggered) | Delegate remaining work to sub-agent |
-| Red | Degraded (> 90% indicators triggered) | Stop, create checkpoint, spawn fresh agent |
-
-## Monitoring Protocol
-
-### Passive Monitoring (Always Active)
-
-Agents should self-assess context health at natural breakpoints:
-- After completing each sub-task or implementation step
-- Before starting a new file or module
-- After receiving an error or unexpected result
-- Every 10 conversation turns
-
-### Self-Assessment Checklist
-
-At each checkpoint, the agent evaluates:
-1. **Can I accurately recall the original task requirements without re-reading?**
-2. **Am I making progress or cycling on the same issue?**
-3. **Are my tool calls succeeding at a reasonable rate?**
-4. **Is my understanding of the codebase still current?**
-5. **Have I drifted from the issue's acceptance criteria?**
-
-### Corrective Actions
-
-#### Refresh (Yellow)
-- Re-read the issue body and acceptance criteria
-- Re-read key files that have been modified
-- Summarize progress so far in a structured checkpoint
-
-#### Delegate (Orange)
-- Create a structured handoff document with: completed work, remaining tasks, key context, file list
-- Spawn a sub-agent with the handoff document using the Task tool
-- The sub-agent starts fresh with full context window
-
-#### Checkpoint and Stop (Red)
-- Save a progress checkpoint: files changed, tests written, current blockers
-- Post a status comment on the GitHub issue with progress
-- Recommend the user start a new conversation for the remaining work
-
-## Integration with Board Pickup
-
-When `board-pickup` operates in auto-advance mode:
-- Context health is checked between each issue
-- If health drops to Orange, the current issue is completed and a fresh agent handles the next one
-- If health drops to Red mid-issue, the issue is marked as PARTIAL and moved back to Ready
-
-## Output Format
-
-```
-## Context Health Check
-
-**Level:** GREEN | YELLOW | ORANGE | RED
-
-**Indicators:**
-- Conversation depth: {turns} / 30
-- Token usage: ~{estimated}% of context window
-- Topic coherence: {assessment}
-- Error rate: {n} failures in last {m} operations
-- File staleness: {n} files not re-read in {m} turns
-
-**Recommendation:** {CONTINUE | REFRESH | DELEGATE | CHECKPOINT}
-
-**Action taken:** {what corrective action was performed, if any}
-```
-
----
-
-## Error Handling
-
-- **Self-assessment failure:** If the agent cannot determine its own health level, default to Yellow and perform a context refresh.
-- **Delegation failure:** If sub-agent spawn fails, fall back to Checkpoint and Stop (Red protocol).
-- **Board integration failure:** Log warning and continue. Context health operates independently of board state.
-
----
-
-## Guardrails
-
-- **Never ignore Red status.** A Red assessment always results in a checkpoint and stop.
-- **Do not inflate health.** When uncertain, round toward the more degraded level.
-- **Passive monitoring is mandatory** during board-pickup auto-advance mode.
-- **Handoff documents must be complete.** Never delegate without listing completed work, remaining tasks, key context, and file list.
-- **Do not expand scope during refresh.** Re-reading context is not an invitation to add new tasks.

package/commands/hatch3r-cost-tracking.md

@@ -1,163 +0,0 @@
----
-id: hatch3r-cost-tracking
-type: command
-orchestrator: false
-description: Track and report token usage and estimated costs across agent workflows and board operations
-tags: [maintenance]
-quality_charter: agents/shared/quality-charter.md
-efficiency_patterns: agents/shared/efficiency-patterns.md
-cache_friendly: true
-parallel_tool_default: true
----
-## Agent Pipeline
-
-This command tracks token usage and costs. It does not spawn sub-agents directly — it monitors sub-agent usage across the session.
-
-# Cost Tracking — Token Usage and Cost Reporting
-
-Track token consumption and estimated costs across sub-agent workflows, board operations, and development sessions. Provides visibility into AI usage patterns and enforces cost guardrails.
-
----
-
-## Cost Tracking Model
-
-### Token Estimation
-
-Since exact token counts are not always available from the runtime, use estimation:
-
-| Content Type | Estimation Rule |
-|-------------|----------------|
-| User message | ~4 characters per token |
-| Assistant response | ~4 characters per token |
-| Tool call (input) | JSON stringified length / 4 |
-| Tool call (output) | Response length / 4 |
-| File read | File character count / 4 |
-| Web search | ~500 tokens per search |
-
-### Cost Estimation
-
-| Model Tier | Input (per 1M tokens) | Output (per 1M tokens) |
-|-----------|----------------------|----------------------|
-| Fast | $0.25 | $1.00 |
-| Standard | $3.00 | $15.00 |
-| Premium | $15.00 | $75.00 |
-
-These are reference rates — update based on actual provider pricing.
-
-## Tracking Scope
-
-### Per-Issue Tracking
-- Total tokens consumed implementing an issue
-- Breakdown: planning vs implementation vs testing vs review
-- Sub-agent token usage (each sub-agent reports independently)
-- Estimated cost at current model pricing
-
-### Per-Session Tracking
-- Total tokens in the current conversation
-- Running cost estimate
-- Comparison to session budget (if configured)
-- Warning at 50%, 75%, 90% of budget
-
-### Board Operation Tracking
-- Tokens consumed per board-pickup cycle
-- Tokens per issue type (bug fix vs feature vs refactor)
-- Historical trends across sessions
-- Average cost per completed issue
-
-## Cost Guardrails
-
-### Budget Configuration
-
-Configure in `hatch.json`:
-```json
-{
-  "costTracking": {
-    "sessionBudget": 10.00,
-    "issueBudget": 5.00,
-    "epicBudget": 50.00,
-    "currency": "USD",
-    "warningThresholds": [0.5, 0.75, 0.9],
-    "hardStop": true
-  }
-}
-```
-
-### Default Budgets
-
-When `hatch.json` has no `costTracking` section, the following defaults are applied automatically. These defaults provide baseline guardrails without requiring explicit configuration.
-
-| Budget Type | Default Value | Rationale |
-|------------|--------------|-----------|
-| `sessionBudget` | $10.00 | Covers a typical multi-issue development session (~3-4 issues at ~$3 each, with headroom) |
-| `issueBudget` | $5.00 | Accommodates the full 4-phase pipeline (Research + Implement + Review + Quality) for a standard task |
-| `epicBudget` | $25.00 | Covers ~5 sub-issues with shared overhead for batch coherence assessment |
-| `warningThresholds` | [0.5, 0.75, 0.9] | Progressive alerts at 50%, 75%, and 90% of budget |
-| `hardStop` | false | Defaults to soft warnings (log + alert) rather than blocking. Teams can opt into hard stops explicitly. |
-
-These defaults activate reporting mode: budget warnings are surfaced to the user at each threshold, but work is not halted unless `hardStop` is explicitly set to `true`. To override any default, add the corresponding key to `costTracking` in `hatch.json`.
-
-### Enforcement
-
-| Threshold | Action |
-|-----------|--------|
-| 50% of budget | Log warning, continue |
-| 75% of budget | Alert user, suggest optimization |
-| 90% of budget | Strong warning, recommend delegation or checkpoint |
-| 100% of budget | Stop (if hardStop=true) or alert and continue |
-
-### Cost Optimization Strategies
-
-When approaching budget limits:
-1. **Reduce context**: Summarize long conversations, drop irrelevant file content
-2. **Delegate to faster models**: Use fast-tier sub-agents for routine tasks
-3. **Cache results**: Avoid re-reading unchanged files
-4. **Batch operations**: Combine multiple small tool calls into fewer larger ones
-5. **Scope reduction**: Break remaining work into a new issue for a fresh session
-
-## Output Format
-
-```
-## Cost Report: {scope}
-
-**Period:** {session/issue/sprint}
-
-**Token Usage:**
-- Input tokens: ~{n}
-- Output tokens: ~{n}
-- Total tokens: ~{n}
-
-**Estimated Cost:** ${amount}
-
-**Budget Status:** {amount} / {budget} ({percentage}%)
-
-**Breakdown:**
-
-| Phase | Tokens | Cost | % of Total |
-|-------|--------|------|-----------|
-| Planning | ~{n} | ${x} | {%} |
-| Implementation | ~{n} | ${x} | {%} |
-| Testing | ~{n} | ${x} | {%} |
-| Review | ~{n} | ${x} | {%} |
-| Sub-agents | ~{n} | ${x} | {%} |
-
-**Optimization Opportunities:**
-- {suggestions based on usage patterns}
-```
-
----
-
-## Error Handling
-
-- **Token estimation inaccuracy:** Estimates may drift ±30% from actual usage. Always present values with `~` prefix.
-- **Missing budget config:** If `hatch.json` has no `costTracking` section, operate in report-only mode (no guardrails enforced).
-- **Sub-agent reporting failure:** If a sub-agent does not report token usage, estimate from its output length and log a warning.
-
----
-
-## Guardrails
-
-- **Never suppress budget warnings.** All threshold alerts must be surfaced to the user.
-- **Hard stop is respected.** When `hardStop: true` and budget is exhausted, the agent must stop and checkpoint.
-- **Estimates are clearly labeled.** Never present estimated costs as exact figures.
-- **Budget config is read-only.** This command reads budget configuration but never modifies `hatch.json`.
-- **Cost data does not leak across sessions.** Each session starts with a fresh cost counter unless explicitly aggregating historical data.

package/commands/hatch3r-dep-audit.md

@@ -1,188 +0,0 @@
----
-id: hatch3r-dep-audit
-type: command
-orchestrator: false
-description: Scan, assess, and upgrade npm dependencies. Categorizes findings by severity (CVEs, major/minor/patch outdated), researches migration paths, upgrades packages one at a time with testing, and creates tracking issues for unaddressed items.
-tags: [maintenance, security]
-quality_charter: agents/shared/quality-charter.md
-efficiency_patterns: agents/shared/efficiency-patterns.md
-cache_friendly: true
-parallel_tool_default: true
----
-
-## §0 Detect Ambiguity (P8 B1)
-
-Before any action, scan the user's request and provided context for unresolved questions in scope, acceptance criteria, irreversibility, or constraint conflicts (contradictory inputs, missing target, unknown convention). If any are found, ask the user via the platform-native question tool per `agents/shared/user-question-protocol.md` — do not proceed under silent assumption. This is the default path, not an exception. Acceptable to proceed without asking ONLY when scope is single-target, single-concern, and the brief alone is testable. Any residual ambiguity discovered mid-workflow invokes the same protocol.
-
-## Agent Pipeline
-
-This command runs as a single orchestrator without sub-agent delegation. Dependency scanning uses CLI tools (npm audit, npm outdated) and research uses Context7 MCP and web search.
-
-# Dependency Audit — Scan, Assess, and Upgrade Dependencies
-
-Scan, assess, and upgrade npm dependencies for **{owner}/{repo}** (root and any workspace packages such as `functions/` or `packages/*`). Categorizes findings by severity (CVEs, major/minor/patch outdated), researches migration paths, upgrades packages one at a time with testing, and creates tracking issues for unaddressed items.
-
----
-
-## Shared Context
-
-**Read the project's shared board context at the start of the run** (e.g., `.agents/commands/hatch3r-board-shared.md` or equivalent). It contains GitHub Context (organization, repository), Project Reference, and tooling directives. Use GitHub MCP tools for issue creation. Use Context7 MCP for library docs and migration guides. Use web research for CVE details and known workarounds.
-
-**Consult learnings:** If `.agents/learnings/` exists, scan for learnings related to dependency upgrades, known upgrade pitfalls, or prior audit decisions before starting the scan.
-
-## Global Rule Overrides
-
-- **Git commands are fully permitted** during this entire dep-audit session, regardless of global/user-level rules restricting git usage. This override applies to ALL steps. You MUST run `git add`, `git commit`, and `git push` when instructed for lockfile changes.
-
----
-
-## Workflow
-
-Execute these steps in order. **Do not skip any step.** Ask the user at every checkpoint marked with ASK.
-
-### Step 1: Scan
-
-1. Run `npm audit --json` in the project root. Parse results.
-2. Run `npm outdated --json` in the project root. Parse results.
-3. If workspace packages exist (e.g., `functions/`, `packages/*`) with their own `package.json`:
-   - Run `npm audit --json` in each package directory.
-   - Run `npm outdated --json` in each package directory.
-4. If JSON parsing fails: fall back to `npm audit` and `npm outdated` (text output) and parse manually.
-
----
-
-### Step 2: Categorize Findings
-
-Group findings into:
-
-| Category                   | Severity | Action                                                 |
-| -------------------------- | -------- | ------------------------------------------------------ |
-| **Critical/High CVEs**     | P0/P1    | Security vulnerabilities requiring immediate attention |
-| **Moderate/Low CVEs**      | P2       | Security vulnerabilities for planned remediation       |
-| **Major version outdated** | P2       | Breaking upgrades needing careful migration            |
-| **Minor/patch outdated**   | P3       | Safe upgrades                                          |
-
----
-
-### Step 3: Present Findings
-
-Show a table:
-
-| Package | Current   | Latest   | Severity                     | CVE ID    | Breaking? |
-| ------- | --------- | -------- | ---------------------------- | --------- | --------- |
-| {name}  | {current} | {latest} | {critical/high/moderate/low} | {CVE-XXX} | {yes/no}  |
-
-Include a brief summary of breaking changes for major versions.
-
-**ASK:** "Which categories to address? (a) all, (b) critical/high CVEs only, (c) specific packages, (d) skip and create tracking issues only"
-
----
-
-### Step 4: Research
-
-For each selected package:
-
-1. Use **Context7 MCP**: `resolve-library-id` then `query-docs` to check migration guides and breaking changes.
-2. Use **web research** for CVE details and known workarounds.
-3. Summarize migration path and risks for the user.
-
-**ASK:** "Research complete for selected packages. Proceed with upgrades? (yes / review specific package / abort)"
-
----
-
-### Step 5: Upgrade
-
-For each selected package, **one at a time**:
-
-1. Install the new version in the appropriate directory (root or workspace package):
-
-   ```bash
-   npm install {package}@{version}
-   ```
-
-2. Run quality checks (adapt to project conventions):
-
-   ```bash
-   npm run lint && npm run typecheck && npm run test
-   ```
-
-3. If tests fail:
-   - Assess whether it's a breaking change needing code updates or a genuine regression.
-   - **STOP** and report the failure.
-   - **ASK:** "Tests failed for {package}. (a) roll back and create tracking issue, (b) attempt code fixes, (c) skip this package and continue"
-
-4. If code changes are needed (e.g., API changes):
-
-   **ASK:** "Code changes required for {package}. Proceed with fixes? (yes / roll back and create tracking issue)"
-
-5. If upgrade succeeds: commit lockfile changes:
-
-   ```bash
-   git add package-lock.json
-   # or package-specific lockfile if applicable
-   git commit -m "chore(deps): upgrade {package} to {version}"
-   ```
-
-6. Proceed to the next package in the selected set.
-
----
-
-### Step 6: Create Tracking Issues
-
-For any CVEs or outdated packages **NOT** addressed in this session:
-
-1. Create GitHub issues via `issue_write` with:
-   - **Owner:** from shared context
-   - **Repo:** from shared context
-   - **Labels:** `type:bug`, `area:security`, `priority:{based on severity}`, `executor:agent`
-   - **Title:** e.g., `[CVE] {package}: {CVE-ID} - {brief description}` or `[Deps] Upgrade {package} to {version}`
-   - **Body:** Include package name, current version, target version, severity, CVE ID (if applicable), and migration notes from research.
-
-2. Use severity-based priority:
-   - Critical/High → `priority:p0` or `priority:p1`
-   - Moderate/Low → `priority:p2`
-   - Major outdated → `priority:p2`
-   - Minor/patch → `priority:p3`
-
-**ASK:** "Tracking issues created for {N} unaddressed items. Proceed to summary? (yes / review issues)"
-
----
-
-### Step 7: Summary
-
-Present a report:
-
-```
-## Dependency Audit Summary
-
-### Upgraded
-- {package} {old} → {new}
-- ...
-
-### Tracking Issues Created
-- #{N} — [CVE] {package}: {CVE-ID}
-- #{N} — [Deps] Upgrade {package} to {version}
-- ...
-
-### Remaining Technical Debt
-- {package} — {reason not addressed}
-- ...
-```
-
----
-
-## Error Handling
-
-- **npm audit parse failure:** Fall back to `npm audit` text output. Parse manually.
-- **npm install failure:** Roll back. `git checkout package.json package-lock.json` (and workspace equivalents if applicable). Report error.
-- **Test failure:** Stop. Do not proceed with that package. Report and ask user (roll back / fix / skip).
-
----
-
-## Guardrails
-
-- **Never ignore critical CVEs without creating a tracking issue.** Every critical/high CVE must either be fixed or have a tracking issue.
-- **Always test after each upgrade.** Do not batch upgrades without testing.
-- **Never upgrade all packages at once.** One package at a time.
-- **Always commit lockfile changes** after successful upgrades.
-- **ASK at every checkpoint.** Do not proceed without user confirmation.

package/commands/hatch3r-handoff.md

@@ -1,133 +0,0 @@
----
-id: hatch3r-handoff
-type: command
-orchestrator: true
-agentPipeline: [hatch3r-handoff-preparer]
-description: Prepare, resume, list, complete, and prune cross-session handoff documents.
-tags: [core, maintenance]
-quality_charter: agents/shared/quality-charter.md
-efficiency_patterns: agents/shared/efficiency-patterns.md
-cache_friendly: true
-parallel_tool_default: true
-triage_tiers: [1, 2]
-sub_agents_spawned:
-  count: 1
-  rationale: Single hatch3r-handoff-preparer delegation for the `prepare` Tier-2 subcommand; `resume`, `list`, `complete`, `prune` run inline with no sub-agent fan-out (filesystem-read or single-file rename per the Triage table).
----
-
-## §0 Detect Ambiguity (P8 B1)
-
-Before any action, scan the user's request and provided context for unresolved questions in scope, acceptance criteria, irreversibility, or constraint conflicts (contradictory inputs, missing target, unknown convention). If any are found, ask the user via the platform-native question tool per `agents/shared/user-question-protocol.md` — do not proceed under silent assumption. This is the default path, not an exception. Acceptable to proceed without asking ONLY when scope is single-target, single-concern, and the brief alone is testable. Any residual ambiguity discovered mid-workflow invokes the same protocol.
-
-## Agent Pipeline
-
-The `prepare` subcommand delegates to `hatch3r-handoff-preparer` via the Task tool. The other four subcommands (`resume`, `list`, `complete`, `prune`) run inline within this command — they read, list, transition status, or archive files and do not require a sub-agent.
-
-## Learnings Consultation
-
-Before starting, scan `.agents/learnings/` for entries tagged `handoff`, `context-switch`, `resume`, or `session-state`. Apply the protocol in `rules/hatch3r-learning-consult.md` (frontmatter-first scan; surface top 5 by confidence). Skip if the directory has fewer than 3 files.
-
-# Handoff Management — Cross-Session Work Continuity
-
-Manage canonical handoff documents at `.agents/handoffs/active/` for mid-work state capture and resumption across sessions, tools, or developers.
-
----
-
-## Step 0: Triage
-
-Classify the handoff request by subcommand and operation size before routing:
-
-- **Tier 1 (trivial)**: `list`, `complete`, `prune --dry-run`. Filesystem-read or single-file rename; no body composition, no validation gate, no sub-agent. Run inline.
-- **Tier 2 (standard)**: `prepare`, `resume`, `prune` (non-dry-run). Body composition with readiness gate (`prepare`), drift check + status transition (`resume`), or batch archival (`prune`). `prepare` delegates to `hatch3r-handoff-preparer` via the Task tool; the others run inline.
-
-There is no Tier 3 for this command — multi-issue or epic-scale handoffs are out of scope; the caller decomposes into per-work-item handoffs upstream.
-
-## Workflow
-
-Execute these steps in order. **Do not skip any step.** Ask the user at every checkpoint marked with **ASK**.
-
-### Step 1: Detect Subcommand
-
-Read the first positional argument and route to the matching subcommand. If absent or unrecognized:
-
-**ASK:** "Which handoff action? `prepare | resume | list | complete | prune`."
-
-### Step 2: Route
-
-| Subcommand | Semantics |
-|------------|-----------|
-| `prepare` | Capture current session state into a new handoff document |
-| `resume`  | Load and surface a previously-prepared handoff for continuation |
-| `list`    | Show active (and optionally archived) handoffs in a table |
-| `complete`| Transition a handoff to `completed` and move to `archived/` |
-| `prune`   | Archive expired actives and prune archives older than 90 days |
-
----
-
-## Subcommand: prepare
-
-1. Parse optional flags: `--work-item <ref>` (e.g. `gh:owner/repo#42`, `ado:org/project:work-item/123`, `gl:owner/repo!42`), `--summary "<text>"`.
-2. Invoke `hatch3r-handoff-preparer` via the Task tool. Pass `work_item` and `summary` if provided.
-3. The preparer returns the written path plus an Iteration Summary block. Surface both to the user.
-
-**ASK** (before invocation): "Capturing handoff for {current branch}. Confirm or specify `--work-item` / `--summary`."
-
-## Subcommand: resume
-
-1. Parse optional `<id>` positional. If provided, route directly to `skills/hatch3r-handoff-resume` with that id.
-2. If `<id>` absent, call `listHandoffs({ status: ["open","in-progress","blocked","handed-off"] })` from `src/content/handoffs/index.ts` and present a numbered table (id, status, branch, summary, updated).
-
-**ASK:** "Which handoff to resume? (number, or `cancel`)"
-
-3. Invoke `skills/hatch3r-handoff-resume` with the chosen id. The skill performs validation, drift check, and status transition.
-
-## Subcommand: list
-
-1. Parse flags: `--status <status>`, `--work-item <ref>`, `--include-archived`.
-2. Call `listHandoffs(filter)` and render:
-
-```
-ID                                              STATUS         BRANCH                SUMMARY                                  UPDATED
-2026-05-17_T1430_a3f2c_issue-42-cache-refactor  in-progress    feat/cache-refactor   Token caching for board-fill researcher  2026-05-17 14:30
-```
-
-3. If empty, display: `No active handoffs. Run 'hatch3r-handoff prepare' to capture one.`
-
-## Subcommand: complete
-
-1. Parse positional `<id>` (required). If absent, **ASK** the user to pick from `list`.
-2. Read the handoff via `readHandoff(id)`. Display the `summary` and `Work Remaining` section.
-3. Parse optional `--reason "<text>"` for the archival notice.
-
-**ASK:** "Mark `{id}` completed and archive? (y/N). Reason will be recorded: `{reason or 'no reason given'}`."
-
-4. On confirm: transition `status` to `completed`, stamp `updated` to now, prepend the archival notice (mirrors learnings archival format), then atomic-rename to `.agents/handoffs/archived/<id>.md`.
-
-## Subcommand: prune
-
-1. Parse `--dry-run` flag.
-2. Scan `.agents/handoffs/active/`: collect entries whose `expires_after` ISO-8601 timestamp is at-or-before now (preparer default stamps `created + 30 days`).
-3. Scan `.agents/handoffs/archived/`: collect entries where `updated` is older than 90 days.
-4. Present a two-section preview (Active expirations to archive, Archives to delete).
-5. If `--dry-run`: print the preview and exit.
-
-**ASK:** "Proceed with prune? Will archive {n} active and delete {m} archived. (y/N)"
-
-6. On confirm: archive each expired active (prepend `Expired on {date}` notice, move to `archived/`); delete each over-90-day archive.
-
----
-
-## Error Handling
-
-- `.agents/handoffs/active/` missing or empty: emit `No active handoffs. Run 'hatch3r-handoff prepare' to capture one.` and exit 0.
-- Ambiguous `<id>` (multiple partial matches): list the matches and **ASK** the user to pick one.
-- Write conflict (concurrent prepare for same `work_item`): surface the existing handoff path and **ASK** whether to overwrite (only if existing handoff is older than 24 hours per `writeHandoff` policy).
-- `complete` or `prune` requested on a missing id: report the path that was looked up and suggest `hatch3r-handoff list`.
-
-## Guardrails
-
-- **Never delete** a handoff without explicit user confirmation. Prune deletes only archives older than 90 days, and only after the confirm prompt.
-- **Never modify** a file already in `.agents/handoffs/archived/`. Archived entries are immutable history.
-- **Never include secrets** (API keys, tokens, credentials) in any handoff body. The preparer scans for credential-shaped strings; reject the write if any are detected.
-- **Never write** outside `.agents/handoffs/active/` for new handoffs. Archival is the only path into `archived/`.
-- **Always emit the Iteration Summary block** at the end of the iteration per `rules/hatch3r-iteration-summary.md`.