Skip to content

bug: verify.schema-drift parses files_modified as an inline array only — block-sequence plans give it an empty file set #4562

Closed as duplicate

Description

@Vince-Cercury

Summary

verify.schema-drift extracts its file list from plan frontmatter with a regex that only matches an inline array. Plans written with a YAML block sequence — which is what gsd-planner itself emits — never match, so the gate inspects zero files and returns block: false without checking anything.

The gate is declared blocking: true at execute:wave:post, so this is a silent pass on a gate that is meant to stop a wave.

The code

bin/lib/verify.cjs, in cmdVerifySchemaDrift (~line 1959):

const fmMatch = content.match(/files_modified:\s*\[([^\]]{0,8000})\]/);

The \[ requires an inline array:

files_modified: [a.py, b.py]     # matches

But a block sequence has no [:

files_modified:                  # does NOT match
  - backend/app/models/job.py
  - backend/app/services/queue.py

fmMatch is null, nothing is pushed to allFiles, and checkSchemaDrift([], executionLog) early-returns at schema-detect.cjs:86 on detectSchemaFiles([]).detected === false — before the loop that reads executionLog. So neither of the function's two inputs is consulted.

Reproduction

On a phase whose plans use block-sequence files_modified:

$ gsd-tools query check verify.schema-drift 01 --raw
{
  "block": false,
  "drift_detected": false,
  "blocking": false,
  "schema_files": [],
  "orms": [],
  "unpushed_orms": [],
  "message": "",
  "skipped": false
}

Matching the regex against every plan in the phase directly:

plans whose files_modified the regex MATCHED: 0
plans whose files_modified it MISSED:        12

The empty schema_files / orms are the only tell that the gate did no work — the verdict alone is indistinguishable from a real pass.

Why this is likely to be widespread

gsd-planner emits block-sequence files_modified. Every plan in the affected project was produced by GSD's own planner, so any project on that default format has a permanently green blocking gate. phase-plan-index parses the same field correctly, so the two disagree about what a plan declares.

Suggested fix

Accept both forms where files_modified is read, ideally via one shared parser rather than a second regex. A block-sequence branch:

const block = content.match(/^files_modified:[ \t]*\n((?:[ \t]+-[ \t]*.+\n)+)/m);

Separate note — not part of this bug

After fixing the parse locally and feeding the gate 135 correctly-parsed entries, it still returns schemaFiles: []. SCHEMA_PATTERNS (schema-detect.cjs:17-28) covers five JS/TS ORMs — payload, prisma, drizzle, supabase, typeorm — and no Python ORM at all, so SQLAlchemy/Alembic projects get no coverage either way. That is a feature gap rather than a defect and is not what this issue asks you to fix; flagging it only so the parse fix is not mistaken for full coverage on a Python backend.

Found on @opengsd/gsd-core 1.13.0.

Activity

  1. trek-e commented on Sep 9, 2026

    @trek-e
    Collaborator

    This was generated by AI during triage.

    Diagnosis

    Reproduced: yes — wrote a throwaway plan frontmatter fixture with files_modified as a YAML block sequence (files_modified:\n - a\n - b) and ran the exact regex from cmdVerifySchemaDrift against it: content.match(/files_modified:\s*\[([^\]]{0,8000})\]/) returns null. The reporter's suggested fix regex (/^files_modified:[ \t]*\n((?:[ \t]+-[ \t]*.+\n)+)/m) matched correctly against the same fixture.
    Root cause: inline-array-only regex never matches a YAML block sequence, in src/verify.cts:2195 (cmdVerifySchemaDrift). allFiles stays empty, and checkSchemaDrift([], executionLog) early-returns driftDetected: false at src/schema-detect.cts:128 (if (!detection.detected) return {...}) before executionLog is ever consulted. Confirmed the two parsers disagree: cmdPhasePlanIndex (src/phase.cts:814, via RawPlan.filesModified) reads frontmatter through frontmatter.cts's parseGuardedYamlRegion, which parses through a real vendored js-yaml engine that handles inline arrays and block sequences identically — only the drift gate's hand-rolled regex is inline-only. The canonical schema doc docs/reference/plan-md.md:34-37 (titled "PLAN.md schema reference", stating plans are produced by gsd-planner) documents the real annotated example as a block sequence, confirming this is the format actually produced in practice, matching the reporter's live 0/12 evidence.
    Introduced by: long-standing, not a recent regression — get_timeline on cmdVerifySchemaDrift shows the identical inline-only fmMatch regex present in all 24 recorded versions from 2026-07-30 through current HEAD. No recorded decision (recall_decision) ties this to a deliberate inline-only constraint.
    Blast radius: LOW graph radius (get_impact upstream: only routeVerifyCommand/routeCheckCommand, the CLI dispatch wiring), but functionally significant — this is a silent false-negative gate at execute:wave:post (blocking: true) that never fires for any plan using block-sequence files_modified.
    Coupled (must not miss): src/verify-command-router.cts and src/check-command-router.cts (both route to this function; check-command-router.cts:32 is a re-export alias, not a second regex copy — confirmed no duplicate inline-only regex exists elsewhere). tests/bugs-1656-1657.test.cjs co-changes with this function (6 shared commits/30d) and should be checked for assumptions pinned to the old regex. Any fix should reuse the real-YAML parsing path (frontmatter.cts's parseGuardedYamlRegion) that phase-plan-index already uses, rather than hand-rolling a third regex variant.
    Regression test: add a case to tests/schema-drift.test.cjs with a plan file whose files_modified frontmatter is a YAML block sequence pointing at a SCHEMA_PATTERNS path (e.g. prisma/schema.prisma) with no push-command evidence in the execution/git log. Today this asserts driftDetected: false (wrong); after the fix it must assert driftDetected: true, blocking: true. Add a companion case confirming the existing inline-array form still matches, and a single-element block-sequence boundary case.

  2. trek-e commented on Sep 9, 2026

    @trek-e
    Collaborator

    Agent Brief

    Category: bug
    Summary: The schema-drift gate's files_modified frontmatter parser only recognizes an inline YAML array and silently treats a block-sequence list as empty, so the gate never fires for plans written that way.
    Current behavior: When a plan's files_modified frontmatter field is written as a YAML block sequence (one - path per line under the key) rather than an inline [a, b] array, the schema-drift check extracts zero files from that plan, short-circuits its detection with no schema files found, and reports no drift regardless of whether a schema file was actually touched or whether the corresponding push command ran.
    Desired behavior: The schema-drift check must extract files_modified correctly regardless of whether the plan author (or gsd-planner) wrote it as an inline array or a YAML block sequence, matching the same field the phase-plan-index parser already reads correctly. Existing inline-array plans must continue to work unchanged.
    Key interfaces: the files_modified frontmatter contract shared by gsd-planner-authored plans, the verify schema-drift / check schema-drift CLI gate (execute:wave:post, blocking: true), and the existing frontmatter YAML-parsing path already used to read the same field elsewhere in the codebase.
    Acceptance criteria: A plan whose files_modified is a YAML block sequence and which lists a schema-relevant file (matching one of the existing ORM detection patterns) with no corresponding push-command evidence in the execution/git log is correctly flagged as drift (driftDetected: true, blocking: true). A plan using the existing inline-array form continues to behave exactly as before (no regression). A single-item block-sequence list and a multi-item block-sequence list are both handled. A regression test demonstrating the original failure exists and passes after the fix.
    Out of scope: Python/SQLAlchemy ORM detection coverage (separate feature gap, not part of this fix).

  3. added
    bugSomething isn't working
    and removed
    needs-triageNew issue awaiting maintainer review
    on Sep 9, 2026
  4. github-actions commented on Sep 9, 2026

    @github-actions
    Contributor

    Branch fix/4562-bug-verify-schema-drift-parses-files-mod created.

    git fetch origin && git checkout fix/4562-bug-verify-schema-drift-parses-files-mod
  5. trek-e commented on Sep 11, 2026

    @trek-e
    Collaborator

    Closing as a duplicate of #4631 — consolidating at the seam rather than fixing per-symptom.

    This is not a dismissal of the report. Your specifics are preserved verbatim in that epic's Absorbed issues table, and its Done when checklist requires a failing-first regression test for this exact defect before the epic can close.

    Why it is being consolidated: a scan of all 69 open confirmed-bug issues (2026-09-11) found this one shares a single root cause with seven other open issues — a gate hand-rolls a narrow derivation of what it should evaluate, the derivation comes back empty, and "empty" is reported as "pass". Fixing each occurrence where it was found leaves the remaining call sites carrying the same bug, which is the pattern that produced this cluster in the first place.

    The epic delivers one resolveEvaluationScope(), evidence read through the existing document seams instead of per-gate regex, and an Evidence type that distinguishes "none" from "could not read" so a gate can no longer pass vacuously, plus a machine-enforced anti-divergence ratchet so a new hand-written copy cannot be introduced — the approach that worked for #1372 (markdown sectionizer), #2143 (table + bounded mutation) and #2121 (phase-id), each of which closed its bug class structurally.

    Track the fix at #4631.

  6. added
    duplicateThis issue or pull request already exists
    on Sep 11, 2026
  7. added 3 commits that reference this issue on Oct 2, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't workingconfirmed-bugVerified reproducible bugduplicateThis issue or pull request already exists

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions