@tekyzinc/gsd-t 4.15.10 → 4.17.10

package/CHANGELOG.md

@@ -2,6 +2,42 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [4.17.10] - 2026-07-01
+
+### Changed — `/gsd-t-estimate` v2: generalized + supervised + adversarial, with a permanent Sheets service account
+
+Reshaped the estimator from scan-only to a general work-document pricer, made it human-in-the-loop, added an operator-arbitrated Estimate Red Team, and replaced the throwaway-per-run Google service account with a permanent reusable one.
+
+- **Input generalized** — scan register OR new-feature/new-app requirements doc OR PRD-in; line-items become findings or requirements (Step 0 classifies + picks id vocabulary).
+- **Numbering hygiene** — renumber only when numbering is absent / non-sequential / doesn't start at 1; preserve hierarchical numbering (`1`/`1.1`/`1.1.1`), never flatten.
+- **Estimate Adjustments** (Step 2.5) broadened from familiarization-only to familiarization + R&D/unknown-approach/spike risk, documented per-item; M→L 3× cliff caution retained.
+- **Parameterized** — rate / hoursPerDay / sizeScale / totalMF / highFactor / sheet template / GCP project via `$ARGUMENTS` or `.gsd-t/estimate-config.json`; defaults are Tekyz values, always named in the report (no silent default).
+- **Human-in-the-loop** — judgment phases (sizing, adjustments, PRD, Red Team) pause for operator review; mechanical phases flow-but-show.
+- **NEW Step 8 Estimate Red Team** — adversarial pass on under-sizing / missing line-items / optimistic multipliers / cross-check integrity; **operator is the final arbiter** (argue until concede or a definitive ruling; Red Team then grudgingly accepts and may document overridden objections to `share/<Repo>-estimate-redteam-notes.md`).
+- **Sheet write: permanent reusable service account** — Step 0 asks for the sheet URL first + extracts the id; Step 5 reuses a permanent SA (`gsd-t-sheets-writer@ai-estimator-415612.iam.gserviceaccount.com`, key at `~/.claude/gsd-t-secrets/…`, chmod 600, outside any repo) instead of creating+deleting a throwaway each run. Recreation breaks existing sheet shares, so the SA is never deleted; each sheet is shared with it once.
+
+- `commands/gsd-t-estimate.md`: full rewrite (generalization, HITL, Step 8 Red Team, Step 0 URL-first, Step 5 permanent SA, config table).
+- `templates/estimate-config.json`: new optional documented override (installed to `~/.claude/templates/` via `SHARED_TEMPLATES`, not auto-scaffolded into projects).
+- `bin/gsd-t.js`: `estimate-config.json` added to `SHARED_TEMPLATES`.
+- `templates/playbooks/tekyz-estimation-and-prd-playbook.md`: header + Phase 5 updated to match.
+- `commands/gsd-t-help.md`, `README.md`, `GSD-T-README.md`: description + version-history ripple.
+- `.gsd-t/contracts/graph-metrics-contract.md`: `doMetrics` line citation 4742→4743 (shifted by the `SHARED_TEMPLATES` edit; keeps the M99 T6 line-ref test green).
+
+Also captured two HIGH-priority framework-default backlog items (#47 universal build-number rule, #48 universal trace + audit logging) — promote-later; no code yet.
+
+## [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.17.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 any work doc (scan, requirements, feature/app spec) into a Tekyz client estimate (Google Sheet: T-Shirt Size + Team Mix) + matching PRD — supervised, with an operator-arbitrated Estimate Red Team | Manual |
 | `/gsd-t-populate` | Auto-populate docs from existing codebase | Manual |
 | `/gsd-t-design-decompose` | Decompose design into element/widget/page contracts | Manual |
 

package/bin/gsd-t.js

@@ -1708,6 +1708,7 @@ const SHARED_TEMPLATES = [
   "page-contract.md",
   "design-contract.md",
   "shared-services-contract.md",
+  "estimate-config.json",
 ];
 
 function installSharedTemplates() {

package/commands/gsd-t-estimate.md

@@ -0,0 +1,189 @@
+# GSD-T: Estimate — Tekyz Client Estimate + PRD from any Work Document
+
+You are turning a **structured work document** into a **Tekyz client estimate** (a Google Sheet with a T-Shirt-Size tab + a Team-Mix cross-check) and a matching **PRD deliverable**. The input can be a GSD-T tech-debt scan register, a **new-feature requirements doc**, a **new-application requirements doc**, an existing PRD, or any comparable spec. `$ARGUMENTS` may carry the input path + a scope override (e.g. `--severity high`, `--input docs/requirements.md`).
+
+**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 (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.
+
+## Human-in-the-Loop (MANDATORY — this command is SUPERVISED, not auto)
+
+This process is judgment-heavy. **You (the operator) are the final arbiter of every estimate.** The command does NOT run end-to-end autonomously.
+
+- **Judgment phases PAUSE for review** before advancing: **Step 2 (sizing)**, **Step 2.5 (adjustments)**, **Step 6 (PRD)**, **Step 8 (Red Team)**. Present the output, wait for the user's `continue` or corrections.
+- **Mechanical phases FLOW but SHOW their result**: Step 1 (numbering), Step 5 (sheet write), Step 7 (reconcile). Don't block on these, but display what happened so nothing is invisible.
+- **Escape hatch:** if the user says e.g. "run through sizing and grouping, then stop," batch those phases and pause where they asked.
+
+## Configuration (parameterized — defaults are Tekyz values)
+
+Read these from `$ARGUMENTS` or `.gsd-t/estimate-config.json` if present; otherwise use the Tekyz defaults. **Always name the active values in the report** (no silent defaults). This config is **optional and NOT auto-created** (it's Tekyz-estimate-specific, not every-project state) — to override the defaults, copy the documented template `templates/estimate-config.json` (in the GSD-T package, or `~/.claude/templates/estimate-config.json`) to `.gsd-t/estimate-config.json` and edit. Every field is individually optional; an omitted field falls back to its Tekyz default.
+
+| Param | Default (Tekyz) | Meaning |
+|-------|-----------------|---------|
+| `rate` | `$50/hr` | Blended hourly rate for the LOW figure. |
+| `hoursPerDay` | `8` | Hours per person-day. |
+| `sizeScale` | `XS 0.25 · S 0.5 · M 1 · L 3 · XL 5 · XXL 7` | T-shirt → person-days. |
+| `totalMF` | `0.7` | Overhead multiplier = QA 0.3 + PM 0.1 + Analysis 0.05 + Deployment 0.05 + Buffer 0.2. |
+| `highFactor` | `1.25` | HIGH = LOW × this. |
+| `sheetTemplateId` | (blank) | Optional template to clone; normally blank — operator pastes the target sheet URL at Step 0. |
+| `gcpProject` | `ai-estimator-415612` | GCP project hosting the permanent Sheets-writer SA. |
+| `serviceAccountEmail` | `gsd-t-sheets-writer@ai-estimator-415612.iam.gserviceaccount.com` | **Permanent** SA — share each sheet with this as Editor. |
+| `serviceAccountKeyPath` | `~/.claude/gsd-t-secrets/gsd-t-sheets-writer-key.json` | SA key (chmod 600, outside any repo). |
+
+## Step 0: Inputs + Scope + Sheet
+
+1. **ASK FOR THE GOOGLE SHEET URL FIRST.** The operator ALWAYS provides an existing sheet to edit — this command never creates the sheet. Prompt: *"Paste the Google Sheet URL for this estimate."* Extract the **sheet ID** = the segment between `/d/` and the next `/` in `https://docs.google.com/spreadsheets/d/<ID>/edit`. Confirm the ID back to the operator.
+2. **Ensure the sheet is shared with the permanent estimate service account** (details in Step 5). The reusable SA email is **`gsd-t-sheets-writer@ai-estimator-415612.iam.gserviceaccount.com`**. Do a quick read-probe (Step 5's JWT→token→`GET spreadsheets/<id>`): if it returns `403`, the sheet isn't shared yet → prompt the operator to share it with that email as **Editor** ("Notify people" unchecked), wait for confirmation, re-probe. If the SA/key doesn't exist yet, Step 5 provisions it once.
+3. **Resolve the input document** (from `$ARGUMENTS --input`, else default to `.gsd-t/techdebt.md`). If none found → "No input document found. Pass `--input <path>` or run `/gsd-t-scan` first." and stop.
+4. **Classify the input** so the parser + line-item vocabulary match:
+   - **Scan register** (`.gsd-t/techdebt.md`) → line-items are *findings* (`TD-n`), scoped by severity.
+   - **Requirements doc / feature spec / app spec / PRD-in** → line-items are *requirements* (`FR-n` or the doc's own numbering).
+5. **Scope** (from `$ARGUMENTS`): scan default = **all CRITICAL findings** ("close the critical gap"); `--severity high|medium|low|all` widens it. Requirements default = **all requirements** unless the user narrows. Confirm the scope + item count with the user before sizing.
+6. Confirm the active config values above (rate/MF/highFactor — from `.gsd-t/estimate-config.json` or Tekyz defaults).
+7. Decide whether this is a **new-team project** (triggers the familiarization adjustment, Step 2.5) — usually YES for a fresh client.
+
+## Step 1: Numbering hygiene (MECHANICAL — show result)
+
+Client-facing line-items must carry **sequential, rational numbering starting at 1**. Requirements docs often have NO numbers, or hierarchical numbers, or (rarely) a scan that crashed-and-reran starts high (e.g. TD-618, which looks bad — "why does #1 start at 618?"). (`tekyz-tech-debt-numbering-caution`.)
+
+**Renumber ONLY when the numbering is absent, non-sequential, or doesn't start at 1.** If it is already sequential and rational, LEAVE IT.
+
+- **Unnumbered input** → assign sequential ids (`FR-1, FR-2, …` or `TD-1, …`).
+- **Hierarchical numbering** (`1`, `1.1`, `1.1.1` = requirement / sub / sub-sub) → **preserve the hierarchy**; renumber only to make each level sequential-and-rational (no gaps, starts at 1 within its parent). Never flatten a hierarchy.
+- **Already-clean numbering** → no change.
+- When you DO renumber, do it SAFELY (numbering-only, zero value changes):
+  - Confirm the id range is contiguous first, so a blind offset aligns.
+  - **Range-bounded regex** — remap ONLY numbers in the doc'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:** the input doc, 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.**
+  - **Second pass for non-prefixed formats:** bare `| 618 |` table cells, slashed chains (`TD-2/623`), header text. A first-pass `PREFIX-NNN` regex misses these.
+  - **Back up files before the bulk edit.**
+- A client that wants the original numbering keeps it — offer, don't force.
+
+## Step 2: Size each line-item (T-Shirt Size tab) — JUDGMENT · PAUSE FOR REVIEW
+
+For each in-scope item, build a row — cols **A** Module · **B** User Type · **C** Functionality (**include the `(TD-n)` / `(FR-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 per `sizeScale`: **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 × totalMF` · `Total Days = Days + MFactor` · `LOW $ = Total × hoursPerDay × rate` · `HIGH $ = LOW × highFactor`. **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:** raise Buffer/QA when confidence is low; raise `highFactor` above 1.25 for more unknowns.
+- **PAUSE:** present the sized rows (or the clusters + representative sizes) and the running total. Wait for `continue` or corrections before Step 2.5.
+
+## Step 2.5: Estimate Adjustments (familiarization + risk/unknowns) — JUDGMENT · PAUSE FOR REVIEW
+
+Base sizes assume *familiar* devs on *well-understood* work. Adjust for the two things that make real work heavier than the naive size. Document each adjustment per-item so the client sees **why** an item is heavier. (`tekyz-familiarization-bump`.)
+
+**(a) New-team familiarization** — ramp for a team new to the codebase. Bump each item's SIZE in proportion to its complexity — **NOT the MF** (the Analysis MF is for a Business Analyst, not dev ramp).
+- Trivial config / single-route → **no bump**. Repeated-pattern guards, few routes → **+0–1 tier**. High-volume sweeps + new-surface builds → **+1 tier**.
+- Optionally add a one-time **"Codebase Onboarding & Downstream Analysis"** Common line (sized L–XL) — document as optional, client can remove.
+
+**(b) R&D / unknown-approach / spike risk** — an item needing research, an unproven approach, or an unknown integration gets an uplift for the uncertainty. Either bump its SIZE, or raise its per-item risk contribution (and consider raising `highFactor` for the whole estimate if unknowns dominate). Name the unknown explicitly ("requires spike: undocumented 3rd-party API").
+
+**⚠️ 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 routine-work bumps at M.
+- Reference calibration: HILO 21 criticals = $8,700 familiar → $11,730 new-team (+35%, bumps capped at M) → $13,090 incl Project Setup.
+- **PAUSE:** present every adjustment (item, reason, before→after size, total delta). Wait for `continue` or corrections.
+
+## 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 (PERMANENT reusable service account) — MECHANICAL · show result
+
+**gcloud's `spreadsheets` OAuth scope is blocked by Google** (browser shows "This app is blocked"; `gcloud auth print-access-token` is unusable for Sheets), so a **service account with a self-signed JWT** is the only working path (`google-sheets-service-account-workaround`). A **PERMANENT, reusable SA already exists** — do NOT create a throwaway per run.
+
+**The permanent estimate SA (provisioned once, reused every run):**
+- **Email (the sheet share-target):** `gsd-t-sheets-writer@ai-estimator-415612.iam.gserviceaccount.com`
+- **GCP project:** `ai-estimator-415612` · **Sheets API:** enabled
+- **Key file:** `~/.claude/gsd-t-secrets/gsd-t-sheets-writer-key.json` (chmod 600, outside any repo — never commit an SA key)
+
+1. **Self-heal / provision-once (idempotent):** if the key file is missing, recreate the SA + mint a key before proceeding — this is the ONLY create path, and it runs at most once ever:
+   ```bash
+   PROJECT=ai-estimator-415612
+   SA=gsd-t-sheets-writer@$PROJECT.iam.gserviceaccount.com
+   KEY=~/.claude/gsd-t-secrets/gsd-t-sheets-writer-key.json
+   gcloud services enable sheets.googleapis.com --project=$PROJECT
+   gcloud iam service-accounts describe "$SA" --project=$PROJECT >/dev/null 2>&1 || \
+     gcloud iam service-accounts create gsd-t-sheets-writer \
+       --display-name="GSD-T Estimate Sheets Writer (permanent, reusable)" --project=$PROJECT
+   # SA creation is eventually-consistent — poll describe before minting the key
+   [ -f "$KEY" ] || { mkdir -p ~/.claude/gsd-t-secrets && chmod 700 ~/.claude/gsd-t-secrets && \
+     gcloud iam service-accounts keys create "$KEY" --iam-account="$SA" --project=$PROJECT && chmod 600 "$KEY"; }
+   ```
+2. **Share check:** the SA has no access until the sheet is shared with it. If a read-probe (below) returns `403`, **prompt the operator to share the sheet with `gsd-t-sheets-writer@ai-estimator-415612.iam.gserviceaccount.com` as Editor** (uncheck "Notify people"), wait for confirmation, re-probe. Because the SA is permanent, this is a **one-time** share per sheet — no re-share churn.
+3. **Auth = self-signed JWT** (pure stdlib + openssl, no client libraries): read the key file, sign an RS256 JWT (`openssl dgst -sha256 -sign`), scope `https://www.googleapis.com/auth/spreadsheets`, exchange at `oauth2.googleapis.com/token` (grant `urn:ietf:params:oauth:grant-type:jwt-bearer`) for a Bearer token. JWT `exp = now + 3600`; **mint fresh each run** (1h expiry).
+4. **Write via Sheets v4 REST** with the Bearer token: `values/<range>/PUT?valueInputOption=USER_ENTERED` for cell values; `:batchUpdate` for inserts/formatting/merges. **Reads:** `GET spreadsheets/<id>?ranges=...&includeGridData=true` (used for the 403 share-probe too).
+5. **Gotcha fixes (all proven on HILO):**
+   - **403 quota-project** on the Sheets API → add header `X-Goog-User-Project: ai-estimator-415612`.
+   - **URL-encode every range** (`urllib.parse.quote`) — spaces in tab names (e.g. `'T-Shirt Size Estimate'!A19`) break the URL.
+   - **Hardcoded SUMIF/total ranges don't auto-expand** on a plain values-write → use `insertDimension` (which shifts ranges) when inserting rows (ties back to Step 3's WIDEN note).
+   - **`drive.file` scope 404s on a pre-existing sheet** → must use the full `spreadsheets` scope.
+6. **No cleanup / no delete.** The SA is PERMANENT and reused — never delete it, never delete the key. (Deleting + recreating an SA changes its internal id and silently breaks every existing sheet share even with an identical email → 403. Keeping it permanent is the whole point.)
+
+## Step 6: Generate the PRD — JUDGMENT · PAUSE FOR REVIEW
+
+**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 requirement↔finding 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. (For a pure requirements input with no scan, the "Finding" column becomes the source requirement id.)
+- **§3.1 FR tables** — a **dedicated Finding/Source column** (never bury the id in trailing prose).
+- **§3.2 NFR** — an **"Applies to" column listing EVERY id** each cross-cutting NFR touches.
+- **§4 enforcement, §8 API, §10 estimate** — explicit id 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).
+- **PAUSE:** present the PRD (or its outline + disclaimer + §10 total) for review before finalizing.
+
+## Step 7: Verify — reconcile the three totals (MECHANICAL · show result)
+
+**The three totals 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 advancing to the Red Team.
+
+## Step 8: Estimate Red Team (adversarial) — JUDGMENT · PAUSE · YOU ARE THE ARBITER
+
+An independent adversarial pass that challenges the estimate before it reaches the client — the estimate-time analogue of GSD-T's build Red Team. **Its job is to protect Tekyz from a money-losing under-estimate AND to keep the estimate competitive** (paired realism, per `feedback_red_team_realism_gate` — don't pad every item to XXL "to be safe").
+
+**What it attacks:**
+- **Under-sized items** — "this 'S' implies a DB migration + backfill → really M; +2 days."
+- **Missing line-items** — work a requirement implies but nothing sized (migrations, tests, auth, error states, rollout).
+- **Optimistic multipliers** — Buffer/QA too low for the stated confidence; `highFactor` too tight for the unknowns.
+- **Adjustment gaps** — an R&D/unknown item (Step 2.5b) sized as if it were routine.
+- **Cross-check integrity** — do the three totals ACTUALLY reconcile, or is a hardcoded cell hiding a break.
+- **Assumption / scope gaps** — unstated assumptions that would blow up mid-project.
+
+**Verdict:** `FAIL` (material under-estimate or missing scope found) / `GRUDGING-PASS` (exhaustive search, nothing material).
+
+### The arbitration protocol (David is the final judge — NOT bot ping-pong)
+
+When the Red Team returns `FAIL`, it does **NOT** loop back-and-forth with the skill until it grudgingly passes. It surfaces to **the operator**:
+
+1. **Present each objection PLAINLY:** *what* shouldn't pass, *why*, and *the estimate impact* (which item, before→after size, dollar delta). One clear list, ranked by dollar impact.
+2. **The operator decides, per objection:**
+   - **Agree** → operator says `continue` → apply the fix.
+   - **Disagree** → operator gives feedback → **the Red Team argues back.** The argument continues until **one side concedes** OR the operator ends it definitively.
+3. **Definitive-decision override:** if the operator says anything conclusive — e.g. *"No more argument. I've decided on X,"* or any clearly final ruling — the Red Team **MUST grudgingly accept the operator's decision immediately, regardless of how many rounds have passed.** It **MAY document its unresolved objection** (in the PRD as a footnote or a `share/<Repo>-estimate-redteam-notes.md` file) **for later consideration** — but it does not re-litigate.
+4. The Red Team **never self-satisfies into a pass** and **never overrides the operator.** It either persuades the operator or defers to them.
+
+**PAUSE** at every objection — this phase is inherently interactive.
+
+## Step 9: Deliver
+
+All client-facing files land in `share/` with the repo-name prefix. Report: input type + scope + item count, the active config values (rate/MF/highFactor), the eng-days + LOW–HIGH dollar range, the sheet URL, the PRD path, the Red Team verdict, and any documented-but-overridden Red Team objections.
+
+## Document Ripple
+
+- `share/<Repo>-PRD-*.md` (new PRD deliverable) + the Google Sheet (external) + optional `share/<Repo>-estimate-redteam-notes.md` (overridden objections).
+- If renumbering (Step 1) ran: the input + 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 any structured work document — a scan register, a new-feature or new-app requirements doc, or a PRD-in — 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 source doc/docs/scan files) + optional `share/<Repo>-estimate-redteam-notes.md`
+- **Use when**: You need a client-facing paid estimate + PRD (T-shirt sizing, dollar range, sign-off) from a scan OR a requirements/feature/app spec. **SUPERVISED** — judgment phases (sizing, adjustments, PRD, Red Team) pause for your review; **you are the final arbiter** of an Estimate Red Team that challenges the numbers. Rate + sheet template + factors are parameterized (default Tekyz). Encodes the 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.17.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/estimate-config.json

@@ -0,0 +1,39 @@
+{
+  "$schema": "Optional config for /gsd-t-estimate. Copy to .gsd-t/estimate-config.json and edit. ALL fields are optional — any omitted field falls back to the Tekyz default shown here. The active values are always named in the estimate report (no silent defaults).",
+
+  "rate": 50,
+  "_rate": "Blended hourly rate (USD) used for the LOW dollar figure. Tekyz default: 50.",
+
+  "hoursPerDay": 8,
+  "_hoursPerDay": "Hours per person-day. Default: 8.",
+
+  "sizeScale": { "XS": 0.25, "S": 0.5, "M": 1, "L": 3, "XL": 5, "XXL": 7 },
+  "_sizeScale": "T-shirt size -> person-days. NON-LINEAR: M->L is a 3x cliff (1 -> 3 days). Do not push routine work across M->L.",
+
+  "totalMF": 0.7,
+  "_totalMF": "Overhead multiplier applied to raw Days. Tekyz 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.",
+
+  "mfBreakdown": { "qa": 0.3, "pm": 0.1, "analysis": 0.05, "deployment": 0.05, "buffer": 0.2 },
+  "_mfBreakdown": "Optional itemized breakdown of totalMF (must sum to totalMF). Tune per project; e.g. raise buffer for low-confidence scope.",
+
+  "highFactor": 1.25,
+  "_highFactor": "HIGH dollar figure = LOW x this. Raise above 1.25 when unknowns dominate (many R&D / spike items).",
+
+  "currency": "USD",
+  "_currency": "Currency label for the report. Default: USD.",
+
+  "sheetTemplateId": "",
+  "_sheetTemplateId": "Optional. Google Sheet ID of a template to clone. Normally BLANK — the operator pastes the target sheet URL at run start (Step 0) and the command extracts the ID.",
+
+  "gcpProject": "ai-estimator-415612",
+  "_gcpProject": "GCP project hosting the PERMANENT reusable Sheets-writer service account. Default: ai-estimator-415612 (AI Estimator).",
+
+  "serviceAccountEmail": "gsd-t-sheets-writer@ai-estimator-415612.iam.gserviceaccount.com",
+  "_serviceAccountEmail": "The PERMANENT reusable SA — share each target sheet with THIS email as Editor. Never deleted/recreated (recreation breaks existing shares).",
+
+  "serviceAccountKeyPath": "~/.claude/gsd-t-secrets/gsd-t-sheets-writer-key.json",
+  "_serviceAccountKeyPath": "Local path to the SA JSON key (chmod 600, outside any repo — NEVER commit). Step 5 self-provisions the SA+key here if missing.",
+
+  "newTeamDefault": true,
+  "_newTeamDefault": "Whether to assume a new-team familiarization adjustment (Step 2.5a) by default. Usually true for a fresh client."
+}

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

@@ -0,0 +1,130 @@
+# 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 **any structured work
+> document** — a GSD-T tech-debt scan register, a new-feature or new-application
+> requirements doc, or an existing PRD. 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.
+>
+> **This process is SUPERVISED and JUDGMENT-HEAVY.** The operator reviews the
+> judgment phases (sizing, adjustments, PRD) and is the FINAL ARBITER of the
+> Estimate Red Team (Phase 8). It does not run autonomously. Rate + sheet template
+> + factors are parameterized (defaults are the Tekyz values below). See
+> `commands/gsd-t-estimate.md` for the authoritative, current phase list.
+
+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` OAuth scope is **blocked by Google** (user ADC unusable).
+Use the **PERMANENT reusable service account** (see
+`google-sheets-service-account-workaround` memory + `commands/gsd-t-estimate.md`
+Step 5 for the authoritative runbook):
+- **SA (share-target):** `gsd-t-sheets-writer@ai-estimator-415612.iam.gserviceaccount.com`
+- **Project:** `ai-estimator-415612` · **Key:** `~/.claude/gsd-t-secrets/gsd-t-sheets-writer-key.json` (chmod 600).
+
+Flow: operator pastes sheet URL → extract id → shares sheet with the SA email as
+Editor (one-time per sheet — SA is permanent) → JWT (RS256 via openssl) → token →
+Sheets v4 REST (`values PUT` / `:batchUpdate`; reads via `GET ...includeGridData`).
+Gotchas: `X-Goog-User-Project` header for 403 quota; `urllib.parse.quote` every
+range; `insertDimension` to shift hardcoded SUMIF ranges; full `spreadsheets` scope
+(not `drive.file`); JWT `exp=now+3600`, mint fresh each run.
+**NEVER delete/recreate the SA** — recreation breaks every existing sheet share.
+
+---
+
+## 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.