@harness-engineering/cli 1.14.0 → 1.16.0

package/dist/agents/commands/cursor/harness/harness-dependency-health.mdc

@@ -0,0 +1,187 @@
+---
+description: Analyze structural health of the codebase using graph metrics
+alwaysApply: false
+---
+
+<!-- Generated by harness generate-slash-commands. Do not edit. -->
+
+# Harness Dependency Health
+
+> Analyze structural health of the codebase and surface problems before they become incidents.
+
+## When to Use
+
+- Weekly scheduled health check on the codebase
+- Before major refactoring — understand current structural health
+- When onboarding to a new project — assess codebase quality
+- NOT for checking layer violations (use enforce-architecture)
+- NOT for finding dead code (use cleanup-dead-code)
+
+## Prerequisites
+
+A knowledge graph at `.harness/graph/` enables full analysis. If no graph exists,
+the skill uses static analysis fallbacks (see Graph Availability section).
+Run `harness scan` to enable graph-enhanced analysis.
+
+### Graph Availability
+
+Before starting, check if `.harness/graph/graph.json` exists.
+
+**If graph exists:** Check staleness — compare `.harness/graph/metadata.json`
+scanTimestamp against `git log -1 --format=%ct` (latest commit timestamp).
+If graph is more than 2 commits behind (`git log --oneline <scanTimestamp>..HEAD | wc -l`),
+run `harness scan` to refresh before proceeding. (Staleness sensitivity: **High**)
+
+**If graph exists and is fresh (or refreshed):** Use graph tools as primary strategy.
+
+**If no graph exists:** Output "Running without graph (run `harness scan` to
+enable full analysis)" and use fallback strategies for all subsequent steps.
+
+## Process
+
+### Phase 1: METRICS — Compute Graph Structural Metrics
+
+Query the graph for five key structural indicators:
+
+1. **Hub detection**: Find nodes with high fan-in (>10 inbound `imports` edges).
+
+   ```
+   query_graph(rootNodeIds=[all file nodes], includeEdges=["imports"])
+   ```
+
+   Hubs are single points of failure — changes to them have outsized blast radius.
+
+2. **Orphan detection**: Find file nodes with zero inbound `imports` edges that are not entry points.
+
+   ```
+   get_relationships(nodeId=<file>, direction="inbound")
+   ```
+
+   Orphans may be dead code or missing from the module system.
+
+3. **Cycle detection**: Use `check_dependencies` to find circular import chains.
+   Cycles create fragile coupling — any change in the cycle affects all members.
+
+4. **Deep chain detection**: Find import chains longer than N hops (default: 7).
+
+   ```
+   query_graph(rootNodeIds=[entry points], maxDepth=10, includeEdges=["imports"])
+   ```
+
+   Deep chains are fragile — a change at the bottom propagates unpredictably.
+
+5. **Module cohesion**: For each module (directory), count internal vs external edges. Low internal cohesion (many external edges, few internal) suggests misplaced code.
+
+#### Fallback (without graph)
+
+When no graph is available, use static analysis to approximate structural metrics:
+
+1. **Build adjacency list**: Grep all source files for `import`/`require` statements. Parse each to extract the imported path. Build an adjacency list mapping each file to its imports.
+2. **Hub detection**: From the adjacency list, count inbound edges per file. Files with >10 importers are hubs.
+3. **Orphan detection**: Files with zero inbound edges that are not entry points (not `index.*`, not in `package.json` main/exports). Use glob to find all source files, then subtract those that appear as import targets.
+4. **Cycle detection**: Run DFS on the adjacency list. When a back-edge is found, report the cycle path.
+5. **Deep chain detection**: From entry points, DFS to find the longest import chain. Report chains exceeding 7 hops.
+6. **Module cohesion (approximate)**: For each directory, count imports that stay within the directory (internal) vs imports that leave it (external). Cohesion = internal / (internal + external).
+7. **Run `check_dependencies` CLI** — this works without a graph and can detect layer violations.
+
+> Fallback completeness: ~60% — cannot compute transitive depth beyond what import parsing reveals; coupling metrics are approximate.
+
+### Phase 2: SCORE — Calculate Health Score
+
+Compute a weighted health score (0-100):
+
+| Metric            | Weight | Scoring                                   |
+| ----------------- | ------ | ----------------------------------------- |
+| Hubs (>10 fan-in) | 25%    | 0 hubs = 100, 1-3 = 70, 4-6 = 40, >6 = 10 |
+| Orphans           | 20%    | 0 = 100, 1-5 = 80, 6-15 = 50, >15 = 20    |
+| Cycles            | 25%    | 0 = 100, 1 = 60, 2-3 = 30, >3 = 0         |
+| Deep chains (>7)  | 15%    | 0 = 100, 1-3 = 70, >3 = 30                |
+| Cohesion (avg)    | 15%    | >0.7 = 100, 0.5-0.7 = 70, <0.5 = 30       |
+
+**Grades**: A (90-100), B (75-89), C (60-74), D (40-59), F (<40)
+
+### Phase 3: RECOMMEND — Generate Recommendations
+
+For each problem found, generate a specific, actionable recommendation:
+
+- **Hubs**: "Split `src/utils/helpers.ts` (14 importers) into domain-specific utilities"
+- **Orphans**: "Remove `src/legacy/old-parser.ts` (0 importers, not an entry point)"
+- **Cycles**: "Break cycle A→B→C→A by extracting shared types to `src/types/shared.ts`"
+- **Deep chains**: "Consider flattening chain: entry→A→B→C→D→E→F→G (8 hops)"
+- **Low cohesion**: "Module `src/services/` has 80% external edges — consider splitting"
+
+### Output
+
+```
+## Dependency Health Report
+
+### Score: B (78/100)
+
+### Metrics
+| Metric | Count | Score |
+|--------|-------|-------|
+| Hubs (>10 fan-in) | 2 | 70/100 |
+| Orphans | 3 | 80/100 |
+| Cycles | 0 | 100/100 |
+| Deep chains (>7) | 1 | 70/100 |
+| Module cohesion | 0.62 avg | 70/100 |
+
+### Top Issues
+1. **Hub**: src/utils/helpers.ts — 14 importers (split recommended)
+2. **Hub**: src/types/index.ts — 12 importers (acceptable for type barrel)
+3. **Orphan**: src/legacy/old-parser.ts — 0 importers
+4. **Deep chain**: entry→auth→user→db→pool→config→env→loader (8 hops)
+
+### Recommendations
+1. Split src/utils/helpers.ts into domain-specific modules
+2. Investigate src/legacy/old-parser.ts for removal
+3. Flatten auth chain by having auth import db directly
+```
+
+## Harness Integration
+
+- **`harness scan`** — Recommended before this skill for full graph-enhanced analysis. If graph is missing, skill uses static analysis fallbacks.
+- **`harness validate`** — Run after acting on findings to verify project health.
+- **Graph tools** — This skill uses `query_graph`, `get_relationships`, and `check_dependencies` MCP tools.
+
+## Success Criteria
+
+- Health score computed on 0-100 scale with letter grade (A-F)
+- All five structural metrics gathered (hubs, orphans, cycles, deep chains, cohesion)
+- Recommendations are specific and actionable (name files, suggest concrete fixes)
+- Report follows the structured output format
+- All findings are backed by graph query evidence (with graph) or systematic static analysis (without graph)
+
+## Examples
+
+### Example: Weekly Health Check on Monorepo
+
+```
+Input: Scheduled weekly run on project root
+
+1. METRICS    — query_graph for hubs: 2 found (helpers.ts, index.ts)
+                get_relationships for orphans: 3 found
+                check_dependencies for cycles: 0 found
+                query_graph for deep chains: 1 found (8 hops)
+                Module cohesion average: 0.62
+2. SCORE      — Weighted score: 78/100 (Grade: B)
+3. RECOMMEND  — "Split helpers.ts (14 importers) into domain modules"
+                "Investigate old-parser.ts for removal (0 importers)"
+                "Flatten auth chain — 8 hops exceeds threshold"
+
+Output:
+  Score: B (78/100)
+  Top issues: 2 hubs, 3 orphans, 1 deep chain
+  3 actionable recommendations generated
+```
+
+## Gates
+
+- **Graph preferred, fallback available.** If no graph exists, use fallback strategies (import parsing, DFS cycle detection, hub/orphan identification). Do not stop — produce the best analysis possible.
+- **Systematic analysis required.** All metrics must come from graph queries (with graph) or systematic import parsing (without graph). Do not guess — parse actual import statements.
+
+## Escalation
+
+- **When score is F (<40)**: Flag as critical and recommend immediate architectural review.
+- **When graph is stale**: Warn and suggest re-scanning before trusting results.
+

