feat(instructions)!: disclaimer SSOT migration (stacked on #1497)

[WilliamBerryiii]

Pull Request

Description

This PR migrates the planner disclaimer single-source-of-truth (SSOT) from the standalone YAML config at .github/config/disclaimers.yml to a markdown authoring contract embedded in .github/instructions/shared/disclaimer-language.instructions.md. It stacks on #1497 (feat/sssc-planner-rai-parity) because removing disclaimers.yml would conflict with any branch in the stack that does not include this migration.

The instruction file now defines the disclaimer corpus as H2 sections whose slugified headings (for example, RAI Planning → rai-planner) are the parser-derived keys. Each section carries a CAUTION blockquote that captures the session-start disclaimer, plus prose paragraphs joined into a single string by the parser. A short Authoring Contract preamble documents the rules so future edits stay machine-readable without referring to the validator source.

The validator, scripts/linting/Validate-PlannerArtifacts.ps1, swaps its YAML loader for Import-DisclaimerSource, which parses the new markdown SSOT, derives planner keys from heading slugs, extracts CAUTION blockquotes (stripping the > [!CAUTION] prefix), and joins multi-line prose. The function's -DisclaimerConfigPath parameter is renamed to -DisclaimerSourcePath to reflect the markdown origin.

A new contract suite, scripts/tests/linting/Test-DisclaimerArtifacts.Tests.ps1 (8 cases), asserts that:

• the SSOT instruction file parses into the expected planner keys with non-empty CAUTION blockquotes and prose; and
• every planner identity file (RAI and Security) carries the required Session Start Display literal and an Exit Point Reminder section that references each named exit point.

To satisfy the second assertion, this PR also adds the Disclaimer and Attribution Protocol section to .github/instructions/security/identity.instructions.md, sourced verbatim from the snapshot. The hunks in scripts/tests/linting/Validate-PlannerArtifacts.Tests.ps1 are trimmed to disclaimer-related coverage only; the SSSC-parity hunks are deferred to a later PR in the stack.

The three regenerated plugins/*/README.md files reflect the disclaimer SSOT description text and are produced by npm run plugin:generate.

Related Issue(s)

Stacks on #1497. No other issue references in commits or branch name.

Type of Change

Select all that apply:

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

Infrastructure & Configuration:

• GitHub Actions workflow
• Linting configuration (markdown, PowerShell, etc.)
• Security configuration
• DevContainer configuration
• Dependency update

AI Artifacts:

• Reviewed contribution with prompt-builder agent and addressed all feedback
• Copilot instructions (.github/instructions/*.instructions.md)
• Copilot prompt (.github/prompts/*.prompt.md)
• Copilot agent (.github/agents/*.agent.md)
• Copilot skill (.github/skills/*/SKILL.md)

Note for AI Artifact Contributors:

• Agents: Research, indexing/referencing other project (using standard VS Code GitHub Copilot/MCP tools), planning, and general implementation agents likely already exist. Review .github/agents/ before creating new ones.
• Skills: Must include both bash and PowerShell scripts. See Skills.
• Model Versions: Only contributions targeting the latest Anthropic and OpenAI models will be accepted. Older model versions (e.g., GPT-3.5, Claude 3) will be rejected.
• See Agents Not Accepted and Model Version Requirements.

Other:

• Script/automation (.ps1, .sh, .py)
• Other (please describe):

Sample Prompts (for AI Artifact Contributions)

For detailed contribution requirements, see:

• Common Standards: docs/contributing/ai-artifacts-common.md - Shared standards for XML blocks, markdown quality, RFC 2119, validation, and testing
• Agents: docs/contributing/custom-agents.md - Agent configurations with tools and behavior patterns
• Prompts: docs/contributing/prompts.md - Workflow-specific guidance with template variables
• Instructions: docs/contributing/instructions.md - Technology-specific standards with glob patterns
• Skills: docs/contributing/skills.md - Task execution utilities with cross-platform scripts

Testing

Automated validation performed by the agent:

