@tekyzinc/gsd-t 5.19.11 → 5.20.11

package/bin/gsd-t.js

@@ -1910,6 +1910,10 @@ const GLOBAL_BIN_TOOLS = [
   // caught four times before ([[project_global_bin_propagation_gap]]). Also in
   // PROJECT_BIN_TOOLS below — both lists, both tools.
   "gsd-t-testplan-lint.cjs", "gsd-t-testplan-halt.cjs", "gsd-t-testplan-rows.cjs",
+  // v5.20.10 — deterministic Tekyz estimate-sheet writer + read-back audit
+  // (`gsd-t estimate-sheet`). Dispatched by bin/gsd-t.js AND read by
+  // /gsd-t-estimate, so it ships in BOTH lists ([[project_global_bin_propagation_gap]]).
+  "gsd-t-estimate-sheet.cjs",
 ];
 
 // Directories under bin/ that must ship whole. A runner whose parts stay behind
@@ -2180,6 +2184,7 @@ const SHARED_TEMPLATES = [
   "design-contract.md",
   "shared-services-contract.md",
   "estimate-config.json",
+  "estimate-sheet-spec.md",
 ];
 
 function installSharedTemplates() {
@@ -3461,6 +3466,20 @@ async function doUpdateAll() {
   );
 }
 
+// Numeric dotted-version compare: negative when a < b, 0 when equal, positive when a > b.
+// GSD-T versions are plain Major.Minor.Patch integers (patch always ≥ 10), so a
+// segment-wise numeric compare is exact; no prerelease tags exist.
+function versionCmp(a, b) {
+  const pa = String(a).split(".").map((n) => parseInt(n, 10));
+  const pb = String(b).split(".").map((n) => parseInt(n, 10));
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const x = Number.isNaN(pa[i]) ? 0 : pa[i];
+    const y = Number.isNaN(pb[i]) ? 0 : pb[i];
+    if (x !== y) return x - y;
+  }
+  return 0;
+}
+
 // Upgrade the globally-installed @tekyzinc/gsd-t to @latest. Returns
 // { upgraded: bool, reexec: bool, error?: string }.
 // - reexec=true when the on-disk version after `npm install -g` is newer than
@@ -3494,6 +3513,19 @@ async function upgradeGlobalBinary() {
     // Best-effort; fall through.
   }
 
+  if (newVersion && versionCmp(newVersion, PKG_VERSION) < 0) {
+    // v5.20.10 (2026-09-17): right after `npm publish`, npm's cached package
+    // listing still named the PREVIOUS version as @latest, so this step
+    // installed 5.19.11 over a running 5.20.10, reported it as an "upgrade",
+    // handed off to the OLD binary, and that binary overwrote ~/.claude/commands
+    // and every project with the old release. A downgrade is never an upgrade —
+    // HALT and say how to fix it, never continue on a stale listing.
+    error(`HALT: npm installed v${newVersion} over the running v${PKG_VERSION} — @latest resolved to an OLDER release.`);
+    info("npm's cached package listing is stale. Run `npm cache clean --force`, wait until");
+    info(`\`curl -sI https://registry.npmjs.org/@tekyzinc/gsd-t/-/gsd-t-${PKG_VERSION}.tgz\` returns 200, then re-run update-all.`);
+    info(`Restore the current release first: npm install -g @tekyzinc/gsd-t@${PKG_VERSION}`);
+    process.exit(1);
+  }
   if (newVersion && newVersion !== PKG_VERSION) {
     success(`Global binary upgraded: v${PKG_VERSION} → v${newVersion}`);
     info("Handing off to the newly-installed binary for propagation...");
@@ -3701,6 +3733,10 @@ const PROJECT_BIN_TOOLS = [
   // and /gsd-t-test-plan calls them directly — same propagation-gap class as the
   // graph tools above. Also in GLOBAL_BIN_TOOLS — both lists, both tools.
   "gsd-t-testplan-lint.cjs", "gsd-t-testplan-halt.cjs", "gsd-t-testplan-rows.cjs",
+  // v5.20.10 — deterministic Tekyz estimate-sheet writer + read-back audit
+  // (`gsd-t estimate-sheet`). Dispatched by bin/gsd-t.js AND read by
+  // /gsd-t-estimate, so it ships in BOTH lists ([[project_global_bin_propagation_gap]]).
+  "gsd-t-estimate-sheet.cjs",
 ];
 
 // Files that older versions of this installer copied into project bin/ but
@@ -5990,6 +6026,14 @@ if (require.main === module) {
       });
       process.exit(res.status == null ? 1 : res.status);
     }
