@tekyzinc/gsd-t 3.29.11 → 4.0.14

package/commands/gsd-t-doc-ripple.md

@@ -1,156 +1,40 @@
 # GSD-T: Doc-Ripple — Automated Document Ripple Enforcement
 
-You are the doc-ripple agent. You identify and update all downstream documents after code changes. You are spawned by execute, integrate, quick, debug, and wave after primary work is committed.
+You are the doc-ripple agent. You identify and update all downstream documents after code changes, per the Document Ripple Completion Gate. You are normally spawned by execute, integrate, quick, debug, and wave after primary work is committed — and you can also be run standalone. Either way, run the doc-ripple phase by invoking the generic upper-stage Workflow at `templates/workflows/gsd-t-phase.workflow.js` with `phase: "doc-ripple"`. You write NO code — docs only.
 
-## Model Assignment
-
-Per `.gsd-t/contracts/model-selection-contract.md` v1.0.0.
-
-- **Default**: `sonnet` (`selectModel({phase: "doc-ripple"})`) — downstream documentation updates are routine prose editing.
-- **Escalation**: `/advisor` convention-based fallback from `bin/advisor-integration.js` when a doc change involves rewriting an architectural invariant or a contract. Never silently skip doc-ripple under context pressure — M35 removed that behavior.
-
-## Step 1: Load Context
-
-Read:
-1. `CLAUDE.md` — project conventions and Pre-Commit Gate (project-specific extensions)
-2. `.gsd-t/contracts/doc-ripple-contract.md` — trigger conditions, manifest format, update protocol
-3. `.gsd-t/contracts/pre-commit-gate.md` — the gate checklist you cross-reference
-
-Run via Bash:
-`git diff --name-only HEAD~1 2>/dev/null || git diff --cached --name-only`
-
-Store the changed file list for Steps 2–3.
-
-## Step 2: Threshold Check
-
-Evaluate the changed file list against trigger conditions from `doc-ripple-contract.md`.
-
-Output exactly:
-```
-DOC-RIPPLE THRESHOLD: {FIRE|SKIP}
-  Files changed: {N} across {N} directories
-  Cross-cutting signals: {list or "none"}
-  Reason: {brief explanation}
-```
-
-**If SKIP**: log the decision, output `Doc-ripple: SKIP — {reason}`, and stop. No manifest. No updates.
-
-**If FIRE**: proceed to Step 3.
-
-## Step 3: Blast Radius Analysis
-
-For each changed file, classify its type: source, test, contract, template, command, doc, config.
-
-Cross-reference `.gsd-t/contracts/pre-commit-gate.md` gate checklist:
-- API endpoint/shape changed → api-contract.md, Swagger spec, CLAUDE.md, README.md
-- Database schema changed → schema-contract.md, docs/schema.md
-- UI component interface changed → component-contract.md
-- New files or directories added → owning domain scope.md
-- Requirement implemented or changed → docs/requirements.md
-- Component or data flow changed → docs/architecture.md
-- Any file modified → .gsd-t/progress.md (Decision Log entry)
-- Architectural decision made → .gsd-t/progress.md (with rationale)
-- Tech debt discovered or fixed → .gsd-t/techdebt.md
-- New convention established → CLAUDE.md or domain constraints.md
-- Command file added/changed → GSD-T-README.md, README.md, templates/CLAUDE-global.md, commands/gsd-t-help.md
-- Command added/removed → all 4 above + package.json version + bin/gsd-t.js count
-- Wave flow changed → gsd-t-wave.md, GSD-T-README.md, README.md
-- Template changed → verify gsd-t-init output
-
-Build the final list: `{ document, status (UPDATED|SKIPPED), action, reason }`.
-
-## Step 4: Generate Manifest
-
-Write `.gsd-t/doc-ripple-manifest.md` (overwrite):
-
-```markdown
-# Doc-Ripple Manifest — {date}
-
-## Trigger
-- Command: {triggering command}
-- Files changed: {N}
-- Threshold: FIRE — {reason}
-
-## Blast Radius
-
-| Document | Status | Action | Reason |
-|----------|--------|--------|--------|
-| {path} | {UPDATED|SKIPPED} | {action} | {reason} |
-
-## Summary
-- Documents checked: {N}
-- Documents updated: {N}
-- Documents skipped (already current): {N}
-```
-
-## Step 5: Update Documents
-
-Count documents marked UPDATED.
-
-**Fewer than 3 updates — inline:**
-For each document: read current content → determine minimal edit → apply via Edit tool (not Write) → verify after edit.
-
-**3 or more updates — parallel subagents:**
-
-For each document or logical group:
-
-⚙ [haiku] gsd-t-doc-ripple → update {document}
-(Use sonnet for docs/architecture.md and docs/requirements.md — these need reasoning.)
-
-**OBSERVABILITY LOGGING (MANDATORY) — wrap each document-update subagent with `captureSpawn`:**
+## What this command does
 
 ```
-node -e "
-const { captureSpawn } = require('./bin/gsd-t-token-capture.cjs');
-(async () => {
-  await captureSpawn({
-    command: 'gsd-t-doc-ripple',
-    step: 'Step 5',
-    model: '{haiku|sonnet}',
-    description: 'update {document}',
-    projectDir: '.',
-    domain: 'doc-ripple',
-    task: '-',
-    notes: 'update:{document}',
-    spawnFn: async () => { /* Task subagent call for the document-update prompt below */ },
-  });
-})();
-"
+preflight → brief (kind=doc-ripple) → doc-ripple agent (opus, with phase protocol)
 ```
 
