@tekyzinc/gsd-t 4.16.10 → 4.18.10

package/CHANGELOG.md

@@ -2,6 +2,41 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [4.18.10] - 2026-07-03
+
+### Added — Scan Consolidation Opportunities + type-grouped register; init-scan-setup repo adoption
+
+The scan register is now organized by TD **type within each severity**, and a new **Consolidation** phase (opus + graph-assisted) appends a **🧩 Consolidation Opportunities** section listing high-confidence clusters of findings that share a root and should be fixed as one workstream. `/gsd-t-init-scan-setup` gains a **Step 0 "Adopt a Foreign Repo"** sanitization pass and a **Step 4a completeness check**, so repos built by others (or plain Claude) run correctly on this machine and an incomplete/hand-driven scan is caught and re-run.
+
+- `templates/workflows/gsd-t-scan.workflow.js`: register `fmtChunks` groups by `typeOf(area)` within severity via a shared `orderedFindings` ordering (so consolidation TD-N ids match the register exactly); new `Consolidation` phase (opus, graph-assisted via `who-imports`/`who-calls`/`blast-radius`) emits `CG-N` groups (members/sharedRoot/recommendedAction/effort) appended at the end; `meta.phases` +1. Best-effort — any failure leaves the register intact.
+- `commands/gsd-t-init-scan-setup.md`: Step 0 adoption (settings reconciled vs global, CLAUDE.md regenerated from fresh scan, no foreign/stale workflow-script execution) + Step 4a post-scan completeness check + 8-phase scan description + corrected graph note (`graphDB/`).
+- `commands/gsd-t-scan.md`: synthesis/consolidation phase description.
+- `.gsd-t/backlog.md`: split logging item #48 → #48 (trace) + #49 (audit) with full specs.
+- Lints green: M71 runtime-native, M85 tier-policy, M76 ascii. Suite 2631/2631.
+
+## [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

package/README.md

@@ -1,6 +1,6 @@
 # GSD-T: Contract-Driven Development for Claude Code
 
-**v4.16.10** - A methodology for reliable, parallelizable development using Claude Code with optional Agent Teams support.
+**v4.18.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,7 +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-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

@@ -1,49 +1,87 @@
-# GSD-T: Estimate — Tekyz Client Estimate + PRD from a Scan
+# GSD-T: Estimate — Tekyz Client Estimate + PRD from any Work Document
 
-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`).
+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 (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.
+**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.
 
-## Step 0: Inputs + Scope
+## Human-in-the-Loop (MANDATORY — this command is SUPERVISED, not auto)
 
-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.
+This process is judgment-heavy. **You (the operator) are the final arbiter of every estimate.** The command does NOT run end-to-end autonomously.
 
-## Step 1: Renumber for the client (if scan TDs start high)
+- **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.
 
-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`.)
+## Configuration (parameterized — defaults are Tekyz values)
 
-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.
+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.
 
-## Step 2: Size each finding (T-Shirt Size tab)
+| 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). |
 
-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.**
+## Step 0: Inputs + Scope + Sheet
 
-- **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.**
+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:** `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.
+- **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: Familiarization bump (new-team projects only)
+## Step 2.5: Estimate Adjustments (familiarization + risk/unknowns) — JUDGMENT · PAUSE FOR REVIEW
 
-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`.)
+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**.
-- **⚠️ 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.
+- 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)
 
@@ -59,41 +97,92 @@ Reorder items into domains (**A–G to match the PRD sections**). Insert a **blu
 - **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
+## 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 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).
+- **§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.
 
-## Step 7: Verify + Deliver
+**PAUSE** at every objection — this phase is inherently interactive.
 
-**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.
+## Step 9: Deliver
 
-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.
+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).
-- 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.
+- `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
 

package/commands/gsd-t-help.md

@@ -359,10 +359,10 @@ Use these when user asks for help on a specific command:
 - **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
+- **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 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`)
+- **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

package/commands/gsd-t-init-scan-setup.md

