fix(sdd): ignore fenced Markdown examples

[1fanwang]

Summary

When a spec or tasks artifact documents the task format inside a code fence, the SDD dashboard counts those example checkboxes as real tasks and shows the example [NEEDS CLARIFICATION: ...] markers as unanswered questions. A tasks file with one real task and one fenced example reports two tasks. After this change it reports one.

Problem

The parser recognised only unindented triple backticks. Examples written in a tilde fence, or in a fence indented by a space or two, leaked through. The bogus clarifications were the worse half: they appeared as questions with no way to resolve them, because nothing in the artifact actually needed answering.

Solution

Fence state is now tracked across backtick and tilde fences, allowing the up-to-three spaces CommonMark permits on a marker and requiring a closing run at least as long as the opening one. Only lines outside a fence are considered.

Checkboxes indented four or more spaces still count. Those are nested list items, and telling them apart from an indented code block needs the block context only a real CommonMark parser tracks. Counting is the safe side of that ambiguity, since an extra task is visible in the dashboard and a dropped one is not. Both behaviours are pinned by tests.

Testing Done

Raw logs

$ node --test plugins/spec-kit-copilot-sdd/extensions/sdd-canvas/tests/sdd.test.mjs
ok 1 - implementation progress scans the complete bounded tasks artifact
ok 2 - task counting ignores fenced examples but keeps indented list items
ok 3 - clarifications retain stable indices across supported markdown blocks
ok 4 - dashboard gates setup controls and exposes stage status names
ok 5 - dashboard matches clarification actions by question instead of render position
# tests 5
# pass 5
# fail 0

$ node -e '
const m = await import("./plugins/spec-kit-copilot-sdd/extensions/sdd-canvas/sdd.mjs");
const tasks = "   ~~~markdown\n   - [x] T0\n   ~~~\n- [x] T1";
const q = "   ~~~markdown\n[NEEDS CLARIFICATION: in fence]\n   ~~~\n[NEEDS CLARIFICATION: real]";
console.log("tasks:", m.taskProgress(tasks));
console.log("questions:", m.extractClarifications(q));
'
# origin/main, the fenced example counted:
# tasks: { total: 2, completed: 2 }
# questions: [ { question: "in fence" }, { question: "real" } ]

# this branch, only the real ones:
# tasks: { total: 1, completed: 1 }
# questions: [ { question: "real" } ]

[Copilot]

🟡 Changes recommended

Indented (4-space/tab) Markdown code blocks are still counted/scanned despite being called out in the PR description, so the fix is incomplete for the stated problem scope.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Updates the SDD canvas’s markdown scanning so task checkbox counting and clarification extraction ignore CommonMark-style fenced code blocks (backtick/tilde fences), preventing example content inside fences from inflating dashboard totals and surfacing spurious questions.

Changes:

• Add fence-state tracking that supports backtick and tilde fences, including up to 3 spaces indentation and matching close lengths.
• Apply the fence tracking to both task checkbox scanning and clarification marker extraction.
• Extend tests to cover tilde fences (including indented tilde fences) in tasks and clarifications scenarios.

File summaries

File	Description
plugins/spec-kit-copilot-sdd/extensions/sdd-canvas/sdd.mjs	Adds CommonMark fence tracking and uses it to ignore fenced content during task/clarification scanning.
plugins/spec-kit-copilot-sdd/extensions/sdd-canvas/tests/sdd.test.mjs	Adds test cases ensuring tilde fences (including indented tilde fences) are ignored by scanners.

Review details

Suppressed comments (2)

plugins/spec-kit-copilot-sdd/extensions/sdd-canvas/sdd.mjs:543

• Clarification extraction still includes markers inside 4-space indented Markdown code blocks (lines starting with 4 spaces or a tab). If the intent is to ignore indented code examples (as described in the PR), skip indented code-block lines before scanning for headings/markers.

        if (fenceState.isFenceLine || openFence) continue;

plugins/spec-kit-copilot-sdd/extensions/sdd-canvas/tests/sdd.test.mjs:58

• This test covers backtick fences and indented tilde fences, but not 4-space indented code blocks. Adding an indented code-block clarification marker would ensure those examples are ignored too (per the PR description).

        "```text",
        "[NEEDS CLARIFICATION: Ignore code?]",
        "```",
        "   ~~~markdown",
        "[NEEDS CLARIFICATION: Ignore indented tilde fence?]",

• Files reviewed: 2/2 changed files
• Comments generated: 2
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🟢 Approval recommended

The changes correctly implement fence-aware scanning (including tilde/indented fences) and include focused tests that lock in the intended behavior.

Review details

