@tekyzinc/gsd-t 5.13.10 → 5.14.11

package/CHANGELOG.md

@@ -2,6 +2,90 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [5.14.11] - 2026-08-25
+
+### Fixed — gap analysis harvests the tracker instead of asking for a spec
+
+The client-deliverable mode shipped in 5.14.10 stalled a live run: it asked
+for a requirements document that was never going to exist. Root cause in how
+it was built — the proven session was distilled from the operator's turns, and
+the assistant's tool calls, where the actual derivation lived, were skipped
+(26 tracker calls, 21 graph calls, 25 agents).
+
+Five corrections, each traced to that session:
+
+- **Step 3a HARVEST replaces "parse the provided spec."** The source is the
+  tracker project itself. Attachments come first: on the proven run the project
+  description was empty and all three requirement documents were attached
+  files, one a 1,431-line Statement of Work whose Exhibit B was the real
+  specification. Then every task, then the 192 subtasks where the file
+  citations live because the parent tasks are coarse rollups, then comments. A
+  zero-task view is not an empty project until attachments have been checked.
+- **Step 3b REPAIR the graph.** Build it when missing, re-index when stale,
+  repair it when it emits unresolved edges and re-verify anything already
+  judged against it. Halt only when it cannot be built at all. The previous
+  text failed loud on a missing index, contradicting the standing rule that an
+  absent index is repairable.
+- **Tracker status is a flag, never an answer.** On the proven run three of six
+  tasks showed open while their own comments named the shipping pull request
+  and commits.
+- **Debt mappings resolve through `.gsd-t/techdebt.md`** for real file
+  citations; 152 of 154 subtasks had to be matched back to the local register
+  because the tracker notes were too thin to judge from.
+- **A red-team finding can overturn a status call**, not just its wording. One
+  checker reversed a verdict by reading the code the original judgment had not.
+
+- `commands/gsd-t-gap-analysis.md`: Steps 3a and 3b added; Step 2 is skipped in
+  client-deliverable mode.
+- `.gsd-t/pseudocode/PseudoCode-GapAnalysis.md`: harvest and graph-repair flows.
+
+## [5.14.10] - 2026-08-25
+
+### Added — gap analysis can now produce a red-teamed client deliverable
+
+`/gsd-t-gap-analysis` gains a second mode, distilled from the HILO AI
+Scheduling run. That workflow existed only in one session's history: it was
+recovered from the live transcript and from the estimating sheet itself, read
+through the service-account path `/gsd-t-estimate` already uses.
+
+The real artifact was measured rather than guessed: 33 feature rows carrying
+595 checkable claims — 33 purpose sentences, 241 requirement bullets, 108 gap
+bullets, 32 status notes, 76 references, 104 debt mappings — with the estimate
+columns still empty.
+
+**Upgraded in place, not retired.** Without `--sheet`, the command produces the
+markdown report exactly as before, so the two tests and two workflows that call
+it keep working unchanged. With `--sheet <url>`, it runs the full procedure:
+strip everything that would not add code or stored data, roll the survivors up
+into features whose individual requirements are bullets inside one row,
+describe each in instruction voice, judge it against the code, red team the
+result, and write columns A-D and M-P.
+
+Four decisions came from the evidence rather than from preference:
+
+- **The strip step blocks for human confirmation.** It removes most of the
+  input, and it needed live correction during the proven run — "run in shadow
+  beside real schedules" is operational policy, not something anyone builds. A
+  wrongly-dropped requirement is invisible in every later artifact.
+- **The checkers are a red team, not reviewers.** They are told the sheet
+  contains false claims and asked to produce them. A friendly seven-row sample
+  had already approved a column later found 70% defective — 45 of 64 sentences.
+- **Coverage splits by what one check costs.** Every claim is checked where
+  checking means reading a sentence or following a link; claims that require
+  proving code is absent are checked in a batch of 20, widening to every claim
+  when three or more of the batch are wrong.
+- **All checkers returning clean is a failed check**, not a clean sheet. The
+  proven run had one clean column out of six.
+
+A correction is treated as an unverified claim: fresh checkers attack the fixed
+cells, and two non-converging cycles halt rather than looping. The money
+columns are never written — `/gsd-t-estimate` owns those, and the sheet's own
+formulas compute days and dollars from them.
+
+- `commands/gsd-t-gap-analysis.md`: Steps 4a-6c, gated on `--sheet`.
+- `.gsd-t/pseudocode/PseudoCode-GapAnalysis.md`: behaviour map, style gate
+  clean.
+
 ## [5.13.10] - 2026-08-22
 
 ### Added — trim and case are enforced at the boundary, FAIL-CLOSED

