feat(agents): security-planner SSSC parity#1642
Merged
Merged
Conversation
…idation Bring the SSSC Planner to feature parity with the RAI Planner across identity, disclaimers, footers, phase prompts, handoff signing, validation, and docs. Changes by RAI #1287 category: 1. Identity and state — Update sssc-identity.instructions.md to add signingRequested, signingManifestPath, and disclaimer acknowledgment fields in the state schema; add a JSON schema (sssc-state.schema.json) for validation; align session recovery and orchestration language with RAI. 2. Disclaimer infrastructure — Register sssc-full-disclaimer in .github/config/disclaimers.yml so the SSSC handoff renders the same professional-review notice tier RAI uses. 3. Footer tier — Add sssc-handoff-with-disclaimer to .github/config/footer-with-review.yml (Tier 1 + checkbox + Tier 2 disclaimer, scoped to .github/instructions/security/sssc-*); rename the companion RAI tier human-facing-with-disclaimer to rai-handoff-with-disclaimer for naming symmetry. 4. Phase instructions and prompts — Refresh sssc-{assessment,gap-analysis, standards,backlog,handoff}.instructions.md and sssc-{capture,from-brd, from-prd,from-security-plan}.prompt.md for the parity flow, signing prompts, and disclaimer wiring. 5. Handoff signing — Update sssc-handoff.instructions.md Phase 6 to invoke pwsh scripts/security/Sign-PlannerArtifacts.ps1 with the SSSC manifest and to record signingRequested / signingManifestPath in state. 6. Signing script and tests — Add scripts/security/Sign-PlannerArtifacts.ps1 (planner-agnostic cosign wrapper) plus scripts/tests/security/Sign-PlannerArtifacts.Tests.ps1. 7. Validation — Extend scripts/tests/linting/Validate-PlannerArtifacts.Tests.ps1 to cover the new SSSC tier, the renamed RAI tier, and the JSON schema. 8. Documentation and generated outputs — Update sssc-planner.agent.md, the docs/agents/sssc-planning overview, collection markdown for hve-core-all, project-planning, and security, regenerate the matching plugins/ READMEs, and add SSSC terms to .cspell.json. Validation: targeted Pester suite Validate-PlannerArtifacts.Tests.ps1 = 31/31 PASS; lint:yaml, lint:md, lint:ps, lint:frontmatter, lint:collections-metadata, lint:marketplace, lint:version-consistency, lint:permissions, lint:dependency-pinning, lint:py, spell-check, plugin:validate all PASS. 🤖 Crafted with precision by ✨Copilot following brilliant human instruction, then carefully refined by our team of discerning human reviewers.
…ction descriptions 🔧 - Generated by Copilot
…able-formatter 🎨 - Generated by Copilot
…th Pester coverage - replace npm script with pwsh wrapper at scripts/linting/Format-MarkdownTables.ps1 - add 13 Pester tests covering empty repo, no-git, formatted/unformatted tables, dot-prefixed dirs, verbose mode - guard PS7 Start-Process flush race with WaitForExit + size-check retry + ReadAllText - surface stdout/stderr byte counts via Should -Because for diagnosability 🧪 - Generated by Copilot
- regenerate vulnerability and principle indexes across owasp-* and secure-by-design skill references - reformat tables in CUSTOM-AGENTS, instructions README, pull-request instructions - reformat skill READMEs (powerpoint corpus, video-to-gif examples, jql-reference, pr-reference REFERENCE) - reformat workflow README and doc-update-check tables 📐 - Generated by Copilot
- Replace removed outputPreferences references with userPreferences.targetSystem to match sssc-state.schema.json 🔒 - Generated by Copilot
…orecardProjection) - Replace removed adoptionPlaybook/executiveSummary references with the current sbom and scorecardProjection state slots 🔒 - Generated by Copilot
…-state schema - Move signingRequested under state and expand userPreferences to the five fields defined by sssc-state.schema.json 🔒 - Generated by Copilot
…ce test cleanup catch - Anchor repo-root boundary check on the OS directory separator to avoid prefix matches across sibling paths - Replace empty catch in Test-Format-MarkdownTables junction cleanup with Write-Verbose to satisfy PSAvoidUsingEmptyCatchBlock 🔒 - Generated by Copilot
- Add Node 24 setup with npm cache and npm ci so the Pester job has the toolchain expected by the test fixtures 🔒 - Generated by Copilot
…ADMEs - Bump ms.date to 2026-05-01 to clear freshness check warnings on these long-stable docs 🔒 - Generated by Copilot
🔒 - Generated by Copilot
…-parity # Conflicts: # .cspell.json # package.json
🔒 - Generated by Copilot
…oration-first planner openers Introduces a shared coaching-patterns instruction (applyTo rai/security/sssc plans) that encodes exploration-first opener conventions adapted from Design Thinking research methods. Bundles it into hve-core-all, project-planning, and security collections and regenerates plugin outputs. Adds a structural test asserting the file's frontmatter and nine canonical H2 sections.
…ner to sssc-planner Aligns the SSSC Planner with the RAI Planner's exploration-first coaching model. Updates the planner agent, identity/assessment/backlog instructions, and the four SSSC prompts (capture, from-brd, from-prd, from-security-plan) to share a single Phase 1 opener pattern, phase-gate transitions, and SSOT references. Adds a test asserting the inline state schema preserves five canonical context keys.
Introduces canonical JSON schema for Security Planner state.json with three lifecycle fixtures (phase-1 minimal, phase-4 mid, phase-6 complete) and a Pester contract suite. Asserts byte-identical disclaimerShownAt property definitions between security-state and rai-state schemas for cross-planner parity. Also adopts the local superset of ai-artifact-config.schema.json to resolve the cross-PR schema conflict. Signed-off-by: williamberryiii <wberry@microsoft.com>
Brings the security-planner agent, its supporting instructions, and the shared RAI capture-coaching guidance up to the same phase-gate, state, and question-cadence parity established by the sssc-planner work in PR #1497. Bundles the planner-startup, cadence, risk-grid, and schema test suites that guard those conventions. Stacked on PR #1638 (security-state-schema); intended to merge after the PR #1497 -> PR A cascade completes.
34 tasks
Adds a Common Pitfalls row to docs/rpi/task-reviewer.md so reviewers expand `-ForEach` arity before flagging a Pester suite as undersized, and annotates the five planner-linter test files with explicit effective-case-count `.NOTES` so the same false positive doesn't recur on visual inspection. Addresses CR-01 and MJ-01 from the phase-3.1 validation log on PR #1642.
This was referenced May 24, 2026
WilliamBerryiii
force-pushed
the
stack/security-state-schema
branch
from
May 31, 2026 01:55
7312381 to
f170c50
Compare
WilliamBerryiii
added a commit
that referenced
this pull request
Jun 4, 2026
) # 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.
…bject 🧪 - Generated by Copilot
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #1642 +/- ##
==========================================
- Coverage 80.55% 80.55% -0.01%
==========================================
Files 112 112
Lines 18679 18679
==========================================
- Hits 15047 15046 -1
- Misses 3632 3633 +1
Flags with carried forward coverage won't be shown. Click here to find out more. 🚀 New features to boost your workflow:
|
- add Phase 5/6 human-review exit reminders and Phase 6 signing offer - replace numeric risk multiplication with named-bucket grid pointer - extend state.json schema with signing and artifact preference fields - add security:sign and sssc:sign npm wrappers - add risk-appetite calibration note and clarify coaching preferences 🔒 - Generated by Copilot
Contributor
Dependency Review✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.Scanned FilesNone |
…Preferences schema 🔧 - Generated by Copilot
Closed
- add raiRecommendationShown to gate handoff recommendation display - mark raiPlannerDispatched only when user starts RAI handoff - point RAI from-security-plan at state.json via securityPlanRef - back-fill security-state schema with raiRecommendationShown - replace U+00D7 with x in two test docstrings 🔒 - Generated by Copilot
…hema 🔒 - Generated by Copilot
🧪 - Generated by Copilot
agreaves-ms
approved these changes
Jun 6, 2026
📝 - Generated by Copilot
agreaves-ms
approved these changes
Jun 6, 2026
agreaves-ms
approved these changes
Jun 6, 2026
bindsi
approved these changes
Jun 8, 2026
bindsi
left a comment
bindsi
left a comment
Member
There was a problem hiding this comment.
Automated batch review: no actionable findings.
raymond-nassar
approved these changes
Jun 8, 2026
raymond-nassar
left a comment
raymond-nassar
left a comment
Collaborator
There was a problem hiding this comment.
I like it a lot. Great changes :)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
5 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Brings the
security-planneragent, its supporting instructions, and the shared RAI capture-coaching guidance up to the same phase-gate, state, and question-cadence parity established by thesssc-plannerwork in PR #1497. Bundles the planner-startup, cadence Rule 5 ordering, risk-grid grammar, and state-schema test suites that guard those conventions going forward.Stacking
stack/security-state-schema(PR feat(planning): add Security Planner state schema with contract suite and fixtures #1638, "PR A")Changes
Modified (10):
.github/agents/security/security-planner.agent.md.github/instructions/security/identity.instructions.md.github/instructions/security/security-model.instructions.md.github/instructions/security/backlog-handoff.instructions.md.github/instructions/rai-planning/rai-capture-coaching.instructions.md.github/prompts/security/security-capture.prompt.md.github/prompts/security/security-plan-from-prd.prompt.mdplugins/hve-core-all/README.md(auto-regen)plugins/project-planning/README.md(auto-regen)plugins/security/README.md(auto-regen)Added (5 Pester suites):
scripts/tests/linting/Test-PlannerStateSchema.Tests.ps1— 8 testsscripts/tests/linting/Test-PlannerStateSchemas.Tests.ps1— 4 testsscripts/tests/linting/Test-CadenceRule5Ordering.Tests.ps1— 2 testsscripts/tests/linting/Test-PlannerStartupBlocks.Tests.ps1— 6 testsscripts/tests/linting/Test-RiskGridGrammar.Tests.ps1— 7 testsValidation
npm run plugin:validatenpm run lint:mdnpm run lint:frontmatternpm run lint:md-linksnpm run lint:psTest-PlannerStateSchemaTest-PlannerStateSchemasTest-CadenceRule5OrderingTest-PlannerStartupBlocksTest-RiskGridGrammarNotes for Reviewers
disclaimerShownAt: nullin identity state schema — Adds one line to the inline state schema inidentity.instructions.mdso the canonical state shape declares the field with a default. Full Disclaimer/Attribution Protocol prose that consumes the field remains in PR C (feat(instructions)!: disclaimer SSOT migration (stacked on #1497) #1639). Three-way overlap with PR feat(instructions)!: disclaimer SSOT migration (stacked on #1497) #1639 on this file is expected.Test-PlannerStateSchemas.Tests.ps1assertion direction — Authored draft usedShould -Not -Contain 'disclaimerShownAt'against therequiredarrays. Per plan decision DD-06/ID-02 (.copilot-tracking/plans/2026-05-22/stacked-prs-from-pr-1497-plan.instructions.mdline 41), the snapshot demotion ofdisclaimerShownAt/signingManifestPathfromrequiredwas rejected for uniformity acrosssecurity-state,rai-state, andsssc-stateschemas. Flipped both assertions toShould -Containso the test now affirms the documented uniformity decision. Schemas themselves are unchanged.Auto-regenerated plugin READMEs —
plugins/hve-core-all/README.md,plugins/project-planning/README.md, andplugins/security/README.mdreflect descriptive SSSC text drift produced bynpm run plugin:generate. Benign; produced by tooling.Sandbox/environment note — All Pester suites and pwsh-yaml-dependent lints (
plugin:generate,plugin:validate,lint:frontmatter,lint:md-links,lint:ps) require unsandboxed execution because thePowerShell-Yamlmodule is installed under~/.local/share/powershell/Modules.Merge Order
This PR is part of a 5-PR stack split from PR #1497. Merge in this order:
feat(scripts): security-planner state schema(base)feat(prompts): RAI disclaimer/attribution protocol(independent of B, but lands before B for review continuity)feat(agents): security-planner SSSC parity(depends on feat(planning): add Security Planner state schema with contract suite and fixtures #1638)Independent of the above sequence:
feat(scripts): risk-grid grammar enforcement(no shared files)chore(plugins): regenerated plugin READMEs(tooling output only)After #1638 and #1639 merge, rebase this branch onto
mainbefore merging.