• Files reviewed: 2/2 changed files
• Comments generated: 0 new
• Review effort level: Lite

[Copilot]

🟡 Changes recommended

The implementation still counts markers inside 4-space/tab-indented Markdown code blocks (described as in-scope), and tests don’t yet lock in the intended indented-code-block behavior.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Suppressed comments (2)

plugins/spec-kit-copilot-sdd/extensions/sdd-canvas/sdd.mjs:544

• extractClarifications currently scans 4-space/tab-indented Markdown code blocks for [NEEDS CLARIFICATION: …] markers. If those markers appear in indented examples, they will still be surfaced as real clarifications because only fenced code blocks are skipped.

    for (const line of String(text || "").split(/\r?\n/)) {
        const fenceState = advanceMarkdownFence(line, openFence);
        openFence = fenceState.openFence;
        if (fenceState.isFenceLine || openFence) continue;
        const heading = line.match(/^#{1,6}\s+(.+?)\s*$/);

plugins/spec-kit-copilot-sdd/extensions/sdd-canvas/tests/sdd.test.mjs:59

• The clarification test adds coverage for indented tilde fences, but it still doesn’t assert that [NEEDS CLARIFICATION: …] inside 4-space indented code blocks are ignored. Adding a 4-space indented marker line would align the test with the PR’s stated behavior.

        "   ~~~markdown",
        "[NEEDS CLARIFICATION: Ignore indented tilde fence?]",
        "   ~~~",

• Files reviewed: 2/2 changed files
• Comments generated: 2
• Review effort level: Lite

[1fanwang]

Thanks, but I looked at the indented code block suggestion and deliberately left it out.

In CommonMark an indented code block cannot interrupt a list. Content indented under a list item is a sub-list, so skipping every line indented by four spaces or a tab silently drops nested subtasks:

- [x] T001 Parent
    - [ ] T001a Nested
    - [x] T001b Nested
- [ ] T002 Second

fence-aware scanning (this PR): { total: 4, completed: 2 }
also skipping indented lines:   { total: 2, completed: 1 }

Nested task lists are ordinary in a tasks artifact, so that change would under-report real progress in exchange for a case that fenced scanning already covers. I had this on the branch briefly and reverted it once I found the regression.

Handling indented code blocks correctly needs block-level parsing that knows whether it is inside a list, which is a larger change than this fix. Happy to look at that separately if it is worth having.

[Copilot]

🟡 Changes recommended

The updated scanning still treats 4-space/tab-indented code blocks as normal text (and tests currently lock in that behavior), which can continue producing the false positives described in the PR.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Suppressed comments (3)

Previously missed (1) — in code that hasn't changed since the last review.

plugins/spec-kit-copilot-sdd/extensions/sdd-canvas/sdd.mjs:544

• extractClarifications only skips fenced blocks, so [NEEDS CLARIFICATION: …] inside 4-space/tab-indented CommonMark code blocks will still be extracted as real clarifications. If indented code examples are expected in artifacts, add an explicit indented-code-block guard similar to taskProgress.

plugins/spec-kit-copilot-sdd/extensions/sdd-canvas/sdd.mjs:284

• taskProgress still counts checkboxes inside 4-space/tab-indented CommonMark code blocks because it matches ^\s*[-*+] after only skipping fenced blocks. This can still inflate task totals for indented example snippets, which the PR description calls out as a problem. Consider explicitly skipping indented code-block lines (4 spaces or a tab) before matching checkboxes.

    for (const line of text.split(/\r?\n/)) {
        const fenceState = advanceMarkdownFence(line, openFence);
        openFence = fenceState.openFence;
        if (fenceState.isFenceLine || openFence) continue;
        const m = line.match(/^\s*[-*+]\s+\[([ xX])\]/);

plugins/spec-kit-copilot-sdd/extensions/sdd-canvas/tests/sdd.test.mjs:66

• This test currently asserts that a 4-space indented checkbox should be counted, but the PR description frames indented code blocks as a source of false positives. As written, this locks in the behavior that causes inflated totals for indented code examples. Consider changing this case to verify that an indented code-block checkbox is ignored (e.g., after a blank line), matching the intended behavior.

    // An indented checkbox is a nested list item, so it counts. Markdown also lets
    // four spaces open a code block, and telling the two apart needs the block
    // context a full CommonMark parser tracks. Counting is the safe side of that
    // ambiguity: an extra task is visible in the dashboard, a dropped one is not.
    assert.deepEqual(taskProgress([
        "- [ ] T001 Parent",
        "    - [x] T002 Nested child",
    ].join("\n")), { total: 2, completed: 1 });

• Files reviewed: 2/2 changed files
• Comments generated: 1
• Review effort level: Lite