• npm run lint:md — markdown linting: Passed (211 files, 0 errors).
• npm run lint:frontmatter — frontmatter validation: Passed (541 files, 0 errors).
• npm run lint:ps — PowerShell analysis: Passed.
• npm run lint:yaml — YAML validation: Passed (50 files).
• npm run plugin:validate — plugin metadata: Passed.
• npm run plugin:generate — plugin outputs regenerated and committed.
• npm run test:ps -- -TestPath scripts/tests/linting/Test-DisclaimerArtifacts.Tests.ps1 — 8/8 passed.
• npm run test:ps -- -TestPath scripts/tests/linting/Validate-PlannerArtifacts.Tests.ps1 — 34/34 passed.
• grep -r "config/disclaimers" .github docs scripts collections plugins — empty, confirming no orphan references.

Security analysis findings:

• No secrets, credentials, or customer data in the diff.
• No new runtime dependencies introduced. The validator uses only built-in PowerShell cmdlets to parse markdown.
• No changes that broaden privilege boundaries.

Diff-based assessments:

• All changed files match expected paths derived from the commit subject and the migration scope documented in the stack plan.
• The markdown SSOT, validator, and tests follow the existing .github/instructions/, scripts/linting/, and scripts/tests/linting/ conventions.

Note

Manual testing was not performed.

Checklist

Required Checks

• Documentation is updated (if applicable) — instruction file gains an authoring contract and the SSOT corpus.
• Files follow existing naming conventions.
• Changes are backwards compatible (if applicable) — (N/A — this PR is a BREAKING change. .github/config/disclaimers.yml is removed; consumers must reference disclaimer-language.instructions.md. Tree-wide grep confirms zero in-codebase consumers of the deleted path; all internal callers are updated in this PR.)
• Tests added for new functionality (if applicable).

AI Artifact Contributions

• Used /prompt-analyze to review contribution
• Addressed all feedback from prompt-builder review
• Verified contribution follows common standards and type-specific requirements

Required Automated Checks

The following validation commands must pass before merging:

• Markdown linting: npm run lint:md
• Spell checking: npm run spell-check
• Frontmatter validation: npm run lint:frontmatter
• Skill structure validation: npm run validate:skills
• Link validation: npm run lint:md-links
• PowerShell analysis: npm run lint:ps
• Plugin freshness: npm run plugin:generate
• Docusaurus tests: npm run docs:test

Security Considerations

• This PR does not contain any sensitive or NDA information
• Any new dependencies have been reviewed for security issues — (N/A — no new dependencies.)
• Security-related scripts follow the principle of least privilege — (N/A — no security-related scripts modified.)

Additional Notes

This PR is the second stacked increment in the post-#1497 stack (PR C in plan ordering). The base will switch from feat/sssc-planner-rai-parity to main after #1497 merges. The companion PRs in the stack are:

• PR A (feat(planning): add Security Planner state schema with contract suite and fixtures #1638) — Security Planner state schema and fixtures.
• PR B — Security Planner agent and phase-gate parity (depends on PR A).
• PR D — Planner linter hardening (sibling off main).
• PR E — Dev environment alignment (sibling off main, optional).

A small Disclaimer and Attribution Protocol section is added to .github/instructions/security/identity.instructions.md (sourced verbatim from the snapshot) so the new contract test passes for both planner identities. The SSSC-parity hunks in Validate-PlannerArtifacts.Tests.ps1 are intentionally deferred to PR B, which lands them alongside the Security Planner content they exercise.

Merge Order

This PR is part of a stack derived from PR #1497. Required merge sequence:

1. feat(planning): add Security Planner state schema with contract suite and fixtures #1638 (PR A — stack/security-state-schema) — adds disclaimerShownAt to canonical schemas
2. feat(instructions)!: disclaimer SSOT migration (stacked on #1497) #1639 (PR C — this PR) — relocates disclaimer protocol to shared instructions
3. feat(agents): security-planner SSSC parity (stacked on PR A and #1497) #1642 (PR B — stack/security-planner-parity) — consumes both

#1640 and #1641 are siblings and may merge in any order independent of this chain.

[rezatnoMsirhC]

The test array includes backlog-handoff.instructions.md alongside sssc-backlog.instructions.md, but backlog-handoff.instructions.md does not contain either the noteLiteral or checkboxLiteral strings asserted here. Both of these tests will fail for that file.

sssc-backlog.instructions.md carries both literals in its ADO and GitHub format sections and will pass. Consider either adding both literals to the work item templates in backlog-handoff.instructions.md, or removing it from $script:backlogFiles if the attribution requirement does not apply to that file.