+    case "estimate-sheet": {
+      // v5.20.10 — deterministic Tekyz estimate-sheet writer + audit
+      // (`gsd-t estimate-sheet read|plan-check|write|audit --sheet <id>`).
+      const { spawnSync } = require("child_process");
+      const js = path.join(__dirname, "gsd-t-estimate-sheet.cjs");
+      const res = spawnSync(process.execPath, [js, ...args.slice(1)], { stdio: "inherit" });
+      process.exit(res.status == null ? 1 : res.status);
+    }
     case "test-data": {
       // M58 D1 — `gsd-t test-data --list|--purge` thin dispatcher.
       const { spawnSync } = require("child_process");

package/commands/cpua.md

@@ -120,6 +120,19 @@ G="$(npm root -g)/@tekyzinc/gsd-t"
 #    the pre-publish package listing cached and `@tekyzinc/gsd-t@{NEW}` returns ETARGET
 #    for minutes while `npm view` already shows the version (v5.17.14, 2026-09-03).
 #    The tarball URL bypasses the cached listing and is deterministic.
+# 1b. WAIT until the registry actually SERVES the tarball, then CLEAR npm's cached listing.
+#    v5.20.10 (2026-09-17): `npm publish` printed "+ @tekyzinc/gsd-t@5.20.10" and `npm view`
+#    showed it, but the tarball URL 404'd for ~4 minutes. Worse, npm's cached package
+#    listing still said latest = the PREVIOUS version, so `gsd-t update-all` (which runs
+#    `npm install -g @tekyzinc/gsd-t@latest`) DOWNGRADED the global, handed off to the old
+#    binary, and that binary rewrote ~/.claude/commands and 34 projects with the old release
+#    — twice. Poll the tarball, then clean the cache, then install. Never skip either.
+for i in $(seq 1 60); do
+  [ "$(curl -s -o /dev/null -w '%{http_code}' "https://registry.npmjs.org/@tekyzinc/gsd-t/-/gsd-t-{NEW_VERSION}.tgz")" = "200" ] && break
+  sleep 10
+done
+[ "$(curl -s -o /dev/null -w '%{http_code}' "https://registry.npmjs.org/@tekyzinc/gsd-t/-/gsd-t-{NEW_VERSION}.tgz")" = "200" ] || { echo "HALT: tarball still 404 after 10 min"; exit 1; }
+npm cache clean --force
 npm install -g "https://registry.npmjs.org/@tekyzinc/gsd-t/-/gsd-t-{NEW_VERSION}.tgz"
 # 2. VERIFY ON DISK — never trust npm's exit code for this step. On v5.17.13 `npm install -g`
 #    reported success and left the OLD version in place; `update-all` then ran from the
@@ -140,7 +153,11 @@ fi
 #    file and the command files; only then does update-all see the new release.
 gsd-t install 2>&1 | tail -5
 [ "$(cat ~/.claude/.gsd-t-version)" = "{NEW_VERSION}" ] || { echo "HALT: ~/.claude/.gsd-t-version did not advance"; exit 1; }
-# 4. Propagate, then prove the global is STILL the new version and a NEW file reached a project.
+# 4. Prove `@latest` now resolves to the NEW version (update-all installs `@latest`; a stale
+#    listing here is the downgrade path — since v5.20.11 update-all HALTS on a downgrade
+#    instead of handing off, but do not rely on the halt: check first).
+[ "$(npm view @tekyzinc/gsd-t dist-tags.latest)" = "{NEW_VERSION}" ] || { echo "HALT: registry latest is not {NEW_VERSION}"; exit 1; }
+# 5. Propagate, then prove the global is STILL the new version and a NEW file reached a project.
 gsd-t update-all 2>&1 | tail -30
 [ "$(node -p "require('$G/package.json').version")" = "{NEW_VERSION}" ] || { echo "HALT: global package reverted during update-all"; exit 1; }
 ```

package/commands/gsd-t-estimate.md

@@ -1,8 +1,10 @@
-# GSD-T: Estimate — Tekyz Client Estimate + PRD from any Work Document
+# GSD-T: Estimate — Tekyz Client Estimate (T-Shirt Size + Team Mix + Technology Stack)
 
-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`).
+You are turning a **structured work document** into a **Tekyz client estimate** in a Google Sheet: a **T-Shirt Size** tab (sized line-items → days → dollars), a **Team Mix** tab (who does the work, month by month), and a **Technology Stack** tab. The input can be a GSD-T tech-debt scan register, a gap-analysis sheet, a new-feature or new-application requirements doc, or any comparable spec. `$ARGUMENTS` may carry `--sheet <url>`, `--input <path>`, and a scope override (`--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 (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.
+**Scope is the SHEET only.** This command does NOT write a PRD or any other document — a client PRD is `/gsd-t-prd`'s job, run separately if wanted. The one client-facing artifact here is the sheet; the only optional file is `share/<Repo>-estimate-redteam-notes.md` (overridden Red Team objections).
+
+**THE SHEET IS WRITTEN BY A TOOL, NOT BY HAND.** `gsd-t estimate-sheet` (`bin/gsd-t-estimate-sheet.cjs`, project-local `bin/` first, else the global `gsd-t`) reads the sheet, validates a JSON plan, writes all three tabs with the exact formulas and styling, and audits by reading back — halting on any violation. **You never PUT a cell or send a batchUpdate yourself.** Your output is the plan (judgment only: sizes, team FTE, tech-stack lines); the tool computes everything derived. Spec: `~/.claude/templates/estimate-sheet-spec.md` (bundled: `templates/estimate-sheet-spec.md`) — §6 shows the plan shape (`gsd-t estimate-sheet plan-schema` prints it). Procedure background: `~/.claude/playbooks/tekyz-estimation-and-prd-playbook.md` (else `templates/playbooks/`).
 
 > **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.
 
@@ -10,180 +12,159 @@ You are turning a **structured work document** into a **Tekyz client estimate**
 
 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.
+- **Judgment phases PAUSE for review** before advancing: **Step 2 (sizing)**, **Step 2.5 (adjustments)**, **Step 4 (Team Mix roster + ramp)**, **Step 8 (Red Team)**. Present the output, wait for `continue` or corrections.
+- **Mechanical phases FLOW but SHOW their result**: Step 1 (numbering), Step 6 (sheet write + audit), Step 7 (reconcile). Don't block, but display what happened so nothing is invisible.
+- **Never skip Step 2.5 or Step 8 silently.** Both were skipped on shipped estimates and the operator had to ask for them afterwards. If you skip one, say so in the report and why.
 - **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.
+Read 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). The config is **optional and NOT auto-created** — to override, copy `templates/estimate-config.json` (or `~/.claude/templates/estimate-config.json`) to `.gsd-t/estimate-config.json` and edit. Every field is individually optional.
 
 | 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. |
+| `totalMF` | `0.7` | Overhead multiplier. **The sheet's own MF list (`E4:F9`) wins when a sheet exists** — read it, never overwrite it. Hilo sheets run `0.9` (QA .3 · PM .1 · Analysis .1 · Deployment .05 · StdUps/Mtgs .15 · Buffer .2). |
+| `highFactor` | `1.25` | HIGH = LOW × this (the sheet's `G4` wins when a sheet exists). |
+| `sheetTemplateId` | (blank) | Optional template to clone; normally blank — the operator supplies the target sheet. |
 | `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). |
+| `newTeamDefault` | `true` | Apply the new-team familiarization adjustment (Step 2.5a) by default. |
 
 ## 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.
+1. **Resolve the Google Sheet.** Take `--sheet <url>` from `$ARGUMENTS`; otherwise ask: *"Paste the Google Sheet URL for this estimate."* The operator ALWAYS provides an existing sheet — this command never creates one. Extract the **sheet ID** (between `/d/` and the next `/`) and confirm it back.
+2. **Probe access + read the layout in one step:** `gsd-t estimate-sheet read --sheet <url>` (then `--tab "T-Shirt Size Estimate"`, `--tab "Team Mix"`). A `403` halt means the sheet is not shared — prompt the operator to share it with the SA email as **Editor** ("Notify people" unchecked), wait, re-run. (The tool never sends `X-Goog-User-Project`; with it these sheets 403 even when shared.)
+3. From the read: note the MF list (`E4:F9`), high factor (`G4`), rate (`H4`), whether item rows already exist (→ `sizes` mode) or the tab is empty (→ `items` mode), and whether the Technology Stack tab is filled. The tool reads these again at write time; you read them now so the plan matches the sheet.
+4. **Resolve the input document** (`--input`, else `.gsd-t/techdebt.md`). None → "No input document found. Pass `--input <path>` or run `/gsd-t-scan` / `/gsd-t-gap-analysis` first." and stop.
+5. **Classify the input** so the line-item vocabulary matches: scan register → *findings* (`TD-n`) scoped by severity; gap-analysis sheet → *gaps* (`GA-n`, rows already on the T-Shirt tab with columns A–D filled — you fill E–G only); requirements / feature / app spec → *requirements* (`FR-n` or the doc's own numbering).
+6. **Scope**: scan default = all CRITICAL findings; `--severity high|medium|low|all` widens. Requirements default = all. Confirm scope + item count with the user before sizing.
+7. **Confirm the active config values** — rate, MF list (from the sheet), high factor, and whether this is a **new-team project** (Step 2.5a; 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.
+Client-facing line-items carry **sequential, rational numbering starting at 1**. Renumber ONLY when numbering is absent, non-sequential, or doesn't start at 1 (a crashed-and-rerun scan starting at TD-618 looks bad). Already clean → 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.**
+- **Unnumbered** → assign sequential ids (`FR-1, FR-2, …` or `TD-1, …`).
+- **Hierarchical** (`1`, `1.1`, `1.1.1`) → preserve the hierarchy; renumber only to make each level sequential within its parent. Never flatten.
+- When you DO renumber, do it SAFELY: confirm the id range is contiguous; **range-bounded regex** so you never touch `DC-n` or another project's numbering; scope to CURRENT deliverables only (input doc, plain-English companion, `.gsd-t/scan/*.md`, `docs/*.md`, README, `share/*`, the sheet labels) — **leave `.gsd-t/scan/archive/`, transcripts, heartbeats untouched**; second pass for non-prefixed forms (`| 618 |`, `TD-2/623`, headers); **back up files first**.
 - 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.**
+For each in-scope item build a row per spec §1.2 — `A` Module · `B` User Type · `C` Functionality (**with the item id**) · `D` Low-Level Requirement · `E` Phase · `F` Web Portal size · `G` Backend/API size. `H:L` are formulas, never values.
 
-- **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.
+- **Size each column INDEPENDENTLY** (FE and BE each get their own letter; blank = 0). Scale: **XS 0.25 · S 0.5 · M 1 · L 3 · XL 5 · XXL 7** person-days.
+- **Bare codes in `F:G`** — `XS` `S` `M` `L` `XL` `XXL`. Never the legend text (`"XS - Extra Small"`). The lookup happens to compute either way, which is why the long form shipped unnoticed.
+- The sheet computes: `Days = F+G` → `MFactor Days = Days × Total MF` → `Total Days` → `LOW $ = Total × 8 × rate` → `HIGH $ = LOW × high factor`.
+- **Cluster by fix-shape to size fast**: "add existing guard to N routes" (XS–S, repeated) vs "new backend surface" (M, +FE) vs "config / single route" (XS). Size the cluster once, apply to members.
+- **Tune the MF per project** (raise Buffer/QA when confidence is low; raise the high factor above 1.25 for more unknowns) — but change the sheet's MF list only with the operator's say-so.
+- **PAUSE:** present the sized rows (or clusters + representative sizes) and the running total (recomputed from raw sizes: `Σ(FE,BE days) × (1 + MF)`). Wait for `continue` or corrections.
 
 ## 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`.)
+Base sizes assume *familiar* devs on *well-understood* work. Adjust for the two things that make real work heavier. Document each adjustment per-item so the client sees **why**. **This step is ON by default (`newTeamDefault: true`) — it was skipped on shipped estimates and had to be asked for.**
+
+**(a) New-team familiarization** — 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 (L–XL), documented as optional.
 
-**(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: bump its SIZE or raise the high factor if unknowns dominate. Name the unknown explicitly ("requires spike: undocumented 3rd-party API").
 
-**(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).** Never push an item across M→L unless it is genuinely multi-day. Cap routine-work bumps at M. Calibration: HILO 21 criticals = $8,700 familiar → $11,730 new-team (+35%, bumps capped at M).
 
-**⚠️ 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)
+## Step 3: Group by domain + section headings (T-Shirt tab)
+
+Reorder items into domains. Insert a **section-heading row** before each group per spec §1.2 (merge `A:L`, bg `#1C4F8B`, white bold Arial 10). **No subtotals.**
+
+- Insert rows with `insertDimension` (it shifts ranges); never write into rows below a summed range.
+- After reordering, **re-point EVERY aggregate on the tab**: the totals row, the phase rollups `K4:N7` (their `$E$14:$E$<last>` ranges), and the summary block — then move the summary block BELOW the totals row if the template left it inside the summed range (circular `#REF!` otherwise).
 
-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).
+## Step 4: Team Mix — JUDGMENT · PAUSE FOR REVIEW
 
-- **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.
+Your judgment is ONE thing: the FTE per discipline (`teamMix.fte` in the plan — `backend` `frontend` `qa` `pm` `ba`, optionally `techlead` `devops`). Everything else on the tab is computed by the tool per spec §2: the split into people (saturate at 1.00, then spill), months, the column count, the ramp by discipline, the remainder formula.
 
-## Step 4: Team Mix cross-check
+1. **Staff every weighted MF factor** — QA → `qa`, PM → `pm`, Analysis → `ba`. Deployment / standups / buffer are absorbed by the engineers and lead. Typical fractions: PM 0.20–0.25 · BA 0.10 · Tech Lead 0.25 · QA 0.40–0.50. The tool HALTS on a roster that leaves a factor unstaffed — do not argue with it; add the person.
+2. **Run `gsd-t estimate-sheet plan-check --sheet <url> --plan <plan.json>`.** It prints the MF list it read, the T-Shirt total, and the roster table it WOULD write (person · Count · Mths · Days · Hrs · Mon 1..N with the remainder) — or halts with the violation.
+3. **PAUSE:** present that table verbatim. Wait for `continue` or corrections (a resize or a different FTE → edit the plan, re-run plan-check, present again).
 
-`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`.
+## Step 5: Technology Stack
 
-- **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.**
+Fill the tab per spec §3 from **internal, grep-able facts** — `docs/architecture.md`, `docs/infrastructure.md`, package manifests, lockfiles, CI config. One row per category that applies (`Frontend` · `Backend` · `Auth` · `Data Store` · `Cache / Session Store` · `Object Storage` · `Events / Webhooks` · `Tools / Integrations` · `LLM / Reasoning` · `Observability` · `Infrastructure`), one plain-English line each with versions where the manifest states them. **Never leave the tab blank and never guess a version** — an unknown is "not determined from the repo", not an invented number.
 
-## Step 5: Write to the Google Sheet (PERMANENT reusable service account) — MECHANICAL · show result
+## Step 6: Write to the Google Sheet + audit (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.
+**Write the plan to `.gsd-t/estimate-plan.json`, then 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)
+```bash
+gsd-t estimate-sheet write --sheet <url> --plan .gsd-t/estimate-plan.json   # add --replace only if the T-Shirt tab already has rows you mean to overwrite
+```
 
-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.)
+It writes the T-Shirt tab (items or sizes mode), the Team Mix, the Technology Stack, re-points every rollup, propagates the Phase dropdown, applies the styling — and then runs the spec §5 audit by reading back, printing every check with ✓/✗. **Exit 4 = a ✗ — fix the plan (or the sheet, for a template problem it names) and re-run. Exit 64 = auth/API/input halt.** Show the tool's output to the operator verbatim. Do not hand-patch cells around the tool; if the tool cannot express something the sheet needs, that is a tool change, and you say so.
 
-## Step 6: Generate the PRD — JUDGMENT · PAUSE FOR REVIEW
+**Auth** (used by the tool) = the PERMANENT reusable service account (never create a throwaway, never delete or recreate it — recreation breaks every existing share): email `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, outside any repo). gcloud's `spreadsheets` OAuth scope is Google-blocked, so: read the key, 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`), `exp = now + 3600`, mint fresh each run. If the key file is missing, provision ONCE:
 
