fix(#2788): recover Gaps Found rows; mark-complete no longer false-succeeds on a rejected row (#2902)
* fix(#2788): recover Gaps Found rows; mark-complete no longer false-succeeds on a rejected row
Two coupled defects in the requirement traceability state machine:
Defect 1 (terminal state): requirements revert-phase (the gaps_found response)
left a row at 'Gaps Found' with no inverse — neither mark-complete's /^pending$/i
guard nor the phase-complete reconcile's /^(?:pending|in progress)$/i accepted it,
so a single failed verification stranded every requirement permanently and blocked
the milestone. Widen both guards to accept 'gaps found' so a genuinely-satisfied
stranded row reaches Complete again.
Defect 2 (false success): mark-complete ORed checkboxHit || tableHit for 'updated',
so on a Gaps Found row it flipped the checkbox but could not move the row, yet
reported updated:true. When a traceability table has a row for an ID, gate 'updated'
on the row moving (tableHit) — a checkbox-only flip on a table-bearing file no
longer lies. The #2140 table_unmatched path (no row for the ID) is preserved.
* chore(#2788): backfill changeset PR 2902
---------
Co-authored-by: Test <test@example.com>
(cherry picked from commit 9f567a1627)
This commit is contained in:
5
.changeset/noble-cranes-march.md
Normal file
5
.changeset/noble-cranes-march.md
Normal file
@@ -0,0 +1,5 @@
|
|||||||
|
---
|
||||||
|
type: Fixed
|
||||||
|
pr: 2902
|
||||||
|
---
|
||||||
|
**A requirement row stranded at `Gaps Found` can now be completed again, and `requirements mark-complete` no longer reports false success on a row it could not move** — the completion guards now accept `Gaps Found` (so `revert-phase`'s stranded rows are recoverable instead of permanently blocking the milestone), and when a traceability table has a row for an ID, `mark-complete` counts it as updated only if the row actually moved (not merely because the checkbox flipped). (#2788)
|
||||||
@@ -156,10 +156,15 @@ function cmdRequirementsMarkComplete(cwd: string, reqIdsRaw: string[], raw: bool
|
|||||||
// Surface 1 — the checkbox: - [ ] **REQ-ID** → - [x] **REQ-ID**
|
// Surface 1 — the checkbox: - [ ] **REQ-ID** → - [x] **REQ-ID**
|
||||||
// Use replace() + compare to avoid the test()+replace() global regex
|
// Use replace() + compare to avoid the test()+replace() global regex
|
||||||
// lastIndex bug where test() advances state and replace() misses matches.
|
// lastIndex bug where test() advances state and replace() misses matches.
|
||||||
|
// (#2788 defect 2: the flip is CONDITIONAL — when a traceability row EXISTS
|
||||||
|
// for this ID but its Status write is rejected, the checkbox must NOT flip,
|
||||||
|
// so the two surfaces cannot silently diverge. The row-write outcome below
|
||||||
|
// gates whether the flip is kept.)
|
||||||
const checkboxPattern = new RegExp(`(-\\s*\\[)[ ](\\]\\s*\\*\\*${reqEscaped}\\*\\*)`, 'gi');
|
const checkboxPattern = new RegExp(`(-\\s*\\[)[ ](\\]\\s*\\*\\*${reqEscaped}\\*\\*)`, 'gi');
|
||||||
|
const beforeCheckbox = reqContent;
|
||||||
const afterCheckbox = reqContent.replace(checkboxPattern, '$1x$2');
|
const afterCheckbox = reqContent.replace(checkboxPattern, '$1x$2');
|
||||||
const checkboxHit = afterCheckbox !== reqContent;
|
const checkboxFlipped = afterCheckbox !== beforeCheckbox;
|
||||||
if (checkboxHit) reqContent = afterCheckbox;
|
if (checkboxFlipped) reqContent = afterCheckbox;
|
||||||
|
|
||||||
// Surface 2 — the traceability row: | <REQ-ID> | Phase N | Pending | → ... Complete |
|
// Surface 2 — the traceability row: | <REQ-ID> | Phase N | Pending | → ... Complete |
|
||||||
// via the markdown-table seam (ADR-2143 §7) — supersedes the prior ordinal
|
// via the markdown-table seam (ADR-2143 §7) — supersedes the prior ordinal
|
||||||
@@ -178,7 +183,11 @@ function cmdRequirementsMarkComplete(cwd: string, reqIdsRaw: string[], raw: bool
|
|||||||
// updateTableCell call both probes the current value and writes.
|
// updateTableCell call both probes the current value and writes.
|
||||||
let tableHit = false;
|
let tableHit = false;
|
||||||
const tableUpdate = updateTraceabilityCell(reqContent, rowMatch, 'Status', (current) => {
|
const tableUpdate = updateTraceabilityCell(reqContent, rowMatch, 'Status', (current) => {
|
||||||
if (/^pending$/i.test(current.trim())) {
|
// #2788: accept `Gaps Found` as a forward input too — `revert-phase` (the
|
||||||
|
// documented gaps_found response) leaves a row stranded at Gaps Found with
|
||||||
|
// no inverse; a genuinely-satisfied requirement must be able to reach
|
||||||
|
// Complete again via mark-complete, or the milestone is blocked forever.
|
||||||
|
if (/^(pending|gaps found)$/i.test(current.trim())) {
|
||||||
tableHit = true;
|
tableHit = true;
|
||||||
return ' Complete ';
|
return ' Complete ';
|
||||||
}
|
}
|
||||||
@@ -188,6 +197,18 @@ function cmdRequirementsMarkComplete(cwd: string, reqIdsRaw: string[], raw: bool
|
|||||||
reqContent = tableUpdate.value;
|
reqContent = tableUpdate.value;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
// #2788 defect 2: if a row EXISTS for this ID but its Status write was
|
||||||
|
// rejected (e.g. the row reads `Blocked`, which mark-complete does not
|
||||||
|
// accept), roll the checkbox back so the checkbox and the row cannot
|
||||||
|
// silently diverge. The checkbox and the row are two representations of the
|
||||||
|
// same fact; flipping one while the other rejects the write is the lie.
|
||||||
|
let checkboxHit = checkboxFlipped;
|
||||||
|
const rowExistsProbe = tableUpdate; // ok === a row matched (probes existence)
|
||||||
|
if (checkboxFlipped && rowExistsProbe.ok && !tableHit) {
|
||||||
|
reqContent = beforeCheckbox;
|
||||||
|
checkboxHit = false;
|
||||||
|
}
|
||||||
|
|
||||||
// ADR-2143 §6 per-ID write-set entries: this ID's checkbox surface is
|
// ADR-2143 §6 per-ID write-set entries: this ID's checkbox surface is
|
||||||
// always tracked; the traceability surface is tracked only when the file
|
// always tracked; the traceability surface is tracked only when the file
|
||||||
// has a traceability table at all (same `hasTable` gate the existing
|
// has a traceability table at all (same `hasTable` gate the existing
|
||||||
@@ -215,7 +236,14 @@ function cmdRequirementsMarkComplete(cwd: string, reqIdsRaw: string[], raw: bool
|
|||||||
const doneCheckbox = new RegExp(`-\\s*\\[x\\]\\s*\\*\\*${reqEscaped}\\*\\*`, 'i').test(reqContent);
|
const doneCheckbox = new RegExp(`-\\s*\\[x\\]\\s*\\*\\*${reqEscaped}\\*\\*`, 'i').test(reqContent);
|
||||||
const doneTable = Boolean(hasRow && /^complete$/i.test(currentStatusCell.trim()));
|
const doneTable = Boolean(hasRow && /^complete$/i.test(currentStatusCell.trim()));
|
||||||
|
|
||||||
if (checkboxHit || tableHit) {
|
// #2788 defect 2: when a traceability table exists AND this ID has a row in
|
||||||
|
// it, `updated`/`marked_complete` must reflect the ROW moving, not a
|
||||||
|
// checkbox-only flip. Otherwise (`table_unmatched` — no row for this ID, or
|
||||||
|
// no table at all) the checkbox flip is a legitimate partial reconcile / the
|
||||||
|
// sole completion surface, so the #2140 OR semantics are preserved.
|
||||||
|
const rowExists = hasTable && hasRow;
|
||||||
|
const idUpdated = rowExists ? tableHit : (checkboxHit || tableHit);
|
||||||
|
if (idUpdated) {
|
||||||
updated.push(reqId);
|
updated.push(reqId);
|
||||||
} else if (doneTable || (doneCheckbox && !hasTable)) {
|
} else if (doneTable || (doneCheckbox && !hasTable)) {
|
||||||
// Fully reconciled: the table row is Complete, OR the checkbox is done and
|
// Fully reconciled: the table row is Complete, OR the checkbox is done and
|
||||||
|
|||||||
@@ -2078,7 +2078,9 @@ function cmdPhaseComplete(cwd: string, phaseNum: string, raw: boolean): void {
|
|||||||
// Complete" gate is folded into the newValue callback so one
|
// Complete" gate is folded into the newValue callback so one
|
||||||
// updateTableCell call both probes and writes.
|
// updateTableCell call both probes and writes.
|
||||||
const reqUpdate = updateTraceabilityCell(reqContent, reqRowMatch, 'Status', (current) =>
|
const reqUpdate = updateTraceabilityCell(reqContent, reqRowMatch, 'Status', (current) =>
|
||||||
/^(?:pending|in progress)$/i.test(current.trim()) ? ' Complete ' : current);
|
// #2788: accept `Gaps Found` too so a phase stranded by revert-phase (the
|
||||||
|
// gaps_found response) can complete without hand-editing the table.
|
||||||
|
/^(?:pending|in progress|gaps found)$/i.test(current.trim()) ? ' Complete ' : current);
|
||||||
if (reqUpdate.ok) {
|
if (reqUpdate.ok) {
|
||||||
reqContent = reqUpdate.value;
|
reqContent = reqUpdate.value;
|
||||||
} else if (!isPlaceholderReqId(reqId)) {
|
} else if (!isPlaceholderReqId(reqId)) {
|
||||||
|
|||||||
@@ -971,6 +971,117 @@ describe('requirements mark-complete command', () => {
|
|||||||
assert.strictEqual(output.updated, false);
|
assert.strictEqual(output.updated, false);
|
||||||
assert.strictEqual(output.reason, 'REQUIREMENTS.md not found');
|
assert.strictEqual(output.reason, 'REQUIREMENTS.md not found');
|
||||||
});
|
});
|
||||||
|
|
||||||
|
// #2788: a requirement row stranded at `Gaps Found` (by revert-phase, the
|
||||||
|
// gaps_found response) must be recoverable — mark-complete moves it to Complete.
|
||||||
|
// Pre-fix the `/^pending$/i` guard rejected `Gaps Found`, stranding the row
|
||||||
|
// permanently (no inverse transition existed) AND mark-complete reported
|
||||||
|
// `updated: true` while the row stayed `Gaps Found` (defect 2, the lie).
|
||||||
|
const GAPS_FOUND_REQUIREMENTS = `# Requirements
|
||||||
|
|
||||||
|
## Coverage
|
||||||
|
- [ ] **REQ-01**: feature one
|
||||||
|
- [ ] **REQ-02**: feature two
|
||||||
|
|
||||||
|
## Traceability
|
||||||
|
|
||||||
|
| Requirement | Phase | Status |
|
||||||
|
|-------------|-------|--------|
|
||||||
|
| REQ-01 | Phase 1 | Gaps Found |
|
||||||
|
| REQ-02 | Phase 1 | Complete |
|
||||||
|
`;
|
||||||
|
|
||||||
|
test('#2788 defect 1: a Gaps Found row moves to Complete via mark-complete (no longer terminal)', () => {
|
||||||
|
writeRequirements(tmpDir, GAPS_FOUND_REQUIREMENTS);
|
||||||
|
const result = runGsdTools('requirements mark-complete REQ-01', tmpDir);
|
||||||
|
assert.ok(result.success);
|
||||||
|
const out = JSON.parse(result.output);
|
||||||
|
// The row EXISTS and moved to Complete, so updated/marked_complete are truthful.
|
||||||
|
assert.ok(out.updated, 'the stranded Gaps Found row must be recoverable');
|
||||||
|
assert.ok(out.marked_complete.includes('REQ-01'));
|
||||||
|
const content = readRequirements(tmpDir);
|
||||||
|
assert.ok(/REQ-01 \| Phase 1 \| Complete/.test(content),
|
||||||
|
'the row must read Complete after mark-complete; got:\n' + content);
|
||||||
|
assert.ok(content.includes('- [x] **REQ-01**'), 'the checkbox must be checked');
|
||||||
|
});
|
||||||
|
|
||||||
|
test('#2788 defect 2: when a row EXISTS but the write is rejected, updated is FALSE (no false success)', () => {
|
||||||
|
// A row at `Blocked` (a status mark-complete does not accept) EXISTS for REQ-01.
|
||||||
|
// The checkbox flips, but the row does not move — `updated` must be false so the
|
||||||
|
// operator is not told it worked while the audit row still reads Blocked.
|
||||||
|
const blockedRequirements = `# Requirements
|
||||||
|
|
||||||
|
## Coverage
|
||||||
|
- [ ] **REQ-01**: feature one
|
||||||
|
|
||||||
|
## Traceability
|
||||||
|
|
||||||
|
| Requirement | Phase | Status |
|
||||||
|
|-------------|-------|--------|
|
||||||
|
| REQ-01 | Phase 1 | Blocked |
|
||||||
|
`;
|
||||||
|
writeRequirements(tmpDir, blockedRequirements);
|
||||||
|
const result = runGsdTools('requirements mark-complete REQ-01', tmpDir);
|
||||||
|
assert.ok(result.success);
|
||||||
|
const out = JSON.parse(result.output);
|
||||||
|
assert.strictEqual(out.updated, false,
|
||||||
|
'a checkbox flip on a table-bearing file whose row EXISTS but did not move must NOT report updated:true');
|
||||||
|
assert.ok(!out.marked_complete.includes('REQ-01'),
|
||||||
|
'REQ-01 must not be in marked_complete when the row write was rejected');
|
||||||
|
const content = readRequirements(tmpDir);
|
||||||
|
assert.ok(/REQ-01 \| Phase 1 \| Blocked/.test(content),
|
||||||
|
'the row must still read Blocked (write rejected); got:\n' + content);
|
||||||
|
// #2788 defect 2: the checkbox must NOT flip when the row write is rejected —
|
||||||
|
// the checkbox and the row are two representations of the same fact, so they
|
||||||
|
// must not silently diverge. The checkbox stays unchecked on disk.
|
||||||
|
assert.ok(content.includes('- [ ] **REQ-01**'),
|
||||||
|
'the checkbox must stay unchecked when the row write was rejected; got:\n' + content);
|
||||||
|
// write_set carries the truth: NEITHER surface applied (checkbox rolled back,
|
||||||
|
// traceability rejected).
|
||||||
|
const checkboxEntry = out.write_set.find(
|
||||||
|
(e) => e.requirement === 'REQ-01' && e.surface === 'checkbox');
|
||||||
|
assert.ok(checkboxEntry && checkboxEntry.applied === false,
|
||||||
|
'write_set must record the checkbox surface as not applied (rolled back)');
|
||||||
|
const traceabilityEntry = out.write_set.find(
|
||||||
|
(e) => e.requirement === 'REQ-01' && e.surface === 'traceability');
|
||||||
|
assert.ok(traceabilityEntry && traceabilityEntry.applied === false,
|
||||||
|
'write_set must record the traceability surface as not applied');
|
||||||
|
});
|
||||||
|
|
||||||
|
test('#2788 end-to-end: revert-phase (Complete → Gaps Found) then mark-complete (Gaps Found → Complete) round-trips', () => {
|
||||||
|
const completeRequirements = `# Requirements
|
||||||
|
|
||||||
|
## Coverage
|
||||||
|
- [x] **REQ-01**: feature one
|
||||||
|
|
||||||
|
## Traceability
|
||||||
|
|
||||||
|
| Requirement | Phase | Status |
|
||||||
|
|-------------|-------|--------|
|
||||||
|
| REQ-01 | Phase 1 | Complete |
|
||||||
|
`;
|
||||||
|
writeRequirements(tmpDir, completeRequirements);
|
||||||
|
// revert-phase strands the row at Gaps Found (the gaps_found response).
|
||||||
|
const reverted = JSON.parse(runGsdTools('requirements revert-phase REQ-01', tmpDir).output);
|
||||||
|
assert.ok(reverted.reverted.includes('REQ-01'));
|
||||||
|
let content = readRequirements(tmpDir);
|
||||||
|
assert.ok(/REQ-01 \| Phase 1 \| Gaps Found/.test(content), 'revert should strand at Gaps Found');
|
||||||
|
// Now the requirement is genuinely satisfied again — mark-complete must recover it.
|
||||||
|
const marked = JSON.parse(runGsdTools('requirements mark-complete REQ-01', tmpDir).output);
|
||||||
|
assert.ok(marked.updated, 'the stranded row must be recoverable via mark-complete');
|
||||||
|
content = readRequirements(tmpDir);
|
||||||
|
assert.ok(/REQ-01 \| Phase 1 \| Complete/.test(content),
|
||||||
|
'after mark-complete the row must read Complete again');
|
||||||
|
});
|
||||||
|
|
||||||
|
test('#2788 negative-space: the normal Pending → Complete path is unchanged', () => {
|
||||||
|
writeRequirements(tmpDir, STANDARD_REQUIREMENTS);
|
||||||
|
const out = JSON.parse(runGsdTools('requirements mark-complete TEST-01', tmpDir).output);
|
||||||
|
assert.ok(out.updated);
|
||||||
|
assert.ok(out.marked_complete.includes('TEST-01'));
|
||||||
|
const content = readRequirements(tmpDir);
|
||||||
|
assert.ok(/TEST-01 \| Phase 1 \| Complete/.test(content), 'Pending row still moves to Complete');
|
||||||
|
});
|
||||||
});
|
});
|
||||||
|
|
||||||
// ─────────────────────────────────────────────────────────────────────────────
|
// ─────────────────────────────────────────────────────────────────────────────
|
||||||
|
|||||||
Reference in New Issue
Block a user