package/README.md

@@ -1,6 +1,6 @@
 # GSD-T: Contract-Driven Development for Claude Code
 
-**v5.13.10** - A methodology for reliable, parallelizable development using Claude Code with optional Agent Teams support.
+**v5.14.11** - A methodology for reliable, parallelizable development using Claude Code with optional Agent Teams support.
 
 **Eliminates context rot** — task-level fresh dispatch (one subagent per task, ~10-20% context each) means compaction never triggers.
 **Compaction-proof debug loops** — `gsd-t headless --debug-loop` runs test-fix-retest cycles as separate `claude -p` sessions. A JSONL debug ledger persists all hypothesis/fix/learning history across fresh sessions. Anti-repetition preamble injection prevents retrying failed hypotheses. Escalation tiers (sonnet → opus → human) and a hard iteration ceiling enforced externally.

package/commands/gsd-t-gap-analysis.md

@@ -2,6 +2,19 @@
 
 You are performing a gap analysis between a provided specification and the existing codebase. The user pastes requirements or a spec, and you systematically identify what's done, what's partial, what's wrong, and what's missing.
 
+## Two modes — chosen by whether a sheet URL was given
+
+| Invocation | Mode | Output |
+|---|---|---|
+| `/gsd-t-gap-analysis <spec>` | **Report** (default) | `.gsd-t/gap-analysis.md` — Steps 0.5-9 below, unchanged |
+| `/gsd-t-gap-analysis <spec> --sheet <url>` | **Client deliverable** | The estimating sheet's columns A-D and M-P, red-teamed — Steps 3a-6c |
+
+**Report mode is the default and is unchanged.** Every existing caller — `/gsd-t-scan`'s next-step offer, `gsd-t-phase.workflow.js` routing — invokes it without `--sheet` and behaves exactly as before.
+
+**Client-deliverable mode** is the procedure proven on the HILO AI Scheduling sheet: 141 raw requirements reduced to 33 feature rows carrying 595 checkable claims, judged against the code, then attacked by a red team that found a 70% defect rate in a column a friendly sample had already approved. It writes only the *what and whether* columns; `/gsd-t-estimate` sizes and prices them afterward. Behaviour map: `.gsd-t/pseudocode/PseudoCode-GapAnalysis.md`.
+
+In client-deliverable mode, run Step 0.5 and Step 1, then branch to **Step 3a (Harvest)** — do NOT run Step 2 (Parse Requirements). Step 2 assumes a finished specification was handed to you; in this mode **there usually is no such document**, and expecting one is how a run stalls asking for a spec that was never going to exist.
+
 ## Step 0.5: Scan Freshness Auto-Refresh
 
 ```bash
@@ -181,6 +194,153 @@ If agent teams are not available or there are fewer than 3 requirements, run seq
 - Read source files, test files, config, schema, contracts, and docs
 - Classify each requirement with evidence
 
+---
+
+# Client-deliverable mode (Steps 3a-6c) — only when `--sheet <url>` was given
+
+Report mode skips this whole block and continues at Step 6.
+
+## Step 3a: HARVEST the sources — the requirements do not exist yet, you are deriving them
+
+**Do not ask the user for a requirements document. In this mode there usually isn't one.** The job is to harvest everything a tracker project holds and synthesize requirements from it. A run that stops to request a spec has misread the task — this exact stall happened on the FRC Predictive run.
+
+Harvest, in this order, and report a count for each:
+
+1. **The project's attachments** — NOT its description. On the proven run the description was empty and all three requirement documents were attached files. Pull `attachments?parent=<project_gid>`, then each attachment's `download_url`, and read them. A Statement of Work PDF was the single richest source: **1,431 lines, whose Exhibit B (~1,000 lines) was the real specification.**
+2. **Every task** — name, notes, and status.
+3. **Every subtask.** Parent tasks are usually coarse rollups; the real detail and the file citations live one level down. The proven run pulled **192 subtasks** because *"the rollups are too coarse."* One rollup alone carried 46 findings.
+4. **Task comments.** One Bugs section — a ticket plus three pull-request comments — drove several rows by itself.
+5. **Any spec documents in the repo**, if the user named one.
+
+**An empty section list or a zero-task view is not an empty project.** Check attachments before concluding anything is missing.
+
+**If a genuinely required source cannot be reached** — no credentials, a 403, an attachment that will not download — say exactly which one and stop. That is a blocked run. "The project has no tasks" is not, until attachments have been checked too.
+
+**Tracker status is unreliable — never carry it through as truth.** On the proven run *"3 of the 6 tasks still show open, but their comments say implemented in PR #4386 with named commits."* Every status is re-decided against the code in Step 5a; a tracker status only ever becomes a flag that the tracker disagrees with reality.
+
+## Step 3b: REPAIR the graph before you rely on it
+
+The judgment in Step 5a is only as good as the index it queries.
+
+1. `gsd-t graph status`.
+2. **Missing → build it**: `gsd-t graph index` (allow up to 900s on a large repo). An absent index is repairable, never a reason to stop.
+3. **Stale → re-index** the touched set.
+4. **Broken → repair, then re-verify anything already judged against it.** The proven run found its own index producing *"unresolved call edges"* and had to re-check the Partial/Implemented calls that hinge on whether code is actually wired in.
+5. **Cannot build it → HALT.** Do not answer structural questions by grep; grep matches text, and the question is about relationships.
+
+Report which of these happened. A silent "the graph was fine" claim is not acceptable — say whether it was built, re-indexed, repaired, or already current.
+
+## Step 4a: Strip everything that isn't buildable — HUMAN-CONFIRMED
+
+**This step removes most of the input, and getting it wrong poisons every step after it.**
+
+Sort every parsed requirement by one question: **would building it add or change code, or something stored?**
+
+- **Yes → keep.** A setting the system reads, a rule it applies, a screen, an endpoint, a table.
+- **No → drop.** Rollout policy, planning steps, trial design, training plans, decisions about how to run the project.
+
+Worked examples from the proven run:
+
+| Item | Verdict | Why |
+|---|---|---|
+| "Run in shadow beside real schedules" | **DROP** | An operational policy. Nobody writes code for it. |
+| "Resolve each student's required events-per-week" | **KEEP** | A computation the system performs. |
+| "Agree the scheduling priorities with stakeholders" | **DROP** | A planning step. Its *output* may become a rule; the step itself is not one. |
+| "Store per-location override for duty limits" | **KEEP** | Stored data plus the code that reads it. |
+
+A planning step whose *result* is a rule: drop the step, keep the rule if the rule is stated somewhere. If it isn't, the rule doesn't exist yet — say so under open questions rather than inventing it.
+
+**Keep the dropped list with a one-line reason each**, and show the user the count kept vs dropped plus the full dropped list. **Wait for confirmation before continuing** — this is the one blocking pause in the flow, because a wrongly-dropped requirement is invisible in every later artifact.
+
+## Step 4b: Roll up to features
+
+Group the survivors into features a person would name (`Availability, Operating Hours and Blackouts`, not `SCH-046`).
+
+- One feature = one row. Its individual requirements become **bullets inside that row's cell**, never rows of their own.
+- Target shape, measured on the proven sheet: **33 rows carrying 241 bullets** — roughly 3-10 bullets per row.
+- Assign each row a **domain** (column A) and the **user types** it serves (column B).
+
+## Step 4c: Describe each feature
+
+- **Column C** — the feature name in bold, then ONE sentence of purpose beneath it.
+- **Column D** — the requirements as bullets, written as **instructions**: "Work out each student's required events-per-week." **Never** as statements of current fact: "Resolves each student's required events-per-week."
+
+Present tense reads as a description of working code. On a row that turns out to be unbuilt, the row contradicts itself — this exact defect appeared in the proven run and had to be rewritten across all 32 rows.
+
+Plain words in column D. No jargon a client would have to decode.
+
+## Step 5a: Judge each feature against the code
+
+Query the code graph for each feature's surface (`gsd-t graph`), read what it names, and decide:
+
+- **Implemented** — every bullet is built.
+- **Not Implemented** — none of it is.
+- **Partial** — some is. **MUST be followed by `Not implemented:` and the specific bullets that are missing.** A bare "Partial" is not an answer anyone can act on.
+
+Write the verdict to **column M**, and to **column N** what works today versus what does not.
+
+## Step 5b: References and impacting debt
+
+- **Column O** — where each claim came from: `Requirements doc (6 reqs) · Asana task · PR #4386`. Short clickable names, each token its own link. Never a wall of file paths.
+- **Column P** — open Extreme/Critical findings that would hit this feature. **Judge by the code each finding cites, not by keyword match.**
+
+**Where the findings come from, and why the tracker alone is not enough:** pull the hardening project's open items at **subtask level** — the parent tasks are rollups. Then **match each subtask back to `.gsd-t/techdebt.md`** for its real file citations. On the proven run the tracker notes were too thin to judge from, and 152 of 154 subtasks had to be resolved against the local register to get the file paths that make the mapping decidable. Of 154 open subtasks, 28 genuinely touched the feature set.
+
+A feature with no findings is a real answer, not a miss — usually an unbuilt feature with no shipped code for a defect to land on. Say so rather than leaving the cell ambiguous.
+
+## Step 6a: RED TEAM the sheet — NOT a review
+
+Spawn adversarial checkers via the `Agent` tool, **blocking, no `name`** (see the blocking-subagent guard in `gsd-t-quick.md`). Each gets a fresh context and this framing:
+
+> **This sheet contains false claims. Your job is to find them.** Report what is wrong and where. If you searched exhaustively and found nothing, say so plainly — a clean verdict must be earned.
+
+Verdict per checker: `FAIL` (defects listed) or `GRUDGING-PASS` (searched, found none).
+
+**Coverage is split by what one check costs:**
+
+| Column | Claims (proven sheet) | Coverage | Why |
+|---|---|---|---|
+| C — purpose sentences | 33 | **Every one** | Reading a sentence is free. A 7-row sample here missed a 70% defect rate. |
+| D — requirement bullets | 241 | **Every one** | Text against source text; no code read needed. |
+| N — status notes | 32 | **Every one** | Cheap. |
+| O — references | 76 | **Every one** | A link resolves or it doesn't. |
+| Dropped list (Step 4a) | all | **Every one** | A wrongly-dropped requirement is invisible downstream — nothing else can catch it. |
+| M — gap bullets | 108 | **Batch of 20** | Each asserts code is absent; disproving it costs a search. |
+| P — debt mappings | 104 | **Batch of 20** | Each needs the finding read AND the feature's code read. |
+
+**Widening rule:** if **3 or more** of a batch of 20 are wrong, that column goes to every-claim. The batch proved the column is unreliable; sampling further only hides the rest.
+
+**A red-team finding can overturn the analysis, not just its wording.** On the proven run a checker reversed a substantive verdict: *"My reconciliation claimed aircraft ranking didn't exist. The code does build a real ordered list."* When a checker contradicts a status call, the checker's evidence wins unless you can cite code that refutes it — the checker read the code fresh, the original judgment did not.
+
+**One checker does nothing but hunt cross-column contradictions** — a row whose column C asserts a capability in present tense while column M lists that same capability as the row's defining gap. No single-column checker can see this; it is the defect class that reached the client sheet in the proven run.
+
+**All checkers returning clean is a FAILED check, not a clean sheet.** The proven run had one clean column out of six. An all-clean result means the framing was too gentle: re-run with sharper prompts. Do NOT report a clean sheet on the first all-pass.
+
+## Step 6b: Fix, then RE-RED-TEAM the fixes
+
+1. Correct the cells the red team named.
+2. Hand the corrected cells to a **fresh** red team — a correction is an unverified claim, exactly like the original.
+3. Clean → done. Still failing → correct once more, check once more.
+4. **Still failing after the second cycle → HALT.** Report to the user what will not settle. Two rounds that cannot converge signals a wrong premise, not a third round.
+
+## Step 6c: Write the sheet — leave the money alone
+
+Write columns **A-D and M-P** using the service-account path documented in `commands/gsd-t-estimate.md` Step 5 (permanent SA `gsd-t-sheets-writer@ai-estimator-415612.iam.gserviceaccount.com`, self-signed JWT, Sheets v4 REST). A `403` on the read-probe means the sheet isn't shared — prompt the user to share it as Editor and re-probe.
+
+**NEVER write columns E-L** (Phase, Web Portal, Backend/API, Days, MFactor Days, Total Days, LOW $, HIGH $). Those are `/gsd-t-estimate`'s to fill, and the sheet's own formulas compute the money from them.
+
+Then end with:
+
+```
+## ▶ Next Up
+
+**Estimate** — size the gaps and price them
+
+`/gsd-t-estimate --sheet {url}`
+```
+
+---
+
 ## Step 6: Generate Gap Analysis Document
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "5.13.10",
+  "version": "5.14.11",
   "description": "GSD-T: Contract-Driven Development for Claude Code — 54 slash commands with headless-by-default workflow spawning, unattended supervisor relay with event stream, graph-powered code analysis, real-time agent dashboard, task telemetry, doc-ripple enforcement, backlog management, impact analysis, test sync, milestone archival, and PRD generation",
   "author": "Tekyz, Inc.",
   "license": "MIT",