pi-dev-team 0.2.0

package/skills/competitive-analysis/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: competitive-analysis
+description: >-
+  Compare this plugin against external plugins, tools, feature sets, or ideas to
+  find gaps and weaknesses. Produces a structured gap analysis report with rough
+  specs for closing each gap. Use this skill whenever the user references
+  capabilities from OUTSIDE the plugin — another plugin they found, a competitor's
+  tool, a feature list from a different project, a repo URL, or a hypothetical
+  concept for capabilities we lack. Trigger phrases include "how do we compare
+  to X", "what does Y have that we don't", "what are we missing", "gap analysis",
+  "competitive analysis", "weaknesses compared to", "stack up against",
+  "where do we fall short", and "should we add X — I saw it in another tool".
+  Also trigger when the user pastes a feature list or describes capabilities
+  they saw elsewhere and asks whether we should have them. Do NOT trigger for
+  internal operations like running reviews, auditing our own agents, adding
+  skills, threat modeling, domain analysis, or debugging — those use other skills.
+role: orchestrator
+user-invocable: true
+---
+
+# Competitive Analysis
+
+## Overview
+
+Systematic comparison of the dev-team plugin against another plugin, tool, feature set, or idea. The goal is to surface gaps, weaknesses, and improvement opportunities — then produce rough specs for closing each gap.
+
+This skill is analytical first, generative second. It catalogs what both sides offer, identifies where dev-team falls short, and then drafts actionable specs for each gap. The analysis should be honest — if the other plugin does something better, say so plainly.
+
+## Input Sources
+
+The comparison target can come in several forms. Determine which applies and gather the data accordingly:
+
+| Source | How to gather |
+| -------- | -------------- |
+| **URL** (repo, docs, marketplace) | Fetch the URL. Look for README, CLAUDE.md, plugin manifests, agent/skill/command directories. If the repo is large, focus on the manifest, README, and directory listing first. |
+| **Local path** | Read the directory structure, then key files (README, CLAUDE.md, manifests, agent/skill dirs). |
+| **Pasted description or feature list** | Use as-is. Ask clarifying questions only if the description is too vague to compare against. |
+| **Concept or idea** | Treat as a hypothetical plugin with the described capabilities. Note in the report that the comparison is against an idea, not a shipped product. |
+
+## Analysis Framework
+
+### Step 1: Catalog dev-team
+
+Read `knowledge/agent-registry.md` for the full inventory. Organize into these capability layers:
+
+- **Team agents** — roles and primary focus areas
+- **Review agents** — what code quality aspects are covered
+- **Skills** — reusable knowledge modules
+- **Commands** — user-invocable workflows
+- **Templates** — language/framework-specific scaffolding
+- **Knowledge files** — progressive-disclosure reference data
+- **Hooks** — automated guards and triggers
+- **Workflows** — multi-phase orchestration (Research → Plan → Implement)
+
+### Step 2: Catalog the comparison target
+
+Map the other plugin's capabilities into the same layers where possible. Not every plugin will have all layers — that's fine. For capabilities that don't map cleanly, create an "Other" category and describe them.
+
+For each capability, note:
+
+- What it does (one line)
+- How mature it appears (shipped, experimental, documented but not implemented)
+- Whether dev-team has an equivalent
+
+### Step 3: Gap analysis
+
+Compare layer by layer. For each gap, classify it:
+
+| Classification | Meaning |
+| --------------- | --------- |
+| **Missing (dev-team)** | The other plugin has this; we have nothing equivalent |
+| **Weaker (dev-team)** | We have something similar, but the other plugin's version is more capable or better designed |
+| **Different approach** | Both plugins address this need, but with fundamentally different strategies worth examining |
+| **Stronger (dev-team)** | We do this better (include these for balance — the report should be honest in both directions) |
+
+Focus the gap analysis on things that matter. A missing agent for an obscure framework isn't as important as a missing workflow capability. Use judgment about what would actually improve the plugin if addressed.
+
+**Always write the classification with the `(dev-team)` qualifier in every table cell** — never the bare word alone. "Stronger" and "Weaker" are meaningless out of context to a reader scanning a single row without the legend in view; "Missing (dev-team)" and "Stronger (dev-team)" are unambiguous on their own. `Different approach` needs no qualifier since it doesn't imply a direction.
+
+### Step 4: Rough specs for gaps
+
+For each **Missing** or **Weaker** gap, produce a rough spec:
+
+```markdown
+### Gap: [Name]
+
+**Classification**: Missing (dev-team) | Weaker (dev-team)
+**Layer**: Agent | Skill | Command | Workflow | Hook | Template | Knowledge
+**Priority**: High | Medium | Low
+
+**What the other plugin does**:
+[1-2 sentences]
+
+**What we have now** (if Weaker):
+[What exists and why it falls short]
+
+**Proposed addition**:
+- **Type**: [agent / skill / command / hook / template]
+- **File**: [proposed file path]
+- **Description**: [What it would do — 2-3 sentences]
+- **Dependencies**: [What existing components it would interact with]
+- **Estimated complexity**: [Small / Medium / Large]
+- **Model tier**: [haiku / sonnet / opus — if applicable]
+```
+
+For **Different approach** items, don't write a spec — write a short analysis of tradeoffs instead, so the reader can decide whether to adopt the alternative approach.
+
+### Step 5: Prioritization
+
+After listing all gaps, rank the top 5 by impact. Impact considers:
+
+- How many users would benefit
+- How fundamental the capability is (workflow > convenience)
+- How much effort it would take relative to the value (quick wins first)
+- Whether it addresses a real limitation vs. a nice-to-have
+
+## Output Format
+
+Write the report to `.dev-team-reports/competitive-analysis-<date>.md` using this structure.
+
+For the header block and closing Provenance section, follow
+`knowledge/report-template.md`; the sections below are this skill's own
+body.
+
+(`Date`, `Target`, `Tool versions`, and `Scope` come from that shared
+header — `Tool versions` renders `_Not applicable — no tool version applies
+to a comparison._` per the empty-section rule; `Source type` has no
+shared-contract equivalent and stays as this skill's own field.)
+
+```markdown
+# Competitive Analysis: dev-team vs [Target]
+
+**Date**: <date>
+**Target**: [Name, URL, or description of what was compared]
+**Tool versions**: _Not applicable — no tool version applies to a comparison._
+**Scope**: [Layers/capabilities compared]
+**Source type**: URL | Local path | Description | Concept
+
+## Executive Summary
+
+[2-3 sentences: what was compared, how many gaps found, top finding]
+
+## Capability Comparison
+
+### [Layer Name]
+
+| Capability | dev-team | [Target] | Classification |
+|-----------|-----------------|----------|----------------|
+| ...       | ...             | ...      | Missing (dev-team) / Weaker (dev-team) / Different approach / Stronger (dev-team) |
+
+[Repeat for each layer that has differences]
+
+## Gap Specs
+
+[One spec block per Missing or Weaker gap, using the template from Step 4]
+
+## Different Approaches Worth Examining
+
+[Short tradeoff analysis for each Different Approach item]
+
+## Our Strengths
+
+[Brief list of areas where dev-team is stronger — keeps the report balanced]
+
+## Top 5 Priorities
+
+| Rank | Gap | Layer | Complexity | Why |
+|------|-----|-------|-----------|-----|
+| 1    | ... | ...   | ...       | ... |
+
+## Next Steps
+
+[Concrete recommendations: which gaps to address first, any quick wins, things that need more research]
+
+## Provenance
+
+- Repository: `<repo path>`
+- Branch / SHA: `<branch>` / `<sha>`
+- Run parameters: `<flags>`
+- `dev-team` plugin version: `<plugin_version>`
+```
+
+## Presenting Results
+
+After writing the report, display in chat:
+
+1. The file path
+2. The executive summary
+3. The top 5 priorities table
+
+Do not repeat the full report in chat.

package/skills/context-loading-protocol/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: context-loading-protocol
+description: Decide which agents and skills to load for a given task. Use at the start of every task to select the minimum viable context load, calculate the token budget, and stay below the 40% utilization ceiling.
+role: orchestrator
+user-invocable: true
+---
+
+# Context Loading Protocol
+
+Token-budget reference (CLAUDE.md baseline, full-load ceiling, per-agent and per-skill costs) is the **Baseline Budget** section of `CLAUDE.md`. This skill is the runtime procedure; don't duplicate the table here — it goes stale.
+
+## Constraints
+
+- Never load all agents upfront; load only the primary agent for each phase.
+- Keep total context below **40%** of the model's window at all times.
+- Load agents on demand when their phase begins, not speculatively.
+- Use tool-based file reads (Read); do not paste file contents into the prompt.
+
+## Enforcement
+
+No hook blocks or warns on capability loads any more (the former context
+ceiling hook was removed; see [ADR 0043](../../../../docs/adr/0043-replace-the-context-ceiling-guard-with-harness-autocompact.md)).
+The harness compacts the conversation itself at the percentage
+`/dev-team:setup` writes to the repo's `.claude/settings.json`
+(`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`, default 40). Repos that never ran `/setup`
+keep the harness default, which is much later, and get a one-line advisory at
+session start. After a compaction, a `compact` SessionStart hook re-injects
+the active `/build` phase, step and plan progress.
+
+So the budget estimate below is the planning tool you apply *before* loading,
+and `/handoff` is yours to run by hand when a deliberate, structured summary
+is worth more than a generic compaction.
+
+### Why 40%
+
+The 40% default is a conservative planning target, not a claimed accuracy cliff.
+Chroma's [Context Rot study](https://www.trychroma.com/research/context-rot) found
+degradation across 18 models (including Claude 4) is gradual, not a sharp drop at
+any single percentage. Needle-in-a-haystack benchmarks like RULER and NoLiMa show a
+model's *effective* context is often only about half its advertised window, with
+sharp accuracy drops on non-lexical retrieval well before the window limit. Anthropic's
+[effective context engineering guidance](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents)
+recommends proactive compaction well ahead of the limit. Given that evidence,
+budgeting to 40% of the window leaves headroom before quality degrades, rather
+than chasing a precise threshold that doesn't exist. There is no absolute token
+cap: the percentage applies to the window, so 40% of a 1M window is 400K.
+
+Full guide — how the threshold is configured, the two SessionStart hooks,
+troubleshooting: [Context Management](../../docs/context-management.md).
+
+## Loading Decision Procedure
+
+### Step 0: Confirm there is a task
+
+Before loading anything or reading files, confirm an actionable instruction exists. If the user has not yet said what they want, wait — do not speculatively read files, verify code, or load agents. Premature investigation before a task is given wastes context and is a common interrupt trigger. Once a task exists, proceed to Step 1.
+
+### Step 1: Classify the task
+
+| Profile | Description | Example |
+|---|---|---|
+| **Simple/Single** | One agent, no skills | "Fix this typo", "Write a unit test" |
+| **Standard/Single** | One agent + 1–2 skills | "Implement this feature using hexagonal architecture" |
+| **Multi-Agent** | 2–3 agents coordinating | "Design and implement a new API endpoint" |
+| **Complex/Multi** | 3+ agents + skills | "Build a new bounded context with full test coverage" |
+
+### Step 2: Select agents
+
+Load the **minimum set**:
+
+1. Identify the **primary agent** (owns the deliverable).
+2. Identify **supporting agents** (input or review).
+3. Do NOT load agents for downstream validation yet — load them when their phase begins.
+
+Order: primary first, then supporting agents one at a time as their phase begins.
+
+### Step 3: Select skills
+
+For each loaded agent, check its `## Skills` section:
+
+- Only load skills **relevant to the current task** — not all skills the agent references.
+- Skills shared by multiple loaded agents only need to be loaded once.
+
+### Step 4: Calculate token budget
+
+```
+Total = CLAUDE.md baseline
+      + conversation history (estimate)
+      + agent files (sum selected)
+      + skill files (sum selected)
+      + expected output (estimate)
+```
+
+**Target: total < 40% of the model's context window.** For Claude with a 200K window, that's < 80K tokens; on a 1M-window model it is 400K (there is no absolute cap). See [Why 40%](#why-40) for the rationale. The config files are a small fraction; the real budget concern is conversation history + output accumulation over multi-turn tasks.
+
+### Step 5: Load via tool-based file reads
+
+```
+Read agents/software-engineer.md
+Read skills/hexagonal-architecture/SKILL.md
+```
+
+Do NOT copy file contents into the system prompt or conversation.
+
+## Loading Profiles
+
+Pre-computed loading sets for common task types.
+
+### Code Implementation
+
+- **Load**: Software Engineer + relevant skill(s)
+- **Defer**: QA (load after implementation), Architect (load only if design questions arise)
+
+### Architecture Design
+
+- **Load**: Architect + relevant architecture skill(s)
+- **Defer**: Software Engineer (load at implementation), QA (load at validation)
+
+### Bug Fix
+
+- **Load**: Software Engineer only
+- **Defer**: QA (load if regression test needed)
+
+### New Feature (full lifecycle)
+
+Three phases, each in a fresh context window with a human review gate between. Each phase's output is a structured progress file in `.claude/memory/` that onboards the next phase.
+
+| Phase | Load | Purpose | Output |
+|---|---|---|---|
+| 1. Research | Orchestrator + sub-agents (exploration) | Understand system, find files, trace data flows | Research progress file |
+| 2. Plan | Architect + PM (if needed) + relevant skill(s) | Specify every change: files, snippets, tests | Implementation plan progress file |
+| 3. Implement | Software Engineer + QA + skill(s) | Execute the plan; code, tests | Working code + test results |
+
+Key rules:
+
+- Each phase starts with a fresh context window, loading only the previous phase's progress file.
+- Human reviews and approves the progress file before the next phase begins.
+- Sub-agents primarily provide context isolation — they search, read, and return concise findings.
+- If implementation is large, compact mid-phase: update the plan progress file with completed steps and continue in a fresh context.
+
+## Unloading
+
+Since tokens can't be literally removed from context:
+
+1. **Phase transitions** — summarize completed phase output into `.claude/memory/` and start a new conversation for the next phase.
+2. **Within a conversation** — stop referencing the agent/skill; the orchestrator mentally notes it's no longer active. Use the Handoff skill (continue mode) to compress stale content.
+3. **Multi-turn accumulation** — when conversation history crosses **30%** utilization, trigger summarization before loading additional agents.
+
+## Anti-patterns
+
+- Loading all agents upfront — wastes tokens before any work begins. Load only the primary agent.
+- Loading all of an agent's skills — most are irrelevant to the specific request.
+- Never unloading — context grows monotonically until hallucination risk. Summarize and phase-transition.
+- Loading agents "just in case" — adds cost without value. Load on demand when the phase begins.
+
+## Output
+
+Loading plan as one table: selected agents + skills, token costs, estimated total, and utilization percentage against the 40% ceiling. No narration.

package/skills/continue/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: continue
+description: >-
+  Resume work from a prior session by reading phase progress files in
+  .claude/memory/ and active plans. Use this when starting a new session on in-progress work,
+  or when the user says "continue", "pick up where I left off", "resume",
+  or "what was I working on".
+argument-hint: ""
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash(git log *), Bash(git branch *), Bash(git status *), Bash(git diff *), Bash(ls *)
+---
+
+# Continue Session
+
+Role: orchestrator. This command resumes work from a prior session — it does not start new work.
+
+Arguments: optional — a phase or plan name to resume; defaults to the most recent.
+
+You have been invoked with the `/continue` command.
+
+## Orchestrator constraints
+
+1. Resume from .claude/memory/ progress files; do not restart completed phases.
+2. Summarize prior state; do not replay full history.
+3. **Be concise.** Report where work resumes, no narration.
+
+## Steps
+
+### 1. Scan for in-progress work
+
+Find phase progress files with `Glob(".claude/memory/*.md")` — never `Read` the bare `.claude/memory/` directory to see what it contains (`${CLAUDE_PLUGIN_ROOT}/knowledge/directory-enumeration.md`). These follow the pattern:
+
+- `.claude/memory/research-progress-*.md` — Research phase output
+- `.claude/memory/plan-progress-*.md` — Plan phase output
+- `.claude/memory/implementation-progress-*.md` — Implementation phase output
+- `.claude/memory/decisions.md` — Accumulated decision log
+
+Also check (same rule — `Glob`, not a directory `Read`):
+
+- `plans/` directory for active plan files
+- `docs/specs/` for design documents without corresponding implementation — or, on a repo that opted into `/specs`' issue-first persistence convention, a `--spec-issue <url>` reference recorded in the active plan instead of a file
+- `.claude/review-summaries/` for recent review results
+- `corrections/` for unapplied code review fixes
+
+### 2. Check git state
+
+Run `git status` and `git log --oneline -5` to understand:
+
+- Current branch and its relationship to main
+- Any uncommitted changes
+- Recent commit messages for context
+
+### 3. Summarize current state
+
+Present a structured summary:
+
+```markdown
+## Session State
+
+**Branch**: feature/xyz (ahead of main by 3 commits)
+**Last phase completed**: Plan (2026-03-17)
+**Next phase**: Implement
+
+### In-Progress Work
+- [Plan] Widget refactor — 8/12 steps complete
+- [Review] 2 unapplied corrections from last review
+
+### Uncommitted Changes
+- `src/widget.ts` — modified
+- `src/widget.test.ts` — modified
+
+### Recommended Next Action
+Continue implementation from step 9 of the widget refactor plan.
+```
+
+### 4. Ask for confirmation
+
+Present the recommended next action and ask: "Resume from here, or would you like to do something else?"
+
+If the user confirms, load the appropriate phase context and continue execution.
+
+### 5. Load phase context
+
+Based on the identified phase:
+
+- **Research**: Load research progress file + relevant design doc
+- **Plan**: Load plan progress file + design doc
+- **Implement**: Load implementation progress file + plan + any review corrections
+
+Follow the Context Loading Protocol for phased loading.

package/skills/cost-report/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: cost-report
+description: >-
+  Report actual token spend and dollar cost of dispatched work — per agent and
+  total — and flag cost regressions. Use when the user asks "how much did that
+  cost", "token spend", "cost of this run", "cost report", or wants to check for
+  a cost regression after /code-review or an orchestration run.
+argument-hint: "[--transcript <path>] [--tolerance <n>]"
+user-invocable: true
+allowed-tools: >-
+  Bash(python3 *, jq *, tail *, cat *, ls *, test *)
+---
+
+# Cost Report (#102)
+
+Role: worker. Reports runtime cost/token spend captured by the cost meter.
+
+Token usage is not available to hooks, so the `Stop`/`SubagentStop` hook
+(`hooks/cost_meter.py`) records a per-session summary to
+`metrics/cost-metering.jsonl` by parsing the session transcript, converting
+tokens to dollars via `knowledge/model-pricing.json`. This skill reports that
+data.
+
+## Steps
+
+1. **Per-session breakdown.** If the user passes `--transcript <path>` (or you
+   know the current transcript path), run an exact per-agent report:
+
+   ```bash
+   python3 "${CLAUDE_PLUGIN_ROOT}/hooks/lib/cost_meter.py" report --transcript <path>
+   ```
+
+   Otherwise show the most recently recorded session from the metrics log
+   (prefer the migrated `.claude/metrics/` location, falling back to the
+   legacy bare `metrics/` path for a project mid-transition):
+
+   ```bash
+   log=".claude/metrics/cost-metering.jsonl"; [ -f "$log" ] || log="metrics/cost-metering.jsonl"
+   tail -n 1 "$log" | python3 -m json.tool
+   ```
+
+2. **Regression check.** Compare the latest session's total cost against the
+   rolling mean of prior sessions (default tolerance +50%):
+
+   ```bash
+   log=".claude/metrics/cost-metering.jsonl"; [ -f "$log" ] || log="metrics/cost-metering.jsonl"
+   python3 "${CLAUDE_PLUGIN_ROOT}/hooks/lib/cost_meter.py" regression \
+     --log "$log" --tolerance 0.5
+   ```
+
+3. Report the per-model, per-thread (main/subagent), and per-agent-type tokens
+   + cost, the session total, and whether a cost regression was detected. Do
+   not invent numbers — print exactly what the meter emits. If
+   `.claude/metrics/cost-metering.jsonl` (or the legacy `metrics/cost-metering.jsonl`)
+   is absent, tell the user the meter hasn't recorded a session yet (the hook
+   records on turn end).
+
+   For a windowed cost-regression baseline (mean of only the N most recent prior
+   sessions instead of all-time), pass `--window N`:
+
+   ```bash
+   log=".claude/metrics/cost-metering.jsonl"; [ -f "$log" ] || log="metrics/cost-metering.jsonl"
+   python3 "${CLAUDE_PLUGIN_ROOT}/hooks/lib/cost_meter.py" regression \
+     --log "$log" --tolerance 0.5 --window 10
+   ```
+
+## Attribution dimensions (#102, #170, #1094)
+
+`report` breaks spend down by **model**, by **thread** (main-loop vs
+subagent), and by **agent type** (#1094), plus the session **total**.
+
+The agent-type dimension answers "which agent type drives spend" (e.g.
+`security-review` vs `test-review` vs `general-purpose`): main-loop turns land
+in `main`; sidechain turns are attributed via the native `attributionAgent`
+field the harness stamps on subagent records, falling back to the Task/Agent
+dispatch join (`tool_use` `input.subagent_type` paired with
+`toolUseResult.agentId`). Sidechain spend carrying neither signal lands in an
+honest `unattributed` bucket — the meter never guesses. The meter also folds in
+the sibling per-subagent transcript files
+(`<dir>/<session-id>/subagents/agent-*.jsonl`) that newer harness versions
+write instead of inline sidechain turns, so subagent spend stays visible.
+
+Attribution is limited to what the Claude Code harness actually records on
+transcript turns. Per-command, per-phase, and per-fix-loop-iteration buckets
+were **removed** (#170): they relied on `attributionSkill` / `orchestrationPhase`
+/ `fixLoopIteration` fields the harness never writes (verified 0/312 in a real
+transcript), and a plugin has no write-path into the transcript — so those
+dimensions were always empty. The main/subagent split uses the native
+`isSidechain` flag, which the harness does provide; the agent-type dimension
+likewise reads only harness-recorded fields (verified against a real
+transcript, #1094).
+
+## Review value (#348)
+
+`/build` records, per inline review checkpoint, whether review actually changed
+anything (`metrics/review-value.jsonl`, schema in `performance-metrics`). When
+that file exists, surface a compact "review value" summary so the user can see
+whether the pipeline's review overhead paid off on this work — the count of
+checkpoints that **found+fixed** a defect vs. those that **passed no-op**, with
+the fix-loop iterations spent:
+
+```bash
+log=".claude/metrics/review-value.jsonl"; [ -f "$log" ] || log="metrics/review-value.jsonl"
+[ -f "$log" ] && jq -s '
+  {checkpoints: length,
+   no_op:    (map(select(.outcome=="no-op"))    | length),
+   fixed:    (map(select(.outcome=="fixed"))     | length),
+   escalated:(map(select(.outcome=="escalated")) | length),
+   issues_found: (map(.issues_found) | add // 0),
+   issues_fixed: (map(.issues_fixed) | add // 0),
+   fix_iterations: (map(.fix_iterations) | add // 0)}' \
+  "$log"
+```
+
+A run that is mostly `no_op` is evidence the review ceremony is over-provisioned
+for that class of work — feed it back into the `/plan` plan-tier and `/build`
+per-step complexity routing. Counts only; no code or file content is stored.
+
+## Context pollution — per-phase resident vs one-time spend (#1520)
+
+A one-time token bill and context that lingers and "charges rent" on every
+subsequent turn are economically different costs (Martin Fowler, "The
+Orchestrator's Tax"). The session totals above cannot tell them apart. The
+`phase_marker.py` PostToolUse hook records a marker at every `/handoff` (a
+phase boundary) capturing, for the **main-loop** context, the resident
+occupancy and the cumulative output spend at that boundary. `phase-report`
+turns the marker sequence into a per-phase ratio:
+
+```bash
+log=".claude/metrics/phase-markers.jsonl"; [ -f "$log" ] || log="metrics/phase-markers.jsonl"
+python3 "${CLAUDE_PLUGIN_ROOT}/hooks/lib/cost_meter.py" phase-report --log "$log"
+```
+
+Report the per-phase `resident_tokens`, `spent_tokens` (output generated during
+the phase), and `resident_to_spent_ratio`. A **high** ratio flags a phase whose
+context stayed resident (pollution — a candidate for earlier mid-phase
+compaction or narrower subagent scoping) rather than being one-time cost; a low
+ratio means most of the phase's spend was transient. If the log is absent, tell
+the user no phase boundary has been recorded yet (the hook records on each
+`/handoff`).
+
+**Honesty caveat — this is a session-scoped proxy, not exact per-phase
+accounting.** `resident` is sampled at the `/handoff` marker because that is the
+closest phase boundary the harness exposes; the harness records no explicit
+phase marker of its own (the same reason per-command/per-phase *cost*
+attribution was removed in #170 — see Attribution dimensions above). The metric
+lives in its own `phase-markers.jsonl` log and is never folded into the
+`cost-metering.jsonl` incremental state.
+
+## Privacy boundary
+
+The meter persists **only** token counts, dollar amounts, model identifiers,
+the main/subagent thread flag, agent-type identifiers, and — for phase markers —
+a phase label and the resident/spent token counts. It never records prompt
+text, code, file paths, or tool payloads. `metrics/cost-metering.jsonl` and
+`metrics/phase-markers.jsonl` are metrics-only artifacts by construction.
+
+1. **Account pace (optional, #142).** When the user asks "am I on track for my
+   budget", "how much have I burned this week", or "which model should I use for
+   the rest of the period", report account-level pace: cumulative spend over a
+   rolling window, the implied daily rate, and the projected spend for a billing
+   period — flagging when pace would exhaust a stated budget:
+
+   ```bash
+   log=".claude/metrics/cost-metering.jsonl"; [ -f "$log" ] || log="metrics/cost-metering.jsonl"
+   python3 "${CLAUDE_PLUGIN_ROOT}/hooks/lib/cost_meter.py" pace \
+     --log "$log" --budget 100 --period-days 30 --window-days 7
+   ```
+
+   Without `--budget` it reports pace only (no flag). When it flags an
+   over-budget pace it suggests dropping a model tier (Opus→Sonnet) for the rest
+   of the window.
+
+## Notes
+
+- Disable the meter with `DEV_TEAM_COST_METER=off`.
+- Pricing lives in `knowledge/model-pricing.json` — update it when rates change
+  (it is the named instrument for every cost number this skill prints).