-**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`.)
+```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"; }
+```
 
-- **§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.
+**What the tool does** (spec §0, all learned the hard way — listed so you can recognise a template problem when it halts): no `X-Goog-User-Project` header; every range URL-encoded; Phase cells `copyPaste`d from the sheet's existing dropdown cell (it halts if the template has none — add one to E14); clear-then-paint from the current shape; small batches that halt on the first failure; Team Mix header on row 2 only with `Mon 1..N` + `Total Hrs` derived from the month count; sage on exactly Days / Hrs / Total Hrs; Arial 10; bands across every month column; then the read-back audit. **Any ✗ is fixed before Step 7** — a 200 on the write is not evidence the cell landed.
 
-## Step 7: Verify — reconcile the three totals (MECHANICAL · show result)
+## Step 7: Verify — reconcile (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.
+- `gsd-t estimate-sheet audit --sheet <url>` must exit 0 (it recomputes **T-Shirt `Total Days` == Team Mix `Σ Days`** independently — raw sizes × (1+MF) vs Σ Count × Mths × 20 — and checks every §5 line). A ✗ here after a clean write means someone edited the sheet; find the break before the Red Team.
+- **Overview `C2/E2/C3/E3` resolve to numbers** (they reference the T-Shirt rollups `L8/K8/N8/M8`; the estimates index imports exactly these cells).
+- If the estimate is linked from the estimates index and shows `#REF!`, that is the one-time `IMPORTRANGE` "Allow access" click — report it for the operator; it is not yours to fix.
 
 ## 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").
