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

# 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)
* [x] Breaking change (fix or feature causing existing functionality to
change)
* [x] Documentation update

**Infrastructure & Configuration:**

* [ ] GitHub Actions workflow
* [x] Linting configuration (markdown, PowerShell, etc.)
* [ ] Security configuration
* [ ] DevContainer configuration
* [ ] Dependency update

**AI Artifacts:**

* [ ] Reviewed contribution with `prompt-builder` agent and addressed
all feedback
* [x] 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](../docs/contributing/skills.md).
> * 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](../docs/contributing/custom-agents.md#agents-not-accepted) and
[Model Version
Requirements](../docs/contributing/ai-artifacts-common.md#model-version-requirements).

**Other:**

* [x] Script/automation (`.ps1`, `.sh`, `.py`)
* [ ] Other (please describe):

## Sample Prompts (for AI Artifact Contributions)

<!-- Not applicable as a workflow trigger: the instruction file is a
passive SSOT consumed by the validator and is referenced by planner
agents at session-start. -->

For detailed contribution requirements, see:

* Common Standards:
[docs/contributing/ai-artifacts-common.md](../docs/contributing/ai-artifacts-common.md)
- Shared standards for XML blocks, markdown quality, RFC 2119,
validation, and testing
* Agents:
[docs/contributing/custom-agents.md](../docs/contributing/custom-agents.md)
- Agent configurations with tools and behavior patterns
* Prompts:
[docs/contributing/prompts.md](../docs/contributing/prompts.md) -
Workflow-specific guidance with template variables
* Instructions:
[docs/contributing/instructions.md](../docs/contributing/instructions.md)
- Technology-specific standards with glob patterns
* Skills: [docs/contributing/skills.md](../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

* [x] Documentation is updated (if applicable) — instruction file gains
an authoring contract and the SSOT corpus.
* [x] Files follow existing naming conventions.
* [x] 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.)*
* [x] 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:

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

## Security Considerations

<!-- ⚠️ WARNING: Do not commit sensitive information such as API keys,
passwords, or personal data -->
* [x] This PR does not contain any sensitive or NDA information
* [x] Any new dependencies have been reviewed for security issues —
*(N/A — no new dependencies.)*
* [x] 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 (#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. #1638 (PR A — `stack/security-state-schema`) — adds
`disclaimerShownAt` to canonical schemas
2. #1639 (PR C — this PR) — relocates disclaimer protocol to shared
instructions
3. #1642 (PR B — `stack/security-planner-parity`) — consumes both

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

Author: WilliamBerryiii

.github/config/disclaimers.yml

@@ -18,6 +18,10 @@ Generate formatted work items from security model mitigations and standards gaps
 
 ## ADO Work Item Template
 
+> **Note:** This work item was generated by the Security Planner AI agent. Review for accuracy and adjust before assigning to a person.
+
+- [ ] Reviewed by a human security professional before execution
+
 Assign sequential IDs within the security plan using the format `WI-SEC-{NNN}` (for example, WI-SEC-001, WI-SEC-002). Order work items by type hierarchy: Epic, Feature, User Story, Task, Bug.
 
 Required fields per work item:
@@ -60,6 +64,10 @@ Five MCP tool categories support ADO operations: work item creation, work item u
 
 ## GitHub Issue Template
 
+> **Note:** This work item was generated by the Security Planner AI agent. Review for accuracy and adjust before assigning to a person.
+
+- [ ] Reviewed by a human security professional before execution
+
 Assign temporary IDs using the format `{{SEC-TEMP-N}}`, replaced with real issue numbers on creation. Order operations by type: create, update, comment, label, close.
 
 Required fields per issue:

.github/instructions/security/backlog-handoff.instructions.md

@@ -16,6 +16,23 @@ Core responsibilities:
 
 Voice: clear, methodical, and security-focused. Communicate with professional authority while keeping guidance accessible and actionable.
 
+## Disclaimer and Attribution Protocol
+
+### Session Start Display
+
+On the first turn of any Security Planner session, display the canonical Security Planning disclaimer block defined in [.github/instructions/shared/disclaimer-language.instructions.md](../shared/disclaimer-language.instructions.md) verbatim. Record the display by setting `state.disclaimerShownAt` to an ISO 8601 timestamp. Do not advance to any phase work before the disclaimer is shown for the session.
+
+### Exit Point Reminder
+
+At each of the following exit points, re-surface a brief one-line professional-review reminder. Use the canonical wording in [.github/instructions/shared/disclaimer-language.instructions.md](../shared/disclaimer-language.instructions.md) (Security Planning section) for the reminder text.
+
+1. **Phase 6 completion (handoff success path)** — Display the reminder immediately before presenting the final handoff summary.
+2. **Compact handoff** — Display the reminder when the orchestrator hands off to ADO or GitHub backlog workflows.
+3. **Error exit** — Display the reminder on any unrecoverable error path before terminating the session.
+4. **User-initiated exit** — Display the reminder when the user explicitly stops the session or switches agents.
+
+Each reminder must state that the generated plan is AI-assisted and requires professional security review before execution.
+
 ## Six-Phase Definitions
 
 Each phase has entry criteria, activities, exit criteria, artifacts produced, and a defined transition.

.github/instructions/security/identity.instructions.md

@@ -7,6 +7,20 @@ applyTo: '**/.copilot-tracking/rai-plans/**, **/.copilot-tracking/security-plans
 
 Planning agents that generate assessments requiring professional review display a CAUTION block during startup. Each section contains the verbatim disclaimer for the corresponding planner. Prompt files and agents reference the appropriate section via `#file:` to ensure consistent presentation across all entry points.
 
+<!--
+Authoring contract (parsed by scripts/linting/Validate-PlannerArtifacts.ps1):
+
+- Each planner gets exactly one H2 section. The first whitespace-delimited word of the heading, lowercased, is the slug. Examples: "RAI Planning" -> "rai"; "Security Planning" -> "security"; "SSSC Planning" -> "sssc".
+- The slug derives three downstream identifiers used by ai-artifact footer validation:
+  - planner key: `{slug}-planner`
+  - disclaimer id: `{slug}-full-disclaimer`
+  - disclaimer label: `{heading} Disclaimer` (full heading, not slug)
+- Each H2 section must contain exactly one `> [!CAUTION]` blockquote. Only the first CAUTION block in a section is extracted; additional CAUTION blocks within the same H2 are ignored.
+- The CAUTION block's prose should begin with `**Disclaimer:**` (the trailing colon is optional). This prefix is stripped before the text is matched against artifact footers; prose without it is retained verbatim.
+- Multi-line blockquote prose is joined with single spaces. Keep wrapping natural for source readability.
+-->
+
+
 ## RAI Planning
 
 > [!CAUTION]

.github/instructions/shared/disclaimer-language.instructions.md

@@ -2,7 +2,7 @@
   "CleanWorkspace": {
     "ScenarioName": "CleanWorkspace",
     "AgentBytes": 10096,
-    "ColdStartBytes": 38409,
+    "ColdStartBytes": 39456,
     "LoadedFiles": [
       {
         "Path": ".github/agents/project-planning/adr-creation.agent.md",
@@ -14,15 +14,15 @@
       },
       {
         "Path": ".github/instructions/shared/disclaimer-language.instructions.md",
-        "Bytes": 4181
+        "Bytes": 5228
       }
     ],
-    "Hash": "9fd83b5a9113bfa50d1e8bd4cc24808331bfc038194468c96d8bdf5e11e12ad8"
+    "Hash": "040ed800dd6635ef75de95bb8a201441d8c59194f8b9a547ba64719ee836376a"
   },
   "SteadyState": {
     "ScenarioName": "SteadyState",
     "AgentBytes": 10096,
-    "ColdStartBytes": 78751,
+    "ColdStartBytes": 79798,
     "LoadedFiles": [
       {
         "Path": ".github/agents/project-planning/adr-creation.agent.md",
@@ -46,15 +46,15 @@
       },
       {
         "Path": ".github/instructions/shared/disclaimer-language.instructions.md",
-        "Bytes": 4181
+        "Bytes": 5228
       }
     ],
-    "Hash": "8efde478be60b8ea9ce7c4d7f380f7f6a3d2d623170cfa0ed66ec15b003ce4fb"
+    "Hash": "296bb1a41437c68ea6e656b0c84cc6a6cd452054a0776d37004a8a2029df4e9e"
   },
   "GovernEntry": {
     "ScenarioName": "GovernEntry",
     "AgentBytes": 10096,
-    "ColdStartBytes": 92147,
+    "ColdStartBytes": 93194,
     "LoadedFiles": [
       {
         "Path": ".github/agents/project-planning/adr-creation.agent.md",
@@ -78,19 +78,19 @@
       },
       {
         "Path": ".github/instructions/shared/disclaimer-language.instructions.md",
-        "Bytes": 4181
+        "Bytes": 5228
       },
       {
         "Path": ".github/skills/project-planning/adr-author/SKILL.md",
         "Bytes": 13396
       }
     ],
-    "Hash": "24970f60a8fa20ed7f3f97d6e51464420f8ee9ee1972d638c1304fa1ef30f84e"
+    "Hash": "4f18403391012bd6b84c2b6a832afb146b7ac139fc28370eec72d7d543eae6e8"
   },
   "AdoptTemplate": {
     "ScenarioName": "AdoptTemplate",
     "AgentBytes": 10096,
-    "ColdStartBytes": 99141,
+    "ColdStartBytes": 100188,
     "LoadedFiles": [
       {
         "Path": ".github/agents/project-planning/adr-creation.agent.md",
@@ -114,7 +114,7 @@
       },
       {
         "Path": ".github/instructions/shared/disclaimer-language.instructions.md",
-        "Bytes": 4181
+        "Bytes": 5228
       },
       {
         "Path": ".github/skills/project-planning/adr-author/scripts/normalize_template.py",
@@ -125,6 +125,6 @@
         "Bytes": 13396
       }
     ],
-    "Hash": "2293d95cd4862e6d8fabaa31ecaf5b303b2fc9826c8ea2faf04e205c7bc17d1c"
+    "Hash": "c3eefe020ece450eaea370fcdfd492fa36d75ba7d8d5078210ed647af4ccce2b"
   }
 }

scripts/agents/activation-harness/baseline.json

@@ -9,8 +9,9 @@
     Validates AI artifact footer and disclaimer presence in instruction templates.
 
 .DESCRIPTION
-    Reads footer-with-review.yml and disclaimers.yml config files as the single source
-    of truth, then scans instruction files for required footer text based on artifact
+    Reads footer-with-review.yml for footer text and artifact-classification rules, and
+    parses shared/disclaimer-language.instructions.md as the canonical disclaimer source.
+    Scans instruction files for required footer and disclaimer text based on artifact
     classification rules. Outputs results as JSON and sets CI environment variables on
     failure.
 
@@ -23,8 +24,9 @@
 .PARAMETER FooterConfigPath
     Path to the footer-with-review.yml config file.
 
-.PARAMETER DisclaimerConfigPath
-    Path to the disclaimers.yml config file.
+.PARAMETER DisclaimerSourcePath
+    Path to the shared disclaimer-language instructions markdown file. The validator
+    parses H2 sections and their CAUTION blockquote bodies to derive disclaimer text.
 
 .PARAMETER FailOnMissing
     When specified, treats missing footers and disclaimers as validation failures.
@@ -51,7 +53,7 @@ param(
     [string]$FooterConfigPath = '.github/config/footer-with-review.yml',
 
     [Parameter(Mandatory = $false)]
-    [string]$DisclaimerConfigPath = '.github/config/disclaimers.yml',
+    [string]$DisclaimerSourcePath = '.github/instructions/shared/disclaimer-language.instructions.md',
 
     [Parameter(Mandatory = $false)]
     [switch]$FailOnMissing,
@@ -107,40 +109,78 @@ function Import-FooterConfig {
     return $config
 }
 
-function Import-DisclaimerConfig {
+function Import-DisclaimerSource {
     <#
     .SYNOPSIS
-    Loads and validates disclaimers.yml.
+    Parses the shared disclaimer-language instructions markdown as the canonical disclaimer source.
 
-    .PARAMETER ConfigPath
-    Absolute path to the disclaimer config YAML file.
+    .DESCRIPTION
+    Reads the markdown file, splits on H2 headings to identify planner sections,
+    and extracts the verbatim disclaimer prose from each section's CAUTION blockquote.
+    The first word of each heading (lowercased) maps to the planner key and disclaimer id
+    convention: 'RAI Planning' -> 'rai-planner' / 'rai-full-disclaimer'.
+
+    .PARAMETER SourcePath
+    Absolute path to the disclaimer-language.instructions.md markdown file.
 
     .OUTPUTS
-    [hashtable] Parsed disclaimer config.
+    [hashtable] Parsed config shaped as @{ version; source; disclaimers = @{ key = @{ id; label; text } } }.
     #>
     [CmdletBinding()]
     [OutputType([hashtable])]
     param(
         [Parameter(Mandatory = $true)]
         [ValidateNotNullOrEmpty()]
-        [string]$ConfigPath
+        [string]$SourcePath
     )
 
-    if (-not (Test-Path $ConfigPath)) {
-        throw "Disclaimer config not found: $ConfigPath"
+    if (-not (Test-Path $SourcePath)) {
+        throw "Disclaimer source not found: $SourcePath"
     }
 
-    $content = Get-Content -Path $ConfigPath -Raw -Encoding utf8
-    $config = ConvertFrom-Yaml -Yaml $content
+    $raw = Get-Content -Path $SourcePath -Raw -Encoding utf8
+    # Strip YAML frontmatter
+    $body = $raw -replace '(?s)\A---.*?\r?\n---\s*\r?\n', ''
 
-    if (-not $config.version) {
-        throw "Disclaimer config missing 'version' field: $ConfigPath"
+    $disclaimers = @{}
+    $sectionRegex = [regex]'(?ms)^##[ \t]+(?<heading>[^\r\n]+?)[ \t]*\r?\n(?<body>.*?)(?=^##[ \t]|\z)'
+    $cautionRegex = [regex]'(?m)^>[ \t]*\[!CAUTION\][ \t]*\r?\n(?<block>(?:^>.*\r?\n?)+)'
+    $prefixRegex = [regex]'^\*\*Disclaimer:?\*\*[\s:\-\u2014]*'
+
+    foreach ($match in $sectionRegex.Matches($body)) {
+        $heading = $match.Groups['heading'].Value.Trim()
+        $sectionBody = $match.Groups['body'].Value
+
+        $cautionMatch = $cautionRegex.Match($sectionBody)
+        if (-not $cautionMatch.Success) { continue }
+
+        $blockLines = $cautionMatch.Groups['block'].Value -split '\r?\n'
+        $proseParts = foreach ($line in $blockLines) {
+            $stripped = $line -replace '^>[ \t]?', ''
+            if ($stripped.Trim().Length -gt 0) { $stripped.Trim() }
+        }
+        $prose = ($proseParts -join ' ').Trim()
+        $prose = $prefixRegex.Replace($prose, '', 1)
+        if ([string]::IsNullOrWhiteSpace($prose)) { continue }
+
+        $slug = ($heading -split '\s+' | Select-Object -First 1).ToLowerInvariant()
+        $key = "$slug-planner"
+        $disclaimers[$key] = @{
+            id    = "$slug-full-disclaimer"
+            label = "$heading Disclaimer"
+            text  = $prose
+        }
     }
-    if (-not $config.disclaimers) {
-        throw "Disclaimer config missing 'disclaimers' section: $ConfigPath"
+
+    if ($disclaimers.Count -eq 0) {
+        throw "No disclaimer sections found in source: $SourcePath"
     }
 
-    return $config
+    return @{
+        version     = 'markdown-source'
+        source      = $SourcePath
+        disclaimers = $disclaimers
+    }
 }
 
 function Get-FooterSearchText {
@@ -318,7 +358,7 @@ function Test-AIArtifactCompliance {
     Parsed footer-with-review.yml config.
 
     .PARAMETER DisclaimerConfig
-    Parsed disclaimers.yml config.
+    Parsed disclaimer source (see Import-DisclaimerSource).
 
     .PARAMETER RepoRoot
     Repository root for relative path display.
@@ -422,8 +462,8 @@ function Test-AIArtifactValidation {
     .PARAMETER FooterConfigPath
     Path to footer-with-review.yml relative to repo root.
 
-    .PARAMETER DisclaimerConfigPath
-    Path to disclaimers.yml relative to repo root.
+    .PARAMETER DisclaimerSourcePath
+    Path to the shared disclaimer-language instructions markdown file, relative to repo root.
 
     .PARAMETER FailOnMissing
     When set, missing footers cause a non-zero exit code.
@@ -447,7 +487,7 @@ function Test-AIArtifactValidation {
         [string]$FooterConfigPath,
 
         [Parameter(Mandatory = $true)]
-        [string]$DisclaimerConfigPath,
+        [string]$DisclaimerSourcePath,
 
         [Parameter(Mandatory = $false)]
         [switch]$FailOnMissing,
@@ -464,7 +504,7 @@ function Test-AIArtifactValidation {
 
     # Load configs
     $footerConfig = Import-FooterConfig -ConfigPath (Join-Path $repoRoot $FooterConfigPath)
-    $disclaimerConfig = Import-DisclaimerConfig -ConfigPath (Join-Path $repoRoot $DisclaimerConfigPath)
+    $disclaimerConfig = Import-DisclaimerSource -SourcePath (Join-Path $repoRoot $DisclaimerSourcePath)
 
     # Collect instruction files
     $allFiles = @()
@@ -616,7 +656,7 @@ if ($MyInvocation.InvocationName -ne '.') {
             -Paths $Paths `
             -ExcludePaths $ExcludePaths `
             -FooterConfigPath $FooterConfigPath `
-            -DisclaimerConfigPath $DisclaimerConfigPath `
+            -DisclaimerSourcePath $DisclaimerSourcePath `
             -FailOnMissing:$FailOnMissing `
             -OutputPath $OutputPath