package/dist/agents/commands/cursor/harness/harness-docs-pipeline.mdc

@@ -0,0 +1,468 @@
+---
+description: Orchestrator composing 4 documentation skills into a sequential pipeline with convergence-based remediation and qualitative health reporting
+alwaysApply: false
+---
+
+<!-- Generated by harness generate-slash-commands. Do not edit. -->
+
+# Harness Docs Pipeline
+
+> Orchestrator composing 4 documentation skills into a sequential pipeline with convergence-based remediation, producing a qualitative documentation health report.
+
+## When to Use
+
+- When you want a single-command documentation health check across drift, coverage, links, and freshness
+- After major refactoring that may have caused widespread documentation drift
+- As a periodic hygiene check (weekly or per-sprint)
+- When onboarding a new project that has no AGENTS.md (bootstrap mode)
+- When `on_doc_check` triggers fire
+- NOT for fixing a single known drift issue (use align-documentation directly)
+- NOT for generating AGENTS.md from scratch when you know you have a graph (use harness-knowledge-mapper directly)
+- NOT for validating a single file's context (use validate-context-engineering directly)
+
+## Relationship to Sub-Skills
+
+| Skill                        | Pipeline Phase | Role                                        |
+| ---------------------------- | -------------- | ------------------------------------------- |
+| detect-doc-drift             | DETECT         | Find drift between code and docs            |
+| align-documentation          | FIX            | Apply fixes for drift findings              |
+| validate-context-engineering | AUDIT          | Find gaps in documentation coverage         |
+| harness-knowledge-mapper     | FILL           | Generate/regenerate AGENTS.md and fill gaps |
+
+This orchestrator delegates to sub-skills — it never reimplements their logic. Each sub-skill retains full standalone functionality.
+
+## Iron Law
+
+**The pipeline delegates, never reimplements.** If you find yourself writing drift detection logic, fix application logic, or gap analysis logic inside the pipeline, STOP. Delegate to the dedicated sub-skill.
+
+**Safe fixes are silent, unsafe fixes surface.** Never apply a fix classified as `unsafe` without explicit user approval. Never prompt the user for a fix classified as `safe`.
+
+## Flags
+
+| Flag           | Effect                                                            |
+| -------------- | ----------------------------------------------------------------- |
+| `--fix`        | Enable convergence-based auto-fix (default: detect + report only) |
+| `--no-freshen` | Skip graph staleness check                                        |
+| `--bootstrap`  | Force AGENTS.md regeneration even if one exists                   |
+| `--ci`         | Non-interactive: apply safe fixes only, report everything else    |
+
+## Shared Context Object
+
+All phases read from and write to a shared `DocPipelineContext`:
+
+```typescript
+interface DocPipelineContext {
+  // Pipeline state
+  graphAvailable: boolean;
+  agentsMdExists: boolean;
+  bootstrapped: boolean; // true if AGENTS.md was created this run
+
+  // Phase outputs
+  driftFindings: DriftFinding[];
+  fixesApplied: DocFix[];
+  gapFindings: GapFinding[];
+  fillsApplied: DocFix[];
+  exclusions: Set<string>; // finding IDs already addressed
+
+  // Health verdict
+  verdict: 'pass' | 'warn' | 'fail';
+  summary: string;
+}
+
+interface DriftFinding {
+  id: string;
+  file: string;
+  line?: number;
+  driftType: 'renamed' | 'new-code' | 'deleted-code' | 'changed-behavior' | 'moved-code';
+  priority: 'critical' | 'high' | 'medium' | 'low';
+  staleText: string;
+  codeChange: string;
+  suggestedFix: string;
+  fixSafety: 'safe' | 'probably-safe' | 'unsafe';
+}
+
+interface GapFinding {
+  id: string;
+  file?: string;
+  gapType: 'undocumented' | 'broken-link' | 'stale-section' | 'missing-context';
+  priority: 'critical' | 'high' | 'medium' | 'low';
+  description: string;
+  suggestedFix: string;
+  fixSafety: 'safe' | 'probably-safe' | 'unsafe';
+}
+
+interface DocFix {
+  findingId: string;
+  file: string;
+  oldText: string;
+  newText: string;
+  safety: 'safe' | 'probably-safe';
+  verified: boolean; // harness check-docs passed after applying
+}
+```
+
+The context is passed to sub-skills via `handoff.json` with a `pipeline` field. Sub-skills check for this field; if absent, they run in standalone mode.
+
+## Process
+
+### Phase 1: FRESHEN — Graph Freshness and AGENTS.md Bootstrap
+
+**Skip this phase if `--no-freshen` flag is set.**
+
+1. **Check graph existence.** Look for `.harness/graph/` directory.
+   - If exists: set `context.graphAvailable = true`
+   - If not: set `context.graphAvailable = false`, log notice: "No knowledge graph available. Pipeline will use static analysis fallbacks. Run `harness scan` for richer results."
+
+2. **Check graph staleness** (only if graph exists).
+   - Count commits since last graph update: `git rev-list --count HEAD ^$(cat .harness/graph/.last-scan-commit 2>/dev/null || echo HEAD)`
+   - If >10 commits behind: run `harness scan` to refresh
+   - If <=10 commits: proceed with current graph
+
+3. **Check AGENTS.md existence.**
+   - If exists and `--bootstrap` not set: set `context.agentsMdExists = true`, proceed to DETECT
+   - If exists and `--bootstrap` set: proceed to step 4 (regenerate)
+   - If not exists: proceed to step 4
+
+4. **Bootstrap AGENTS.md.**
+
+   **If graph available:**
+   - Invoke `harness-knowledge-mapper` to generate AGENTS.md
+   - Set `context.bootstrapped = true`
+   - Set `context.agentsMdExists = true`
+
+   **If no graph (directory structure fallback):**
+   - Glob source directories: `src/*/`, `packages/*/`, `lib/*/`
+   - Read `package.json` for project name and description
+   - Identify entry points: files matching `src/index.*`, `main` field in package.json
+   - List top-level modules: each immediate subdirectory of `src/` (or `packages/`) with its directory name as the module name
+   - Generate minimal AGENTS.md:
+
+     ```markdown
+     # AGENTS.md
+
+     > Generated from directory structure. Run `harness scan` for richer output.
+
+     ## Project
+
+     <name from package.json> — <description from package.json>
+
+     ## Entry Points
+
+     - <each identified entry point>
+
+     ## Modules
+
+     - **<dir-name>/** — <inferred from directory name>
+     ```
+
+   - Set `context.bootstrapped = true`
+   - Set `context.agentsMdExists = true`
+
+5. Proceed to DETECT phase.
+
+### Phase 2: DETECT — Find Documentation Drift
+
+1. **Write pipeline context to handoff.json.** Set the `pipeline` field in `.harness/handoff.json` with the current `DocPipelineContext` so detect-doc-drift can read it.
+
+2. **Invoke detect-doc-drift.** Run the skill's full process:
+   - Phase 1 (Scan): `harness check-docs` and `harness cleanup --type drift`
+   - Phase 2 (Identify): Classify each finding into drift types
+   - Phase 3 (Prioritize): Rank by impact (Critical > High > Medium > Low)
+   - Phase 4 (Report): Structured output
+
+3. **Populate context with DriftFinding objects.** For each finding from detect-doc-drift, create a `DriftFinding` with:
+   - `id`: deterministic hash of `file + line + driftType` (for dedup tracking)
+   - `driftType`: map to one of `renamed`, `new-code`, `deleted-code`, `changed-behavior`, `moved-code`
+   - `priority`: map to `critical`, `high`, `medium`, `low`
+   - `fixSafety`: classify using the safety table below
+
+4. **Store findings.** Set `context.driftFindings = <all DriftFinding objects>`.
+
+5. **If `--fix` flag is not set:** Skip to AUDIT phase (Phase 4).
+
+### Fix Safety Classification
+
+| Category        | Safe (apply silently)                                              | Probably safe (present diff)                                                    | Unsafe (surface to user)                                          |
+| --------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
+| **Drift fixes** | Update file path where rename is unambiguous; fix import reference | Rewrite description for simple rename/parameter change; update code examples    | Rewrite behavioral explanations; remove sections for deleted code |
+| **Gap fills**   | Add entry for new file with obvious single-purpose name            | Add entry for new file requiring description; update AGENTS.md section ordering | Write documentation for complex modules; create new doc pages     |
+| **Link fixes**  | Redirect broken link where target is unambiguous                   | Redirect when multiple candidates exist (present options)                       | Remove link when target no longer exists                          |
+
+### Phase 3: FIX — Convergence-Based Drift Remediation
+
+**This phase runs only when `--fix` flag is set.**
+
+#### Convergence Loop
+
+```
+previousCount = context.driftFindings.length
+maxIterations = 5
+
+while iteration < maxIterations:
+  1. Partition findings by safety
+  2. Apply safe fixes → verify → record
+  3. Present probably-safe fixes → apply approved → verify → record
+  4. Surface unsafe fixes to user (no auto-apply)
+  5. Re-run detect-doc-drift
+  6. newCount = remaining findings
+  7. if newCount >= previousCount: STOP (converged)
+  8. previousCount = newCount
+  9. iteration++
+```
+
+#### Step-by-step
+
+1. **Partition findings by fixSafety.**
+   - `safeFixes`: findings where `fixSafety === 'safe'`
+   - `probablySafeFixes`: findings where `fixSafety === 'probably-safe'`
+   - `unsafeFixes`: findings where `fixSafety === 'unsafe'`
+
+2. **Apply safe fixes silently.**
+   - Write pipeline context to handoff.json with `pipeline.fixBatch = safeFixes`
+   - Invoke align-documentation to apply the fixes
+   - Run `harness check-docs` after the batch
+   - If check passes: record each fix as a `DocFix` with `verified: true` in `context.fixesApplied`
+   - If check fails: revert the batch (`git checkout -- <files>`), record fixes as `verified: false`
+   - Add fixed finding IDs to `context.exclusions`
+
+3. **Present probably-safe fixes** (skip in `--ci` mode).
+   - For each fix, show the diff (oldText vs newText) to the user
+   - Apply user-approved fixes
+   - Run `harness check-docs` after the batch
+   - Same verify/revert logic as safe fixes
+   - Add fixed finding IDs to `context.exclusions`
+
+4. **Surface unsafe fixes.**
+   - List each unsafe finding with its `suggestedFix` text
+   - Do not apply — user must handle manually
+   - In `--ci` mode: log to report, do not prompt
+
+5. **Re-run detect-doc-drift** to check for cascading issues revealed by fixes.
+   - If new finding count < previous count: loop back to step 1
+   - If new finding count >= previous count: stop (converged or no progress)
+   - If max iterations reached: stop
+
+6. **Record remaining unfixed findings** for the REPORT phase.
+
+### Phase 4: AUDIT — Find Documentation Gaps
+
+1. **Write pipeline context to handoff.json.** Update the `pipeline` field with the current `DocPipelineContext` (including `exclusions` from FIX phase).
+
+2. **Invoke validate-context-engineering.** Run the skill's full process:
+   - Phase 1 (Audit): `harness validate` and `harness check-docs`
+   - Phase 2 (Detect Gaps): Classify into undocumented, broken-link, stale-section, missing-context
+   - Phase 3 (Suggest Updates): Generate specific suggestions
+   - Phase 4 (Apply): Deferred to FILL phase
+
+3. **Populate context with GapFinding objects.** For each finding, create a `GapFinding` with:
+   - `id`: deterministic hash of `file + gapType + description`
+   - `gapType`: map to `undocumented`, `broken-link`, `stale-section`, `missing-context`
+   - `priority`: map to `critical`, `high`, `medium`, `low`
+   - `fixSafety`: classify using the safety table from DETECT phase
+
+4. **Dedup against FIX phase.** Remove any `GapFinding` whose `id` appears in `context.exclusions`. This prevents double-counting items already fixed in the FIX phase.
+
+5. **Store findings.** Set `context.gapFindings = <deduplicated GapFinding objects>`.
+
+6. **If `--fix` flag is not set:** Skip to REPORT phase (Phase 6).
+
+### Phase 5: FILL — Convergence-Based Gap Remediation
+
+**This phase runs only when `--fix` flag is set.**
+
+1. **Check if AGENTS.md needs regeneration.** If `context.bootstrapped === true` and gap findings include AGENTS.md coverage issues, invoke harness-knowledge-mapper (if graph available) or the directory-structure fallback to improve AGENTS.md quality.
+
+2. **Run convergence loop** (same pattern as FIX phase):
+
+   ```
+   previousCount = context.gapFindings.length
+   maxIterations = 5
+
+   while iteration < maxIterations:
+     1. Partition findings by safety
+     2. Apply safe fills → verify → record
+     3. Present probably-safe fills → apply approved → verify → record
+     4. Surface unsafe fills to user
+     5. Re-run validate-context-engineering
+     6. newCount = remaining gaps (after dedup against exclusions)
+     7. if newCount >= previousCount: STOP (converged)
+     8. previousCount = newCount
+     9. iteration++
+   ```
+
+3. **Apply safe fills silently.**
+   - For `broken-link` with unambiguous target: redirect the link
+   - For `undocumented` with obvious single-purpose name: add minimal entry
+   - Run `harness check-docs` after each batch
+   - Record in `context.fillsApplied`
+   - Add filled finding IDs to `context.exclusions`
+
+4. **Present probably-safe fills** (skip in `--ci` mode).
+   - Show diff for: new file entries requiring description, AGENTS.md section reordering
+   - Apply approved fills, verify, record
+
+5. **Surface unsafe fills.**
+   - Documentation for complex modules, new doc pages
+   - Log for report, do not apply
+
+6. **Record remaining unfilled gaps** for the REPORT phase.
+
+### Phase 6: REPORT — Synthesize Health Verdict
+
+1. **Run final `harness check-docs`** to establish the post-pipeline state.
+
+2. **Compute verdict.**
+
+   **FAIL if any of:**
+   - Any critical drift findings remain unfixed
+   - `harness check-docs` fails after all fix attempts
+   - AGENTS.md does not exist and bootstrap failed
+
+   **WARN if any of:**
+   - High-priority drift or gap findings remain (user-deferred)
+   - > 30% of source modules are undocumented
+   - Graph not available (reduced accuracy notice)
+
+   **PASS if:**
+   - No critical or high findings remaining
+   - `harness check-docs` passes
+   - AGENTS.md exists and covers >70% of modules
+
+3. **Generate per-category breakdown:**
+
+   | Category  | Metric                                 |
+   | --------- | -------------------------------------- |
+   | Accuracy  | Drift findings remaining (by priority) |
+   | Coverage  | Undocumented modules remaining         |
+   | Links     | Broken references remaining            |
+   | Freshness | Graph staleness status                 |
+
+4. **List actions taken:**
+   - Auto-fixes applied (safe): count and file list
+   - User-approved fixes (probably-safe): count and file list
+   - Findings deferred to user (unsafe): count and details
+   - AGENTS.md bootstrapped: yes/no and method (graph or directory structure)
+
+5. **Set context verdict and summary.** Write `context.verdict` and `context.summary`.
+
+6. **Output report** to console. Format:
+
+   ```
+   === Documentation Health Report ===
+
+   Verdict: PASS | WARN | FAIL
+
+   Accuracy:  N drift findings remaining (0 critical, 0 high, N medium, N low)
+   Coverage:  N/M modules documented (N%)
+   Links:     N broken references remaining
+   Freshness: Graph current | Graph stale (N commits behind) | No graph
+
+   Actions:
+     - N safe fixes applied silently
+     - N probably-safe fixes applied (user-approved)
+     - N unsafe findings deferred to user
+     - AGENTS.md bootstrapped from <graph|directory structure>
+
+   Remaining findings:
+     [list of unfixed findings with priority and suggested action]
+   ```
+
+## Harness Integration
+
+- **`harness check-docs`** — Run in DETECT, after each fix batch in FIX/FILL, and in REPORT for final state
+- **`harness cleanup --type drift`** — Used by detect-doc-drift during DETECT phase
+- **`harness scan`** — Used in FRESHEN to refresh stale graph
+- **`harness validate`** — Run as final step in each task to verify project health
+
+## Success Criteria
+
+- `harness-docs-pipeline` runs all 4 sub-skills in the right order with shared context
+- FIX and FILL phases iterate until converged; cascading fixes are caught
+- Safe fixes are applied silently; unsafe changes surface to user
+- `harness check-docs` runs after every fix batch; failed fixes are reverted
+- Bootstrap handles cold start (no AGENTS.md) with graph path and directory structure fallback
+- Standalone skills work independently exactly as today when invoked without pipeline context
+- Entire pipeline runs without graph using static analysis fallbacks
+- PASS/WARN/FAIL report includes per-category breakdown and specific remaining findings
+- Drift fixes in FIX phase are excluded from AUDIT findings (no double-counting)
+
+## Examples
+
+### Example: Full pipeline run with fixes
+
+```
+Input: --fix flag set, graph available, AGENTS.md exists
+
+1. FRESHEN  — Graph exists, 3 commits behind (< 10, skip refresh)
+               AGENTS.md exists, no bootstrap needed
+2. DETECT   — detect-doc-drift found 8 findings:
+               2 critical (deleted file still referenced)
+               3 high (renamed functions)
+               2 medium (stale descriptions)
+               1 low (formatting)
+3. FIX      — Iteration 1:
+                 3 safe fixes applied (renamed file paths)
+                 2 probably-safe presented, 2 approved
+                 2 unsafe surfaced to user
+                 harness check-docs: pass
+               Re-detect: 1 new finding (cascading rename)
+               Iteration 2:
+                 1 safe fix applied
+                 Re-detect: 0 new findings — converged
+4. AUDIT    — validate-context-engineering found 5 gaps
+               2 already in exclusions (fixed in FIX) → 3 remaining
+5. FILL     — 1 safe fill (broken link redirect)
+               1 probably-safe (new module entry) → approved
+               1 unsafe (complex module docs) → deferred
+               Re-audit: converged
+6. REPORT   — Verdict: WARN
+               Accuracy: 2 drift findings remaining (0 critical, 0 high, 1 medium, 1 low)
+               Coverage: 12/14 modules documented (86%)
+               Links: 0 broken references
+               Freshness: Graph current
+```
+
+### Example: CI mode (non-interactive)
+
+```
+Input: --fix --ci flags set, no graph
+
+1. FRESHEN  — No graph (notice logged), AGENTS.md exists
+2. DETECT   — 4 findings (1 critical, 2 high, 1 medium)
+3. FIX      — 2 safe fixes applied silently
+               probably-safe and unsafe: logged to report (no prompts)
+4. AUDIT    — 2 gaps (1 deduped) → 1 remaining
+5. FILL     — 0 safe fills, 1 probably-safe logged to report
+6. REPORT   — Verdict: FAIL (1 critical finding remains)
+```
+
+### Example: Bootstrap from directory structure
+
+```
+Input: --bootstrap flag set, no graph, no AGENTS.md
+
+1. FRESHEN  — No graph, no AGENTS.md
+               Fallback bootstrap: glob src/*, read package.json
+               Generated minimal AGENTS.md (32 lines)
+               context.bootstrapped = true
+2. DETECT   — 0 drift findings (fresh AGENTS.md, no stale refs)
+3. AUDIT    — 6 gaps (4 undocumented modules, 2 missing context)
+4. REPORT   — Verdict: WARN (>30% modules undocumented, no graph)
+```
+
+## Gates
+
+- **No fix without verification.** Every fix batch must be followed by `harness check-docs`. If check fails, revert the batch.
+- **No unsafe auto-apply.** Fixes classified as `unsafe` are never applied without explicit user approval. In `--ci` mode, they are logged but never applied.
+- **No reimplementation of sub-skill logic.** The pipeline delegates to sub-skills. If the DETECT phase is writing drift detection code, the plan is wrong.
+- **No convergence without progress.** If a convergence loop iteration does not reduce the finding count, stop immediately. Do not retry.
+- **Max 5 iterations per convergence loop.** Hard cap to prevent runaway loops.
+
+## Escalation
+
+- **When findings exceed 50:** Focus on critical and high priority only. Defer medium and low to a follow-up run.
+- **When bootstrap produces low-quality AGENTS.md:** This is expected without a graph. Log a notice recommending `harness scan` and accept the reduced quality for the current run.
+- **When convergence loop does not converge within 5 iterations:** Stop the loop, log remaining findings, and proceed to the next phase. The report will reflect the unconverged state.
+- **When a sub-skill fails:** Log the failure, skip the phase, and continue the pipeline. The report will note the skipped phase with a WARN or FAIL verdict.
+- **When `harness check-docs` is unavailable:** Fall back to file existence checks and link validation via grep. Log a notice about reduced verification accuracy.
+