From c8f08b61fb554631fce2b41389c4b075c7d6f8fc Mon Sep 17 00:00:00 2001 From: Tom Boucher Date: Fri, 28 Aug 2026 11:40:34 -0400 Subject: [PATCH] fix(#3782): segment verification debt by the archived_milestone stamp in progress step 1.6 (#4001) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * test(#3782): step 1.6 must segment verification debt by the archived stamp * fix(#3782): segment verification debt by the archived_milestone stamp in progress step 1.6 progress.md step 1.6 read the cross-population summary.total_items as current-milestone debt while claiming the whole query respects milestone boundaries. The active tree is milestone-filtered; archived trees are deliberately unfiltered (each result stamped archived_milestone), so a healthy current milestone presented six shipped milestones' still-open items as CURRENT debt on every /gsd-progress run (#3782). Step 1.6 now computes CURRENT_DEBT/ARCHIVED_DEBT via jq selects on the stamp, tracks archived_debt separately (visible with its own labeled header — segmented, never hidden), corrects the scoping claim, and unwraps the CLI's @file: large-payload redirect before jq so counters cannot silently read 0. A structural guard test pins the segmentation. parse_gap_files stays deliberately cross-population. Emitted-Drift-Ack-Growth: progress.md — #3782: +1406 bytes — step 1.6 gains the CURRENT_DEBT/ARCHIVED_DEBT segmentation jq, the @file: unwrap, and the archived-visibility paragraph; parse-gap paragraph reworded to match * chore(#3782): changeset fragment (pr number backfilled after PR creation) * chore(#3782): backfill changeset PR number (4001) --------- Co-authored-by: sim --- .changeset/mellow-pandas-parade.md | 5 ++ gsd-core/workflows/progress.md | 24 +++++-- .../progress-debt-segmentation-guard.test.cjs | 65 +++++++++++++++++++ 3 files changed, 88 insertions(+), 6 deletions(-) create mode 100644 .changeset/mellow-pandas-parade.md create mode 100644 tests/progress-debt-segmentation-guard.test.cjs diff --git a/.changeset/mellow-pandas-parade.md b/.changeset/mellow-pandas-parade.md new file mode 100644 index 000000000..9adceda22 --- /dev/null +++ b/.changeset/mellow-pandas-parade.md @@ -0,0 +1,5 @@ +--- +type: Fixed +pr: 4001 +--- +**`/gsd-progress` no longer presents archived milestones\' verification debt as current-milestone debt** — the Verification Debt warning segments by the audit\'s `archived_milestone` stamp (current vs still-open-in-archived-mileses), keeps the archived segment visible with its own label, and no longer silently reads zero on large audits (`@file:` payload unwrap). (#3782) diff --git a/gsd-core/workflows/progress.md b/gsd-core/workflows/progress.md index e586f2733..85feb9d44 100644 --- a/gsd-core/workflows/progress.md +++ b/gsd-core/workflows/progress.md @@ -246,22 +246,34 @@ Track: **Step 1.6: Cross-phase health check** -Scan ALL phases in the current milestone for outstanding verification debt using the CLI (which respects milestone boundaries via `getMilestonePhaseFilter`): +Scan ALL phases for outstanding verification debt using the CLI. Milestone scoping note (#3782): the audit milestone-filters the ACTIVE phase tree (`getMilestonePhaseFilter`), and deliberately adds ARCHIVED milestone trees unfiltered — each archived result carries an `archived_milestone` stamp. `summary.total_items` spans BOTH populations, so never read it as current-milestone debt. ```bash DEBT=$(gsd_run query audit-uat --raw 2>/dev/null) +# A cross-population audit is exactly the payload that can exceed the CLI's +# ~50KB stdout budget (io.cjs swaps in an `@file:` pointer) — unwrap it +# before jq, the same pattern Step 1's INIT fetch uses, or every counter +# below silently reads 0. +if [[ "$DEBT" == @file:* ]]; then DEBT=$(cat "${DEBT#@file:}"); fi ``` -Parse JSON for `summary.total_items`, `summary.total_files`, and `summary.parse_gap_files`. +Segment the debt by population before counting (#3782): -Track: `outstanding_debt` — `summary.total_items` from the audit. Track `parse_gap_files` — `summary.parse_gap_files` from the audit. +```bash +CURRENT_DEBT=$(printf '%s' "$DEBT" | jq '[.results[] | select(has("archived_milestone") | not)] | map(.items | length) | add // 0' 2>/dev/null || echo 0) +ARCHIVED_DEBT=$(printf '%s' "$DEBT" | jq '[.results[] | select(has("archived_milestone"))] | map(.items | length) | add // 0' 2>/dev/null || echo 0) +``` -`summary.parse_gap_files` counts EVERY file with `parse_gap: true`, archived or not — the same as `outstanding_debt` (`summary.total_items`), which has no archived split either. An outstanding item does not stop mattering because its phase belongs to an already-archived milestone: a deferred human-UAT scenario or a `skipped` live-stack test is exactly what gets archived still-open, so an archived parse gap is exactly as much unread outstanding work as an archived `result: pending` row. +Track: `outstanding_debt` — `CURRENT_DEBT`, the non-archived (current-milestone) count. Track `archived_debt` — `ARCHIVED_DEBT`, the still-open items in already-archived milestones. Track `parse_gap_files` — `summary.parse_gap_files` from the audit. -**If outstanding_debt > 0 OR parse_gap_files > 0:** Add a warning section to the progress report output (in the `report` step), placed between "## What's Next" and the route suggestion: +Archived debt stays VISIBLE — an item archived still-open is still open (the archived set can include an unrun security-boundary test). Render it as its own labeled line; never fold it into the current-milestone total and never filter it away. + +`summary.parse_gap_files` counts EVERY file with `parse_gap: true`, archived or not — deliberately cross-population, unlike `outstanding_debt` (which #3782 scopes to non-archived results). An outstanding item does not stop mattering because its phase belongs to an already-archived milestone: a deferred human-UAT scenario or a `skipped` live-stack test is exactly what gets archived still-open, so an archived parse gap is exactly as much unread outstanding work as an archived `result: pending` row — it surfaces through `parse_gap_files` and the unparsed row below, keeping the whole cross-population picture visible. + +**If outstanding_debt > 0 OR archived_debt > 0 OR parse_gap_files > 0:** Add a warning section to the progress report output (in the `report` step), placed between "## What's Next" and the route suggestion: ```markdown -## Verification Debt ({N} files across prior phases) +## Verification Debt ({N} items across current-milestone phases; {M} items still open in archived milestones) | Phase | File | Issue | |-------|------|-------| diff --git a/tests/progress-debt-segmentation-guard.test.cjs b/tests/progress-debt-segmentation-guard.test.cjs new file mode 100644 index 000000000..c15d3549b --- /dev/null +++ b/tests/progress-debt-segmentation-guard.test.cjs @@ -0,0 +1,65 @@ +'use strict'; + +// ───────────────────────────────────────────────────────────────────────────── +// #3782 — progress.md step 1.6 must SEGMENT verification debt by the +// `archived_milestone` stamp instead of reading the cross-population +// `summary.total_items`. +// +// `query audit-uat` milestone-filters the ACTIVE tree but deliberately adds +// ARCHIVED trees unfiltered (each result stamped `archived_milestone`), while +// `summary.total_items` spans both populations. Reading that summary as +// current-milestone debt made every /gsd-progress run present six shipped +// milestones' worth of still-open items as CURRENT debt (49 reported vs 13 +// real). The fix counts non-archived results only and gives archived debt its +// own labeled line — segmented, never hidden (an item archived still-open is +// still open; the reporter's archived set included an unrun security +// boundary test). +// ───────────────────────────────────────────────────────────────────────────── + +const { test } = require('node:test'); +const assert = require('node:assert/strict'); +const fs = require('node:fs'); +const path = require('node:path'); + +const PROGRESS_MD = path.join(__dirname, '..', 'gsd-core', 'workflows', 'progress.md'); + +// progress.md is shipped workflow text — the bytes ARE what the runtime +// loads, so a structural scan over it tests the deployed contract (same +// shape as tests/config-get-raw-guard.test.cjs, which needs no marker for +// .md reads). +function step16() { + const md = fs.readFileSync(PROGRESS_MD, 'utf-8'); + const start = md.indexOf('**Step 1.6: Cross-phase health check**'); + assert.ok(start > 0, 'progress.md must contain Step 1.6'); + const end = md.indexOf('**Step 1.7:', start); + assert.ok(end > start, 'progress.md must contain Step 1.7 after 1.6'); + return md.slice(start, end); +} + +test('#3782: step 1.6 counts current-milestone debt from non-archived results only', () => { + const step = step16(); + assert.ok( + /select\(has\("archived_milestone"\)\s*\|\s*not\)/.test(step), + '#3782: the debt count must select results WITHOUT the archived_milestone stamp', + ); + assert.ok( + !/Track:\s*`outstanding_debt`\s*—\s*`summary\.total_items`/.test(step), + '#3782: outstanding_debt must not read the cross-population summary.total_items', + ); + assert.ok( + !/which respects milestone boundaries/.test(step), + '#3782: the false whole-query milestone-boundaries claim must be corrected (only the active tree is filtered)', + ); +}); + +test('#3782: archived debt stays visible with its own labeled line', () => { + const step = step16(); + assert.ok( + /archived_debt/.test(step), + '#3782: archived debt must be tracked as its own value', + ); + assert.ok( + /items still open in archived milestones\)/.test(step), + '#3782: the warning header must label the archived segment — segmented, not hidden', + ); +});