-`captureSpawn` parses `result.usage` and writes the row to `.gsd-t/token-log.md` under the canonical header. Tokens column renders as `in=N out=N cr=N cc=N $X.XX` or `—`, never `N/A`.
+The agent identifies the full blast radius of recent code changes and updates every affected document in one pass: `docs/requirements.md`, `docs/architecture.md`, `docs/workflows.md`, `.gsd-t/contracts/`, owning `scope.md`, `README.md`, and (for this repo) the 4 command-reference files when a command interface changed.
 
-**Each document-update subagent prompt:**
-```
-Task subagent (general-purpose, model: {haiku|sonnet}):
-"Update a single document as part of doc-ripple enforcement.
-
-Document to update: {path}
-Action: {action from manifest}
-Reason: {reason from manifest}
-Git diff context (changed files): {file list}
+## Step 1: Determine the change set
 
-Instructions:
-1. Read the current document
-2. Apply the minimal edit — add/update only the affected section
-3. Use the Edit tool (not Write) — preserve all existing content
-4. Re-read after edit to confirm correctness
-5. Report: 'Updated {document} — {one-line summary of change}'"
-```
+Read the recent commit range (or `$ARGUMENTS` if a specific scope is given) and `.gsd-t/progress.md` Decision Log to learn what changed.
 
-## Step 6: Report Summary
+## Step 2: Invoke the phase Workflow
 
-Output:
-```
-Doc-ripple: {N} checked, {N} updated, {N} skipped
+```js
+{
+  scriptPath: "templates/workflows/gsd-t-phase.workflow.js",
+  args: {
+    phase: "doc-ripple",
+    projectDir: ".",
+    userInput: "$ARGUMENTS"
+  }
+}
 ```
 
-List each updated document with a one-line summary of what changed.
+## Step 3: Interpret the result
 
-If any update failed, list it under `Failures:` and flag for manual review.
+The Workflow returns `{ status, artifacts, summary, decisions }`.
 
-$ARGUMENTS
+- `status === "complete"`: every document in the blast radius updated; `artifacts` lists them.
+- `status === "partial"`: the agent found docs it could not confidently update. Surface them — do NOT report doc-ripple done until the blast radius is fully covered.
+- `status === "failed"`: read `summary`.
 
-## Auto-Clear
+## Note
 
-All work is written to project files. Execute `/clear` to free the context window for the next command.
+This is a standalone enforcement command with no workflow successor — control returns to whatever spawned it (or to the user).