@@ -4,6 +4,48 @@ One command to fully onboard a project into GSD-T. Combines project directory se
 
 Can be run from anywhere — does not require being in the project folder first.
 
+## Entry States (READ FIRST — the command is IDEMPOTENT and SAFE to re-run)
+
+This command behaves **identically and unambiguously** across all three entry states:
+
+- **(A) Greenfield** — brand-new project, no code, no `.gsd-t/`.
+- **(B) Existing, new to this machine** — has code and/or a `.gsd-t/` dir but is not in this machine's registry.
+- **(C) Already-registered, being re-run.**
+
+**Existing `.gsd-t/` artifacts are NEVER a reason to skip scan or setup.** The ONLY thing "already exists" skips is **re-creating directory structure** (Step 3). Steps 4 (scan) and 5 (setup) **ALWAYS run**, on every invocation, in every entry state.
+
+**Re-running is expected and safe.** Archiving an existing `techdebt.md` and regenerating scan docs + CLAUDE.md is the **designed behavior** of this command — it is NOT a destructive action and does NOT require user approval. Stale scan docs from a prior milestone are the exact failure this command exists to prevent. Never stop to ask permission for the archive/regenerate steps.
+
+## Step 0: Adopt a Foreign Repo — Sanitize Inherited Context (MANDATORY, runs FIRST)
+
+**Why:** projects are frequently imported that were built by others — with plain Claude Code, or with GSD-T on a *different* machine/context. Such a repo arrives carrying **foreign context**: a committed `.claude/settings.json`, a `CLAUDE.md` authored in another environment, and `.gsd-t/` state / git history from a prior GSD-T install. That inherited context leaks and makes the project behave unexpectedly on THIS machine (e.g. an agent hand-authoring a scan from a foreign session's pattern instead of invoking the installed Workflow). **Adoption severs that** so the repo runs the way THIS machine's GSD-T expects — independent of whoever built it.
+
+Detect a foreign repo when ANY of these is true: the git remote is not the operator's own, the commit history shows GSD-T/Claude workflow commits (`milestone(...)`, `feat(...task-N)`, `chore(scan)`), there is a committed in-repo settings file, or `.gsd-t/` exists but the project is not in this machine's registry (entry state B).
+
+### 0a. Settings reconciliation (in-repo settings vs GLOBAL — global is source of truth)
+
+For each in-repo settings file (`.claude/settings.json`, `.claude/settings.local.json`, or any `settings*.json` committed in the repo tree — NOT `~/.claude/` global files):
+
+- **Compare every entry against the operator's GLOBAL settings** (`~/.claude/settings.json` + `~/.claude/settings.local.json`).
+- **Any permission the global ALREADY grants or denies → global wins → DELETE that entry** (or the whole file if all its content is global-governed). No approval needed — global is the single source of truth for anything it covers. The project always falls back to global.
+- **Project-distinct content the global says NOTHING about** (a permission/env/setting unrelated to global) → **do NOT delete. HALT onboarding and SURFACE it to the operator**: show the exact content, explain it's distinct from global, and ask keep-or-discard. **Nothing proceeds past this point until the operator decides** — do not run scan/setup on an unresolved settings question.
+- Log every deletion and every surfaced item.
+
+### 0b. CLAUDE.md — always regenerate from the fresh scan
+
+The imported `CLAUDE.md` may have been authored in a different project's context and cannot be trusted as current — **even if it looks correct.** Adoption does NOT try to judge foreign-vs-fine. Instead:
+
+- **Back up** the imported file to `CLAUDE.md.imported.bak` (lossless — nothing is destroyed).
+- **Always regenerate** the project `CLAUDE.md` from the NEW scan findings in Step 5. (The regenerate is deferred to Step 5 where the fresh scan exists; Step 0b only takes the backup + marks it for regeneration so Step 5 does not skip it.)
+
+### 0c. Foreign `.gsd-t/` + workflow residue
+
+- Existing `.gsd-t/` state is REFRESHED by the normal flow (Step 4 re-scan archives + regenerates), not trusted as-is.
+- **Never run a scan from a script found inside the repo or a prior session** — always resolve `gsd-t workflow-path scan` and invoke the installed Workflow (Step 4). A repo-committed `*.workflow.js` is foreign residue; do not execute it.
+- Register the project by FULL ABSOLUTE PATH on this machine (Step 3).
+
+**Adoption is idempotent + safe:** on a repo already adopted, 0a finds nothing to reconcile, 0b re-backs-up only if the file changed, 0c is a no-op. It never blocks a clean project.
+
 ## Step 1: Project Directory
 
 ### 1a. Resolve the base projects directory (for new projects)
@@ -93,33 +135,48 @@ Execute the full init workflow (same as `/gsd-t-init`):
 7. Initialize backlog with auto-derived categories
 8. Register project in `~/.claude/.gsd-t-projects`
 
-**If `.gsd-t/` already exists**: Skip init — it's already done. Log and continue to scan. Still check and create settings.local (step 5) even if init is skipped.
+**Registry check — match by FULL ABSOLUTE PATH, not bare project name.** The registry stores full paths; a bare-name grep produces a false "not registered" (two projects can share a basename) and erodes trust in the rest of the detected state. A missing entry means "register it now" — it must NOT cast doubt on any other detected state. If already present, log and continue silently.
+
+**If `.gsd-t/` already exists**: Skip **ONLY the dir-structure creation** that already exists — it's already done. **This skip does NOT extend to Step 4 (scan) or Step 5 (setup), which ALWAYS run.** Always ensure `settings.local` (step 5 above) and the registry entry regardless of whether init dir-creation was skipped.
 
 ## Step 3.5: Graph Indexing Note
 
-If the project has source code, graph indexing (`.gsd-t/graph/`) will run as part of the scan phase (Step 4). The graph provides code-level queries (callers, callees, domain ownership, dead code detection) that enhance all subsequent GSD-T commands. No separate setup is needed — the scan handles it.
+If the project has source code, the **graph index is built automatically inside the scan's Graph-Wiring phase (Step 4)** — the scan builds the index if it is absent, then queries it. The store lives at `.gsd-t/graphDB/` (consolidated) — the graph provides code-level queries (callers, callees, domain ownership, dead-code detection) that enhance all subsequent GSD-T commands. **No separate indexing step is needed — the scan handles it.** (You can also build/refresh the index on demand with `gsd-t graph index`, but the scan does it for you.)
 
 ## Step 4: Deep Codebase Scan (gsd-t-scan)
 
-Execute the full scan by invoking the volume-scaled scan Workflow (same as `/gsd-t-scan` — `templates/workflows/gsd-t-scan.workflow.js`):
+**Invoke the PACKAGED scan Workflow — never hand-drive it.** Resolve the absolute path with `gsd-t workflow-path scan`, then call the `Workflow` tool with that `scriptPath`. **Do NOT author your own scan script, do NOT run finders/probe/synthesis by hand, and do NOT execute any `*.workflow.js` found inside the repo or a prior session** — a hand-driven or foreign scan skips phases (Graph-Wiring, Document, Plain-English) and produces an incomplete result. This is the exact failure mode observed on imported repos.
+
+The packaged Workflow runs **8 phases**: Preflight → Probe → **Graph-Wiring** → Deep Scan → Synthesis → **Consolidation** → **Document** → **Plain-English**. It:
 
-1. The volume-probe slices the codebase by area (scaling with volume, not a fixed dimension set); per-slice deep finders enumerate; a single verify pass drops false positives.
-2. Synthesis builds the `.gsd-t/techdebt.md` register and the `.gsd-t/scan/*.md` analysis files.
-3. Cross-populate findings into living documents (docs/architecture.md, docs/workflows.md, docs/infrastructure.md, docs/requirements.md) from the register + analysis files.
-4. Update README.md with discovered tech stack and setup info.
+1. Volume-probes and slices the codebase by area; per-slice deep finders enumerate; a single verify pass drops false positives.
+2. **Graph-Wiring** — builds the graph index if absent, then queries a structural slice (dead-code / dangling / cluster) injected additively into the finders.
+3. Synthesis builds `.gsd-t/techdebt.md` + the `.gsd-t/scan/*.md` analysis files.
+4. Document cross-populates living docs (architecture/workflows/infrastructure/requirements) + README.
+5. Plain-English writes the non-technical companion.
 
 The Workflow's fan-out scales with codebase volume automatically — no team-mode toggle.
 
-**If `.gsd-t/techdebt.md` already exists**: the Workflow archives it to `.gsd-t/techdebt_YYYY-MM-DD.md` and continues TD numbering.
+**ALWAYS run the scan on every invocation, even on a fully-onboarded project.** Existing `techdebt.md` is archived to `techdebt_YYYY-MM-DD.md` and the scan regenerates it (TD numbering continues). **NEVER skip the scan because `.gsd-t/` or `scan/*.md` already exist — stale scan docs are the exact failure this command prevents.** Archiving is designed behavior, NOT a destructive action, and does NOT require user approval.
+
+### 4a. Post-scan completeness check (catches a hand-driven / incomplete scan)
+
+After the scan returns, VERIFY the packaged 7-phase Workflow actually ran by confirming its expected outputs exist and are fresh (mtime within this run):
+
+- `.gsd-t/techdebt.md` (regenerated) **and** at least the 5 `.gsd-t/scan/*.md` dimension files
+- the merged living docs (architecture/workflows/infrastructure/requirements touched this run)
+- the plain-English companion (`.gsd-t/techdebt_in_plain_english.md` or equivalent)
+
+**If any are missing → LOUD failure, do not proceed:** "⛔ Incomplete scan — the packaged Workflow's Document / Plain-English / Graph-Wiring outputs are absent. This means the scan was hand-driven or a foreign/stale script ran instead of the installed Workflow. Re-run: resolve `gsd-t workflow-path scan` and invoke the `Workflow` tool." Then re-invoke correctly, once.
 
 ## Step 5: Generate Project CLAUDE.md (gsd-t-setup)
 
-Execute the full setup workflow (same as `/gsd-t-setup`):
+Execute the full setup workflow (same as `/gsd-t-setup`). **ALWAYS run — regenerate/refresh the project CLAUDE.md from the NEW scan findings; do NOT assume an existing CLAUDE.md is current.** If Step 0b flagged an imported CLAUDE.md (backed up to `CLAUDE.md.imported.bak`), this regeneration is what replaces it with a machine-correct version — do NOT skip it.
 
 1. Read global `~/.claude/CLAUDE.md` to understand what's already covered
-2. Use scan findings + auto-detection to populate project-specific sections
+2. Use the **fresh** scan findings + auto-detection to populate project-specific sections
 3. Remove any global duplicates from the project CLAUDE.md
-4. Generate and write the optimized CLAUDE.md
+4. Generate and write the optimized CLAUDE.md (refresh the existing one — don't skip because a CLAUDE.md already exists)
 
 At Level 3: skip questions that were auto-detected — only ask what's truly unknown.
 At Level 1-2: ask all targeted questions per the setup workflow.
@@ -136,7 +193,11 @@ Project Onboarded: {project name}
   Scan:     {N} tech debt items ({critical} critical, {high} high, {medium} medium, {low} low)
   Setup:    CLAUDE.md generated ({N} sections)
   Registry: {registered | already registered}
+```
+
+For an already-onboarded project (entry state B/C), the report reads as **"re-scanned and refreshed,"** never "nothing to do": show the archived `techdebt_YYYY-MM-DD.md` path, the fresh finding counts, and that CLAUDE.md was regenerated.
 
+```
 Next steps:
   → Review .gsd-t/techdebt.md for critical items
   → /gsd-t-milestone to define your first milestone
@@ -145,7 +206,7 @@ Next steps:
 
 ### Autonomy Behavior
 
-**Level 3 (Full Auto)**: Run all steps without pausing. Only stop if git remote is needed (requires user input) or if a scan reveals critical security blockers.
+**Level 3 (Full Auto)**: Run all steps without pausing. Only stop if git remote is needed (requires user input) or if a scan reveals critical security blockers. **"Already onboarded" NEVER means "nothing to do" — it means "re-scan and refresh."** Do NOT pause to ask permission for the archive/regenerate steps; re-running is expected and safe.
 
 **Level 1-2**: Pause after each major step (init, scan, setup) for user review before continuing.
 

package/commands/gsd-t-scan.md

@@ -41,7 +41,7 @@ The current scan architecture (enumerate + per-file deep-finders) is **KEPT FULL
 preflight → volume-probe → pipeline(per-slice deep finder → single verify) → synthesis → document → render
 ```
 
-**Why volume-scaled (M66):** the legacy scan hard-coded exactly 5 teammates (one per dimension) with zero volume scaling — a 5-file repo and a 1,809-file repo both got 5 agents, so a single `quality` agent sampled the top ~5 issues across the whole codebase and stopped. The volume-probe stage now measures the codebase (files, routes, ORM tables, components, top-level dirs) and carves it into **narrow slices** — one deep-finder agent per area, scaling from 1-3 slices on a tiny repo to 15-40 on a large one. Each finder OWNS its slice and is mandated to *enumerate, not sample*. A single verify pass confirms each finding against the real code and drops false positives. Synthesis dedups/merges/re-ranks into `techdebt.md` and continues TD numbering from the archived prior register.
+**Why volume-scaled (M66):** the legacy scan hard-coded exactly 5 teammates (one per dimension) with zero volume scaling — a 5-file repo and a 1,809-file repo both got 5 agents, so a single `quality` agent sampled the top ~5 issues across the whole codebase and stopped. The volume-probe stage now measures the codebase (files, routes, ORM tables, components, top-level dirs) and carves it into **narrow slices** — one deep-finder agent per area, scaling from 1-3 slices on a tiny repo to 15-40 on a large one. Each finder OWNS its slice and is mandated to *enumerate, not sample*. A single verify pass confirms each finding against the real code and drops false positives. Synthesis dedups/merges/re-ranks into `techdebt.md` (items **grouped by type within each severity** — Security/Vulnerability, Dead Code, Duplication, etc.) and continues TD numbering from the archived prior register. A **Consolidation** phase (opus + graph-assisted) then appends a **🧩 Consolidation Opportunities** section at the END of the register: high-confidence clusters of TDs that share a root and should be fixed as ONE workstream (duplicate-function families, batch dead-code deletions, a guard missing across N sites), each a candidate for a single consolidation milestone.
 
 **Deep document stage (M67):** after the register lands, a `document` phase fans out **one agent per document**, each drawing on the same slices + verified findings, to deterministically produce the full living-document set — `docs/architecture.md` (component map per feature-domain slice), `docs/workflows.md` (a user journey per slice), `docs/infrastructure.md`, `docs/requirements.md`, `README.md` (all merge-not-overwrite) — plus the five `.gsd-t/scan/*.md` dimension files (`architecture`, `security`, `quality`, `business-rules`, `contract-drift`) in the renderer's parsed formats. This replaces M66's non-deterministic "lead-agent follow-on" so the documents are as thorough as the register. The deterministic `bin/scan-*.js` renderers (schema extraction, diagrams, HTML report) run last, reading the deep `.gsd-t/scan/architecture.md`.
 

package/package.json

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

@@ -1,9 +1,17 @@
 # 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.
+> 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`,
@@ -81,10 +89,20 @@ cells does NOT auto-expand hardcoded ranges; only `insertDimension` shifts them.
 
 ## 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.
+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.
 
 ---
 

package/templates/workflows/gsd-t-scan.workflow.js

@@ -34,7 +34,8 @@ export const meta = {
     { title: "Probe",         detail: "volume probe → per-area slice list", model: "sonnet" },
     { title: "Graph-Wiring",  detail: "M94-D6: build index if absent + query structural slice (dead-code/dangling/cluster) → inject into finders ADDITIVELY; fallback announced on graph-unavailable", model: "haiku" },
     { title: "Deep Scan",     detail: "pipeline: per-slice deep finder (graph-augmented when wired) → single verify" },
-    { title: "Synthesis",     detail: "archive prior + write fresh register + git", model: "opus" },
+    { title: "Synthesis",     detail: "archive prior + write fresh register (type-grouped within severity) + git", model: "opus" },
+    { title: "Consolidation", detail: "opus + graph-assisted: high-confidence clusters of TDs to fix as one workstream → appended to register", model: "opus" },
     { title: "Document",      detail: "living docs + 5 dimension files (per-doc fan-out)" },
     { title: "Plain-English", detail: "non-technical companion: batched gen + severity-grouped chunked write" },
   ],
@@ -785,6 +786,35 @@ function ascii(s) {
     .replace(/…/g, "...")              // ellipsis
     .replace(/[ \t]+\n/g, "\n");            // tidy trailing whitespace
 }
+
+// Register ordering — SINGLE source of truth so the formatter's TD-numbering and the
+// consolidation stage's TD references stay identical. Within each severity, findings
+// are sub-grouped by TYPE (derived from `area`). typeOf() maps free-text area→bucket;
+// unmatched → "Other". `orderedFindings` is the final, numbered sequence (TD-tdStart..).
+function typeOf(f) {
+  const a = String(f.area || "").toLowerCase() + " " + String(f.title || "").toLowerCase();
+  if (/(vuln|idor|auth|injection|xss|csrf|secret|privilege|tenant|security|rce|ssrf)/.test(a)) return "Security / Vulnerability";
+  if (/(dead.?code|unreachable|unused|orphan|never (called|used|imported))/.test(a)) return "Dead Code";
+  if (/(duplicat|redundant|reimplement|copy)/.test(a)) return "Duplication";
+  if (/(data.?integrity|race|concurren|transaction|idempoten|double|constraint)/.test(a)) return "Data Integrity / Concurrency";
+  if (/(perf|n\+1|slow|latency|batch|query.?count)/.test(a)) return "Performance";
+  if (/(contract.?drift|schema.?drift|api.?mismatch|404|endpoint.*(missing|not exist))/.test(a)) return "Contract Drift";
+  if (/(test|coverage|shallow|flaky)/.test(a)) return "Testing";
+  return "Other";
+}
+const TYPE_ORDER = ["Security / Vulnerability", "Dead Code", "Duplication", "Data Integrity / Concurrency", "Performance", "Contract Drift", "Testing", "Other"];
+const SEV_ORDER2 = { CRITICAL: 0, HIGH: 1, MEDIUM: 2, LOW: 3 };
+// Stable sort: severity, then type, then original index. Computed ONCE; both consumers use it.
+const orderedFindings = finalFindings
+  .map((f, i) => ({ f, i, t: typeOf(f) }))
+  .sort((a, b) => {
+    const sv = (SEV_ORDER2[a.f.severity] ?? 9) - (SEV_ORDER2[b.f.severity] ?? 9);
+    if (sv !== 0) return sv;
+    const tv = TYPE_ORDER.indexOf(a.t) - TYPE_ORDER.indexOf(b.t);
+    if (tv !== 0) return tv;
+    return a.i - b.i;
+  });
+
 function fmtChunks(today) {
   const sevHead = { CRITICAL: "🔴 Critical", HIGH: "🟠 High", MEDIUM: "🟡 Medium", LOW: "🟢 Low" };
   const head = [];
@@ -820,11 +850,17 @@ function fmtChunks(today) {
 
   const CHUNK_MAX = 30000;
   const chunks = [head.join("\n")];
-  let buf = "", n = tdStart, lastSev = null;
+  let buf = "", n = tdStart, lastSev = null, lastType = null;
   const flush = () => { if (buf) { chunks.push(buf); buf = ""; } };
-  for (const f of finalFindings) {
+  // Consume the shared `orderedFindings` (severity → type → original-index) so the
+  // TD numbers assigned here are IDENTICAL to those the consolidation stage references.
+  for (const { f, t } of orderedFindings) {
     let piece = "";
-    if (f.severity !== lastSev) { piece += `\n## ${sevHead[f.severity] || f.severity} Priority\n\n`; lastSev = f.severity; }
+    if (f.severity !== lastSev) { piece += `\n## ${sevHead[f.severity] || f.severity} Priority\n\n`; lastSev = f.severity; lastType = null; }
+    // Type sub-heading uses a bold marker line (NOT `###`) so it never collides with
+    // the `### TD-N` item headings that downstream tools grep for. ASCII hyphens only
+    // (M76: no em/en-dashes in fmtChunks literals).
+    if (t !== lastType) { piece += `**-- ${t} --**\n\n`; lastType = t; }
     piece += itemMd(f, n++);
     if (buf.length + piece.length > CHUNK_MAX) flush();
     buf += piece;
@@ -889,6 +925,99 @@ log(`register written in ${chunkOk}/${chunks.length} chunks (${counts.total} fin
 const synthesis = { status: "written", counts, archivePath, tdRange: `TD-${tdStart}..TD-${lastTd}`, finalFindings };
 log(`register written: ${JSON.stringify(synthesis.counts)} (${synthesis.tdRange})`);
 
+// ── Consolidation Opportunities (opus + graph-assisted) ────────────────────────
+// After the register is written (TD numbers final), cluster HIGH-CONFIDENCE groups
+// of TDs that share a root and should be fixed as ONE workstream (duplicate-function
+// families, batch dead-code deletions, a guard-pattern missing across N sites, god-file
+// splits). Only tight clusters — ungrouped TDs stay standalone (user directive). The
+// section is APPENDED to the END of the register, after all individual items.
+// Graph-assisted: an agent may run `gsd-t graph who-imports/who-calls/blast-radius`
+// (project-local bin first, else global) on a TD's files to confirm two TDs truly share
+// code before grouping — grounds the clustering in real relationships, not just prose
+// similarity. Best-effort: any failure leaves the register intact (no section).
+phase("Consolidation");
+try {
+  // Number from the SHARED `orderedFindings` so each TD-N here is EXACTLY the id the
+  // register wrote (severity → type → original-index — the single ordering source).
+  let _n = tdStart;
+  const consInput = orderedFindings.map(({ f }) => {
+    const td = _n++;
+    return `TD-${td} [${f.severity}] (${ascii(f.area) || "?"}) ${ascii(f.title)} @ ${(f.files && f.files[0]) || "?"}`;
+  }).join("\n");
+  const CONS_SCHEMA = {
+    type: "object", required: ["groups"], additionalProperties: false,
+    properties: {
+      groups: {
+        type: "array",
+        items: {
+          type: "object", required: ["title", "members", "sharedRoot", "recommendedAction"], additionalProperties: false,
+          properties: {
+            title: { type: "string" },
+            members: { type: "array", items: { type: "string" } },   // e.g. ["TD-75","TD-143"]
+            sharedRoot: { type: "string" },
+            recommendedAction: { type: "string" },
+            effort: { type: "string" },                              // GSD-T-native units
+          },
+        },
+      },
+      notes: { type: "string" },
+    },
+  };
+  const consAgent = await agent(
+    [
+      `You are identifying CONSOLIDATION OPPORTUNITIES in a tech-debt register — sets of findings that share a ROOT and should be fixed as ONE workstream, not one-by-one.`,
+      `Below are ${finalFindings.length} findings as "TD-N [SEVERITY] (area) title @ location".`,
+      ``,
+      `Group ONLY HIGH-CONFIDENCE clusters (user directive — tight, not loose themes):`,
+      `  • duplicate-functionality families (same logic implemented 2+ times / diverging copies)`,
+      `  • batch dead-code deletions (multiple never-used modules/components removable together)`,
+      `  • a single missing pattern repeated across N sites (e.g. the same auth guard absent on many routes)`,
+      `  • god-file / god-object splits touching several TDs`,
+      `  • the SAME remediation applied in multiple places`,
+      `Findings with no strong shared root MUST be left OUT (they stay standalone — do not force weak groupings).`,
+      ``,
+      `GRAPH-ASSIST (optional, strengthens confidence): to confirm two TDs truly share code, you MAY run the code graph via Bash on their files — try a project-local binary first then the global one:`,
+      `  \`${projectDir}/bin/gsd-t-graph-query-cli.cjs who-imports <file>\`  OR  \`gsd-t graph who-imports <file>\` (also who-calls / blast-radius). If the graph is unavailable, fall back to the location/area text — do NOT fail.`,
+      ``,
+      `Return "groups": each = { title, members: ["TD-N",...] (>=2), sharedRoot, recommendedAction (which to keep/delete/extract), effort (GSD-T-native units: domain/wave/spawn count — NEVER human-hours) }. If nothing clusters with high confidence, return groups: [].`,
+      ``,
+      consInput.slice(0, 140000),
+    ].join("\n"),
+    { label: "consolidation:cluster", phase: "Consolidation", schema: CONS_SCHEMA, model: "opus" }
+  ).catch((e) => { log(`consolidation cluster failed (non-fatal): ${e && e.message}`); return null; });
+
+  const groups = (consAgent && Array.isArray(consAgent.groups)) ? consAgent.groups : [];
+  if (groups.length) {
+    const cs = [
+      ``, `---`, ``, `## 🧩 Consolidation Opportunities`, ``,
+      `> High-confidence clusters of findings that share a root cause and should be addressed as ONE workstream (candidates for a single consolidation milestone). Findings not listed here have no strong shared root and stand alone. Effort is in GSD-T-native units.`, ``,
+    ];
+    groups.forEach((g, gi) => {
+      cs.push(`### CG-${gi + 1} - ${ascii(g.title)}`);
+      cs.push(`- **Members:** ${(g.members || []).map((m) => ascii(m)).join(", ")}`);
+      cs.push(`- **Shared root:** ${ascii(g.sharedRoot)}`);
+      cs.push(`- **Recommended action:** ${ascii(g.recommendedAction)}`);
+      if (g.effort) cs.push(`- **Effort:** ${ascii(g.effort)}`);
+      cs.push("");
+    });
+    if (consAgent.notes) cs.push(`> Notes: ${ascii(consAgent.notes)}`, "");
+    // Append via a bounded agent Bash heredoc (orchestrator has no fs).
+    const consBlock = cs.join("\n");
+    await agent(
+      [
+        `APPEND EXACTLY the content between the markers to the END of \`${regPath}\` (append — do NOT overwrite existing content). Use a Bash heredoc: \`cat >> ${regPath} <<'GSDTEOF'\` … \`GSDTEOF\`. After writing, reply ONLY "OK".`,
+        ``, `<<<CHUNK>>>`, consBlock, `<<<END_CHUNK>>>`,
+      ].join("\n"),
+      { label: "consolidation:write", phase: "Consolidation", model: "haiku" }
+    ).catch((e) => log(`consolidation append uncertain (non-fatal): ${e && e.message}`));
+    log(`consolidation: ${groups.length} high-confidence group(s) appended to register`);
+  } else {
+    log(`consolidation: no high-confidence clusters found (register unchanged)`);
+  }
+} catch (e) {
+  log(`consolidation phase failed (non-fatal — register intact): ${e && e.message}`);
+}
+
 // Document — per-doc fan-out. Each agent writes its file via Write/Edit (its tools).
 // The orchestrator passes the findings + (for plain-english) tells the agent to
 // READ the just-written register itself, since the orchestrator can't read it.