fix: clarify markdownlint marker placement in PRD Builder

[jkim323]

Pull Request

Description

Clarifies PRD Builder markdown suppression marker placement and aligns the project-planning builder guidance around the consolidated docs/project-planning/ output path.

The original issue focused on PRD Builder wording that could place HTML comments before YAML frontmatter. This update keeps the frontmatter opening delimiter on line 1, moves generated suppression comments immediately after the closing frontmatter delimiter, and brings related PRD, BRD, and shared disclaimer instructions into the same project-planning model.

The workflow check failed in model-validation and from investigation seems like the CI workflows fail intermittently when PSGallery has transient outages during Install-Module. Since every workflow installs modules inline without caching or retry, a single gallery hiccup fails the entire job. The changes for this is large so I'll be creating a follow-up PR for this. To mitigate, I fixed the casing.

Changes

• Updated PRD Builder to write PRDs under docs/project-planning/, preserve valid YAML frontmatter ordering for generated suppression markers, use normalized phaseSkillsLoaded entries, and ingest upstream BRD_TO_PRD_HANDOFF_V1 coverage context when available.
• Updated BRD Builder to write BRDs under docs/project-planning/, defer frontmatter and section requirements to canonical requirements-author templates, and align traceability language around business goals, FR-to-BG coverage, BG/DD identifiers, and quality gates.
• Updated the shared disclaimer-language instruction applyTo pattern to include docs/project-planning/* alongside the relevant planning and review tracking folders.

Related Issue(s)

Fixes #2097

Type of Change

Code & Documentation:

• Bug fix (non-breaking change fixing an issue)
• New feature (non-breaking change adding functionality)
• Breaking change (fix or feature causing existing functionality to change)
• Documentation update

AI Artifacts:

• Copilot instructions (.github/instructions/*.instructions.md)
• Copilot prompt (.github/prompts/*.prompt.md)
• Copilot agent (.github/agents/*.agent.md)
• Copilot skill (.github/skills/*/SKILL.md)

Testing

• Markdown linting: npm run lint:md
• Frontmatter validation: npm run lint:frontmatter
• AI artifact validation: npm run lint:ai-artifacts
• VS Code diagnostics: no errors reported for the changed files

Security Considerations

• This PR does not contain sensitive information, secrets, credentials, or NDA content.
• This PR does not add dependencies or change runtime security posture.

Additional Notes

The scope expanded slightly during review to keep PRD Builder, BRD Builder, and the shared disclaimer protocol consistent with the consolidated project-planning document location.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 81.21%. Comparing base (c857516) to head (288555d).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2098      +/-   ##
==========================================
+ Coverage   81.14%   81.21%   +0.07%     
==========================================
  Files         125      115      -10     
  Lines       18701    18611      -90     
  Branches       12        0      -12     
==========================================
- Hits        15174    15115      -59     
+ Misses       3524     3496      -28     
+ Partials        3        0       -3     

Flag	Coverage Δ
docusaurus	?
pester	85.97% <100.00%> (-0.02%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
scripts/linting/Test-ModelReferences.ps1	88.33% <100.00%> (ø)
scripts/linting/Update-ModelCatalog.ps1	83.68% <100.00%> (ø)

... and 12 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[WilliamBerryiii]

@jkim323 I pushed an additional update on this PR to cover the related project-planning guidance that surfaced while fixing the PRD Builder frontmatter issue.

What changed:

• PRD Builder now writes generated PRDs under docs/project-planning/, keeps YAML frontmatter on line 1, places markdown suppression comments after the closing frontmatter delimiter, uses normalized phase skill keys, and ingests upstream BRD handoff coverage context when available.
• BRD Builder now uses docs/project-planning/, defers frontmatter and section requirements to the canonical requirements-author templates, and aligns traceability language around business goals, FR-to-BG coverage, BG/DD identifiers, and quality gates.
• The shared disclaimer-language instruction now applies to docs/project-planning/* so generated planning docs get the expected disclaimer guidance.

I also updated the linked issue and PR description to reflect the expanded scope. Validation passed with npm run lint:md, npm run lint:frontmatter, npm run lint:ai-artifacts, and VS Code diagnostics for the changed files.

[jkim323]

Another change made for dt-agent. Moved DT coaching artifacts from copilot-tracking to docs/design-thinking/{project-slug}/. The state file (coaching-state.md) remains in .copilot-tracking/design-thinking-sessions/{project-slug}/ since it's ephemeral session state.

Artifacts under .copilot-tracking are gitignored and invisible to other agents. For ex, when the BRD agent needs DT outputs (stakeholder maps, synthesis themes, scope summaries) as input for requirements authoring, it had to re-ask the user for information that already existed in DT artifacts. Placing them under docs/design-thinking makes them accessible to any downstream agent (BRD, PRD, RPI) without repeating discovery questions.

cc @WilliamBerryiii

[github-actions]

Eval Execution

❌ Status: Failed

• Artifacts evaluated: 3
• Specs run: 1
• Assertions passed: 558
• Assertions failed: 192
• Failed specs: 1

Artifact	Kind	Status	Passed	Failed
dt-coach	agent	❌ fail	186	64
brd-builder	agent	❌ fail	186	64
prd-builder	agent	❌ fail	186	64