@opengsd/gsd-core 1.11.0 → 1.12.0

package/gsd-core/bin/lib/audit.cjs

@@ -21,6 +21,9 @@ const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs")
 const markdown_sectionizer_cjs_1 = require("./markdown-sectionizer.cjs");
 const text_lines_cjs_1 = require("./text-lines.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
+const coreUtils = require("./core-utils.cjs");
+const { normalizeLineEndings } = coreUtils;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
 const planningWorkspace = require("./planning-workspace.cjs");
 const { planningDir, quickDirFrom } = planningWorkspace;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
@@ -31,7 +34,7 @@ const phaseIdMod = require("./phase-id.cjs");
 const { PHASE_NUMBER_TOKEN_SOURCE, scopeToPhase } = phaseIdMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseLocator = require("./phase-locator.cjs");
-const { getArchivedPhaseDirs } = phaseLocator;
+const { getAllArchivedPhaseDirs } = phaseLocator;
 const security_cjs_1 = require("./security.cjs");
 const shell_command_projection_cjs_2 = require("./shell-command-projection.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
@@ -279,9 +282,17 @@ function scanDebugSessions(planDir) {
         catch {
             continue;
         }
-        const content = (0, shell_command_projection_cjs_1.platformReadSync)(safeFilePath);
-        if (content === null)
+        // #3078-CR MEDIUM 2 (security review follow-up): normalize a lone-CR
+        // document at this read boundary, same seam as `src/uat.cts`'s
+        // `readNormalizedDocument` — `platformReadSync` performs no line-ending
+        // normalization itself, and extractFrontmatter/status-derivation below
+        // degrade a lone-CR file's frontmatter to `unknown`, which every scan
+        // in this module treats as "not open" (fail-open, the permissive
+        // direction) rather than a real parse gap.
+        const rawContent = (0, shell_command_projection_cjs_1.platformReadSync)(safeFilePath);
+        if (rawContent === null)
             continue;
+        const content = normalizeLineEndings(rawContent);
         const fm = extractFrontmatter(content, safeFilePath);
         const status = (fm.status || 'unknown').toLowerCase();
         if (status === 'resolved' || status === 'complete')
@@ -393,11 +404,15 @@ function scanQuickTasks(planDir) {
             catch {
                 continue;
             }
-            const content = (0, shell_command_projection_cjs_1.platformReadSync)(safeSum);
-            if (content === null) {
+            // #3078-CR MEDIUM 2: same normalize-at-read-boundary fix as the other
+            // scans in this module — see the comment above `scanDebugSessions`'s
+            // read.
+            const rawContent = (0, shell_command_projection_cjs_1.platformReadSync)(safeSum);
+            if (rawContent === null) {
                 status = 'unreadable';
             }
             else {
+                const content = normalizeLineEndings(rawContent);
                 fm = extractFrontmatter(content, safeSum);
                 status = (fm.status || 'unknown').toLowerCase();
             }
@@ -465,9 +480,17 @@ function scanThreads(planDir) {
         catch {
             continue;
         }
-        const content = (0, shell_command_projection_cjs_1.platformReadSync)(safeFilePath);
-        if (content === null)
+        // #3078-CR MEDIUM 2 (security review follow-up): normalize a lone-CR
+        // document at this read boundary, same seam as `src/uat.cts`'s
+        // `readNormalizedDocument` — `platformReadSync` performs no line-ending
+        // normalization itself, and extractFrontmatter/status-derivation below
+        // degrade a lone-CR file's frontmatter to `unknown`, which every scan
+        // in this module treats as "not open" (fail-open, the permissive
+        // direction) rather than a real parse gap.
+        const rawContent = (0, shell_command_projection_cjs_1.platformReadSync)(safeFilePath);
+        if (rawContent === null)
             continue;
+        const content = normalizeLineEndings(rawContent);
         const fm = extractFrontmatter(content, safeFilePath);
         const status = deriveThreadStatus(fm, content);
         if (!openStatuses.has(status))
@@ -532,9 +555,17 @@ function scanTodos(planDir) {
         catch {
             continue;
         }
-        const content = (0, shell_command_projection_cjs_1.platformReadSync)(safeFilePath);
-        if (content === null)
+        // #3078-CR MEDIUM 2 (security review follow-up): normalize a lone-CR
+        // document at this read boundary, same seam as `src/uat.cts`'s
+        // `readNormalizedDocument` — `platformReadSync` performs no line-ending
+        // normalization itself, and extractFrontmatter/status-derivation below
+        // degrade a lone-CR file's frontmatter to `unknown`, which every scan
+        // in this module treats as "not open" (fail-open, the permissive
+        // direction) rather than a real parse gap.
+        const rawContent = (0, shell_command_projection_cjs_1.platformReadSync)(safeFilePath);
+        if (rawContent === null)
             continue;
+        const content = normalizeLineEndings(rawContent);
         const fm = extractFrontmatter(content, safeFilePath);
         // Todos carry no natural status field — presence in pending/ IS "open" by
         // definition (a resolved todo is moved out, not status-flagged). So the
@@ -596,9 +627,17 @@ function scanSeeds(planDir) {
         catch {
             continue;
         }
-        const content = (0, shell_command_projection_cjs_1.platformReadSync)(safeFilePath);
-        if (content === null)
+        // #3078-CR MEDIUM 2 (security review follow-up): normalize a lone-CR
+        // document at this read boundary, same seam as `src/uat.cts`'s
+        // `readNormalizedDocument` — `platformReadSync` performs no line-ending
+        // normalization itself, and extractFrontmatter/status-derivation below
+        // degrade a lone-CR file's frontmatter to `unknown`, which every scan
+        // in this module treats as "not open" (fail-open, the permissive
+        // direction) rather than a real parse gap.
+        const rawContent = (0, shell_command_projection_cjs_1.platformReadSync)(safeFilePath);
+        if (rawContent === null)
             continue;
+        const content = normalizeLineEndings(rawContent);
         const fm = extractFrontmatter(content, safeFilePath);
         const status = (fm.status || 'dormant').toLowerCase();
         if (!unimplementedStatuses.has(status))
@@ -703,8 +742,11 @@ function listAuditPhaseTargets(planDir, cwd) {
             activeUnreadable = true;
         }
     }
+    // #3804: the audit is cross-workstream by design — the shared
+    // getAllArchivedPhaseDirs helper (root + every workstream, distinct
+    // '<ws>/<version>' labels) owns that walk.
     try {
-        for (const archived of getArchivedPhaseDirs(cwd)) {
+        for (const archived of getAllArchivedPhaseDirs(cwd)) {
             targets.push({ dir: archived.name, fullPath: archived.fullPath, milestone: archived.milestone });
         }
     }
@@ -748,9 +790,17 @@ function scanUatGaps(planDir, cwd) {
             catch {
                 continue;
             }
-            const content = (0, shell_command_projection_cjs_1.platformReadSync)(safeFilePath);
-            if (content === null)
+            // #3078-CR MEDIUM 2 (security review follow-up): normalize a lone-CR
+            // document at this read boundary, same seam as `src/uat.cts`'s
+            // `readNormalizedDocument` — `platformReadSync` performs no line-ending
+            // normalization itself, and extractFrontmatter/status-derivation below
+            // degrade a lone-CR file's frontmatter to `unknown`, which every scan
+            // in this module treats as "not open" (fail-open, the permissive
+            // direction) rather than a real parse gap.
+            const rawContent = (0, shell_command_projection_cjs_1.platformReadSync)(safeFilePath);
+            if (rawContent === null)
                 continue;
+            const content = normalizeLineEndings(rawContent);
             const fm = extractFrontmatter(content, safeFilePath);
             const status = (fm.status || 'unknown').toLowerCase();
             const result = (fm.result || '').toLowerCase();
@@ -813,9 +863,17 @@ function scanVerificationGaps(planDir, cwd) {
             catch {
                 continue;
             }
-            const content = (0, shell_command_projection_cjs_1.platformReadSync)(safeFilePath);
-            if (content === null)
+            // #3078-CR MEDIUM 2 (security review follow-up): normalize a lone-CR
+            // document at this read boundary, same seam as `src/uat.cts`'s
+            // `readNormalizedDocument` — `platformReadSync` performs no line-ending
+            // normalization itself, and extractFrontmatter/status-derivation below
+            // degrade a lone-CR file's frontmatter to `unknown`, which every scan
+            // in this module treats as "not open" (fail-open, the permissive
+            // direction) rather than a real parse gap.
+            const rawContent = (0, shell_command_projection_cjs_1.platformReadSync)(safeFilePath);
+            if (rawContent === null)
                 continue;
+            const content = normalizeLineEndings(rawContent);
             const fm = extractFrontmatter(content, safeFilePath);
             const status = (fm.status || 'unknown').toLowerCase();
             if (status !== 'gaps_found' && status !== 'human_needed')
@@ -867,9 +925,17 @@ function scanContextQuestions(planDir, cwd) {
             catch {
                 continue;
             }
-            const content = (0, shell_command_projection_cjs_1.platformReadSync)(safeFilePath);
-            if (content === null)
+            // #3078-CR MEDIUM 2 (security review follow-up): normalize a lone-CR
+            // document at this read boundary, same seam as `src/uat.cts`'s
+            // `readNormalizedDocument` — `platformReadSync` performs no line-ending
+            // normalization itself, and extractFrontmatter/status-derivation below
+            // degrade a lone-CR file's frontmatter to `unknown`, which every scan
+            // in this module treats as "not open" (fail-open, the permissive
+            // direction) rather than a real parse gap.
+            const rawContent = (0, shell_command_projection_cjs_1.platformReadSync)(safeFilePath);
+            if (rawContent === null)
                 continue;
+            const content = normalizeLineEndings(rawContent);
             const fm = extractFrontmatter(content, safeFilePath);
             const questions = deriveOpenQuestions(content, fm);
             if (questions.length === 0)
@@ -947,9 +1013,15 @@ function scanDeferredItems(planDir, cwd) {
         catch {
             continue;
         }
-        const content = (0, shell_command_projection_cjs_1.platformReadSync)(safeFilePath);
-        if (content === null)
+        // #3078-CR MEDIUM 2: normalize at this read boundary too —
+        // `parseDeferredItemsWithStatus` performs no normalization of its own
+        // (unlike `src/uat.cts`'s callers, which route through
+        // `readNormalizedDocument`), so a lone-CR `deferred-items.md` was read as
+        // one unbroken line and every entry in it silently vanished.
+        const rawContent = (0, shell_command_projection_cjs_1.platformReadSync)(safeFilePath);
+        if (rawContent === null)
             continue;
+        const content = normalizeLineEndings(rawContent);
         for (const item of uat.parseDeferredItemsWithStatus(content)) {
             const rawStatus = (item.status || '').toLowerCase();
             if (rawStatus === 'resolved')
@@ -1051,8 +1123,18 @@ function auditOpenArtifacts(cwd) {
             return { items: [{ scan_error: true, phase: '', file: '', text: '' }], acknowledged: 0 };
         }
     })();
-    // Count real items (not scan_error sentinels)
-    const countReal = (arr) => arr.filter(i => !i.scan_error && !i._remainder_count).length;
+    // Count real items (not scan_error sentinels). #3817: a `_remainder_count`
+    // marker is not a phantom — it RECORDS real items the detail list truncated
+    // away for display, so its value counts toward the total. Truncation limits
+    // display, never counting; only scan_error (a read failure, not an item)
+    // contributes zero.
+    const countReal = (arr) => arr.reduce((sum, i) => {
+        if (i.scan_error)
+            return sum;
+        if (typeof i._remainder_count === 'number')
+            return sum + i._remainder_count;
+        return sum + 1;
+    }, 0);
     const counts = {
         debug_sessions: countReal(debugSessions.items),
         quick_tasks: countReal(quickTasks.items),
@@ -1110,10 +1192,7 @@ function auditOpenArtifacts(cwd) {
 function formatAuditReport(auditResult) {
     const { counts, items, has_open_items, acknowledged } = auditResult;
     const lines = [];
-    const hr = '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━';
-    lines.push(hr);
-    lines.push('  Milestone Close: Open Artifact Audit');
-    lines.push(hr);
+    lines.push('### Milestone Close: Open Artifact Audit');
     // WARNING 3 (#3458 follow-up review): the acknowledged tally previously
     // existed only in `--json` output — the human report could not tell
     // "clean because fixed" apart from "clean because silenced", which is the
@@ -1121,13 +1200,13 @@ function formatAuditReport(auditResult) {
     if (!has_open_items) {
         lines.push('');
         if (acknowledged.total > 0) {
-            lines.push(`  All artifact types clear (${acknowledged.total} previously acknowledged item${acknowledged.total !== 1 ? 's' : ''} still suppressed).`);
+            lines.push(`All artifact types clear (${acknowledged.total} previously acknowledged item${acknowledged.total !== 1 ? 's' : ''} still suppressed).`);
         }
         else {
-            lines.push('  All artifact types clear. Safe to proceed.');
+            lines.push('All artifact types clear. Safe to proceed.');
         }
         lines.push('');
-        lines.push(hr);
+        lines.push('---');
         return lines.join('\n');
     }
     // WARNING 3: per-category "N previously acknowledged" suffix, so the
@@ -1228,12 +1307,12 @@ function formatAuditReport(auditResult) {
         }
     }
     lines.push('');
-    lines.push(hr);
-    lines.push(`  ${counts.total} item${counts.total !== 1 ? 's' : ''} require decisions before close.`);
+    lines.push('---');
+    lines.push('');
+    lines.push(`**${counts.total} item${counts.total !== 1 ? 's' : ''} require decisions before close.**`);
     if (acknowledged.total > 0) {
-        lines.push(`  ${acknowledged.total} previously acknowledged item${acknowledged.total !== 1 ? 's' : ''} also suppressed above the ${counts.total} open item${counts.total !== 1 ? 's' : ''}.`);
+        lines.push(`${acknowledged.total} previously acknowledged item${acknowledged.total !== 1 ? 's' : ''} also suppressed above the ${counts.total} open item${counts.total !== 1 ? 's' : ''}.`);
     }
-    lines.push(hr);
     return lines.join('\n');
 }
 // ─── resolvePhaseTargetDir ─────────────────────────────────────────────────────
@@ -1294,18 +1373,42 @@ function resolvePhaseTargetDir(planDir, cwd, phase, archivedMilestone) {
  * any read or write is attempted.
  */
 function cmdAuditAcknowledge(cwd, args, raw) {
-    const { category, milestone, at: atFlag, phase, file, 'archived-milestone': archivedMilestone, slug, 'seed-id': seedId, dir: quickDir, filename, text, } = (0, command_arg_projection_cjs_1.parseNamedArgs)(args, [
-        'category', 'milestone', 'at',
-        'phase', 'file', 'archived-milestone',
-        'slug', 'seed-id', 'dir', 'filename', 'text',
-    ]);
+    // args already has the family + subcommand tokens stripped by the caller
+    // (audit-command-router.cts:147 passes `hubArgs.slice(2)`), so validation
+    // begins at index 0 — there is no positional this handler owns itself.
+    const { category, milestone, at: atFlag, phase, file, 'archived-milestone': archivedMilestone, slug, 'seed-id': seedId, dir: quickDir, filename, text, } = (0, command_arg_projection_cjs_1.parseNamedArgsOrExit)(args, {
+        valueFlags: [
+            'category', 'milestone', 'at',
+            'phase', 'file', 'archived-milestone',
+            'slug', 'seed-id', 'dir', 'filename', 'text',
+        ],
+        positionals: 0,
+    }, ioError);
     if (!category)
         ioError('--category is required');
     if (!milestone)
         ioError('--milestone is required');
+    // All declared flags above are value flags, so each resolves to `string |
+    // null` at runtime; the cast narrows away the `boolean` arm of
+    // ParsedNamedArgs's value type that this call site never produces.
     const at = atFlag || new Date().toISOString().slice(0, 10);
     const planDir = planningDir(cwd);
     const markerBase = { milestone: milestone, at };
+    // #3078-CR MEDIUM 2: every `fs.readFileSync` in this function (below, and
+    // in the flat-category branch further down) is DELIBERATELY left raw,
+    // unlike `auditOpenArtifacts`'s scan reads (which now route through
+    // `normalizeLineEndings`). This function splices frontmatter into the
+    // EXISTING content and writes the result back via `platformWriteSync` /
+    // `uat.acknowledgeDeferredItem` — both `spliceFrontmatter` and
+    // `acknowledgeDeferredItem` locate and rewrite a specific byte span
+    // (frontmatter block / matched deferred-item text) in the file exactly as
+    // it exists on disk. Normalizing first would rewrite the file's line
+    // endings as a side effect of an unrelated acknowledge operation, and a
+    // splice computed against normalized text can land at the wrong offset
+    // when written back over the RAW (un-normalized) original. The snapshot
+    // VALUE computed below IS normalized (on a separate in-memory copy, never
+    // the spliced one) so it agrees with the scanner's frame — see the comment
+    // at `normalizedContent` further down.
     // ── The four phase-scoped categories: --phase --file [--archived-milestone] ──
     const PHASE_SCOPED = new Set(['uat_gaps', 'verification_gaps', 'context_questions', 'deferred_items']);
     if (PHASE_SCOPED.has(category)) {
@@ -1335,7 +1438,10 @@ function cmdAuditAcknowledge(cwd, args, raw) {
             if (result.status === 'already_resolved')
                 ioError(`deferred item is already "status: resolved" — acknowledging a resolved item is a no-op`);
             if (result.status === 'unsupported_heading_shape') {
-                ioError('this deferred-items.md uses the heading-delimited (#3457) entry shape, which the CLI writer does not yet support — edit the file directly');
+                // #3781: heading-shaped entries are supported; the remaining refusal
+                // cause is a GFM table row embedded in the entry's span (non-contiguous
+                // — a write cannot be anchored safely).
+                ioError('this deferred item\'s span embeds a GFM table row, so the CLI writer cannot anchor a safe write to it — edit the file directly');
             }
             if (result.status === 'match_verification_failed') {
                 ioError(`internal error: matched span for --text "${text}" did not re-verify before write — refused rather than risk writing the wrong entry`);
@@ -1346,6 +1452,15 @@ function cmdAuditAcknowledge(cwd, args, raw) {
         }
         const content = node_fs_1.default.readFileSync(safeFilePath, 'utf-8');
         const fm = extractFrontmatter(content, safeFilePath);
+        // Mixed-frame fix (security review, 4th instance on this branch): the
+        // splice above and below stays keyed to RAW `content` (raw byte offsets
+        // must not shift), but `scanUatGaps`/`scanContextQuestions` now derive
+        // their comparison values from `normalizeLineEndings`d content. Deriving
+        // the snapshot here from raw `content` would make a lone-CR file's
+        // stored value permanently disagree with what the scanner recomputes —
+        // `audit acknowledge` would be a silent no-op for lone-CR artifacts. Feed
+        // the derive functions a normalized COPY; never splice from it.
+        const normalizedContent = normalizeLineEndings(content);
         let snapshotKey;
         let currentValue;
         if (category === 'uat_gaps') {
@@ -1353,7 +1468,7 @@ function cmdAuditAcknowledge(cwd, args, raw) {
             // pending scenarios added under the same status — snapshot the
             // composite `deriveUatGapSnapshotValue` instead (see its doc comment).
             snapshotKey = 'gap_snapshot';
-            currentValue = deriveUatGapSnapshotValue((fm.status || 'unknown').toLowerCase(), content);
+            currentValue = deriveUatGapSnapshotValue((fm.status || 'unknown').toLowerCase(), normalizedContent);
         }
         else if (category === 'verification_gaps') {
             snapshotKey = 'status';
@@ -1364,7 +1479,7 @@ function cmdAuditAcknowledge(cwd, args, raw) {
             // question set, not just its count (see `deriveOpenQuestionsDigest`'s
             // doc comment).
             snapshotKey = 'questions_digest';
-            currentValue = deriveOpenQuestionsDigest(deriveOpenQuestions(content, fm));
+            currentValue = deriveOpenQuestionsDigest(deriveOpenQuestions(normalizedContent, fm));
         }
         fm.audit_acknowledged = { ...markerBase, [snapshotKey]: currentValue };
         const newContent = spliceFrontmatter(content, fm);
@@ -1465,6 +1580,13 @@ module.exports = {
     formatAuditReport,
     listAuditPhaseTargets,
     cmdAuditAcknowledge,
+    // #3805: exported so uat.cts's cmdAuditUat routes the SAME artifacts'
+    // suppression through the ONE predicate instead of hand-rolling a tenth
+    // copy outside this file's visibility (the exact defect class the
+    // predicate's own header warns about). The snapshot derivations ride
+    // along so the snapshotKeys cannot drift between the two consumers.
+    isAuditItemAcknowledged,
+    deriveUatGapSnapshotValue,
     // #2142: exported so src/milestone.cts's archiveQuickTaskDirectories README
     // index generator shares this ONE discovery rule rather than re-deriving it.
     resolveQuickTaskSummaryFile,