@tekyzinc/gsd-t 4.14.10 → 4.16.10

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [4.16.10] - 2026-07-01
+
+### Added — `/gsd-t-estimate`: Tekyz client estimate + PRD from a scan
+
+New standalone command that turns a completed scan (`.gsd-t/techdebt.md`) into a Tekyz client estimate (a Google Sheet with a T-Shirt-Size tab + a Team-Mix cross-check) and a matching PRD deliverable. Encodes the 7-phase Tekyz playbook proven on the HILO Figma ATOS project (21 criticals → 32.73 eng-days → $13,090–$16,362).
+
+- `commands/gsd-t-estimate.md` — the skill: scope + read register; client renumber to TD-1 (range-bounded, archives untouched, second pass for bare/chained refs); T-shirt sizing (XS.25/S.5/M1/L3/XL5/XXL7, FE+BE columns independent); familiarization bump for new teams (bump SIZE not MF, never cross the M→L 3× cliff); Google Sheet write via a throwaway service-account + JWT (gcloud's spreadsheets scope is Google-blocked); domain grouping + SUMIF-range widen; Team-Mix reconcile; PRD with FR↔TD crosswalk + estimate-not-quote disclaimer + §10-syncs-the-sheet; three-total verify.
+- `templates/playbooks/tekyz-estimation-and-prd-playbook.md` — bundled reference (ships in the package so the skill works in a fresh install).
+- `commands/gsd-t-help.md`, `templates/CLAUDE-global.md`, `README.md` — doc-ripple (help summary, successor mapping `scan → estimate`, commands table).
+- `test/filesystem.test.js` — command count 45→46 / 51→52.
+
+Note: this produces a paid CLIENT estimate — the "no cost estimates" rule governs GSD-T's own Max-funded build work, not client deliverables.
+
+## [4.15.10] - 2026-06-30
+
+### Added — scan builds the graph index when absent + repo-labeled `share/` export
+
+Two scan improvements, both prompted by a real hilo-figma-atos scan that grep-fell-back and produced same-named docs across projects.
+
+- **Scan auto-builds the graph index when absent** (`templates/workflows/gsd-t-scan.workflow.js`). The wired graph path was documented "build index if absent, then query" but the BUILD step was never wired — `GRAPH_BUILD_SCHEMA` was defined and unused. So on any project without a pre-built index (the common case), scan probed `graph status`, saw not-ok, and silently grep-fell-back — the graph was NEVER used. Observed on hilo-figma-atos (a 30M-token scan grep-fell-back purely because the index had never been built). Fix: the wired branch now runs `gsd-t graph index` (new `runCliBuild` helper), re-probes, and only falls back if the build itself fails. This is the headline value of the whole graph arc — scan now engages the graph on first run, not only when a human pre-built it.
+- **Repo-labeled `share/` export + dated archive (#47)** (`templates/workflows/gsd-t-scan.workflow.js`, `commands/gsd-t-scan.md`). The LAST scan step COPIES the living docs + scan reports into `share/<file>-<repo>.md` (e.g. `share/architecture-hilo-figma-atos.md`) so files shared across projects are distinguishable. INTERNAL files keep their fixed names (`.gsd-t/techdebt.md`, `docs/architecture.md`) so all internal tooling (promote-debt, gap-analysis, complete-milestone, …) is untouched — zero blast radius. Prior scan outputs are archived to `.gsd-t/scan/archive/<name>-YYYYMMDD-HHMM.md` for diffing new-vs-prior.
+- `test/m94-d6-scan-consumer.test.js`: regression tests for both (build-when-absent + re-probe; share/ export + fixed internal names + dated archive).
+
 ## [4.14.10] - 2026-06-30
 
 ### Added — M99: Graph Observability & Consolidation

package/README.md

@@ -1,6 +1,6 @@
 # GSD-T: Contract-Driven Development for Claude Code
 
-**v4.14.10** - A methodology for reliable, parallelizable development using Claude Code with optional Agent Teams support.
+**v4.16.10** - A methodology for reliable, parallelizable development using Claude Code with optional Agent Teams support.
 
 **Eliminates context rot** — task-level fresh dispatch (one subagent per task, ~10-20% context each) means compaction never triggers.
 **Compaction-proof debug loops** — `gsd-t headless --debug-loop` runs test-fix-retest cycles as separate `claude -p` sessions. A JSONL debug ledger persists all hypothesis/fix/learning history across fresh sessions. Anti-repetition preamble injection prevents retrying failed hypotheses. Escalation tiers (sonnet → opus → human) and a hard iteration ceiling enforced externally.
@@ -186,6 +186,7 @@ This will replace changed command files, back up your CLAUDE.md if customized, a
 | `/gsd-t-scan` | Deep codebase analysis → techdebt.md | Manual |
 | `/gsd-t-gap-analysis` | Requirements gap analysis — spec vs. existing code | Manual |
 | `/gsd-t-promote-debt` | Convert techdebt items to milestones | Manual |
+| `/gsd-t-estimate` | Turn a scan into a Tekyz client estimate (Google Sheet: T-Shirt Size + Team Mix) + matching PRD | Manual |
 | `/gsd-t-populate` | Auto-populate docs from existing codebase | Manual |
 | `/gsd-t-design-decompose` | Decompose design into element/widget/page contracts | Manual |
 

package/commands/gsd-t-estimate.md

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

package/commands/gsd-t-help.md

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

package/commands/gsd-t-scan.md

@@ -110,11 +110,11 @@ Present a summary: headline volume totals, findings by severity, the top critica
 
 The scan Workflow updates ALL of these deterministically (no manual follow-on):
 
-- `.gsd-t/techdebt.md` — fresh register (synthesis; prior one archived to `.gsd-t/techdebt_YYYY-MM-DD.md`)
+- `.gsd-t/techdebt.md` — fresh register (synthesis; **the prior register + all prior dimension files are archived with a datetime stamp to `.gsd-t/scan/archive/<name>-YYYYMMDD-HHMM.md`** so you can diff new-vs-prior — #47)
 - `.gsd-t/techdebt_in_plain_english.md` — non-technical companion to the register: every TD item in layman's terms, why it matters, and a real-world analogy (document phase)
 - `.gsd-t/scan/{architecture,security,quality,business-rules,contract-drift}.md` — dimension analysis files (document phase)
-- `docs/architecture.md`, `docs/workflows.md`, `docs/infrastructure.md`, `docs/requirements.md`, `README.md` — living docs, **merged not overwritten** (document phase)
-- HTML scan report via `bin/scan-report.js` (render phase)
+- `docs/architecture.md`, `docs/workflows.md`, `docs/infrastructure.md`, `docs/requirements.md`, `README.md` — living docs, **merged not overwritten** (document phase). These keep their fixed names (GSD-T reads them by hardcoded path).
+- **`share/` — team-shareable, repo-name-labeled COPIES (#47):** the LAST scan step copies the living docs + scan reports into `share/` with the project's repo name suffixed (`share/architecture-<repo>.md`, `share/techdebt-<repo>.md`, …). Originals untouched. This solves "which file is for which project?" when sharing across repos — your team reads from `share/`. Regenerated each scan.
 
 The document phase + render commit these via git on the feature branch (no push). The lead agent should still add a `.gsd-t/progress.md` Decision Log entry with the scan summary stats.
 

package/package.json

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

package/templates/CLAUDE-global.md

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

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

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

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

@@ -88,6 +88,7 @@ const PREFLIGHT_SCHEMA = {
   properties: {
     ok:                  { type: "boolean" },
     branch:              { type: "string" },
+    repoName:            { type: "string", description: "the project directory's basename (e.g. 'hilo-figma-atos') — used to suffix shared scan/doc files" },
     priorRegisterExists: { type: "boolean" },
     priorMaxTd:          { type: "integer", description: "highest TD-NNN in the prior register, 0 if none" },
     notes:               { type: "string" },
@@ -287,6 +288,29 @@ async function runCli(verb, target, label) {
   return r || { ok: false, reason: "graph-unavailable", via: "error" };
 }
 
+// Build the graph index (`gsd-t graph index`) when it is absent. The wired path
+// is documented "build index if absent, then query" but the BUILD step was never
+// wired — so on any project without a pre-built index (the common case), scan
+// silently grep-fell-back and the graph was NEVER used (observed on hilo-figma-atos
+// 2026-06-30: a 30M-token scan grep-fell-back because the index was never built).
+// `graph index` is a longer command than the verb queries → bigger timeout.
+// [RULE] scan-builds-index-when-absent
+async function runCliBuild() {
+  const prompt = [
+    `Build the GSD-T code-graph index for the project at \`${projectDir}\`, then report. Steps:`,
+    `1. If \`${projectDir}/bin/gsd-t.js\` exists, run: \`node ${projectDir}/bin/gsd-t.js graph index\` (via="local"). Otherwise run: \`gsd-t graph index\` (via="global"). Use cwd \`${projectDir}\`. This may take up to a few minutes on a large repo — wait for it to finish. Do NOT redirect stderr.`,
+    `2. Set ok=true if the command exits 0 (the index built). Set ok=false with a short reason + first ~200 chars of stderr otherwise.`,
+    `Do NOT do any other work. ONLY run this one build command and report the structured result.`,
+  ].join("\n");
+  const r = await agent(prompt, {
+    label: "graph:index-build",
+    phase: "Graph-Wiring",
+    model: "haiku",
+    schema: GRAPH_BUILD_SCHEMA,
+  }).catch((e) => ({ ok: false, reason: `agent-error: ${e && e.message}` }));
+  return r || { ok: false, reason: "build-failed" };
+}
+
 // M99 D2: persist a kind:'wiring' ledger line for this workflow.
 // M81 sandbox: all I/O through agent() Bash; no require/fs in the sandbox.
 // Uses the `gsd-t graph wiring-log` CLI shim (avoids embedding require() in strings).
@@ -312,8 +336,9 @@ const pre = await agent(
     `You are the preflight check for a GSD-T deep scan of the project at \`${projectDir}\`.`,
     `Using Bash/Read tools, determine:`,
     `1. The current git branch (\`git -C ${projectDir} rev-parse --abbrev-ref HEAD\`; if not a git repo, report branch "(no-git)").`,
-    `2. Whether \`${projectDir}/.gsd-t/techdebt.md\` exists (priorRegisterExists).`,
-    `3. If it exists, the HIGHEST TD-NNN number in it (grep \`### TD-\`, parse the max integer; priorMaxTd). If absent, priorMaxTd=0.`,
+    `2. The repo name = the basename of the resolved project dir (\`basename "$(cd ${projectDir} && pwd)"\`) — e.g. "hilo-figma-atos". Report as repoName (used to label the team-shared share/ copies).`,
+    `3. Whether \`${projectDir}/.gsd-t/techdebt.md\` exists (priorRegisterExists).`,
+    `4. If it exists, the HIGHEST TD-NNN number in it (grep \`### TD-\`, parse the max integer; priorMaxTd). If absent, priorMaxTd=0.`,
     `Set ok=true unless something makes scanning impossible (e.g. projectDir does not exist). Return JSON per the schema.`,
   ].join("\n"),
   { label: "preflight", phase: "Preflight", schema: PREFLIGHT_SCHEMA, model: "haiku" }
@@ -323,7 +348,12 @@ if (!pre || !pre.ok) {
   return { status: "failed", reason: "preflight-failed", preflight: pre };
 }
 const tdStart = (pre.priorRegisterExists ? (pre.priorMaxTd || 0) : 0) + 1;
-log(`preflight ok — branch=${pre.branch}, priorRegister=${pre.priorRegisterExists}, TD numbering starts at TD-${tdStart}`);
+// #47: repo-name suffix for the TEAM-SHARED copies only. INTERNAL files keep their
+// fixed names (.gsd-t/techdebt.md, .gsd-t/scan/<dim>.md, docs/*.md) so all internal
+// tooling (promote-debt, gap-analysis, complete-milestone, …) keeps working — zero
+// blast radius. The repo suffix appears ONLY on the share/ exports at the end.
+const repoName = (pre.repoName && /^[A-Za-z0-9._-]+$/.test(pre.repoName)) ? pre.repoName : "project";
+log(`preflight ok — branch=${pre.branch}, repo=${repoName}, priorRegister=${pre.priorRegisterExists}, TD numbering starts at TD-${tdStart}`);
 
 // Volume probe — an agent measures the codebase (its own Bash) and carves slices.
 phase("Probe");
@@ -376,12 +406,26 @@ if (graphMode === "disabled") {
 } else {
   // graphMode === "wired": build index if absent, then query structural slice.
   // Step 1: check if index exists and is queryable.
-  const statusResult = await runCli("status", null, "status");
+  let statusResult = await runCli("status", null, "status");
+  // Step 1b: if the index is absent/unqueryable, BUILD it once, then re-probe.
+  // This is the previously-missing build step — without it scan grep-fell-back on
+  // every project lacking a pre-built index (hilo-figma-atos 2026-06-30).
+  // [RULE] scan-builds-index-when-absent
   if (!statusResult || !statusResult.ok) {
-    // Graph unavailable — announce fallback, continue with intact grep-mode scan.
-    // [RULE] parser-fail-disables-loud-never-silent (from graph-query-cli-contract)
+    log(`graph-wiring: index not queryable (${(statusResult && statusResult.reason) || "graph-unavailable"}) — building it now (gsd-t graph index)...`);
+    const buildResult = await runCliBuild();
+    if (buildResult && buildResult.ok) {
+      log(`graph-wiring: index build OK — re-probing status.`);
+      statusResult = await runCli("status", null, "status");
+    } else {
+      log(`graph-wiring: index build FAILED [${(buildResult && buildResult.reason) || "build-failed"}] — falling back to grep-mode.`);
+    }
+  }
+  if (!statusResult || !statusResult.ok) {
+    // Graph still unavailable after a build attempt — announce fallback, continue
+    // with intact grep-mode scan. [RULE] parser-fail-disables-loud-never-silent
     graphWiringMode = "fallback-announced";
-    log(`⚠ GRAPH-FALLBACK (ANNOUNCED): graph status probe returned not-ok [reason=${(statusResult && statusResult.reason) || "graph-unavailable"}, via=${(statusResult && statusResult.via) || "?"}] — scan continues in full grep-mode (today's architecture, intact). Structural findings from LLM reconstruction only. Build the index (gsd-t graph build) to enable graph-wired accuracy.`);
+    log(`⚠ GRAPH-FALLBACK (ANNOUNCED): graph unavailable after build attempt [reason=${(statusResult && statusResult.reason) || "graph-unavailable"}, via=${(statusResult && statusResult.via) || "?"}] — scan continues in full grep-mode (today's architecture, intact). Structural findings from LLM reconstruction only.`);
     await persistWiringMode("fallback-announced"); // M99 D2 [RULE] wiring-mode-three-states
   } else {
     // Step 2: query the structural slice (dead-code + dangling + clusters).
@@ -799,10 +843,15 @@ const today = (typeof todayAgent === "string" && /\d{4}-\d{2}-\d{2}/.test(todayA
 
 let archivePath = "";
 if (pre.priorRegisterExists) {
+  // #47: archive the prior register + ALL prior dimension files into
+  // .gsd-t/scan/archive/ with a DATETIME stamp so the user can diff new-vs-prior.
+  // Handles BOTH the new suffixed names and any legacy unsuffixed leftovers.
   const arch = await agent(
     [
-      `Archive the existing tech-debt register in \`${projectDir}\` via Bash, then report the archive path.`,
-      `Rename \`${projectDir}/.gsd-t/techdebt.md\` to \`${projectDir}/.gsd-t/techdebt_${today}.md\`; if that exists, append _2/_3. Use \`git mv\` if a git repo else \`mv\`. Reply with ONLY the resulting archive filename.`,
+      `Archive the existing scan outputs in \`${projectDir}\` into a dated archive folder so the user can diff new-vs-prior, then report the archive dir. Steps (via Bash):`,
+      `1. STAMP="$(date +%Y%m%d-%H%M)". ARCH="${projectDir}/.gsd-t/scan/archive". mkdir -p "$ARCH".`,
+      `2. Move each existing scan output into "$ARCH" with the STAMP appended before .md. For EACH that exists, move it: \`${projectDir}/.gsd-t/techdebt.md\`, \`${projectDir}/.gsd-t/techdebt_in_plain_english.md\`, and \`${projectDir}/.gsd-t/scan/<dim>.md\` for each dim in {architecture,security,quality,business-rules,contract-drift}. Target name: same basename + "-$STAMP.md" (e.g. techdebt-20260630-1542.md). Use \`git mv\` if a git repo else \`mv\`. Skip any that don't exist (no error).`,
+      `3. Reply with ONLY the archive dir path "$ARCH".`,
     ].join("\n"),
     { label: "synthesis:archive", phase: "Synthesis", model: "haiku" }
   ).catch(() => null);
@@ -815,7 +864,7 @@ const { chunks, lastTd } = fmtChunks(today);
 // each subsequent chunk is APPENDED. Done SEQUENTIALLY so the file builds in order and
 // each agent's prompt+output stays small enough to pass intact. The register path is
 // passed to each chunk; only the chunk content varies.
-const regPath = `${projectDir}/.gsd-t/techdebt.md`;
+const regPath = `${projectDir}/.gsd-t/techdebt.md`; // internal fixed name (shared copy suffixed in share/)
 let chunkOk = 0;
 for (let ci = 0; ci < chunks.length; ci++) {
   const isFirst = ci === 0;
@@ -933,7 +982,7 @@ log(`document phase: ${docsOk.length}/${docTargets.length} written/merged${docsF
 // out bounded generator agents (each writes its batch's entries via the shared gate),
 // then ASSEMBLE deterministically with severity section headers, and chunk-write.
 phase("Plain-English");
-const peTarget = `${projectDir}/.gsd-t/techdebt_in_plain_english.md`;
+const peTarget = `${projectDir}/.gsd-t/techdebt_in_plain_english.md`; // internal fixed name (shared copy suffixed in share/)
 const sevLabel = { CRITICAL: "fix before launch", HIGH: "fix soon", MEDIUM: "schedule", LOW: "clean up eventually" };
 // Attach the deterministic TD number (matches the register: severity-sorted, tdStart+).
 const peItems = finalFindings.map((f, i) => ({
@@ -1023,11 +1072,27 @@ const peComplete = peActual === peExpectedEntries;
 if (!peComplete) log(`⚠ plain-english INCOMPLETE: wrote ${peActual}/${peExpectedEntries} entries (writer said ${typeof peWriteRes === "string" ? peWriteRes.trim().slice(0, 20) : JSON.stringify(peWriteRes).slice(0, 40)})`);
 log(`plain-english: ${peExpectedEntries}/${peItems.length} entries, grouped by severity, ${peChunks.length} chunks, on-disk count ${peActual ?? "?"} (${peComplete ? "COMPLETE" : "INCOMPLETE"})${peFailed ? `; ${peFailed} gen batch(es) failed` : ""}`);
 
-// Commit the docs + dimension files + plain-english via a small agent (Bash git).
+// #47: EXPORT-COPY the living docs into a share/ folder with the repo-name suffix —
+// the LAST scan step. Originals stay at their fixed docs/ names (GSD-T reads them by
+// hardcoded path under the No-Re-Research rule); the share/ copies are the team-shareable,
+// project-labeled set. Regenerated each scan (overwrite). The scan reports themselves are
+// already suffixed in place (techdebt-<repo>.md, scan/<dim>-<repo>.md).
+const shareAgent = await agent(
+  [
+    `Create a shareable, repo-labeled copy of this project's living docs in \`${projectDir}\` via Bash. Steps:`,
+    `1. \`mkdir -p ${projectDir}/share\`.`,
+    `2. COPY (do NOT move — keep the original at its fixed name) each of these that EXISTS into \`${projectDir}/share/\` with the repo name "${repoName}" suffixed before .md. Living docs: \`docs/architecture.md\`→\`share/architecture-${repoName}.md\`, \`docs/requirements.md\`→\`share/requirements-${repoName}.md\`, \`docs/workflows.md\`→\`share/workflows-${repoName}.md\`, \`docs/infrastructure.md\`→\`share/infrastructure-${repoName}.md\`, \`README.md\`→\`share/README-${repoName}.md\`. Scan reports: \`.gsd-t/techdebt.md\`→\`share/techdebt-${repoName}.md\`, \`.gsd-t/techdebt_in_plain_english.md\`→\`share/techdebt_in_plain_english-${repoName}.md\`, and each \`.gsd-t/scan/<dim>.md\`→\`share/<dim>-${repoName}.md\` for dim in {architecture,security,quality,business-rules,contract-drift} (NOTE these scan dimension files share basenames with the living-doc architecture — keep them distinct: prefer \`share/scan-<dim>-${repoName}.md\` for the .gsd-t/scan/ ones to avoid colliding with docs/architecture). Overwrite existing share/ files (always fresh). Skip any source that doesn't exist (no error).`,
+    `3. Reply with ONLY the count of files copied.`,
+  ].join("\n"),
+  { label: "share-export", phase: "Document", model: "haiku" }
+).catch(() => null);
+log(`share/ export: ${typeof shareAgent === "string" ? shareAgent.trim().slice(0, 40) : "done"} → ${projectDir}/share/`);
+
+// Commit the docs + dimension files + plain-english + share/ via a small agent (Bash git).
 const commitAgent = await agent(
   [
     `Commit the GSD-T scan's generated documents in \`${projectDir}\` via Bash git, IF it is a git repo (else report skipped).`,
-    `Stage: \`.gsd-t/scan\`, \`.gsd-t/techdebt_in_plain_english.md\`, \`docs\`, \`README.md\` (do NOT stage \`.gsd-t/scan/.doc-backup\` if present). Commit message: "scan: deep document cross-population (${docsOk.length} docs) + dimension files". Do NOT push. Return JSON per the schema (status "rendered" if committed, "skipped" if not a git repo / nothing to commit, "failed" on error; outputPath optional).`,
+    `Stage: \`.gsd-t/scan\`, \`.gsd-t/techdebt.md\`, \`.gsd-t/techdebt_in_plain_english.md\`, \`share\`, \`docs\`, \`README.md\` (do NOT stage \`.gsd-t/scan/.doc-backup\` if present; \`.gsd-t/scan/archive\` MAY be staged — the dated history is worth keeping). Commit message: "scan: deep document cross-population (${docsOk.length} docs) + dimension files + share/ export". Do NOT push. Return JSON per the schema (status "rendered" if committed, "skipped" if not a git repo / nothing to commit, "failed" on error; outputPath optional).`,
   ].join("\n"),
   { label: "commit-docs", phase: "Document", schema: RENDER_SCHEMA, model: "haiku" }
 ).catch((e) => ({ status: "failed", notes: String(e && e.message) }));