+An independent adversarial pass that challenges the estimate before it reaches the client. **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).
 
 **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.
+- **Missing line-items** — work a requirement implies but nothing sized (migrations, tests, auth, error states, rollout, sandbox issuance, decision cycles with the client, gate-acceptance evidence).
+- **Counts that were guessed** — "510 call sites" that measure at 897; re-measure the big ones.
+- **Optimistic multipliers** — Buffer/QA too low for the stated confidence; high factor too tight for the unknowns.
+- **Adjustment gaps** — an R&D/unknown item sized as if routine; familiarization not applied.
+- **Team Mix realism** — a role missing for a weighted MF factor, a flat ramp, a smeared roster.
+- **Cross-check integrity** — do the two totals ACTUALLY reconcile, or is a hardcoded cell hiding a break.
+- **Assumption / scope gaps** — unstated assumptions that would blow up mid-project (record them on the Overview as assumptions, not padding).
 
-**Verdict:** `FAIL` (material under-estimate or missing scope found) / `GRUDGING-PASS` (exhaustive search, nothing material).
+**Verdict:** `FAIL` (material under-estimate or missing scope) / `GRUDGING-PASS` (exhaustive search, nothing material).
 
-### The arbitration protocol (David is the final judge — NOT bot ping-pong)
+### The arbitration protocol (the operator 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**:
+When the Red Team returns `FAIL`, it does **NOT** loop 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.
+1. **Present each objection PLAINLY:** *what* shouldn't pass, *why*, and *the estimate impact* (item, before→after size, dollar delta). One list, ranked by dollar impact.
+2. **The operator decides, per objection:** **Agree** → `continue` → edit the plan and re-run Steps 4, 6, 7 (a resize changes the roster and the month count; the tool recomputes both). **Disagree** → operator gives feedback → **the Red Team argues back** until one side concedes or the operator ends it.
+3. **Definitive-decision override:** anything conclusive from the operator ("No more argument. I've decided on X") is accepted immediately, regardless of round count. The Red Team **MAY document its unresolved objection** in `share/<Repo>-estimate-redteam-notes.md` — it does not re-litigate.
+4. The Red Team **never self-satisfies into a pass** and **never overrides the operator.**
 
 **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.
