Skip to content

SPEC-123 Pass 2 Fix — read_file_parts rewrite + frontmatter-membership assertions

Decisions

  1. Rewrote read_file_parts rather than swapping bash for awk/python. SIMP-2 (Low) had suggested replacing the ~50-line state machine with a ~10-line awk script. Declined for this pass: the bug is in placement logic, not language choice; staying in bash keeps the regenerate-skill-paths.sh single-file contract. The new state machine has 3 logical states (frontmatter / AUTO-GEN block / body) versus the old 4-state machine that wrongly conflated "post-frontmatter body" with "frontmatter region". Tradeoff captured: if future maintenance pain emerges, SIMP-2 is the lever to pull.

  2. Added a shared lib tests/lib/frontmatter-assertions.sh rather than inlining the awk extract in each test. PAT-1 explicitly recommended a shared helper. Three exported functions: extract_frontmatter, assert_in_frontmatter, assert_not_in_frontmatter. Using grep -F (fgrep) inside so glob characters (*, ?, [) in needles are matched literally — important because paths: globs contain **, *.

  3. Bumped T2 count from 8→12, T11 from 15→19. New T2 cases: G6 (post---write placement) and G7 (idempotency). New T11 cases: paths_key_in_frontmatter per audited skill. T12 already had 10 assertions but several were rewritten to use frontmatter-membership. These are NOT new tests in the SPEC-123 inventory — same test files, stronger assertions.

Learning: TDD RED→GREEN as a built-in re-review filter

The Pass 1 / Pass 2 review failure was a textbook PAT-1 case: 12/12 tests passed while the spec mechanism was completely broken. The structural reason was substring grep against the whole file, which can't distinguish "this token appears in frontmatter" from "this token appears in the body". A frontmatter-scoped assertion would have caught the bug during the original build, not at review pass 2.

The RED-step verification before applying the GREEN fix produced the exact failure pattern reviewers should see when this class of bug recurs: - T11: 11 failures across all 4 audited skills (paths key + each product glob) → "block is misplaced everywhere" - T2 G6: 3 failures on a fresh fixture → "the regen function itself is wrong" - T12: 3 failures → "end-to-end pipeline can't satisfy frontmatter contract"

That signal pattern (per-skill paths-key failure × 4) is the diagnostic fingerprint of SPEC-1 for future bisects.

Confirmed: pre-existing unrelated failure

test-review-gates.sh fails on a missing Manual/Acceptance Tests section in test-plan-template.md. This is pre-existing (test git log shows last touch was eea14acf "complete deploy→finalize rename"), unrelated to regenerate-skill-paths.sh / SPEC-123 mechanism, and not introduced by Pass 2 fix.

Files Touched

  • plugins/core-standards/bin/regenerate-skill-paths.sh — read_file_parts rewrite + reassembly emits --- delimiters
  • plugins/core-standards/tests/lib/frontmatter-assertions.sh — new shared helper (PAT-1)
  • plugins/core-standards/tests/test-paths-generation-from-scope.sh — added G6/G7
  • plugins/core-standards/tests/test-spec-123-first-wave-audit-paths.sh — paths_key_in_frontmatter + frontmatter-scoped glob assertions
  • plugins/core-standards/tests/test-spec-123-full-pipeline.sh — frontmatter-scoped marker/key/glob/leak assertions
  • 4 audited SKILL.md files — regenerated; AUTO-GENERATED block now inside frontmatter
  • docs/concepts/skill-scoping.md:116 — DOC-1 auto-fix from Pass 2 (bundled here)
  • specs/123-repo-scoped-vs-global-skills/state.yaml — build_gate.pass_2_fixes + verification block