@tekyzinc/gsd-t 5.20.14 → 5.20.15

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [5.20.15] - 2026-09-21
+
+### Changed — phases must be contiguous; the Team Mix title row is the phase name only
+
+David's review of the 19 Hilo estimates: one had items in MVP and Phase 2 with nothing in
+Phase 1, and every Team Mix title row carried the estimate name.
+
+- Rule (spec §2.6): phases are contiguous — `MVP`, `Phase 1`, `Phase 2`, … with no empty phase
+  between used ones. The audit fails a gap. New `phases` verb renumbers the item Phase cells to
+  close the gap and rebuilds the Team Mix grids.
+- Rule (spec §2.1): each grid's title row is EXACTLY the phase name. The writer, `teammix` and
+  the audit follow it; the plan's `title` is no longer used. New `titles` verb sets existing
+  grids' title rows (the nearest non-empty row above the header — older grids keep a blank row
+  between title and header).
+- Applied: Acron Academy renumbered (Phase 2→1, Phase 3→2, 20 cells) and its grids rebuilt;
+  all 19 estimates' Team Mix titles renamed.
+- Rule (spec §0 / §1.2): Functionality and Low Level Requirements wrap on every item row, and
+  every cell on every tab is top-aligned. Writer, `format` verb (which now top-aligns all tabs)
+  and audit follow it; applied to all 19 estimates.
+- The 14 single-phase estimates' Team Mixes rebuilt on the Low/High midpoint (`teammix`), so all
+  19 now staff the midpoint; the command's Step 4 states the rule.
+
 ## [5.20.14] - 2026-09-21
 
 ### Added — `gsd-t estimate-sheet teammix` rebuilds any estimate's Team Mix; the reader handles both template layouts

package/README.md

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

package/bin/gsd-t-estimate-sheet.cjs

@@ -25,6 +25,8 @@
  *   write      --sheet <id|url> --plan <plan.json> [--replace]   write T-Shirt + Team Mix + Tech Stack, then audit
  *   teammix    --sheet <id|url> [--fte <json>] [--dry-run] rebuild the Team Mix (one grid per phase) from the sheet's own roster + rollups
  *   format     --sheet <id|url> [--dry-run]              normalise T-Shirt formatting only (section rows, totals band, summary block); values untouched
+ *   phases     --sheet <id|url> [--dry-run]              close phase gaps (MVP, Phase 2 → MVP, Phase 1) on the T-Shirt tab, then rebuild the Team Mix
+ *   titles     --sheet <id|url> [--dry-run]              set each Team Mix grid's title row to exactly its phase name
  *   audit      --sheet <id|url>                          the spec §5 checklist, by read-back
  *   plan-schema                                          print the plan shape
  * Flags: --json (envelope only)  --key <path>  --no-audit (write only; for debugging)
@@ -232,7 +234,7 @@ class SheetsApi {
 
   async grid(tab) {
     const rng = encodeURIComponent(`'${tab}'`);
-    const fields = "sheets(merges,properties,data(rowData(values(formattedValue,userEnteredValue,effectiveValue,userEnteredFormat(backgroundColor,textFormat,horizontalAlignment,numberFormat),dataValidation)),columnMetadata(pixelSize)))";
+    const fields = "sheets(merges,properties,data(rowData(values(formattedValue,userEnteredValue,effectiveValue,userEnteredFormat(backgroundColor,textFormat,horizontalAlignment,verticalAlignment,wrapStrategy,numberFormat),dataValidation)),columnMetadata(pixelSize)))";
     const r = await this.call("GET", `${this.base}?ranges=${rng}&includeGridData=true&fields=${fields}`);
     if (!r.sheets || !r.sheets[0]) throw new Halt(`tab '${tab}' not found`, 64);
     return r.sheets[0];
@@ -412,7 +414,7 @@ function findPhaseSource(grid, fromRow) { return findPhaseSourceIn(grid, fromRow
 // ───────────────────────── plan validation (pure) ─────────────────────────
 
 const PLAN_SCHEMA = {
-  title: "string — Team Mix title, e.g. 'Hilo ATOS — ATP Gap Closure'",
+  title: "optional string — no longer written anywhere (the Team Mix title row is the phase name only)",
   tshirt: {
     mode: "'items' (write whole rows from row 14) | 'sizes' (rows already exist; fill E:L, matched by the id in column C)",
     sections: [{
@@ -437,7 +439,7 @@ function sizeOf(v) { return v == null ? "" : String(v).trim(); }
 function validatePlan(plan) {
   const errors = [];
   if (!plan || typeof plan !== "object") return ["plan is not an object"];
-  if (!plan.title || typeof plan.title !== "string") errors.push("title: required string");
+  if (plan.title != null && typeof plan.title !== "string") errors.push("title: must be a string when given (unused since v5.20.15 — the Team Mix title row is the phase name)");
   const t = plan.tshirt && typeof plan.tshirt === "object" ? plan.tshirt : {};
   if (!["items", "sizes"].includes(t.mode)) errors.push("tshirt.mode: must be 'items' or 'sizes'");
   const sections = Array.isArray(t.sections) ? t.sections : [];
@@ -690,6 +692,13 @@ function tshirtRows(plan, firstRow0) {
 function fmtReq(sheetId, r0, r1, c0, c1, format, fields) {
   return { repeatCell: { range: gridRange(sheetId, r0, r1, c0, c1), cell: { userEnteredFormat: format }, fields } };
 }
+/** Rule (spec §0): every cell on a tab the tool writes is TOP-aligned; Functionality + Low Level Requirements wrap. */
+function topAlignReq(sheetId, rows) {
+  return fmtReq(sheetId, 0, rows, 0, 26, { verticalAlignment: "TOP" }, "userEnteredFormat.verticalAlignment");
+}
+function wrapReq(sheetId, r0, r1, c0, c1) {
+  return fmtReq(sheetId, r0, r1, c0, c1, { wrapStrategy: "WRAP" }, "userEnteredFormat.wrapStrategy");
+}
 function widthReqs(sheetId, widths) {
   return widths.map((w, i) => ({ updateDimensionProperties: { range: { sheetId, dimension: "COLUMNS", startIndex: i, endIndex: i + 1 }, properties: { pixelSize: w }, fields: "pixelSize" } }));
 }
@@ -767,6 +776,8 @@ async function writeTshirt(api, plan, opts) {
       reqs.push(copyPhaseReq(sheetId, phaseSrc, r0)); // carries validation + chip format; value re-put below
     }
   }
+  reqs.push(wrapReq(sheetId, first0, lastItem0, 2, 4)); // Functionality + Low Level Requirements wrap
+  reqs.push(topAlignReq(sheetId, lastWritten1 + 5));    // every cell top-aligned
   reqs.push(...widthReqs(sheetId, TSHIRT_WIDTHS));
   await api.batch(reqs);
   // 5. the Phase VALUES again — copyPaste overwrote them with the source cell's value
@@ -809,7 +820,9 @@ async function writeTshirtSizes(api, grid, sheetId, layout, plan, totals, phaseS
     reqs.push(fmtReq(sheetId, w.r0, w.r0 + 1, 4, 7, FMT_ITEM_SIZE, "userEnteredFormat(horizontalAlignment,textFormat)"));
     reqs.push(fmtReq(sheetId, w.r0, w.r0 + 1, 7, 10, FMT_ITEM_NUM, FMT_FIELDS_ALL));
     reqs.push(fmtReq(sheetId, w.r0, w.r0 + 1, 10, 12, FMT_ITEM_CUR, FMT_FIELDS_ALL));
+    reqs.push(wrapReq(sheetId, w.r0, w.r0 + 1, 2, 4));
   }
+  reqs.push(topAlignReq(sheetId, rowCount(grid) + 2));
   await api.batch(reqs);
   for (const w of writes) await api.putValues(TAB_TSHIRT, `E${w.r0 + 1}`, [[w.phase]]);
   const first1 = layout.firstItemRow + 1;
@@ -872,7 +885,7 @@ function teamMixValues(plan, roster, phase, top) {
   for (let m = 1; m <= n; m++) header.push(`Mon ${m}`);
   header.push("Total Hrs");
   const rows = [];
-  rows.push([phase ? `${plan.title} — ${phase}` : plan.title, ...Array(width - 1).fill("")]);
+  rows.push([phase ? phase : "MVP", ...Array(width - 1).fill("")]); // the title row holds ONLY the phase name (David, 2026-09-21)
   rows.push(header);
   const firstP = top + 3; // 1-based row of the first person
   roster.people.forEach((p, i) => {
@@ -929,7 +942,7 @@ async function writeTeamMix(api, plan, rosters) {
   const grids = [];
   let top = 0;
   for (const r of rosters) {
-    const v = teamMixValues(plan, r.roster, rosters.length > 1 || r.phase ? r.phase : "", top);
+    const v = teamMixValues(plan, r.roster, r.phase, top);
     grids.push({ phase: r.phase, v });
     top = v.bottom + GRID_GAP;
   }
@@ -948,6 +961,7 @@ async function writeTeamMix(api, plan, rosters) {
     maxN = Math.max(maxN, g.v.totalC - g.v.firstMonthC);
   }
   reqs.push(...widthReqs(sheetId, [...TEAM_WIDTHS_FIXED, ...Array(maxN).fill(TEAM_MONTH_WIDTH), TEAM_TOTAL_WIDTH]));
+  reqs.push(topAlignReq(sheetId, lastRow + 5));
   await api.batch(reqs);
   return { grids: grids.map((g) => ({ phase: g.phase, titleR: g.v.titleR, bottom: g.v.bottom, rows: g.v.rows.length })), lastRow };
 }
@@ -969,6 +983,7 @@ async function writeTechStack(api, plan) {
     { mergeCells: { range: gridRange(sheetId, 0, 1, 0, 2), mergeType: "MERGE_ALL" } },
     fmtReq(sheetId, 0, 1, 0, 2, { backgroundColor: hexToColor(COLOR.teamHeaderBg), textFormat: { fontSize: 12, bold: true, foregroundColor: hexToColor(COLOR.white) } }, "userEnteredFormat(backgroundColor,textFormat)"),
     fmtReq(sheetId, 1, rows.length, 0, 2, { textFormat: { fontFamily: "Arial", fontSize: 10 }, wrapStrategy: "WRAP" }, "userEnteredFormat(textFormat,wrapStrategy)"),
+    topAlignReq(sheetId, rows.length + 5),
     ...widthReqs(sheetId, TECH_WIDTHS),
   ]);
   return { rows: rows.length - 1 };
@@ -985,7 +1000,7 @@ function auditTshirt(grid) {
   const { cols } = layout;
   const legendRows = { first1: layout.legendFirst1, last1: layout.legendLast1 };
   const first0 = layout.firstItemRow;
-  const badSizes = [], noDv = [], badFormula = [], sectionsWithSizes = [], badSectionFmt = [];
+  const badSizes = [], noDv = [], badFormula = [], sectionsWithSizes = [], badSectionFmt = [], noWrap = [], notTop = [];
   let lastItem0 = -1, totalRow0 = -1;
   for (let r = first0; r < rowCount(grid); r++) {
     const a = textAt(grid, r, 0);
@@ -1006,14 +1021,22 @@ function auditTshirt(grid) {
     if (!(cell && cell.dataValidation && cell.dataValidation.condition && cell.dataValidation.condition.type === "ONE_OF_LIST")) noDv.push(`${colLetter(cols.phase)}${r + 1}`);
     const f = itemFormulasFor(r + 1, cols, legendRows);
     for (const [c, want] of f.cells) if (formulaAt(grid, r, c) !== want) badFormula.push(`${colLetter(c)}${r + 1}`);
+    for (const c of [2, 3]) { const fm = cellAt(grid, r, c) && cellAt(grid, r, c).userEnteredFormat; if (!fm || fm.wrapStrategy !== "WRAP") noWrap.push(`${colLetter(c)}${r + 1}`); }
+    for (const c of [0, 2, cols.days]) { const fm = cellAt(grid, r, c) && cellAt(grid, r, c).userEnteredFormat; if (!fm || fm.verticalAlignment !== "TOP") notTop.push(`${colLetter(c)}${r + 1}`); }
   }
   check(out, "T-Shirt: at least one item row", lastItem0 >= 0, "no item rows below the header");
+  check(out, "T-Shirt: Functionality + Low Level Requirements wrap on every item row", !noWrap.length, noWrap.slice(0, 8).join(", "));
+  check(out, "T-Shirt: item cells are top-aligned", !notTop.length, notTop.slice(0, 8).join(", "));
   check(out, "T-Shirt: size cells are bare codes (no legend text, no '-')", !badSizes.length, badSizes.slice(0, 10).join(", "));
   check(out, "T-Shirt: every item row has the Phase dropdown", !noDv.length, noDv.slice(0, 10).join(", "));
   check(out, "T-Shirt: Days..HIGH $ are the spec formulas on every item row", !badFormula.length, badFormula.slice(0, 12).join(", "));
   check(out, "T-Shirt: section rows carry no sizes", !sectionsWithSizes.length, `rows ${sectionsWithSizes.join(", ")}`);
   check(out, "T-Shirt: section rows are styled (bg #1C4F8B)", !badSectionFmt.length, badSectionFmt.slice(0, 6).join(", "));
   check(out, "T-Shirt: 'Total (Days)' row exists below the items", totalRow0 > lastItem0 && lastItem0 >= 0, "not found");
+  const usedPhases = new Set();
+  for (let r = first0; r <= lastItem0; r++) { const v = textAt(grid, r, cols.phase).trim(); if (PHASES.includes(v)) usedPhases.add(v); }
+  const gapMap = phaseGapMap([...usedPhases]);
+  check(out, "T-Shirt: phases are contiguous (no empty phase between used ones)", !Object.keys(gapMap).length, `used [${PHASES.filter((p) => usedPhases.has(p)).join(", ")}] — rename ${Object.entries(gapMap).map(([a, b]) => `${a}→${b}`).join(", ")}`);
   let totalDaysCell = NaN;
   const phaseDays = {};
   for (const rr of layout.rollupRows) {
@@ -1163,6 +1186,8 @@ function auditTeamMix(grid, mfList, tshirtTotalDays, phaseDays) {
       }
     }
     check(out, `${label}: body font is Arial (never Calibri)`, !badFont.length, badFont.slice(0, 8).join(", "));
+    const notTopTm = people.filter((p) => { const fm = cellAt(grid, p.r, 0) && cellAt(grid, p.r, 0).userEnteredFormat; return !fm || fm.verticalAlignment !== "TOP"; }).map((p) => `A${p.r + 1}`);
+    check(out, `${label}: cells are top-aligned`, !notTopTm.length, notTopTm.slice(0, 6).join(", "));
     check(out, `${label}: sage on exactly Days, Hrs, Total Hrs of role rows`, !badSage.length && !whiteMissing.length, [...badSage, ...whiteMissing].slice(0, 8).join(", "));
     if (totalR > 0 && totalC > 0) {
       const bandBad = [];
@@ -1179,9 +1204,9 @@ function auditTeamMix(grid, mfList, tshirtTotalDays, phaseDays) {
       // ΣCount × 20 × 0.005 from the exact figure — the tolerance follows the roster size.
       const tol = 0.05 + 0.1 * (Number.isNaN(sumCount) ? 1 : sumCount);
       tolAll += tol;
-      const phase = expectedPhases.find((ph) => title.endsWith(ph));
+      const phase = expectedPhases.find((ph) => title.trim() === ph);
       if (expectedPhases.length) {
-        check(out, `${label}: title names a phase with hours`, !!phase, `title '${title}' ends with none of [${expectedPhases.join(", ")}]`);
+        check(out, `${label}: title row is exactly the phase name`, !!phase, `title '${title}' is not one of [${expectedPhases.join(", ")}]`);
         if (phase) check(out, `${label} (${phase}): Σ Days == midpoint of that phase's Low/High days`, Math.abs(sumDays - phaseDays[phase]) < tol, `Team Mix ${sumDays}, T-Shirt ${phaseDays[phase]} (tolerance ${round2(tol)})`);
       }
       prevBottom = totalR + 1;
@@ -1361,9 +1386,8 @@ async function verbTeamMix(api, opts) {
   const layout = locateTshirt(tshirt);
   const team = await api.grid(TAB_TEAM);
   const fte = opts.fte ? opts.fte : deriveFteFromTeamMix(team);
-  const title = opts.title ? opts.title : textAt(team, 0, 0).replace(/\s+—\s+(MVP|Phase \d)$/, "");
-  if (!title) throw new Halt(`${TAB_TEAM}: A1 has no title to carry over — pass --title`);
-  const plan = { title, teamMix: { fte } };
+  const title = "";
+  const plan = { teamMix: { fte } };
   const rosters = phaseTotalsFromSheet(tshirt, layout).map((ph) => ({ ...ph, roster: buildRoster(plan, ph.staffDays, layout.mf) }));
   if (opts.dryRun) return { title, fte, rosters, table: rostersTable(rosters) };
   const tm = await writeTeamMix(api, plan, rosters);
@@ -1476,11 +1500,83 @@ async function verbFormat(api, opts) {
     fmtReq(sheetId, t1, t1 + 2, cols.total + 1, cols.total + 3, { horizontalAlignment: "RIGHT", numberFormat: { type: "NUMBER", pattern: "0.00" } }, "userEnteredFormat(horizontalAlignment,numberFormat)"),
     fmtReq(sheetId, t1 + 2, t1 + 3, cols.total + 1, cols.total + 3, { horizontalAlignment: "RIGHT", numberFormat: { type: "CURRENCY", pattern: "$#,##0.00" } }, "userEnteredFormat(horizontalAlignment,numberFormat)"),
   ]);
+  // 5. wrap Functionality + Low Level Requirements on item rows; top-align every cell on EVERY tab
+  await api.batch([wrapReq(sheetId, first0, tot0, 2, 4), topAlignReq(sheetId, Math.max(rowCount(grid), t1 + 6))]);
+  const meta = await api.meta();
+  for (const s of meta.sheets) {
+    if (s.properties.title === TAB_TSHIRT) continue;
+    const rows = s.properties.gridProperties && s.properties.gridProperties.rowCount ? Math.min(s.properties.gridProperties.rowCount, 200) : 100;
+    await api.batch([topAlignReq(s.properties.sheetId, rows)]);
+  }
   const result = { plan, totalRow1: t1 };
   if (!opts.noAudit) result.audit = await runAudit(api);
   return result;
 }
 
+/**
+ * Phases must be contiguous: MVP, then Phase 1, Phase 2, … with no empty phase between used
+ * ones (David, 2026-09-21: "MVP then nothing in Phase 1 but items in Phase 2"). Given the set
+ * of phases that carry items, return the rename map that closes the gaps ({} when none).
+ */
+function phaseGapMap(usedPhases) {
+  const numbered = PHASES.filter((p) => p !== "MVP" && usedPhases.includes(p));
+  const map = {};
+  numbered.forEach((p, i) => { const want = `Phase ${i + 1}`; if (p !== want) map[p] = want; });
+  return map;
+}
+
+/** Renumber phases on the T-Shirt tab to close gaps, then rebuild the Team Mix grids to match. */
+async function verbPhases(api, opts) {
+  const grid = await api.grid(TAB_TSHIRT);
+  const layout = locateTshirt(grid);
+  const { cols } = layout;
+  const used = new Set();
+  const cells = [];
+  for (let r = layout.firstItemRow; r < rowCount(grid); r++) {
+    if (/^Total \(Days\)/i.test(textAt(grid, r, 0))) break;
+    const v = textAt(grid, r, cols.phase).trim();
+    if (v === "") continue;
+    if (!PHASES.includes(v)) throw new Halt(`${TAB_TSHIRT}: ${colLetter(cols.phase)}${r + 1} holds '${v}', not one of ${PHASES.join(" | ")}`);
+    used.add(v);
+    cells.push({ r, v });
+  }
+  const map = phaseGapMap([...used]);
+  const plan = { phasesUsed: PHASES.filter((p) => used.has(p)), renames: map, cellsToChange: cells.filter((c) => map[c.v]).length };
+  if (opts.dryRun || !Object.keys(map).length) return { plan, changed: false };
+  for (const c of cells) if (map[c.v]) await api.putValues(TAB_TSHIRT, `${colLetter(cols.phase)}${c.r + 1}`, [[map[c.v]]]);
+  const tm = await verbTeamMix(api, { fte: opts.fte, noAudit: true });
+  const result = { plan, changed: true, teamMix: tm.phases };
+  if (!opts.noAudit) result.audit = await runAudit(api);
+  return result;
+}
+
+/** Set every Team Mix grid's title row to exactly its phase name (rule §2.1). */
+async function verbTitles(api, opts) {
+  const tshirt = await api.grid(TAB_TSHIRT);
+  const layout = locateTshirt(tshirt);
+  const withHours = phaseTotalsFromSheet(tshirt, layout).map((p) => p.phase);
+  const team = await api.grid(TAB_TEAM);
+  const headers = [];
+  for (let r = 0; r < rowCount(team); r++) if (textAt(team, r, 0) === "Skill set") headers.push(r);
+  if (!headers.length) throw new Halt(`${TAB_TEAM}: no grid found`);
+  if (headers.length !== withHours.length) throw new Halt(`${TAB_TEAM}: ${headers.length} grid(s) but ${withHours.length} phase(s) with hours [${withHours.join(", ")}] — run 'teammix' first`);
+  const changes = [];
+  headers.forEach((h, i) => {
+    if (h < 1) throw new Halt(`${TAB_TEAM}: header at row 1 has no title row above it`);
+    // the title is the nearest non-empty row above the header (older grids keep a blank row 2
+    // between title and header — writing into the blank row left the old title in place)
+    const titleR = textAt(team, h - 1, 0).trim() === "" && h >= 2 && textAt(team, h - 2, 0).trim() !== "" ? h - 2 : h - 1;
+    const cur = textAt(team, titleR, 0).trim();
+    const fromTitle = PHASES.find((p) => cur === p || cur.endsWith(` — ${p}`));
+    const want = fromTitle ? fromTitle : withHours[i];
+    if (fromTitle && fromTitle !== withHours[i]) throw new Halt(`${TAB_TEAM}: grid ${i + 1} is titled for ${fromTitle} but the ${i + 1}${["st", "nd", "rd"][i] || "th"} phase with hours is ${withHours[i]} — run 'teammix' first`);
+    if (cur !== want) changes.push({ row1: titleR + 1, from: cur, to: want });
+  });
+  if (opts.dryRun) return { changes, changed: false };
+  for (const c of changes) await api.putValues(TAB_TEAM, `A${c.row1}`, [[c.to]]);
+  return { changes, changed: changes.length > 0 };
+}
+
 async function verbWrite(api, plan, opts) {
   const ts = await writeTshirt(api, plan, opts);
   const rosters = buildRosters(plan, ts.layout);
@@ -1513,7 +1609,7 @@ function printChecks(audit) {
   console.log(`${audit.ok ? "AUDIT PASS" : `AUDIT FAIL (${audit.failed})`} — ${audit.title}`);
 }
 
-const USAGE = "usage: gsd-t estimate-sheet <read|plan-check|write|teammix|format|audit|plan-schema> --sheet <id|url> [--tab <name>] [--plan <plan.json>] [--replace] [--fte '{\"backend\":1.5}'] [--title <t>] [--dry-run] [--no-audit] [--key <path>] [--json]";
+const USAGE = "usage: gsd-t estimate-sheet <read|plan-check|write|teammix|format|phases|titles|audit|plan-schema> --sheet <id|url> [--tab <name>] [--plan <plan.json>] [--replace] [--fte '{\"backend\":1.5}'] [--title <t>] [--dry-run] [--no-audit] [--key <path>] [--json]";
 
 /** Runs a verb; returns the exit code. Throws Halt (or any error) — the runner below turns that into exit 4/64. */
 async function main(args) {
@@ -1542,6 +1638,21 @@ async function main(args) {
     }
     return ok ? 0 : 4;
   }
+  if (verb === "phases") {
+    let fte;
+    if (args.fte) { try { fte = JSON.parse(args.fte); } catch (e) { throw new Halt(`--fte must be JSON: ${e.message}`, 64); } }
+    const r = await verbPhases(api, { dryRun: !!args["dry-run"], noAudit: !!args["no-audit"], fte });
+    const ok = !r.audit || r.audit.ok;
+    if (json) console.log(JSON.stringify({ ok, exitCode: ok ? 0 : 4, ...r }, null, 2));
+    else { console.log(JSON.stringify(r.plan)); console.log(r.changed ? "phases renumbered + Team Mix rebuilt" : (Object.keys(r.plan.renames).length ? "(dry run — nothing written)" : "no gap — nothing to do")); if (r.audit) printChecks(r.audit); }
+    return ok ? 0 : 4;
+  }
+  if (verb === "titles") {
+    const r = await verbTitles(api, { dryRun: !!args["dry-run"] });
+    if (json) console.log(JSON.stringify({ ok: true, exitCode: 0, ...r }, null, 2));
+    else { console.log(r.changes.length ? r.changes.map((c) => `A${c.row1}: '${c.from}' → '${c.to}'`).join("\n") : "titles already correct"); if (args["dry-run"] && r.changes.length) console.log("(dry run — nothing written)"); }
+    return 0;
+  }
   if (verb === "format") {
     const r = await verbFormat(api, { dryRun: !!args["dry-run"], noAudit: !!args["no-audit"] });
     const ok = !r.audit || r.audit.ok;
@@ -1591,7 +1702,7 @@ function haltAndExit(e, json) {
 
 module.exports = {
   validatePlan, splitRoster, rosterViolations, mfCoverageViolations, monthPlan, resampleWeights, rampHours, buildRoster,
-  tshirtTotals, phaseTotals, buildRosters, midDays, deriveFteFromTeamMix, phaseTotalsFromSheet, verbTeamMix, itemFormulasFor, rollupFormulasFor, findCell, itemFormulas, rollupFormulas, tshirtRows, teamMixValues, teamMixFormatReqs, remainderFormula, locateTshirt, findPhaseSource,
+  tshirtTotals, phaseTotals, buildRosters, midDays, deriveFteFromTeamMix, phaseTotalsFromSheet, verbTeamMix, phaseGapMap, verbPhases, verbTitles, itemFormulasFor, rollupFormulasFor, findCell, itemFormulas, rollupFormulas, tshirtRows, teamMixValues, teamMixFormatReqs, remainderFormula, locateTshirt, findPhaseSource,
   auditTshirt, auditTeamMix, auditTechStack, auditOverview, colLetter, hexToColor, colorToHex, sheetIdFromArg,
   constants: { SIZE_CODES, PHASES, COLOR, RAMP, ROLE_LABEL, SOFT_CEILING, FOLD_THRESHOLD, TAB_TSHIRT, TAB_TEAM, TAB_TECH, PLAN_SCHEMA },
   Halt, SheetsApi, getToken, runAudit, main,

package/commands/gsd-t-estimate.md

@@ -87,6 +87,7 @@ Reorder items into domains. Insert a **section-heading row** before each group p
 
 Your judgment is ONE thing: the FTE per discipline (`teamMix.fte` in the plan — `backend` `frontend` `qa` `pm` `ba`, optionally `techlead` `devops`; per-phase override via `teamMix.phases.<phase>.fte`). Everything else on the tab is computed by the tool per spec §2: the split into people (saturate at 1.00, then spill), months, the column count, the ramp by discipline, the remainder formula — and **one grid per phase with hours** (MVP, Phase 1, …), stacked on the one tab with 2 blank rows between.
 
+0. **The Team Mix staffs the MIDPOINT of the Low and High estimates** — per phase, `(Low Hrs + High Hrs) ÷ 2 ÷ 8` days from that phase's rollups — never the Low figure. The tool computes it; you do not choose it.
 1. **Staff every weighted MF factor** — QA → `qa`, PM → `pm`, Analysis → `ba`. Deployment / standups / buffer are absorbed by the engineers and lead. Typical fractions: PM 0.20–0.25 · BA 0.10 · Tech Lead 0.25 · QA 0.40–0.50. The tool HALTS on a roster that leaves a factor unstaffed — do not argue with it; add the person.
 2. **Run `gsd-t estimate-sheet plan-check --sheet <url> --plan <plan.json>`.** It prints the MF list it read, the T-Shirt total, and the roster table it WOULD write (person · Count · Mths · Days · Hrs · Mon 1..N with the remainder) — or halts with the violation.
 3. **PAUSE:** present that table verbatim. Wait for `continue` or corrections (a resize or a different FTE → edit the plan, re-run plan-check, present again).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "5.20.14",
+  "version": "5.20.15",
   "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-sheet-spec.md

@@ -27,6 +27,8 @@ Reference implementation (read it, don't guess): "ATP SOW Gap Analysis and Estim
 | **Map sheet rows to items BY NAME, not by counting.** | Section header rows shift positional alignment and put a whole column on the wrong tasks. |
 | **Recompute the total from raw sizes independently** (`Σ(FE,BE days) × (1 + MF)`) before reporting a number. | A total was reported from a cell just repaired; the true figure differed by 13 days. |
 | **`IMPORTRANGE` `#REF!` on the index sheet needs a human "Allow access" click.** Report it; do not "fix" it. | The service account cannot grant it. |
+| **Every cell on every tab the tool writes is TOP-aligned.** | David, 2026-09-21. |
+| **Functionality and Low Level Requirements wrap** (T-Shirt columns C and D, every item row); Technology Stack descriptions wrap. | Long requirement text was running off the cell. |
 | Access token expires in 1 h — mint fresh per run; regenerate on a sudden 401. | |
 
 ---
@@ -65,8 +67,8 @@ Column widths: `[150, 120, 300, 430, 122, 90, 90, 61, 53, 76, 81, 81]`.
 |---|---|---|
 | `A` | Module | |
 | `B` | User type | |
-| `C` | Functionality — **include the item id** `(GA-n)` / `(TD-n)` / `(FR-n)` | |
-| `D` | Low-level requirement (one or two sentences) | |
+| `C` | Functionality — **include the item id** `(GA-n)` / `(TD-n)` / `(FR-n)` | **wrap** |
+| `D` | Low-level requirement (one or two sentences) | **wrap** |
 | `E` | Phase — `MVP` / `Phase 1` / `Phase 2` / `Phase 3` | **Carries a `ONE_OF_LIST` validation + chip format. Populate by `copyPaste` (`PASTE_NORMAL`) from an existing MVP cell — a values-write drops the dropdown.** |
 | `F` | Web Portal (frontend) size | **Bare code only: `XS` `S` `M` `L` `XL` `XXL`. Never the legend text `"XS - Extra Small"`.** Blank = 0. |
 | `G` | Backend/API size | same |
@@ -97,7 +99,7 @@ Total (Days) | … | H =SUM(H14:H<last>) | I =SUM(I…) | J =SUM(J…) | K =SUM(
 ### 2.1 Layout of ONE grid
 
 ```
-Row t   Title  "<estimate title> — <phase>"  (merged A:<Total Hrs col>)
+Row t   Title  — EXACTLY the phase name: "MVP" / "Phase 1" / …  (merged A:<Total Hrs col>; nothing else in it)
 Row t+1 Header (the ONLY header row in the grid)
 Row t+2.. one row PER PERSON
 Row T   Total        (T = t + 2 + nroles)
@@ -138,6 +140,10 @@ The old `Month / Days / Tot Days / Hrs` layout is retired: `Days` IS the per-per
 
 ### 2.6 One grid per phase
 
+**Phases are contiguous.** Items use `MVP`, then `Phase 1`, `Phase 2`, `Phase 3` with no empty phase between used ones — `MVP` + `Phase 2` with nothing in `Phase 1` is a defect; renumber (`Phase 2` → `Phase 1`, `Phase 3` → `Phase 2`) so the numbering has no gap (`gsd-t estimate-sheet phases` does this and rebuilds the grids). The audit fails a gap.
+
+**The title row of each grid is the phase name and nothing else** — `MVP`, `Phase 1`, … Never the estimate title, never "<title> — Phase 1" (David, 2026-09-21).
+
 Every phase (`MVP` / `Phase 1` / `Phase 2` / `Phase 3`) whose T-Shirt items have hours > 0 gets its own Team Mix grid, in phase order, on the same tab, with 2 blank unformatted rows between grids. Each grid's `Σ Days` reconciles to **the midpoint of that phase's Low and High days** (`(Low Hrs + High Hrs) ÷ 2 ÷ 8` from the phase rollups), and the grids together reconcile to the midpoint of `Total Days` and `Total Days × high factor`. Months and column count are computed per grid. The team mix is the same for every phase unless the plan gives `teamMix.phases.<phase>.fte`.
 
 ### 2.3 Roster shape — one row per PERSON
@@ -212,13 +218,15 @@ Every item is a read-back check against the live sheet. Any ✗ blocks delivery.
 T-SHIRT
   [ ] every size cell in F:G is one of XS S M L XL XXL or blank (no legend text)
   [ ] every item row's E cell has ONE_OF_LIST validation
+  [ ] C and D wrap on every item row; every cell top-aligned
   [ ] every item row's H:L are the §1.2 formulas (no values)
   [ ] section heading rows are merged A:L, bg #1C4F8B, and hold no sizes
   [ ] totals row + phase rollups (K4:N7) + summary block reference <last item row>
   [ ] totals row directly under the last item, grey band #D8DDE8 bold across A:L; summary block directly under it, labels bold, Total Cost in dollars
   [ ] Σ raw sizes × (1+MF) == Total Days cell (recomputed independently)
+  [ ] phases are contiguous — no empty phase between used ones
 TEAM MIX (each grid)
-  [ ] one grid per phase with hours; the title ends with the phase name; exactly 2 empty, unformatted rows between grids
+  [ ] one grid per phase with hours; the title row is EXACTLY the phase name; exactly 2 empty, unformatted rows between grids
   [ ] the header is the row under the title; the row under the header is a person
   [ ] header months read Mon 1..Mon N with N == month column count; last header is Total Hrs
   [ ] no Count > 1.00; per discipline, all rows but the last are 1.00
@@ -251,7 +259,9 @@ gsd-t estimate-sheet audit      --sheet <id|url>                  # §5 checklis
 gsd-t estimate-sheet format     --sheet <id|url> [--dry-run]      # normalise T-Shirt FORMATTING only: section rows (§1.2), grey totals band directly under
                                 # the last item, standard summary block directly under it (§1.3); no size, phase, text or item formula is touched;
                                 # rows under the totals row that are not the old summary block are never overwritten (rows are inserted above them)
-gsd-t estimate-sheet teammix    --sheet <id|url> [--fte '{"backend":1.5,…}'] [--title <t>] [--dry-run]
+gsd-t estimate-sheet phases     --sheet <id|url> [--dry-run]      # close phase gaps on the T-Shirt tab (Phase 2→1, 3→2 …), then rebuild the Team Mix grids
+gsd-t estimate-sheet titles     --sheet <id|url> [--dry-run]      # set each Team Mix grid's title row to exactly its phase name
+gsd-t estimate-sheet teammix    --sheet <id|url> [--fte '{"backend":1.5,…}'] [--dry-run]
                                 # rebuild the Team Mix (one grid per phase) from the sheet's OWN roster and phase rollups — no plan needed;
                                 # the roster is derived from the existing grid (entered Counts summed per discipline; older peak-utilisation
                                 # rosters split the sheet's total FTE by each role's hours); --fte overrides it; halts on a role it cannot map