@tekyzinc/gsd-t 2.50.12 → 2.53.10

package/commands/global-change.md

@@ -1,209 +1,209 @@
----
-argument-hint: <copy|insert|update|delete> <relative-path/filename> [content]
----
-
-# GSD-T: Global Change — Apply Changes Across All GSD-T Projects
-
-You are applying a file-level change to every GSD-T project registered in `.claude/.gsd-t-projects`. This is a **global** slash command (installed to `~/.claude/commands/`) that enables bulk updates to project configuration, CLAUDE.md files, templates, and any other files that need to stay consistent across the GSD-T ecosystem.
-
-## Syntax
-
-```
-/global-change <operation> <relative-path/filename> [arguments]
-```
-
-### Operations
-
-| Operation | Arguments | Description |
-|-----------|-----------|-------------|
-| `copy`    | `<relative-path/filename>` | Copy file from the GSD-T package directory to the same relative path in all projects |
-| `insert`  | `<relative-path/filename> <content>` | Append content to the specified file in all projects |
-| `update`  | `<relative-path/filename> <old_content> %%REPLACE_WITH%% <new_content>` | Find `old_content` in the file and replace it with `new_content` in all projects |
-| `delete`  | `<relative-path/filename>` | Delete the specified file from all projects |
-
-### Examples
-
-```
-/global-change copy .gsd-t/templates/contract.md
-
-/global-change insert .gsd-t/config.json {"newSetting": true}
-
-/global-change update CLAUDE.md
-- `model: haiku` — mechanical tasks
-- `model: sonnet` (default) — reasoning tasks
-%%REPLACE_WITH%%
-- `model: haiku` — mechanical tasks (same as now)
-- `model: sonnet` — mid-tier reasoning: routine code changes, standard refactors, test writing, straightforward synthesis
-- `model: opus` — high-stakes reasoning: architecture decisions, security analysis, complex debugging, cross-module refactors, quality judgment on critical paths
-
-/global-change delete .gsd-t/deprecated-template.md
-```
-
-## Step 1: Load the Project Registry
-
-Read `~/.claude/.gsd-t-projects`. This file contains one absolute project path per line.
-
-```
-# Example .gsd-t-projects
-C:/Users/david/MyNextListen
-C:/Users/david/TimeTracking
-C:/Users/david/tekyz-ai-copilot
-```
-
-If the file does not exist or is empty:
-- STOP. Tell the user: "No GSD-T projects registered. Register projects by adding their absolute paths (one per line) to `~/.claude/.gsd-t-projects`."
-- Do NOT proceed.
-
-Parse the file:
-- Skip blank lines
-- Skip lines starting with `#` (comments)
-- Trim whitespace from each path
-- Store as `PROJECT_PATHS[]`
-
-## Step 2: Parse Arguments
-
-Extract from $ARGUMENTS:
-1. **operation** — first word: `copy`, `insert`, `update`, or `delete`
-2. **relative-path/filename** — second token: the file path relative to each project root (e.g., `CLAUDE.md`, `.gsd-t/config.json`, `docs/architecture.md`)
-3. **Remaining arguments** depend on the operation:
-   - `copy` — no additional arguments
-   - `insert` — everything after the filename is the content to append
-   - `update` — everything after the filename is split by the `%%REPLACE_WITH%%` delimiter into **old_content** (before) and **new_content** (after)
-   - `delete` — no additional arguments
-
-### Parsing the `update` Delimiter
-
-For `update` operations, the content portion (everything after the filename) MUST contain the literal string `%%REPLACE_WITH%%` on its own line. Split on this delimiter:
-- **old_content** = trimmed text before `%%REPLACE_WITH%%` — the exact text to find in the target file
-- **new_content** = trimmed text after `%%REPLACE_WITH%%` — the replacement text
-
-If the delimiter is missing, STOP and show the user the correct syntax:
-```
-Usage: /global-change update <file> <old content> %%REPLACE_WITH%% <new content>
-```
-
-### Validation Rules
-
-- If operation is missing or not one of `copy|insert|update|delete` → STOP, show usage syntax
-- If relative-path/filename is missing → STOP, show usage syntax
-- If operation is `insert` and no content is provided → STOP, tell the user content is required
-- If operation is `update` and `%%REPLACE_WITH%%` delimiter is missing → STOP, show correct syntax
-- If operation is `update` and either old_content or new_content is empty → STOP, both sides of the delimiter are required
-- If operation is `copy` and the source file does not exist in the GSD-T package directory → STOP, tell the user the source file was not found
-
-### Determine GSD-T Package Directory
-
-The source directory for `copy` operations is the installed GSD-T package location. Resolve it by checking (in order):
-1. The directory containing this command file (walk up to the package root)
-2. `node_modules/@tekyz/gsd-t/` relative to the global npm prefix
-3. Ask the user if neither resolves
-
-## Step 3: Dry Run — Scan All Projects First
-
-Before making any changes, scan every project to preview what will happen. For each project in `PROJECT_PATHS[]`:
-
-### For `copy`:
-- Check if the target file already exists → note "will overwrite" or "will create"
-
-### For `insert`:
-- Check if the target file exists → note "will append to existing" or "will create new file"
-
-### For `update`:
-- Read the target file
-- Search for `old_content` in the file contents
-- If found → note "match found — will replace"
-- If NOT found → note "⚠ NO MATCH — will skip" (do NOT modify files where the old content isn't found)
-- If found multiple times → note "⚠ MULTIPLE MATCHES ([count]) — will replace all occurrences"
-
-### For `delete`:
-- Check if the target file exists → note "will delete" or "will skip (not found)"
-
-### Display the dry run summary:
-
-```
-Global Change — Pre-flight Summary
-Operation:  [operation]
-Target:     [relative-path/filename]
-Projects:   [N] registered
-
-[For update — show old/new content preview]
-
-Dry run results:
-  [status] [project-name] — [description]
-  [status] [project-name] — [description]
-```
-
-**Level 3 (Full Auto)**: If ALL projects show clean matches (no warnings), auto-proceed to Step 4 without asking. If ANY project shows a warning (no match, multiple matches), pause and ask.
-
-**Level 1-2**: Always pause and ask for confirmation.
-
-## Step 4: Execute Changes
-
-For each project that passed the dry run:
-
-### `copy`
-1. Determine the target: `{PROJECT_PATH}/{relative-path/filename}`
-2. If the target directory does not exist → create it (including intermediate directories)
-3. Copy the source file to the target, overwriting if it exists
-
-### `insert`
-1. Determine the target: `{PROJECT_PATH}/{relative-path/filename}`
-2. If the target directory does not exist → create it (including intermediate directories)
-3. If the target file does not exist → create it with the provided content
-4. If the target file exists → append a newline + the provided content to the end
-
-### `update`
-1. Determine the target: `{PROJECT_PATH}/{relative-path/filename}`
-2. If the file does not exist → skip
-3. Read the file contents
-4. Search for `old_content` (exact string match, whitespace-sensitive)
-5. If NOT found → skip
-6. If found → replace ALL occurrences of `old_content` with `new_content`
-7. Write the modified contents back to the file
-
-### `delete`
-1. Determine the target: `{PROJECT_PATH}/{relative-path/filename}`
-2. If the target file does not exist → skip
-3. If the target file exists → delete it
-4. Do NOT delete the parent directory even if empty
-
-### Error Handling
-- On failure, record: `FAILED: {error message}`
-- Never abort the entire run because one project failed — continue to the next
-
-## Step 5: Report Results
-
-Display the final summary:
-
-```
-Global Change — Results
-Operation:  [operation] [relative-path/filename]
-Succeeded:  [N] / [total] projects
-Failed:     [N]
-Skipped:    [N]
-
-  [status] [project-name] — [result]
-  [status] [project-name] — [result]
-```
-
-Status icons:
-- `✓` — success
-- `⊘` — skipped (file not found, no match, etc.)
-- `✗` — failed with error
-
-If there were failures, list them with actionable error messages.
-
-## Notes
-
-- **Relative paths use forward slashes** regardless of OS
-- **No glob patterns** — operates on a single file per invocation
-- **Content for `insert`** can be provided inline or pasted in the user's message
-- **Content for `update`** uses the `%%REPLACE_WITH%%` delimiter — old_content match is exact and whitespace-sensitive
-- **Project names in logs** are derived from the last segment of the project path
-- **The `.gsd-t-projects` file** is maintained by `gsd-t init` (auto-registers) and `gsd-t update-all` (reads)
-
-$ARGUMENTS
-
-## Auto-Clear
-
-All work is committed to project files. Execute `/clear` to free the context window for the next command.
+---
+argument-hint: <copy|insert|update|delete> <relative-path/filename> [content]
+---
+
+# GSD-T: Global Change — Apply Changes Across All GSD-T Projects
+
+You are applying a file-level change to every GSD-T project registered in `.claude/.gsd-t-projects`. This is a **global** slash command (installed to `~/.claude/commands/`) that enables bulk updates to project configuration, CLAUDE.md files, templates, and any other files that need to stay consistent across the GSD-T ecosystem.
+
+## Syntax
+
+```
+/global-change <operation> <relative-path/filename> [arguments]
+```
+
+### Operations
+
+| Operation | Arguments | Description |
+|-----------|-----------|-------------|
+| `copy`    | `<relative-path/filename>` | Copy file from the GSD-T package directory to the same relative path in all projects |
+| `insert`  | `<relative-path/filename> <content>` | Append content to the specified file in all projects |
+| `update`  | `<relative-path/filename> <old_content> %%REPLACE_WITH%% <new_content>` | Find `old_content` in the file and replace it with `new_content` in all projects |
+| `delete`  | `<relative-path/filename>` | Delete the specified file from all projects |
+
+### Examples
+
+```
+/global-change copy .gsd-t/templates/contract.md
+
+/global-change insert .gsd-t/config.json {"newSetting": true}
+
+/global-change update CLAUDE.md
+- `model: haiku` — mechanical tasks
+- `model: sonnet` (default) — reasoning tasks
+%%REPLACE_WITH%%
+- `model: haiku` — mechanical tasks (same as now)
+- `model: sonnet` — mid-tier reasoning: routine code changes, standard refactors, test writing, straightforward synthesis
+- `model: opus` — high-stakes reasoning: architecture decisions, security analysis, complex debugging, cross-module refactors, quality judgment on critical paths
+
+/global-change delete .gsd-t/deprecated-template.md
+```
+
+## Step 1: Load the Project Registry
+
+Read `~/.claude/.gsd-t-projects`. This file contains one absolute project path per line.
+
+```
+# Example .gsd-t-projects
+C:/Users/david/MyNextListen
+C:/Users/david/TimeTracking
+C:/Users/david/tekyz-ai-copilot
+```
+
+If the file does not exist or is empty:
+- STOP. Tell the user: "No GSD-T projects registered. Register projects by adding their absolute paths (one per line) to `~/.claude/.gsd-t-projects`."
+- Do NOT proceed.
+
+Parse the file:
+- Skip blank lines
+- Skip lines starting with `#` (comments)
+- Trim whitespace from each path
+- Store as `PROJECT_PATHS[]`
+
+## Step 2: Parse Arguments
+
+Extract from $ARGUMENTS:
+1. **operation** — first word: `copy`, `insert`, `update`, or `delete`
+2. **relative-path/filename** — second token: the file path relative to each project root (e.g., `CLAUDE.md`, `.gsd-t/config.json`, `docs/architecture.md`)
+3. **Remaining arguments** depend on the operation:
+   - `copy` — no additional arguments
+   - `insert` — everything after the filename is the content to append
+   - `update` — everything after the filename is split by the `%%REPLACE_WITH%%` delimiter into **old_content** (before) and **new_content** (after)
+   - `delete` — no additional arguments
+
+### Parsing the `update` Delimiter
+
+For `update` operations, the content portion (everything after the filename) MUST contain the literal string `%%REPLACE_WITH%%` on its own line. Split on this delimiter:
+- **old_content** = trimmed text before `%%REPLACE_WITH%%` — the exact text to find in the target file
+- **new_content** = trimmed text after `%%REPLACE_WITH%%` — the replacement text
+
+If the delimiter is missing, STOP and show the user the correct syntax:
+```
+Usage: /global-change update <file> <old content> %%REPLACE_WITH%% <new content>
+```
+
+### Validation Rules
+
+- If operation is missing or not one of `copy|insert|update|delete` → STOP, show usage syntax
+- If relative-path/filename is missing → STOP, show usage syntax
+- If operation is `insert` and no content is provided → STOP, tell the user content is required
+- If operation is `update` and `%%REPLACE_WITH%%` delimiter is missing → STOP, show correct syntax
+- If operation is `update` and either old_content or new_content is empty → STOP, both sides of the delimiter are required
+- If operation is `copy` and the source file does not exist in the GSD-T package directory → STOP, tell the user the source file was not found
+
+### Determine GSD-T Package Directory
+
+The source directory for `copy` operations is the installed GSD-T package location. Resolve it by checking (in order):
+1. The directory containing this command file (walk up to the package root)
+2. `node_modules/@tekyz/gsd-t/` relative to the global npm prefix
+3. Ask the user if neither resolves
+
+## Step 3: Dry Run — Scan All Projects First
+
+Before making any changes, scan every project to preview what will happen. For each project in `PROJECT_PATHS[]`:
+
+### For `copy`:
+- Check if the target file already exists → note "will overwrite" or "will create"
+
+### For `insert`:
+- Check if the target file exists → note "will append to existing" or "will create new file"
+
+### For `update`:
+- Read the target file
+- Search for `old_content` in the file contents
+- If found → note "match found — will replace"
+- If NOT found → note "⚠ NO MATCH — will skip" (do NOT modify files where the old content isn't found)
+- If found multiple times → note "⚠ MULTIPLE MATCHES ([count]) — will replace all occurrences"
+
+### For `delete`:
+- Check if the target file exists → note "will delete" or "will skip (not found)"
+
+### Display the dry run summary:
+
+```
+Global Change — Pre-flight Summary
+Operation:  [operation]
+Target:     [relative-path/filename]
+Projects:   [N] registered
+
+[For update — show old/new content preview]
+
+Dry run results:
+  [status] [project-name] — [description]
+  [status] [project-name] — [description]
+```
+
+**Level 3 (Full Auto)**: If ALL projects show clean matches (no warnings), auto-proceed to Step 4 without asking. If ANY project shows a warning (no match, multiple matches), pause and ask.
+
+**Level 1-2**: Always pause and ask for confirmation.
+
+## Step 4: Execute Changes
+
+For each project that passed the dry run:
+
+### `copy`
+1. Determine the target: `{PROJECT_PATH}/{relative-path/filename}`
+2. If the target directory does not exist → create it (including intermediate directories)
+3. Copy the source file to the target, overwriting if it exists
+
+### `insert`
+1. Determine the target: `{PROJECT_PATH}/{relative-path/filename}`
+2. If the target directory does not exist → create it (including intermediate directories)
+3. If the target file does not exist → create it with the provided content
+4. If the target file exists → append a newline + the provided content to the end
+
+### `update`
+1. Determine the target: `{PROJECT_PATH}/{relative-path/filename}`
+2. If the file does not exist → skip
+3. Read the file contents
+4. Search for `old_content` (exact string match, whitespace-sensitive)
+5. If NOT found → skip
+6. If found → replace ALL occurrences of `old_content` with `new_content`
+7. Write the modified contents back to the file
+
+### `delete`
+1. Determine the target: `{PROJECT_PATH}/{relative-path/filename}`
+2. If the target file does not exist → skip
+3. If the target file exists → delete it
+4. Do NOT delete the parent directory even if empty
+
+### Error Handling
+- On failure, record: `FAILED: {error message}`
+- Never abort the entire run because one project failed — continue to the next
+
+## Step 5: Report Results
+
+Display the final summary:
+
+```
+Global Change — Results
+Operation:  [operation] [relative-path/filename]
+Succeeded:  [N] / [total] projects
+Failed:     [N]
+Skipped:    [N]
+
+  [status] [project-name] — [result]
+  [status] [project-name] — [result]
+```
+
+Status icons:
+- `✓` — success
+- `⊘` — skipped (file not found, no match, etc.)
+- `✗` — failed with error
+
+If there were failures, list them with actionable error messages.
+
+## Notes
+
+- **Relative paths use forward slashes** regardless of OS
+- **No glob patterns** — operates on a single file per invocation
+- **Content for `insert`** can be provided inline or pasted in the user's message
+- **Content for `update`** uses the `%%REPLACE_WITH%%` delimiter — old_content match is exact and whitespace-sensitive
+- **Project names in logs** are derived from the last segment of the project path
+- **The `.gsd-t-projects` file** is maintained by `gsd-t init` (auto-registers) and `gsd-t update-all` (reads)
+
+$ARGUMENTS
+
+## Auto-Clear
+
+All work is committed to project files. Execute `/clear` to free the context window for the next command.

package/commands/gsd-t-audit.md

@@ -0,0 +1,199 @@
+# GSD-T: Audit — Component Cost/Benefit Analysis and Shadow Testing
+
+You are running a harness self-audit — analyzing the cost and benefit of GSD-T enforcement components, with optional shadow mode testing.
+
+## Step 0: Launch via Subagent
+
+To keep the main conversation context lean, run audit via a Task subagent.
+
+**If you are the orchestrating agent** (you received the slash command directly):
+
+**OBSERVABILITY LOGGING (MANDATORY):**
+Before spawning — run via Bash:
+`T_START=$(date +%s) && DT_START=$(date +"%Y-%m-%d %H:%M") && TOK_START=${CLAUDE_CONTEXT_TOKENS_USED:-0} && TOK_MAX=${CLAUDE_CONTEXT_TOKENS_MAX:-200000}`
+
+Spawn a fresh subagent using the Task tool:
+```
+subagent_type: general-purpose
+model: sonnet
+prompt: "You are running gsd-t-audit with arguments: {$ARGUMENTS}
+Working directory: {current project root}
+Read CLAUDE.md and .gsd-t/progress.md for project context, then execute gsd-t-audit starting at Step 1."
+```
+
+After subagent returns — run via Bash:
+`T_END=$(date +%s) && DT_END=$(date +"%Y-%m-%d %H:%M") && TOK_END=${CLAUDE_CONTEXT_TOKENS_USED:-0} && DURATION=$((T_END-T_START))`
+Compute tokens and compaction:
+- No compaction (TOK_END >= TOK_START): `TOKENS=$((TOK_END-TOK_START))`, COMPACTED=null
+- Compaction detected (TOK_END < TOK_START): `TOKENS=$(((TOK_MAX-TOK_START)+TOK_END))`, COMPACTED=$DT_END
+Append to `.gsd-t/token-log.md` (create with header if missing):
+`| {DT_START} | {DT_END} | gsd-t-audit | Step 0 | sonnet | {DURATION}s | audit: {args summary} | {TOKENS} | {COMPACTED} | | | {CTX_PCT} |`
+
+Relay the subagent's summary to the user. **Do not execute Steps 1–5 yourself.**
+
+**If you are the spawned subagent** (your prompt says "starting at Step 1"):
+Continue to Step 1 below.
+
+## Step 1: Load Context
+
+Parse $ARGUMENTS for flags:
+- `--component=<id>` → target a specific component ID
+- `--shadow` → run in shadow mode (log results, don't enforce)
+- `--report-only` → show current cost/benefit ledger without running tasks
+
+Read:
+1. `.gsd-t/progress.md` — current milestone
+2. `.gsd-t/component-registry.jsonl` — all registered components
+3. `.gsd-t/metrics/component-impact.jsonl` — cost/benefit history
+
+If component registry is missing or empty, run:
+```
+node bin/component-registry.js --seed
+```
+or call `seedRegistry()` from `bin/component-registry.js`.
+
+## Step 2: Route by Mode
+
+### Mode: --report-only
+
+Skip to Step 3 (Report).
+
+### Mode: --shadow [--component=<id>]
+
+Skip to Step 4 (Shadow Run).
+
+### Mode: --component=<id> (no shadow, no report-only)
+
+Run A/B test: disable the target component for the next task run and compare outcomes. Skip to Step 5 (A/B Test).
+
+### Mode: no flags
+
+Generate a full cost/benefit report for all components. Go to Step 3 (Report).
+
+## Step 3: Cost/Benefit Report
+
+Read all records from `.gsd-t/metrics/component-impact.jsonl`.
+
+For each component in the registry, compute:
+- **Total token cost**: sum of `token_cost` across all milestones
+- **Total bugs prevented**: sum of `bugs_prevented`
+- **Total false positives**: sum of `false_positives`
+- **Verdict distribution**: count positive / neutral / negative verdicts
+- **Consecutive negative**: latest `consecutive_negative` value
+- **Status**: current status from registry (active / flagged / deprecated)
+
+Display a summary table:
+
+```
+## Component Cost/Benefit Report — {date}
+
+| Component           | Status   | Milestones | Tokens   | Bugs Prevented | False Positives | Positive | Neutral | Negative | Consec- |
+|---------------------|----------|------------|----------|----------------|-----------------|----------|---------|----------|---------|
+| Red Team Adv. QA    | active   | N          | N        | N              | N               | N        | N       | N        | N       |
+| QA Agent            | active   | N          | N        | N              | N               | N        | N       | N        | N       |
+| ...                 |          |            |          |                |                 |          |         |          |         |
+
+Flagged for review (consecutive_negative >= 3):
+- {component name} (comp-id) — {N} consecutive negative verdicts
+```
+
+If no impact data exists, show:
+```
+No impact data recorded yet. Impact is recorded during complete-milestone via recordImpact().
+```
+
+Write the report to `.gsd-t/audit-report.md`.
+
+## Step 4: Shadow Run
+
+Shadow mode: the target component runs normally but its enforcement actions are logged instead of applied.
+
+1. Identify the target component (from `--component=<id>` or all `shadow_capable: true` components if no ID)
+2. For each target component, check `shadow_capable: true` in registry — skip any that cannot shadow
+3. Log shadow run to `.gsd-t/audit-report.md`:
+
+```
+## Shadow Run — {component name} — {date}
+
+Component: {id}
+Shadow capable: {yes/no}
+Mode: logging only (enforcement skipped)
+
+Results:
+- Would have fired: {yes/no}
+- Findings that would have been enforced: {list or "none"}
+- Token cost (estimated): {N}
+
+Verdict: {what the component would have concluded}
+```
+
+4. Append impact record with verdict `neutral` (shadow runs don't count as real verdicts):
+```javascript
+recordImpact(componentId, milestone, { token_cost: estimated, bugs_prevented: 0, false_positives: 0, context_pct: 0, verdict: "neutral" })
+```
+
+## Step 5: A/B Test (Component Disabled)
+
+A/B test mode: disable the target component for the current task run and compare against baseline.
+
+1. Verify the component has `can_disable: true` — if not, abort with:
+   "Component {id} cannot be cleanly disabled (can_disable: false). Use --shadow instead."
+
+2. Note current state:
+   - Read last 3 milestones of impact history for this component
+   - Establish baseline: avg `bugs_prevented`, avg `token_cost`, avg verdict
+
+3. Run the current task WITHOUT the component:
+   - Log to audit report that the component was disabled for this run
+   - Document any quality differences observed (bugs missed, regressions, etc.)
+
+4. Compare results and write to `.gsd-t/audit-report.md`:
+
+```
+## A/B Test — {component name} — {date}
+
+Component: {id}
+Test milestone: {current milestone}
+Baseline (last 3 milestones): avg {N} bugs prevented, avg {N} tokens
+
+With component DISABLED:
+- Bugs caught by other mechanisms: {N}
+- Bugs missed: {N} (estimated)
+- Token savings: {N}
+- Quality delta: {positive/neutral/negative}
+
+Recommendation: {keep / deprecate / shadow-only}
+```
+
+5. Record the impact with verdict based on quality delta.
+
+## Step 6: Update Progress
+
+Append to `.gsd-t/progress.md` Decision Log:
+`- {date}: gsd-t-audit ran in {mode} mode — {brief summary of findings}`
+
+## Step 7: Report to User
+
+Present a concise summary:
+
+```
+## Audit Complete
+
+Mode: {report-only | shadow | a/b test | full report}
+Components analyzed: {N}
+Flagged for deprecation: {N}
+Report written to: .gsd-t/audit-report.md
+
+Key findings:
+- {finding 1}
+- {finding 2}
+```
+
+If any components have `consecutive_negative >= 3` (flagged status), add:
+```
+⚠ FLAGGED COMPONENTS — recommend patch lifecycle review:
+- {name} ({id}): {N} consecutive negative milestones
+  Run: /user:gsd-t-backlog-add to create a deprecation task
+```
+
+$ARGUMENTS