+Report: input type + scope + item count; the active config values (rate / MF list / high factor); Total Days and the LOW–HIGH dollar range; the sheet URL; the roster (people × Count, months); the audit checklist result; the Red Team verdict and any documented-but-overridden objections; any `#REF!` awaiting the operator's Allow-access click.
 
 ## Document Ripple
 
-- `share/<Repo>-PRD-*.md` (new PRD deliverable) + the Google Sheet (external) + optional `share/<Repo>-estimate-redteam-notes.md` (overridden objections).
+- The Google Sheet (external) — T-Shirt Size Estimate, Team Mix, Technology Stack (+ Overview cells verified) + optional `share/<Repo>-estimate-redteam-notes.md`.
 - 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.
+- No PRD. A client PRD is `/gsd-t-prd`.
 
 ## ▶ Next Up
 
-Standalone command — no auto-successor. After delivering, the user shares the sheet + PRD with the client.
+Standalone command — no auto-successor. After delivering, the user shares the sheet with the client (and runs `/gsd-t-prd` if a PRD is wanted).

package/commands/gsd-t-help.md

@@ -378,10 +378,10 @@ Use these when user asks for help on a specific command:
 - **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
+- **Summary**: Turn any structured work document — a scan register, a gap-analysis sheet, a new-feature or new-app requirements doc — into a Tekyz client estimate Google Sheet: **T-Shirt Size + Team Mix + Technology Stack**, written and audited against `~/.claude/templates/estimate-sheet-spec.md`. No PRD (`/gsd-t-prd` owns that)
 - **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`)
+- **Updates**: the Tekyz estimate Google Sheet (three tabs, written and read-back-audited by `gsd-t estimate-sheet` from `.gsd-t/estimate-plan.json`) + optional `share/<Repo>-estimate-redteam-notes.md` (and, if renumbered, the source doc/docs/scan files)
+- **Use when**: You need a client-facing paid estimate (T-shirt sizing, dollar range, staffed team by month) from a scan, a gap analysis, or a requirements/feature/app spec. **SUPERVISED** — judgment phases (sizing, adjustments, Team Mix, Red Team) pause for your review; **you are the final arbiter** of an Estimate Red Team that challenges the numbers. Accepts `--sheet <url>`. Rate + factors are parameterized (default Tekyz; the sheet's own MF list wins). Playbook: `~/.claude/playbooks/tekyz-estimation-and-prd-playbook.md`
 
 ### stories
 - **Summary**: Generate a dev-team handoff document in the Tekyz user-stories format — discrete user stories with workflows, grouped acceptance criteria, per-story flow diagrams (Mermaid rendered to embedded images), and mapped test-case tables — from any source (scan register, requirements doc, design contract, or a reverse-engineered codebase)

package/package.json

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

package/templates/CLAUDE-global.md

@@ -617,7 +617,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`, `estimate` (client estimate + PRD) |
+| `scan` | `promote-debt` | `milestone`, `estimate` (client estimate sheet) |
 | `init` | `scan` | `milestone` |
 | `init-scan-setup` | `milestone` | |
 | `gap-analysis` | `milestone` | `feature` |

package/templates/estimate-config.json

@@ -14,7 +14,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.",
+  "_mfBreakdown": "Optional itemized breakdown of totalMF (must sum to totalMF). Tune per project; e.g. raise buffer for low-confidence scope. When a target sheet exists its own MF list (T-Shirt tab E4:F9) is the source of truth and is READ, never overwritten — Hilo sheets run 0.9 (qa .3, pm .1, analysis .1, deployment .05, standups .15, buffer .2). Every non-zero factor must have a person in Team Mix (see estimate-sheet-spec.md section 2.4).",
 
   "highFactor": 1.25,
   "_highFactor": "HIGH dollar figure = LOW x this. Raise above 1.25 when unknowns dominate (many R&D / spike items).",
@@ -35,5 +35,8 @@
   "_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."
+  "_newTeamDefault": "Whether to assume a new-team familiarization adjustment (Step 2.5a) by default. Usually true for a fresh client.",
+
+  "sheetSpec": "~/.claude/templates/estimate-sheet-spec.md",
+  "_sheetSpec": "The layout/formula/styling/roster spec every write is audited against. Bundled at templates/estimate-sheet-spec.md in the GSD-T package."
 }