@tekyzinc/gsd-t 4.15.10 → 4.16.10

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [4.16.10] - 2026-07-01
+
+### Added — `/gsd-t-estimate`: Tekyz client estimate + PRD from a scan
+
+New standalone command that turns a completed scan (`.gsd-t/techdebt.md`) into a Tekyz client estimate (a Google Sheet with a T-Shirt-Size tab + a Team-Mix cross-check) and a matching PRD deliverable. Encodes the 7-phase Tekyz playbook proven on the HILO Figma ATOS project (21 criticals → 32.73 eng-days → $13,090–$16,362).
+
+- `commands/gsd-t-estimate.md` — the skill: scope + read register; client renumber to TD-1 (range-bounded, archives untouched, second pass for bare/chained refs); T-shirt sizing (XS.25/S.5/M1/L3/XL5/XXL7, FE+BE columns independent); familiarization bump for new teams (bump SIZE not MF, never cross the M→L 3× cliff); Google Sheet write via a throwaway service-account + JWT (gcloud's spreadsheets scope is Google-blocked); domain grouping + SUMIF-range widen; Team-Mix reconcile; PRD with FR↔TD crosswalk + estimate-not-quote disclaimer + §10-syncs-the-sheet; three-total verify.
+- `templates/playbooks/tekyz-estimation-and-prd-playbook.md` — bundled reference (ships in the package so the skill works in a fresh install).
+- `commands/gsd-t-help.md`, `templates/CLAUDE-global.md`, `README.md` — doc-ripple (help summary, successor mapping `scan → estimate`, commands table).
+- `test/filesystem.test.js` — command count 45→46 / 51→52.
+
+Note: this produces a paid CLIENT estimate — the "no cost estimates" rule governs GSD-T's own Max-funded build work, not client deliverables.
+
 ## [4.15.10] - 2026-06-30
 
 ### Added — scan builds the graph index when absent + repo-labeled `share/` export

package/README.md

@@ -1,6 +1,6 @@
 # GSD-T: Contract-Driven Development for Claude Code
 
-**v4.15.10** - A methodology for reliable, parallelizable development using Claude Code with optional Agent Teams support.
+**v4.16.10** - 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.
@@ -186,6 +186,7 @@ This will replace changed command files, back up your CLAUDE.md if customized, a
 | `/gsd-t-scan` | Deep codebase analysis → techdebt.md | Manual |
 | `/gsd-t-gap-analysis` | Requirements gap analysis — spec vs. existing code | Manual |
 | `/gsd-t-promote-debt` | Convert techdebt items to milestones | Manual |
+| `/gsd-t-estimate` | Turn a scan into a Tekyz client estimate (Google Sheet: T-Shirt Size + Team Mix) + matching PRD | Manual |
 | `/gsd-t-populate` | Auto-populate docs from existing codebase | Manual |
 | `/gsd-t-design-decompose` | Decompose design into element/widget/page contracts | Manual |
 

package/commands/gsd-t-estimate.md

@@ -0,0 +1,100 @@
+# GSD-T: Estimate — Tekyz Client Estimate + PRD from a Scan
+
+You are turning a completed GSD-T tech-debt scan into a **Tekyz client estimate** (a Google Sheet with a T-Shirt-Size tab + a Team-Mix cross-check) and a matching **PRD deliverable**. `$ARGUMENTS` may carry a scope override (e.g. `--severity high`).
+
+**Full proven procedure:** read `~/.claude/playbooks/tekyz-estimation-and-prd-playbook.md` if present, else the bundled copy `templates/playbooks/tekyz-estimation-and-prd-playbook.md` in the GSD-T package (7 phases, produced on the HILO Figma ATOS project: 21 criticals → 32.73 eng-days → $13,090–$16,362). Supporting memories (in the originating project's memory dir): `tekyz-estimation-method`, `tekyz-familiarization-bump`, `tekyz-client-prd-structure`, `tekyz-tech-debt-numbering-caution`, `google-sheets-service-account-workaround`. This skill ENCODES those; read them for edge-case depth.
+
+> **Client-billed work, not GSD-T build work.** This produces a paid client estimate — the "no cost estimates" rule (`feedback_no_human_hour_estimates`) governs GSD-T's OWN Max-funded build work, NOT client deliverables. Dollar figures here are correct and expected.
+
+## Step 0: Inputs + Scope
+
+1. Read `.gsd-t/techdebt.md` (the register). If absent → "No scan register found. Run `/gsd-t-scan` first." and stop.
+2. **Scope** (from `$ARGUMENTS`): default = **all CRITICAL findings** ("close the critical gap"). `--severity high` (or `medium`/`low`/`all`) widens it. Confirm the scope + finding count with the user before sizing.
+3. Confirm you have (or ask the user for):
+   - A copy of the Tekyz estimate template Google Sheet (tabs: **Overview**, **T-Shirt Size Estimate**, **Team Mix**, **Technology Stack**) + its sheet ID.
+   - The GCP project id for the service-account write path (Phase 5).
+4. Decide whether this is a **new-team project** (triggers the familiarization bump, Step 3.5) — usually YES for a fresh client.
+
+## Step 1: Renumber for the client (if scan TDs start high)
+
+GSD-T continues TD numbering across scans (never resets) — a fresh/crashed-and-rerun scan can start at e.g. TD-618, which looks bad to a client ("why does finding #1 start at 618?"). **For a new client project, renumber the deliverables to start at TD-1.** (`tekyz-tech-debt-numbering-caution`.)
+
+Renumber SAFELY (numbering-only, zero value changes):
+- **Confirm the register IDs are contiguous** (`min..max`, no gaps) first, so a blind offset (`subtract base−1`) aligns.
+- **Range-bounded regex** — remap ONLY numbers in the register's actual range, so you never corrupt `DC-n`, another project's `TD-4`, or a different repo's numbering.
+- **Scope to CURRENT deliverables only:** register, plain-English companion, `.gsd-t/scan/*.md`, `docs/*.md`, README, the PRD, `share/*`, and the Google Sheet labels. **Leave `.gsd-t/scan/archive/`, transcripts, heartbeats UNTOUCHED** (historical run numbering).
+- **Second pass for non-`TD-` formats:** bare `| 618 |` table cells, slashed chains (`TD-2/623`, `626/629/631`), header text ("begins at TD-618"). A first-pass `TD-NNN` regex misses these.
+- **Back up files before the bulk edit.**
+- Offer this as an option; a client that wants the original numbering keeps it.
+
+## Step 2: Size each finding (T-Shirt Size tab)
+
+For each in-scope finding, build a row — cols **A** Module · **B** User Type · **C** Functionality (**include the `(TD-n)`**) · **D** Low-Level Requirement · **E** Phase (MVP) · **F** Web Portal (frontend) size · **G** Backend/API size. **Leave H–L (formulas) alone.**
+
+- **Size each column INDEPENDENTLY** (FE and BE each get their own letter; blank = 0). Sizes: **XS 0.25 · S 0.5 · M 1 · L 3 · XL 5 · XXL 7** person-days.
+- The sheet computes: `Days = F+G` · `MFactor Days = Days × Total MF` · `Total Days = Days + MFactor` · `LOW $ = Total × 8hrs × $50/hr` · `HIGH $ = LOW × High Factor (1.25)`. **Ignore the Phase column.**
+- **Cluster by fix-shape to size fast:** "add existing auth guard to N routes" (XS–S, repeated pattern) vs "new backend surface" (M, +FE) vs "config / single route" (XS). Size the cluster once, apply to its members.
+- **Tune the MF per project:** `Total MF` (default 0.7) = QA 0.3 + PM 0.1 + Analysis 0.05 + Deployment 0.05 + Buffer 0.2. Raise Buffer/QA when confidence is low; raise **High Factor** above 1.25 for more unknowns.
+
+## Step 2.5: Familiarization bump (new-team projects only)
+
+Base sizes assume *familiar* devs. For a team new to the codebase, add ramp by **bumping each item's SIZE in proportion to its complexity — NOT the MF** (the Analysis MF is for a Business Analyst, not dev ramp). (`tekyz-familiarization-bump`.)
+
+- Trivial config / single-route → **no bump**. Repeated-pattern guards, few routes → **+0–1 tier**. High-volume sweeps + new-surface builds → **+1 tier**.
+- **⚠️ The scale is NON-LINEAR. M→L is a 3× cliff (1 day → 3 days).** A blind one-tier bump across M→L doubles the total. **Never push an item across M→L unless it is genuinely multi-day.** Cap bumps at M for routine work.
+- Optionally add a one-time **"Codebase Onboarding & Downstream Analysis"** Common line (sized L–XL) for initial ramp on a large repo — separate from per-task build. Document it as an optional line the client can remove.
+- Reference calibration: HILO 21 criticals = $8,700 familiar → $11,730 new-team (+35%, bumps capped at M) → $13,090 incl Project Setup.
+
+## Step 3: Group by domain + blue headings (T-Shirt tab)
+
+Reorder items into domains (**A–G to match the PRD sections**). Insert a **blue section-heading row** before each group (merge A:L, white bold on blue). **No subtotals** (they complicate formulas).
+
+- **After reordering, WIDEN the rollup SUMIF ranges** (e.g. `E19:En`). Writing cells does NOT auto-expand hardcoded ranges — only `insertDimension` shifts them. A missed widen silently under-counts the total.
+
+## Step 4: Team Mix cross-check
+
+`Count` = fractional headcount per role (e.g. Backend 0.75 = one BE dev at 75% over the window). `Days (E) = Month(D) × 20` · `Total Days = Days × Count`.
+
+- **Solve `Month` (D5:D12)** so `sum(Count) × (Month×20) = the T-shirt total`. Sync the Resource (J) column.
+- **Check for hardcoded cells** breaking the formula chain (restore `=E×B`, `=J` where a static number was pasted — the Testing row is a known offender).
+- **Verify BOTH halves (F13, J13) equal the T-shirt total.**
+
+## Step 5: Write to the Google Sheet (service-account path)
+
+**gcloud's `spreadsheets` scope is blocked by Google** — use a throwaway service account (`google-sheets-service-account-workaround`):
+
+1. Confirm Sheets API enabled: `gcloud services list --enabled --project=<proj> --filter="config.name:sheets.googleapis.com"` (else `gcloud services enable sheets.googleapis.com`).
+2. Create a THROWAWAY SA (don't reuse a prod SA): `gcloud iam service-accounts create sheets-writer-tmp --project=<proj>`. **SA creation is eventually-consistent** — poll `describe` before minting the key.
+3. Mint a key: `gcloud iam service-accounts keys create key.json --iam-account=sheets-writer-tmp@<proj>.iam.gserviceaccount.com`.
+4. **PROMPT THE USER to share the sheet with the SA email as Editor** — the robot has no access until shared. (If the SA is deleted+recreated the identity changes → must re-share even if the email string is identical.)
+5. Sign a JWT (RS256 via `openssl dgst -sha256 -sign key.pem`), scope `https://www.googleapis.com/auth/spreadsheets`, exchange at `oauth2.googleapis.com/token`, call Sheets v4 REST (`values.../PUT?valueInputOption=USER_ENTERED` for cells; `:batchUpdate` for inserts/formatting/merges). Pure Python stdlib + openssl, no libs. **URL-encode sheet ranges** (spaces in tab names break the URL). Token expires in 1h — regenerate.
+6. **CLEANUP:** `gcloud iam service-accounts delete` the throwaway SA (removes its keys) + `rm` the local key — but leave the SA alive until the user confirms they're done editing, to avoid re-share churn.
+
+## Step 6: Generate the PRD
+
+**ONE document** (ATOS contractor-handoff template, sections 0–15) with **domain sub-sections (A–G) inside each numbered section** — not one PRD per item. (`tekyz-client-prd-structure`.)
+
+- **§0 Metadata + top-of-doc ⚠️ Estimate Basis & Disclaimer** — planning estimates, NOT a quote/bid/fixed price; will change; no not-to-exceed; no delivery guarantee. **Purge all quote/fixed/guarantee/binding language.**
+- **§3.0 FR↔TD crosswalk** — per-domain tables (Requirement · Finding · Fix). `FR-xN` (domain-sequenced requirement id) and `TD-n` (permanent scan finding id) do NOT run in parallel — always crosswalk them.
+- **§3.1 FR tables** — a **dedicated Finding column** (never bury `TD-n` in trailing prose).
+- **§3.2 NFR** — an **"Applies to" column listing EVERY `TD-n`** each cross-cutting NFR touches.
+- **§4 enforcement, §8 API, §10 estimate** — explicit `TD-n` refs (not bare numbers).
+- **§10 total MUST equal the live sheet rollup** — verify against the sheet's rollup cell, not memory. Watch that Project Setup carries its MF (M/M = 2 raw → 3.4 total, not 2.0). Point-in-time sync is fine; note it.
+- **§15 sign-off = "Approved to proceed (scope, not fixed cost)".**
+- Group tables **by domain with a bold header per group** (no repeating "Domain" column — reads as broken).
+- **Save to `share/<Repo-Name>-PRD-*.md`** (repo-name prefix, matching `/gsd-t-scan`'s `share/` convention).
+
+## Step 7: Verify + Deliver
+
+**Reconcile the three totals — they MUST agree:** T-Shirt Size total = Team Mix total (F13/J13) = PRD §10 total. If any differ, find the break (usually a hardcoded cell or an un-widened SUMIF range) and fix before reporting done.
+
+All client-facing files land in `share/` with the repo-name prefix. Report: scope + finding count, the eng-days + LOW–HIGH dollar range, the sheet URL, and the PRD path.
+
+## Document Ripple
+
+- `share/<Repo>-PRD-*.md` (new PRD deliverable) + the Google Sheet (external).
+- If renumbering (Step 1) ran: the register + plain-English + `scan/*.md` + `docs/*` + README + `share/*` were remapped (archives untouched) — note it in the report so the numbering change is traceable.
+
+## ▶ Next Up
+
+Standalone command — no auto-successor. After delivering, the user shares the sheet + PRD with the client.

package/commands/gsd-t-help.md

@@ -358,6 +358,12 @@ Use these when user asks for help on a specific command:
 - **Updates**: `.gsd-t/roadmap.md`, `.gsd-t/techdebt.md`
 - **Use when**: Ready to address technical debt items
 
+### estimate
+- **Summary**: Turn a completed scan (`.gsd-t/techdebt.md`) into a Tekyz client estimate (Google Sheet: T-Shirt Size + Team Mix) and a matching PRD deliverable
+- **Auto-invoked**: No
+- **Updates**: the Tekyz estimate Google Sheet + `share/<Repo>-PRD-*.md` (and, if renumbered, the register/docs/scan files)
+- **Use when**: A scan is done and you need a client-facing paid estimate + PRD (T-shirt sizing, dollar range, sign-off). Encodes the 7-phase Tekyz playbook (`~/.claude/playbooks/tekyz-estimation-and-prd-playbook.md`)
+
 ### populate
 - **Summary**: Auto-populate all living docs from existing codebase analysis
 - **Auto-invoked**: No

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "4.15.10",
+  "version": "4.16.10",
   "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",

package/templates/CLAUDE-global.md

@@ -452,7 +452,7 @@ Add `**Also available:**` with `- /gsd-t-{alt} — {desc}` lines if alternatives
 | `integrate` | `verify` | |
 | `verify` | *(auto-invokes complete-milestone)* | |
 | `complete-milestone` | `status` | |
-| `scan` | `promote-debt` | `milestone` |
+| `scan` | `promote-debt` | `milestone`, `estimate` (client estimate + PRD) |
 | `init` | `scan` | `milestone` |
 | `init-scan-setup` | `milestone` | |
 | `gap-analysis` | `milestone` | `feature` |
@@ -460,7 +460,7 @@ Add `**Also available:**` with `- /gsd-t-{alt} — {desc}` lines if alternatives
 | `setup` | `status` | |
 | `design-decompose` | `design-build` | `partition` (if domains needed first) |
 
-Commands with no successor (standalone): `quick`, `debug`, `brainstorm`, `status`, `help`, `resume`, `prompt`, `log`, `health`, `pause`, backlog commands.
+Commands with no successor (standalone): `quick`, `debug`, `brainstorm`, `status`, `help`, `resume`, `prompt`, `log`, `health`, `pause`, `estimate`, backlog commands.
 
 Skip the hint if auto-advancing (Level 3 mid-wave) — only show when the user needs to manually invoke the next step.
 

package/templates/playbooks/tekyz-estimation-and-prd-playbook.md

@@ -0,0 +1,112 @@
+# Tekyz Estimation + PRD Playbook
+
+> Reusable procedure for producing a Tekyz client estimate (Google Sheet: T-Shirt
+> Size + Team Mix) and a matching PRD deliverable, from a GSD-T tech-debt scan.
+> Proven on the HILO Figma ATOS project (21 criticals → 32.73 eng-days →
+> $13,090–$16,362). Apply to E-Learning and any other GSD-T client project.
+
+Related memory: `tekyz-estimation-method`, `tekyz-familiarization-bump`,
+`tekyz-client-prd-structure`, `tekyz-tech-debt-numbering-caution`,
+`google-sheets-service-account-workaround`.
+
+---
+
+## Phase 0 — Inputs
+
+1. A completed GSD-T scan (`.gsd-t/techdebt.md`) with findings by severity.
+2. A copy of the Tekyz estimate template Google Sheet (tabs: **Overview**,
+   **T-Shirt Size Estimate**, **Team Mix**, **Technology Stack**).
+3. The ATOS contractor-handoff PRD template (sections 0–15).
+4. Decide the scope: usually **all CRITICAL findings** = "close the critical gap."
+
+---
+
+## Phase 1 — Renumber for the client (if scan numbers start high)
+
+GSD-T continues TD numbering across scans; a fresh/crashed-and-rerun scan can start
+at e.g. TD-618. **For a new client project, renumber to TD-1** before sharing.
+
+- Verify the register IDs are contiguous (`min..max`, no gaps) → clean offset.
+- Remap **only** numbers in the register's range (range-bounded regex) so you don't
+  touch `DC-n`, other projects' TDs, or another repo's numbering.
+- Scope: register, plain-English, `scan/*.md`, `docs/*.md`, README, PRD, `share/*`,
+  and the Google Sheet labels. **Leave archives / transcripts / heartbeats alone.**
+- Second pass for non-`TD-` formats: bare `| 618 |`, chains `TD-2/623`, header text.
+- Back up files first.
+
+---
+
+## Phase 2 — Size each finding (T-Shirt tab)
+
+For each finding, write a row (cols A–G; leave H–L formulas alone):
+`A` Module · `B` User Type · `C` Functionality (include the `(TD-n)`) ·
+`D` Low-Level Requirement · `E` Phase (MVP) · `F` Web Portal size · `G` Backend/API size.
+
+- Size **each column independently** (FE and BE). Sizes: XS .25, S .5, M 1, L 3, XL 5, XXL 7.
+- Sheet computes: `Days = F+G`, `MFactor = Days×MF`, `Total = Days+MFactor`,
+  `LOW$ = Total×8×$50`, `HIGH$ = LOW$×1.25`.
+- **Cluster the work** to size fast: "add existing auth guard to routes" (XS–S,
+  repeated pattern) vs "new backend surface" (M, +FE) vs "config/1-route" (XS).
+
+### Familiarization bump (new-team projects)
+Base sizes assume *familiar* devs. For a new team, bump SIZE in proportion to
+complexity (NOT the MF — Analysis MF is for a Business Analyst):
+- Trivial → no bump. Repeated-pattern guards → +0-1 tier. High-volume sweeps +
+  new-surface → +1 tier. **Never cross the M→L cliff (3×) unless genuinely multi-day.**
+- Optionally add a one-time "Codebase Onboarding & Downstream Analysis" Common line (L–XL).
+
+### Tune the MF (per project)
+`Total MF` = QA + PM + Analysis + Deployment + Buffer (default 0.7). Raise Buffer/QA
+when confidence is low; raise **High Factor** above 1.25 for more unknowns.
+
+---
+
+## Phase 3 — Group by domain + blue headings (T-Shirt tab)
+
+Reorder items into domains (A–G to match the PRD). Insert a **blue section-heading
+row** before each group (merge A:L, white bold on blue). No subtotals (they complicate
+formulas). After reordering: **widen the rollup SUMIF ranges** (`E19:En`) — writing
+cells does NOT auto-expand hardcoded ranges; only `insertDimension` shifts them.
+
+---
+
+## Phase 4 — Team Mix cross-check
+
+`Count` = fractional headcount per role (fixed team shape). Solve `Month (D)` so
+`sum(Count) × (Month×20) = T-shirt total`. Write `Month` to D5:D12; sync the Resource
+(J) column. **Check for hardcoded cells** that break the formula chain (restore `=E×B`,
+`=J`). Verify both halves (F13, J13) equal the T-shirt total.
+
+---
+
+## Phase 5 — Writing to the Google Sheet (auth)
+
+gcloud's `spreadsheets` scope is **blocked by Google**. Use a **throwaway service
+account** (see `google-sheets-service-account-workaround` memory): create SA → mint
+key → user shares sheet with SA email as Editor → JWT (RS256 via openssl) → token →
+Sheets v4 REST (`values PUT` / `:batchUpdate`). Clean up the SA + key when done.
+
+---
+
+## Phase 6 — The PRD deliverable
+
+One document, **domain sub-sections (A–G) inside each numbered section** (0–15).
+
+- **§0 Metadata** + top-of-doc **⚠️ Estimate Basis & Disclaimer** (estimates, not a
+  quote; will change; no not-to-exceed / guarantee). Purge quote/fixed/binding language.
+- **§3.0 FR↔TD crosswalk** (per-domain tables: Requirement · Finding · Fix).
+- **§3.1 FR tables** — dedicated **Finding** column (never bury TD in prose).
+- **§3.2 NFR** — **Applies to** column listing **every** TD each cross-cutting NFR touches.
+- **§4 enforcement, §8 API, §10 estimate** — explicit `TD-n` refs (not bare numbers).
+- **§10 total must equal the live sheet rollup** (verify against the cell; watch that
+  Project Setup carries its MF). Point-in-time sync is fine; note it.
+- **§15 sign-off** = "Approved to proceed (scope, not fixed cost)".
+- Group tables by domain with a bold header per group (no repeating "Domain" column).
+- Save to `share/<Repo-Name>-PRD-*.md` (repo-name-prefixed).
+
+---
+
+## Phase 7 — Deliver
+
+All client-facing files in `share/` with the repo-name prefix. Confirm the three
+estimate views agree: T-Shirt total = Team Mix total = PRD §10 total.