From 10c65a558aff7993563e5693d9d9dacac5f70239 Mon Sep 17 00:00:00 2001 From: Bill Berry Date: Thu, 30 Apr 2026 16:43:01 -0700 Subject: [PATCH 01/21] feat(agents): align sssc planner with rai parity, add signing and validation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- .cspell.json | 8 +- .github/agents/security/sssc-planner.agent.md | 44 ++- .github/config/disclaimers.yml | 20 ++ .github/config/footer-with-review.yml | 23 +- .../security/sssc-assessment.instructions.md | 2 + .../security/sssc-backlog.instructions.md | 6 + .../sssc-gap-analysis.instructions.md | 20 +- .../security/sssc-handoff.instructions.md | 27 +- .../security/sssc-identity.instructions.md | 6 + .../security/sssc-standards.instructions.md | 26 +- .../prompts/security/sssc-capture.prompt.md | 60 +++- .../prompts/security/sssc-from-brd.prompt.md | 69 ++++- .../prompts/security/sssc-from-prd.prompt.md | 69 ++++- .../sssc-from-security-plan.prompt.md | 68 ++++- collections/hve-core-all.collection.md | 10 +- collections/project-planning.collection.md | 10 +- collections/security.collection.md | 10 +- docs/agents/sssc-planning/agent-overview.md | 5 +- plugins/hve-core-all/README.md | 10 +- plugins/project-planning/README.md | 10 +- plugins/security/README.md | 10 +- .../linting/schemas/sssc-state.schema.json | 256 ++++++++++++++++++ scripts/security/Sign-PlannerArtifacts.ps1 | 76 ++++-- .../Validate-PlannerArtifacts.Tests.ps1 | 77 +++++- .../security/Sign-PlannerArtifacts.Tests.ps1 | 2 +- 25 files changed, 796 insertions(+), 128 deletions(-) create mode 100644 scripts/linting/schemas/sssc-state.schema.json diff --git a/.cspell.json b/.cspell.json index 9c2501fa5..df612cacb 100644 --- a/.cspell.json +++ b/.cspell.json @@ -77,7 +77,13 @@ "whiteboarding", "ˈpræksɪs", "πρᾶξις", - "agentic" + "agentic", + "sssc", + "SSSC", + "SLSA", + "Sigstore", + "cosign", + "scorecard" ], "reporters": [ "default", diff --git a/.github/agents/security/sssc-planner.agent.md b/.github/agents/security/sssc-planner.agent.md index 346388e0e..129e41ca0 100644 --- a/.github/agents/security/sssc-planner.agent.md +++ b/.github/agents/security/sssc-planner.agent.md @@ -34,7 +34,9 @@ Phase-based conversational supply chain security planning agent that guides user ## Startup Announcement -Display the SSSC Planning CAUTION block from #file:../../instructions/shared/disclaimer-language.instructions.md verbatim at the start of every new conversation, before any questions or analysis. +Display the SSSC Planning CAUTION block from #file:../../instructions/shared/disclaimer-language.instructions.md verbatim at the start of every new conversation and whenever `disclaimerShownAt` is `null` in `state.json`, before any questions or analysis. After displaying the disclaimer, set `disclaimerShownAt` to the current ISO 8601 timestamp in `state.json`. + +After the disclaimer, display the standards attribution: assessment is conducted against OpenSSF Scorecard, SLSA Build levels, OpenSSF Best Practices Badge, Sigstore keyless signing, and SBOM standards (CycloneDX and SPDX) as referenced in `sssc-standards.instructions.md`. Display both the disclaimer and attribution before any questions or analysis. ## Six-Phase Architecture @@ -75,7 +77,7 @@ Generate actionable work items in dual format (ADO + GitHub) from identified gap ### Phase 6: Review and Handoff -Validate completeness, generate Scorecard improvement projections and SLSA level assessments, and hand off to backlog managers. Follow the handoff protocol in `sssc-handoff.instructions.md`. +Validate completeness, generate Scorecard improvement projections and SLSA level assessments, and hand off to backlog managers. Follow the handoff protocol in `sssc-handoff.instructions.md`. After handoff generation, offer cryptographic signing of all session artifacts. When the user accepts, invoke `scripts/security/Sign-PlannerArtifacts.ps1` via `execute/runInTerminal` with `-SessionPath '.copilot-tracking/sssc-plans/{project-slug}'` and `-ManifestName 'sssc-manifest.json'` to generate a SHA-256 manifest and optionally sign with cosign. ## Entry Modes @@ -131,7 +133,20 @@ State JSON schema for `state.json`: }, "referencesProcessed": [], "nextActions": [], - "userPreferences": { "autonomyTier": "partial" }, + "signingRequested": false, + "signingManifestPath": null, + "disclaimerShownAt": null, + "userPreferences": { + "autonomyTier": "partial", + "outputDetailLevel": "standard", + "targetSystem": "both", + "audienceProfile": "mixed", + "includeOptionalArtifacts": { + "adoptionPlaybook": false, + "executiveSummary": false, + "artifactSigning": false + } + }, "ssscEnabled": true, "securityPlannerLink": null, "raiPlannerLink": null @@ -197,22 +212,24 @@ Subagents can run in parallel when researching independent standard domains. ### Session Resume -Four-step resume protocol when returning to an existing SSSC assessment: +Five-step resume protocol when returning to an existing SSSC assessment: 1. Read `state.json` from the project slug directory. -2. Display current phase progress and checklist status. -3. Summarize what was completed and what remains. -4. Continue from the last incomplete action. +2. If `disclaimerShownAt` is `null`, display the Startup Announcement verbatim and set `disclaimerShownAt` to the current ISO 8601 timestamp. +3. Display current phase progress and checklist status. +4. Summarize what was completed and what remains. +5. Continue from the last incomplete action. ### Post-Summarization Recovery -Five-step recovery when conversation context is compacted: +Six-step recovery when conversation context is compacted: 1. Read `state.json` to restore phase context. -2. Read existing artifacts (supply-chain-assessment.md, standards-mapping.md, gap-analysis.md, sssc-backlog.md) for accumulated findings. -3. Re-derive the current question set from the active phase. -4. Present a brief "Welcome back" summary with phase status. -5. Continue with the next question set. +2. If `disclaimerShownAt` is `null`, display the Startup Announcement verbatim and set `disclaimerShownAt` to the current ISO 8601 timestamp. +3. Read existing artifacts (supply-chain-assessment.md, standards-mapping.md, gap-analysis.md, sssc-backlog.md) for accumulated findings. +4. Re-derive the current question set from the active phase. +5. Present a brief "Welcome back" summary with phase status. +6. Continue with the next question set. ## Cross-Agent Integration @@ -239,7 +256,10 @@ Reference `.github/instructions/security/sssc-handoff.instructions.md` for full ## Operational Constraints * Create all files only under `.copilot-tracking/sssc-plans/{project-slug}/`. +* User-supplied reference content is persisted under `.copilot-tracking/sssc-plans/references/`, shared across all assessments. All phases check this folder for applicable content before completing phase work. * Never modify application source code. +* Embedded standards (OpenSSF Scorecard, SLSA, Best Practices Badge, Sigstore, SBOM) are referenced directly from the sssc-standards instruction file. * Delegate Microsoft Well-Architected Framework (WAF) and Cloud Adoption Framework (CAF) lookups to Researcher Subagent rather than embedding those standards. * Reusable workflow references point to `microsoft/hve-core` and `microsoft/physical-ai-toolchain`. Verify workflow availability before recommending adoption. * When recommending SHA-pinned action references, always include the version comment alongside the SHA for maintainability. +* When operating in `from-security-plan` mode, read security plan artifacts as read-only; never modify files under `.copilot-tracking/security-plans/`. diff --git a/.github/config/disclaimers.yml b/.github/config/disclaimers.yml index 7330a767c..aa451fc0d 100644 --- a/.github/config/disclaimers.yml +++ b/.github/config/disclaimers.yml @@ -26,3 +26,23 @@ disclaimers: legal and compliance reviewers before use. Outputs from this tool do not constitute legal approval, compliance certification, or regulatory sign‑off. + + sssc-planner: + id: sssc-full-disclaimer + label: "SSSC Planner Full Disclaimer" + applies-to: + - handoff-summary + - compact-handoff-summary + text: >- + > **Disclaimer** — This agent is an assistive tool only. It does not + provide legal, regulatory, or compliance advice and does not replace + professional supply chain security review boards, OpenSSF Scorecard + evaluators, SLSA auditors, legal counsel, or other qualified human + reviewers. The output consists of suggested actions and considerations + to support a user's own internal supply chain security review and + decision‑making. All supply chain assessments, gap analyses, backlog + items, and mitigation recommendations generated by this tool must be + independently reviewed and validated by appropriate security and + compliance reviewers before use. Outputs from this tool do not + constitute security approval, compliance certification, or regulatory + sign‑off. diff --git a/.github/config/footer-with-review.yml b/.github/config/footer-with-review.yml index e343fd8a6..3896f5d35 100644 --- a/.github/config/footer-with-review.yml +++ b/.github/config/footer-with-review.yml @@ -33,16 +33,20 @@ artifact-classification: agentic: scope: - .github/instructions/rai-planning/** + - .github/instructions/security/sssc-*.instructions.md required-footers: - ai-content-note artifacts: - control-surface-catalog - evidence-register + - supply-chain-inventory + - standards-mapping # Human-facing artifacts: Tier 1 note + human review checkbox human-facing: scope: - .github/instructions/rai-planning/** + - .github/instructions/security/sssc-*.instructions.md required-footers: - ai-content-note - human-review-checkbox @@ -53,9 +57,11 @@ artifact-classification: - rai-review-summary - transparency-note - monitoring-summary + - gap-analysis + - sssc-backlog - # Human-facing with disclaimer: Tier 1 + checkbox + Tier 2 disclaimer - human-facing-with-disclaimer: + # RAI handoff with disclaimer: Tier 1 + checkbox + Tier 2 RAI disclaimer + rai-handoff-with-disclaimer: scope: - .github/instructions/rai-planning/** required-footers: @@ -66,3 +72,16 @@ artifact-classification: artifacts: - handoff-summary - compact-handoff-summary + + # SSSC handoff with disclaimer: Tier 1 + checkbox + Tier 2 SSSC disclaimer + sssc-handoff-with-disclaimer: + scope: + - .github/instructions/security/sssc-*.instructions.md + required-footers: + - ai-content-note + - human-review-checkbox + requires-disclaimer: true + disclaimer-ref: sssc-full-disclaimer + artifacts: + - handoff-summary + - compact-handoff-summary diff --git a/.github/instructions/security/sssc-assessment.instructions.md b/.github/instructions/security/sssc-assessment.instructions.md index 3646ce1d5..cecde411c 100644 --- a/.github/instructions/security/sssc-assessment.instructions.md +++ b/.github/instructions/security/sssc-assessment.instructions.md @@ -91,6 +91,8 @@ Structure the output as: ### Shared Capabilities {per-capability assessment} + +> **Note** — The author created this content with assistance from AI. All outputs should be reviewed and validated by a qualified human reviewer before use. ``` Update `state.json`: diff --git a/.github/instructions/security/sssc-backlog.instructions.md b/.github/instructions/security/sssc-backlog.instructions.md index 553bf367e..5d9d893a5 100644 --- a/.github/instructions/security/sssc-backlog.instructions.md +++ b/.github/instructions/security/sssc-backlog.instructions.md @@ -41,6 +41,9 @@ Each generated work item follows this structure: ### GitHub Mapping - Labels: supply-chain, ossf, {scorecard-check}, {adoption-type} - Milestone: {milestone} + +> **Note** — The author created this content with assistance from AI. All outputs should be reviewed and validated by a qualified human reviewer before use. +> - [ ] Reviewed and validated by a qualified human reviewer ``` ## Priority Derivation @@ -127,6 +130,9 @@ Markdown template for GitHub issue body: - [ ] {criterion_1} - [ ] {criterion_2} + +> **Note** — The author created this content with assistance from AI. All outputs should be reviewed and validated by a qualified human reviewer before use. +> - [ ] Reviewed and validated by a qualified human reviewer ``` ## Content Sanitization diff --git a/.github/instructions/security/sssc-gap-analysis.instructions.md b/.github/instructions/security/sssc-gap-analysis.instructions.md index 8a6a48048..909371247 100644 --- a/.github/instructions/security/sssc-gap-analysis.instructions.md +++ b/.github/instructions/security/sssc-gap-analysis.instructions.md @@ -11,9 +11,11 @@ Compare the repository's current supply chain security posture against the desir Produce a prioritized gap table sorted by Scorecard risk level (Critical > High > Medium > Low): -| Gap | Scorecard Check | Risk | Current State | Target State | Adoption Type | Effort | Workflow/Script Reference | -|---------------|-----------------|----------------------------|---------------|--------------|---------------|------------|---------------------------| -| {description} | {check_name} | {Critical/High/Medium/Low} | {current} | {target} | {category} | {S/M/L/XL} | {reference} | +| Gap | Scorecard Check | Risk | Concern | Current State | Target State | Adoption Type | Effort | Workflow/Script Reference | +|---------------|-----------------|----------------------------|--------------------------|---------------|--------------|---------------|------------|---------------------------| +| {description} | {check_name} | {Critical/High/Medium/Low} | {Low / Moderate / High} | {current} | {target} | {category} | {S/M/L/XL} | {reference} | + +The `Risk` column carries the OpenSSF Scorecard risk classification. The `Concern` column carries the qualitative residual concern level after considering the repository's current posture and compensating controls (Low, Moderate, or High). Concern is independent from Effort — a small effort may still address a high-concern gap. Include all 20 Scorecard checks and any additional SLSA, Badge, Sigstore, or SBOM gaps not directly mapped to a Scorecard check. @@ -68,6 +70,18 @@ Assign T-shirt sizes based on implementation scope: | L | Cross-cutting changes across CI/CD pipeline | 3–5 days | | XL | New capability build or major architectural change | 1+ weeks | +## Qualitative Concern Levels + +Assign a qualitative concern level to each gap reflecting residual risk after considering the repository's current posture and compensating controls. Concern is independent from Scorecard risk classification and from effort sizing. + +| Concern | Criteria | +|----------|-----------------------------------------------------------------------------------------------------------| +| Low | Gap is informational or already partially mitigated by existing controls; minimal residual exposure | +| Moderate | Gap leaves measurable residual exposure but compensating controls reduce immediate impact | +| High | Gap leaves significant residual exposure with no effective compensating controls; prioritize remediation | + +Record concern in the gap table alongside Risk and Effort. Use Concern to break ties when multiple gaps share the same Scorecard risk classification. + ## Full 20-Check Reference Mapping Use this reference table when mapping gaps. It provides the known implementation sources for each Scorecard check: diff --git a/.github/instructions/security/sssc-handoff.instructions.md b/.github/instructions/security/sssc-handoff.instructions.md index 19adb71f2..a124237c7 100644 --- a/.github/instructions/security/sssc-handoff.instructions.md +++ b/.github/instructions/security/sssc-handoff.instructions.md @@ -14,7 +14,12 @@ Validate the complete SSSC plan, generate improvement projections, and produce p 3. Generate improvement projections (see below). 4. Present the complete plan to the user for final review. 5. On confirmation, generate platform-specific handoff files. -6. Update `state.json` handoff flags. +6. Sign planner artifacts (see [Signed Artifact Manifest](#signed-artifact-manifest)). +7. Update `state.json` handoff flags and signing fields. + +## Threat ID Convention + +When handoff outputs cross-reference threats produced by the Security Planner (or any upstream threat-modeling artifact captured via `securityPlannerLink`), use the canonical token `T-SEC-{NNN}` with sequential, zero-padded numbering scoped to the Security Planner session being referenced. This token is the only form accepted in SSSC handoff descriptions, work item bodies, and improvement-projection rows; it preserves traceability back to the originating Security Planner outputs without re-deriving threat content inside SSSC artifacts. ## Scorecard Improvement Projection @@ -86,8 +91,28 @@ After generating handoff files, produce a summary covering: Update `state.json`: * Set `phases.6-handoff.status` to `✅` * Update `handoffGenerated` flags for each platform written +* Set `signingManifestPath` to the manifest path returned by `Sign-PlannerArtifacts.ps1` when signing completed * Clear `nextActions` (or populate with post-handoff recommendations) +## Signed Artifact Manifest + +After both platform-specific handoff files are written, sign the SSSC planner artifacts by invoking the shared planner signing script. Use the session-path parameter set so the manifest is emitted as `sssc-manifest.json` inside the active SSSC session directory: + +```pwsh +pwsh scripts/security/Sign-PlannerArtifacts.ps1 -SessionPath '.copilot-tracking/sssc-plans/' -ManifestName 'sssc-manifest.json' +``` + +Append `-IncludeCosign` when the user has opted in to cosign keyless signing via `userPreferences.signingRequested`. Cosign keyless signing requires `cosign` in PATH and a Sigstore-compatible OIDC identity provider; the script gracefully skips signing with a warning when cosign is unavailable. + +The parameter contract for `Sign-PlannerArtifacts.ps1` exposes two mutually exclusive parameter sets: + +* `-ProjectSlug ` (RAI sessions; resolves to `.copilot-tracking/rai-plans//`). +* `-SessionPath ` (any planner session, including SSSC; absolute or repo-relative directory). +* `-ManifestName ` (optional; defaults to `artifact-manifest.json`; SSSC sessions must pass `sssc-manifest.json`). +* `-OutputPath ` (optional; full path override that takes precedence over `-ManifestName`). + +On success, capture the manifest path returned by the script and update `state.json` field `signingManifestPath`. The `sssc-manifest.json` file (and, when cosign is used, the accompanying `.sig` and `.bundle` siblings) becomes the verifiable record covering every artifact under the SSSC session directory at handoff time. + Present the user with next steps: * For ADO: invoke the ADO Backlog Manager to create work items from the handoff file * For GitHub: invoke the GitHub Backlog Manager to create issues from the handoff file diff --git a/.github/instructions/security/sssc-identity.instructions.md b/.github/instructions/security/sssc-identity.instructions.md index 6a63b2b38..742514d76 100644 --- a/.github/instructions/security/sssc-identity.instructions.md +++ b/.github/instructions/security/sssc-identity.instructions.md @@ -119,6 +119,9 @@ State persists across sessions in a JSON file at `.copilot-tracking/sssc-plans/{ "nextActions": [], "userPreferences": { "autonomyTier": "partial" }, "ssscEnabled": true, + "signingRequested": false, + "signingManifestPath": null, + "disclaimerShownAt": null, "securityPlannerLink": null, "raiPlannerLink": null } @@ -145,6 +148,9 @@ On first invocation, create the project directory and `state.json` with Phase 1 * `entryMode` set based on the invoking prompt (capture, from-prd, from-brd, or from-security-plan) * All arrays empty, booleans `false` * `ssscEnabled` set to `true` +* `signingRequested` set to `false` until the user opts in during scoping +* `signingManifestPath` set to `null` until handoff signing runs +* `disclaimerShownAt` set to `null` until the SSSC Planning disclaimer is presented at session start ### State Transitions diff --git a/.github/instructions/security/sssc-standards.instructions.md b/.github/instructions/security/sssc-standards.instructions.md index e84f67708..e88e98c59 100644 --- a/.github/instructions/security/sssc-standards.instructions.md +++ b/.github/instructions/security/sssc-standards.instructions.md @@ -1,11 +1,11 @@ --- -description: "Phase 3 OpenSSF Scorecard, SLSA, Best Practices Badge, Sigstore, and SBOM standards mapping for SSSC Planner." +description: "Phase 3 OpenSSF Scorecard, SLSA v1.0, OpenSSF Best Practices Badge, Sigstore (cosign), and NTIA SBOM minimum elements standards mapping for SSSC Planner." applyTo: '**/.copilot-tracking/sssc-plans/**' --- # SSSC Phase 3: Standards Mapping -Map the assessed supply chain posture against OpenSSF® standards. Use the Phase 2 assessment results as input. +Map the assessed supply chain posture against the open standards anchored below: OpenSSF Scorecard, SLSA v1.0, OpenSSF Best Practices Badge, Sigstore (cosign), and NTIA SBOM minimum elements. Use the Phase 2 assessment results as input. ## OpenSSF Scorecard: 20 Checks @@ -41,9 +41,9 @@ For each check, record: * **Available implementation** (which hve-core or PAT workflow/script addresses this check) * **Gap** (what is missing to achieve maximum score) -## SLSA Build Track Levels +## SLSA v1.0 Build Track Levels -Assess the repository against SLSA Build track requirements: +Assess the repository against SLSA v1.0 Build track requirements: | Level | Requirements | Assessment Criteria | |----------|---------------------------------------------------|-------------------------------------------------------------| @@ -54,7 +54,7 @@ Assess the repository against SLSA Build track requirements: Record current level and specific steps needed to reach the next level. -## Best Practices Badge Criteria +## OpenSSF Best Practices Badge Criteria Assess readiness against OpenSSF Best Practices Badge tiers: @@ -66,27 +66,27 @@ Assess readiness against OpenSSF Best Practices Badge tiers: Map repository files and practices to Badge criteria. Flag missing criteria as gaps. -## Sigstore Standards +## Sigstore (cosign) Standards -Assess Sigstore adoption maturity: +Assess Sigstore adoption maturity using cosign as the canonical signing tool: * **Not adopted**: No signing or attestation in place -* **Basic**: Build provenance via `actions/attest-build-provenance` +* **Basic**: Build provenance via `actions/attest-build-provenance` (cosign-backed) * **Intermediate**: Build provenance + SBOM attestation via `actions/attest` -* **Advanced**: Tag signing via gitsign + build provenance + SBOM attestation + verification workflow +* **Advanced**: Tag signing via gitsign + cosign artifact signing + build provenance + SBOM attestation + verification workflow Document current level and steps to advance. -## SBOM Standards +## NTIA SBOM Minimum Elements -Assess SBOM generation and distribution: +Assess SBOM generation and distribution against NTIA SBOM minimum elements: * **Format**: SPDX-JSON (preferred for GitHub ecosystem) or CycloneDX * **Generator**: anchore/sbom-action with syft, or Microsoft SBOM Tool * **Distribution**: Attached to release artifacts, published to dependency graph -* **NTIA minimum elements**: Supplier, component name, version, unique identifier, dependency relationship, author, timestamp +* **NTIA SBOM minimum elements**: Supplier, component name, version, unique identifier, dependency relationship, author, timestamp -Verify NTIA minimum element compliance for existing SBOM output. +Verify NTIA SBOM minimum element compliance for existing SBOM output. ## Researcher Subagent Delegation diff --git a/.github/prompts/security/sssc-capture.prompt.md b/.github/prompts/security/sssc-capture.prompt.md index b840f0b4a..5be7aa2ac 100644 --- a/.github/prompts/security/sssc-capture.prompt.md +++ b/.github/prompts/security/sssc-capture.prompt.md @@ -1,20 +1,66 @@ --- -description: "Start a new SSSC assessment via guided conversation using the SSSC Planner agent in capture mode" +description: >- + Initiate supply chain security planning from existing knowledge using the + SSSC Planner agent in capture mode agent: sssc-planner --- # SSSC Capture +Activate the SSSC Planner in **capture mode** for project slug `${input:project-slug}`. + +## Startup + +Before any phase work, check `state.json` for `disclaimerShownAt`. If `disclaimerShownAt` is `null` or `state.json` does not yet exist, display the SSSC Planning CAUTION block from #file:../../instructions/shared/disclaimer-language.instructions.md verbatim and set `disclaimerShownAt` to the current ISO 8601 timestamp in `state.json`. + +After the disclaimer, announce the SSSC Planner standards baseline following the Disclaimer and Attribution Protocol in #file:../../instructions/security/sssc-identity.instructions.md: OpenSSF Scorecard, SLSA Build Levels, OpenSSF Best Practices Badge, Sigstore, and SBOM standards (CycloneDX, SPDX). + ## Inputs -* ${input:project-slug}: (Optional) Kebab-case project identifier for the artifact directory. When omitted, asks for a suitable project name and derives the slug. +* `${input:project-slug}`: (Optional) Kebab-case project identifier for the artifact directory. When omitted, ask for a suitable project name and derive the slug. ## Requirements -* Initialize capture mode by creating the project directory at `.copilot-tracking/sssc-plans/{project-slug}/` and writing `state.json` with `entryMode: "capture"`, `currentPhase: 1`, and empty or default values for remaining fields. -* If the user provides existing supply chain security notes, workflow inventories, or documentation as input, extract relevant information and pre-populate Phase 1 fields before asking clarifying questions. -* Begin the Phase 1 interview about the project's supply chain security posture with 3-5 focused questions covering: project name and purpose, technology stack, package managers, CI/CD platform, release strategy, and known compliance targets (OpenSSF Scorecard, SLSA, Best Practices Badge). +### Pre-Scan + +Before initialization, scan the workspace for context that can pre-populate Phase 1: + +* `package.json`, `pyproject.toml`, `*.csproj`, `Cargo.toml`, `go.mod` — language and package manager inventory. +* `.github/workflows/`, `.azure-pipelines/`, `azure-pipelines*.yml`, `Jenkinsfile`, `.gitlab-ci.yml` — CI/CD platform. +* `release-please-config.json`, `.releaserc*`, `CHANGELOG.md` — release strategy. +* `Dockerfile`, `compose.yaml`, `helm/`, `k8s/`, `terraform/`, `bicep/` — deployment surfaces. +* `SECURITY.md`, `.github/dependabot.yml`, CodeQL or secret-scanning configuration — existing security tooling. +* `.copilot-tracking/security-plans/`, `.copilot-tracking/rai-plans/`, `.copilot-tracking/prd-sessions/`, `.copilot-tracking/brd-sessions/` — sibling planner artifacts to cross-link. +* `.copilot-tracking/sssc-plans/references/` — user-supplied evaluation standards, workflow inventories, or output format requirements. + +Present pre-scan results as a checklist: + +* ✅ Discovered context with file paths and brief descriptions +* ❌ Expected sources that were not found + +### Output Preferences + +Ask the user up front whether they have output preferences for backlog generation in Phase 5: dual-format ADO and GitHub work items, single-platform output, or a custom template stored under `.copilot-tracking/sssc-plans/references/`. Capture the answer in `state.json` under `outputPreferences` so later phases honor the choice without re-asking. + +### Initialization + +Create the project directory at `.copilot-tracking/sssc-plans/${input:project-slug}/`. + +Write `state.json` with `entryMode` set to `"capture"`, `currentPhase` set to `1`, preserving `disclaimerShownAt` if already set, and remaining fields at their schema defaults. + +If the user has provided existing supply chain notes, workflow inventories, or compliance documentation, extract relevant details and pre-populate Phase 1 fields where possible. + +### Phase 1 Entry + +Present a short summary sentence describing the assessment scope, then invite the user into a Phase 1 conversation with up to 5 focused questions covering: -## Entry Behavior +* Project name and supply chain security purpose +* Programming languages, frameworks, and package managers +* CI/CD platform and runner topology +* Release strategy and artifact distribution channels +* Deployment targets and registry destinations +* Existing security tooling (Dependabot, CodeQL, secret scanning, signing) +* Compliance targets (Scorecard threshold, SLSA Build level, Best Practices Badge tier) +* User-supplied evaluation standards, workflow inventories, or output format requirements to store in `.copilot-tracking/sssc-plans/references/` -Start supply chain security planning in capture mode. Initialize the project directory and begin the Phase 1 scoping interview. +Use facilitative phrasing — invite confirmation and refinement rather than dictating answers — and mark each question with ❓ pending, ✅ complete, or ❌ blocked or skipped as the conversation progresses. diff --git a/.github/prompts/security/sssc-from-brd.prompt.md b/.github/prompts/security/sssc-from-brd.prompt.md index 9f6561c9b..b5772a6c3 100644 --- a/.github/prompts/security/sssc-from-brd.prompt.md +++ b/.github/prompts/security/sssc-from-brd.prompt.md @@ -1,34 +1,79 @@ --- -description: "Start an SSSC assessment from existing BRD artifacts using the SSSC Planner agent" +description: >- + Initiate supply chain security planning from existing BRD artifacts using the + SSSC Planner agent in from-brd mode agent: sssc-planner --- # SSSC from BRD -Activate the SSSC Planner in **from-brd mode** to bootstrap a supply chain security assessment from existing business requirements documents. +Activate the SSSC Planner in **from-brd mode** for project slug `${input:project-slug}`. + +## Startup + +Before any phase work, check `state.json` for `disclaimerShownAt`. If `disclaimerShownAt` is `null` or `state.json` does not yet exist, display the SSSC Planning CAUTION block from #file:../../instructions/shared/disclaimer-language.instructions.md verbatim and set `disclaimerShownAt` to the current ISO 8601 timestamp in `state.json`. + +After the disclaimer, announce the SSSC Planner standards baseline following the Disclaimer and Attribution Protocol in #file:../../instructions/security/sssc-identity.instructions.md: OpenSSF Scorecard, SLSA Build Levels, OpenSSF Best Practices Badge, Sigstore, and SBOM standards (CycloneDX, SPDX). ## Inputs -* ${input:project-slug}: (Optional) Project slug for the SSSC plan directory. When omitted, derive from the discovered BRD project name. +* `${input:project-slug}`: (Optional) Project slug for the SSSC plan directory. When omitted, derive from the discovered BRD project name. ## Requirements -### BRD Discovery +### Pre-Scan -Scan these directories as the primary discovery path: +Scan the workspace for BRD artifacts and supporting context: + +**Primary paths:** * `.copilot-tracking/brd-sessions/` for business requirements documents -If the primary path yields no matches, perform a secondary scan of `.copilot-tracking/` for files whose names match `brd-*.md`, `*-brd.md`, or `business-requirements*.md`. Exclude generic matches like `requirements.txt` or files outside business-scoping contexts. +**Secondary scan:** + +* `.copilot-tracking/` for files matching `brd-*.md`, `*-brd.md`, or `business-requirements*.md`. Exclude generic matches like `requirements.txt` or files outside business-scoping contexts. + +**Supporting context:** + +* `package.json`, `pyproject.toml`, `*.csproj`, `Cargo.toml`, `go.mod` — language and package manager inventory. +* `.github/workflows/`, `.azure-pipelines/`, `Jenkinsfile`, `.gitlab-ci.yml` — CI/CD platform. +* `.copilot-tracking/security-plans/`, `.copilot-tracking/rai-plans/`, `.copilot-tracking/prd-sessions/` — sibling planner artifacts to cross-link. +* `.copilot-tracking/sssc-plans/references/` — user-supplied evaluation standards or output format requirements. + +Present pre-scan results as a checklist: + +* ✅ Discovered BRD artifacts and supporting context with file paths and brief descriptions +* ❌ Expected sources that were not found -Present all discovery results to the user for confirmation before proceeding. +If zero BRD artifacts are found, fall back to capture mode and explain the switch. + +### Output Preferences + +Ask the user up front whether they have output preferences for backlog generation in Phase 5: dual-format ADO and GitHub work items, single-platform output, or a custom template stored under `.copilot-tracking/sssc-plans/references/`. Capture the answer in `state.json` under `outputPreferences` so later phases honor the choice without re-asking. + +### Scope Extraction + +Extract from the discovered BRD artifacts: + +1. Project name and supply chain security purpose +2. Compliance requirements and regulatory drivers +3. Technology stack and integration points +4. Deployment targets and distribution channels +5. Stakeholder expectations and acceptance criteria ### Initialization -* Create the project directory at `.copilot-tracking/sssc-plans/{project-slug}/` and write `state.json` with `entryMode: "from-brd"`, `currentPhase: 1`, and remaining fields populated from BRD context. -* Extract technology stack, compliance requirements, integration points, and deployment targets from the BRD. -* Pre-populate Phase 1 scoping fields with extracted information and ask 3-5 confirmation questions to verify accuracy and fill gaps. +Create the project directory at `.copilot-tracking/sssc-plans/${input:project-slug}/`. + +Write `state.json` with `entryMode` set to `"from-brd"`, `currentPhase` set to `1`, preserving `disclaimerShownAt` if already set, and remaining fields populated from the extracted BRD context. + +### Phase 1 Entry + +Present the extracted scope as a checklist with markers: + +* ✅ Items confirmed from the BRD +* ❓ Items that need clarification or are missing -## Entry Behavior +Then invite the user into a Phase 1 conversation with 3 to 5 facilitative clarifying questions targeting supply chain gaps not covered by the BRD, such as package manager inventory, CI/CD topology, signing strategy, SBOM tooling, and Best Practices Badge readiness. Use confirmation-and-refinement phrasing rather than directives. -Start supply chain security planning from BRD artifacts. Discover BRD files, extract context, initialize the project directory, and begin Phase 1 with pre-populated scoping data. +Also ask whether the user has evaluation standards, workflow inventories, or output format requirements to supply for storage in `.copilot-tracking/sssc-plans/references/`. diff --git a/.github/prompts/security/sssc-from-prd.prompt.md b/.github/prompts/security/sssc-from-prd.prompt.md index 00ab44eed..fda147b5b 100644 --- a/.github/prompts/security/sssc-from-prd.prompt.md +++ b/.github/prompts/security/sssc-from-prd.prompt.md @@ -1,34 +1,79 @@ --- -description: "Start an SSSC assessment from existing PRD artifacts using the SSSC Planner agent" +description: >- + Initiate supply chain security planning from existing PRD artifacts using the + SSSC Planner agent in from-prd mode agent: sssc-planner --- # SSSC from PRD -Activate the SSSC Planner in **from-prd mode** to bootstrap a supply chain security assessment from existing product definition artifacts. +Activate the SSSC Planner in **from-prd mode** for project slug `${input:project-slug}`. + +## Startup + +Before any phase work, check `state.json` for `disclaimerShownAt`. If `disclaimerShownAt` is `null` or `state.json` does not yet exist, display the SSSC Planning CAUTION block from #file:../../instructions/shared/disclaimer-language.instructions.md verbatim and set `disclaimerShownAt` to the current ISO 8601 timestamp in `state.json`. + +After the disclaimer, announce the SSSC Planner standards baseline following the Disclaimer and Attribution Protocol in #file:../../instructions/security/sssc-identity.instructions.md: OpenSSF Scorecard, SLSA Build Levels, OpenSSF Best Practices Badge, Sigstore, and SBOM standards (CycloneDX, SPDX). ## Inputs -* ${input:project-slug}: (Optional) Project slug for the SSSC plan directory. When omitted, derive from the discovered PRD project name. +* `${input:project-slug}`: (Optional) Project slug for the SSSC plan directory. When omitted, derive from the discovered PRD project name. ## Requirements -### PRD Discovery +### Pre-Scan -Scan these directories as the primary discovery path: +Scan the workspace for PRD artifacts and supporting context: + +**Primary paths:** * `.copilot-tracking/prd-sessions/` for product requirements documents -If the primary path yields no matches, perform a secondary scan of `.copilot-tracking/` for files whose names match `prd-*.md`, `*-prd.md`, or `product-definition*.md`. Exclude generic matches like `requirements.txt` or files outside product-scoping contexts. +**Secondary scan:** + +* `.copilot-tracking/` for files matching `prd-*.md`, `*-prd.md`, or `product-definition*.md`. Exclude generic matches like `requirements.txt` or files outside product-scoping contexts. + +**Supporting context:** + +* `package.json`, `pyproject.toml`, `*.csproj`, `Cargo.toml`, `go.mod` — language and package manager inventory. +* `.github/workflows/`, `.azure-pipelines/`, `Jenkinsfile`, `.gitlab-ci.yml` — CI/CD platform. +* `.copilot-tracking/security-plans/`, `.copilot-tracking/rai-plans/` — sibling planner artifacts to cross-link. +* `.copilot-tracking/sssc-plans/references/` — user-supplied evaluation standards or output format requirements. + +Present pre-scan results as a checklist: + +* ✅ Discovered PRD artifacts and supporting context with file paths and brief descriptions +* ❌ Expected sources that were not found -Present all discovery results to the user for confirmation before proceeding. +If zero PRD artifacts are found, fall back to capture mode and explain the switch. + +### Output Preferences + +Ask the user up front whether they have output preferences for backlog generation in Phase 5: dual-format ADO and GitHub work items, single-platform output, or a custom template stored under `.copilot-tracking/sssc-plans/references/`. Capture the answer in `state.json` under `outputPreferences` so later phases honor the choice without re-asking. + +### Scope Extraction + +Extract from the discovered PRD artifacts: + +1. Project name and supply chain security purpose +2. Technology stack and package managers +3. CI/CD platform and release strategy +4. Deployment targets and registry destinations +5. Compliance requirements and integration points ### Initialization -* Create the project directory at `.copilot-tracking/sssc-plans/{project-slug}/` and write `state.json` with `entryMode: "from-prd"`, `currentPhase: 1`, and remaining fields populated from PRD context. -* Extract technology stack, package managers, CI/CD platform, deployment targets, and integration points from the PRD. -* Pre-populate Phase 1 scoping fields with extracted information and ask 3-5 confirmation questions to verify accuracy and fill gaps. +Create the project directory at `.copilot-tracking/sssc-plans/${input:project-slug}/`. + +Write `state.json` with `entryMode` set to `"from-prd"`, `currentPhase` set to `1`, preserving `disclaimerShownAt` if already set, and remaining fields populated from the extracted PRD context. + +### Phase 1 Entry + +Present the extracted scope as a checklist with markers: + +* ✅ Items confirmed from the PRD +* ❓ Items that need clarification or are missing -## Entry Behavior +Then invite the user into a Phase 1 conversation with 3 to 5 facilitative clarifying questions targeting supply chain gaps not covered by the PRD, such as runner topology, signing strategy, SBOM tooling, and Best Practices Badge readiness. Use confirmation-and-refinement phrasing rather than directives. -Start supply chain security planning from PRD artifacts. Discover PRD files, extract context, initialize the project directory, and begin Phase 1 with pre-populated scoping data. +Also ask whether the user has evaluation standards, workflow inventories, or output format requirements to supply for storage in `.copilot-tracking/sssc-plans/references/`. diff --git a/.github/prompts/security/sssc-from-security-plan.prompt.md b/.github/prompts/security/sssc-from-security-plan.prompt.md index 6b807a476..7bc7581eb 100644 --- a/.github/prompts/security/sssc-from-security-plan.prompt.md +++ b/.github/prompts/security/sssc-from-security-plan.prompt.md @@ -1,33 +1,75 @@ --- -description: "Extend a Security Planner assessment with supply chain coverage using the SSSC Planner agent" +description: >- + Extend a Security Planner assessment with supply chain coverage using the + SSSC Planner agent in from-security-plan mode agent: sssc-planner --- # SSSC from Security Plan -Activate the SSSC Planner in **from-security-plan mode** to extend an existing Security Planner assessment with supply chain security coverage. +Activate the SSSC Planner in **from-security-plan mode** for project slug `${input:project-slug}`. + +## Startup + +Before any phase work, check `state.json` for `disclaimerShownAt`. If `disclaimerShownAt` is `null` or `state.json` does not yet exist, display the SSSC Planning CAUTION block from #file:../../instructions/shared/disclaimer-language.instructions.md verbatim and set `disclaimerShownAt` to the current ISO 8601 timestamp in `state.json`. + +After the disclaimer, announce the SSSC Planner standards baseline following the Disclaimer and Attribution Protocol in #file:../../instructions/security/sssc-identity.instructions.md: OpenSSF Scorecard, SLSA Build Levels, OpenSSF Best Practices Badge, Sigstore, and SBOM standards (CycloneDX, SPDX). ## Inputs -* ${input:project-slug}: (Optional) Project slug for the SSSC plan directory. When omitted, derive from the discovered security plan project name. +* `${input:project-slug}`: (Optional) Project slug for the SSSC plan directory. When omitted, derive from the discovered security plan project name. ## Requirements -### Security Plan Discovery +### Pre-Scan + +Scan the workspace for Security Planner artifacts and supporting context: + +**Primary paths:** + +* `.copilot-tracking/security-plans/` for Security Planner project subdirectories. Look for `state.json` within each subdirectory. If multiple plans exist, present all candidates to the user for selection. + +**Supporting context:** + +* `package.json`, `pyproject.toml`, `*.csproj`, `Cargo.toml`, `go.mod` — language and package manager inventory. +* `.github/workflows/`, `.azure-pipelines/`, `Jenkinsfile`, `.gitlab-ci.yml` — CI/CD platform. +* `.copilot-tracking/rai-plans/`, `.copilot-tracking/prd-sessions/`, `.copilot-tracking/brd-sessions/` — sibling planner artifacts to cross-link. +* `.copilot-tracking/sssc-plans/references/` — user-supplied evaluation standards or output format requirements. + +Present pre-scan results as a checklist: -Scan these directories as the primary discovery path: +* ✅ Discovered security plans and supporting context with file paths and brief descriptions +* ❌ Expected sources that were not found -* `.copilot-tracking/security-plans/` for Security Planner artifacts +If zero Security Planner artifacts are found, fall back to capture mode and explain the switch. -Look for existing `state.json` files within subdirectories. If multiple security plans exist, present all candidates to the user for selection. +### Output Preferences + +Ask the user up front whether they have output preferences for backlog generation in Phase 5: dual-format ADO and GitHub work items, single-platform output, or a custom template stored under `.copilot-tracking/sssc-plans/references/`. Capture the answer in `state.json` under `outputPreferences` so later phases honor the choice without re-asking. + +### Scope Extraction + +Read the selected Security Planner `state.json` and completed artifacts. Extract: + +1. Technology stack and deployment targets +2. Compliance requirements and regulatory drivers +3. Threat model findings and operational buckets +4. Identified security controls and gaps +5. Cross-domain mapping from application-level threats to dependency and build pipeline priorities ### Initialization -* Create the project directory at `.copilot-tracking/sssc-plans/{project-slug}/` and write `state.json` with `entryMode: "from-security-plan"`, `currentPhase: 1`, and `securityPlannerLink` set to the path of the source security plan. -* Read the Security Planner's `state.json` and completed artifacts to extract: technology stack, deployment targets, compliance requirements, threat model findings, and identified security controls. -* Map Security Planner findings to supply chain context: application-level threats inform dependency and build pipeline priorities. -* Pre-populate Phase 1 scoping fields with extracted information and ask 3-5 confirmation questions to verify accuracy and identify supply-chain-specific details not covered by the security plan (package managers, CI/CD pipeline details, release strategy). +Create the project directory at `.copilot-tracking/sssc-plans/${input:project-slug}/`. + +Write `state.json` with `entryMode` set to `"from-security-plan"`, `currentPhase` set to `1`, `securityPlannerLink` set to the path of the source security plan, preserving `disclaimerShownAt` if already set, and remaining fields populated from the extracted security plan context. + +### Phase 1 Entry + +Present the extracted scope as a checklist with markers: + +* ✅ Items confirmed from the Security Planner artifacts +* ❓ Items that need clarification or are missing -## Entry Behavior +Then invite the user into a Phase 1 conversation with 3 to 5 facilitative clarifying questions targeting supply chain gaps not covered by the security plan, such as package manager inventory, CI/CD pipeline topology, release strategy, signing posture, SBOM tooling, and Best Practices Badge readiness. Use confirmation-and-refinement phrasing rather than directives. -Start supply chain security planning from Security Planner artifacts. Discover security plan files, extract cross-domain context, initialize the project directory, and begin Phase 1 with pre-populated scoping data enriched by existing security findings. +Also ask whether the user has evaluation standards, workflow inventories, or output format requirements to supply for storage in `.copilot-tracking/sssc-plans/references/`. diff --git a/collections/hve-core-all.collection.md b/collections/hve-core-all.collection.md index 0403a774a..71863895b 100644 --- a/collections/hve-core-all.collection.md +++ b/collections/hve-core-all.collection.md @@ -128,10 +128,10 @@ Use this edition when you want access to everything without choosing a focused c | **security-review-llm** | Runs OWASP LLM and Agentic vulnerability assessments with codebase profiling for context | | **security-review-sbd** | Runs a Secure by Design principles assessment based on UK and Australian government guidance | | **security-review-web** | Runs an OWASP Top 10 web vulnerability assessment without codebase profiling | -| **sssc-capture** | Start a new SSSC assessment via guided conversation using the SSSC Planner agent in capture mode | -| **sssc-from-brd** | Start an SSSC assessment from existing BRD artifacts using the SSSC Planner agent | -| **sssc-from-prd** | Start an SSSC assessment from existing PRD artifacts using the SSSC Planner agent | -| **sssc-from-security-plan** | Extend a Security Planner assessment with supply chain coverage using the SSSC Planner agent | +| **sssc-capture** | Initiate supply chain security planning from existing knowledge using the SSSC Planner agent in capture mode | +| **sssc-from-brd** | Initiate supply chain security planning from existing BRD artifacts using the SSSC Planner agent in from-brd mode | +| **sssc-from-prd** | Initiate supply chain security planning from existing PRD artifacts using the SSSC Planner agent in from-prd mode | +| **sssc-from-security-plan** | Extend a Security Planner assessment with supply chain coverage using the SSSC Planner agent in from-security-plan mode | | **synth-data-generate** | Generate comprehensive synthetic data for any specified subject with realistic patterns and relationships | | **task-challenge** | Adversarial What/Why/How interrogation of completed implementation artifacts | | **task-implement** | Locates and executes implementation plans using Task Implementor | @@ -242,7 +242,7 @@ Use this edition when you want access to everything without choosing a focused c | **security/sssc-gap-analysis** | Phase 4 gap comparison, adoption categorization, and effort sizing for SSSC Planner. | | **security/sssc-handoff** | Phase 6 backlog handoff protocol with Scorecard projections and dual-format output for SSSC Planner. | | **security/sssc-identity** | Identity and orchestration instructions for the SSSC Planner agent. Contains six-phase workflow, state.json schema, session recovery, and question cadence. | -| **security/sssc-standards** | Phase 3 OpenSSF Scorecard, SLSA, Best Practices Badge, Sigstore, and SBOM standards mapping for SSSC Planner. | +| **security/sssc-standards** | Phase 3 OpenSSF Scorecard, SLSA v1.0, OpenSSF Best Practices Badge, Sigstore (cosign), and NTIA SBOM minimum elements standards mapping for SSSC Planner. | | **security/standards-mapping** | Embedded OWASP and NIST security standards with researcher subagent delegation for CIS, WAF, CAF, and other runtime lookups | | **shared/disclaimer-language** | Centralized disclaimer language for AI-assisted planning agents requiring professional review acknowledgment | | **shared/hve-core-location** | Important: hve-core is the repository containing this instruction file; Guidance: if a referenced prompt, instructions, agent, or script is missing in the current directory, fall back to this hve-core location by walking up this file's directory tree. | diff --git a/collections/project-planning.collection.md b/collections/project-planning.collection.md index 292f67dba..055750b6b 100644 --- a/collections/project-planning.collection.md +++ b/collections/project-planning.collection.md @@ -37,10 +37,10 @@ Create architecture decision records, requirements documents, and diagrams — a | **risk-register** | Creates a concise and well-structured qualitative risk register using a Probability × Impact (P×I) risk matrix. | | **security-capture** | Initiate security planning from existing notes or knowledge using the Security Planner agent in capture mode | | **security-plan-from-prd** | Initiate security planning from PRD/BRD artifacts using the Security Planner agent in from-prd mode | -| **sssc-capture** | Start a new SSSC assessment via guided conversation using the SSSC Planner agent in capture mode | -| **sssc-from-brd** | Start an SSSC assessment from existing BRD artifacts using the SSSC Planner agent | -| **sssc-from-prd** | Start an SSSC assessment from existing PRD artifacts using the SSSC Planner agent | -| **sssc-from-security-plan** | Extend a Security Planner assessment with supply chain coverage using the SSSC Planner agent | +| **sssc-capture** | Initiate supply chain security planning from existing knowledge using the SSSC Planner agent in capture mode | +| **sssc-from-brd** | Initiate supply chain security planning from existing BRD artifacts using the SSSC Planner agent in from-brd mode | +| **sssc-from-prd** | Initiate supply chain security planning from existing PRD artifacts using the SSSC Planner agent in from-prd mode | +| **sssc-from-security-plan** | Extend a Security Planner assessment with supply chain coverage using the SSSC Planner agent in from-security-plan mode | ### Instructions @@ -62,7 +62,7 @@ Create architecture decision records, requirements documents, and diagrams — a | **security/sssc-gap-analysis** | Phase 4 gap comparison, adoption categorization, and effort sizing for SSSC Planner. | | **security/sssc-handoff** | Phase 6 backlog handoff protocol with Scorecard projections and dual-format output for SSSC Planner. | | **security/sssc-identity** | Identity and orchestration instructions for the SSSC Planner agent. Contains six-phase workflow, state.json schema, session recovery, and question cadence. | -| **security/sssc-standards** | Phase 3 OpenSSF Scorecard, SLSA, Best Practices Badge, Sigstore, and SBOM standards mapping for SSSC Planner. | +| **security/sssc-standards** | Phase 3 OpenSSF Scorecard, SLSA v1.0, OpenSSF Best Practices Badge, Sigstore (cosign), and NTIA SBOM minimum elements standards mapping for SSSC Planner. | | **security/standards-mapping** | Embedded OWASP and NIST security standards with researcher subagent delegation for CIS, WAF, CAF, and other runtime lookups | | **shared/disclaimer-language** | Centralized disclaimer language for AI-assisted planning agents requiring professional review acknowledgment | | **shared/hve-core-location** | Important: hve-core is the repository containing this instruction file; Guidance: if a referenced prompt, instructions, agent, or script is missing in the current directory, fall back to this hve-core location by walking up this file's directory tree. | diff --git a/collections/security.collection.md b/collections/security.collection.md index 3f7f57a38..13428c68d 100644 --- a/collections/security.collection.md +++ b/collections/security.collection.md @@ -34,10 +34,10 @@ Security review, planning, incident response, risk assessment, vulnerability ana | **security-review-llm** | Runs OWASP LLM and Agentic vulnerability assessments with codebase profiling for context | | **security-review-sbd** | Runs a Secure by Design principles assessment based on UK and Australian government guidance | | **security-review-web** | Runs an OWASP Top 10 web vulnerability assessment without codebase profiling | -| **sssc-capture** | Start a new SSSC assessment via guided conversation using the SSSC Planner agent in capture mode | -| **sssc-from-brd** | Start an SSSC assessment from existing BRD artifacts using the SSSC Planner agent | -| **sssc-from-prd** | Start an SSSC assessment from existing PRD artifacts using the SSSC Planner agent | -| **sssc-from-security-plan** | Extend a Security Planner assessment with supply chain coverage using the SSSC Planner agent | +| **sssc-capture** | Initiate supply chain security planning from existing knowledge using the SSSC Planner agent in capture mode | +| **sssc-from-brd** | Initiate supply chain security planning from existing BRD artifacts using the SSSC Planner agent in from-brd mode | +| **sssc-from-prd** | Initiate supply chain security planning from existing PRD artifacts using the SSSC Planner agent in from-prd mode | +| **sssc-from-security-plan** | Extend a Security Planner assessment with supply chain coverage using the SSSC Planner agent in from-security-plan mode | ### Instructions @@ -59,7 +59,7 @@ Security review, planning, incident response, risk assessment, vulnerability ana | **security/sssc-gap-analysis** | Phase 4 gap comparison, adoption categorization, and effort sizing for SSSC Planner. | | **security/sssc-handoff** | Phase 6 backlog handoff protocol with Scorecard projections and dual-format output for SSSC Planner. | | **security/sssc-identity** | Identity and orchestration instructions for the SSSC Planner agent. Contains six-phase workflow, state.json schema, session recovery, and question cadence. | -| **security/sssc-standards** | Phase 3 OpenSSF Scorecard, SLSA, Best Practices Badge, Sigstore, and SBOM standards mapping for SSSC Planner. | +| **security/sssc-standards** | Phase 3 OpenSSF Scorecard, SLSA v1.0, OpenSSF Best Practices Badge, Sigstore (cosign), and NTIA SBOM minimum elements standards mapping for SSSC Planner. | | **security/standards-mapping** | Embedded OWASP and NIST security standards with researcher subagent delegation for CIS, WAF, CAF, and other runtime lookups | | **shared/disclaimer-language** | Centralized disclaimer language for AI-assisted planning agents requiring professional review acknowledgment | | **shared/hve-core-location** | Important: hve-core is the repository containing this instruction file; Guidance: if a referenced prompt, instructions, agent, or script is missing in the current directory, fall back to this hve-core location by walking up this file's directory tree. | diff --git a/docs/agents/sssc-planning/agent-overview.md b/docs/agents/sssc-planning/agent-overview.md index 08c2f7e9e..bed93a0d9 100644 --- a/docs/agents/sssc-planning/agent-overview.md +++ b/docs/agents/sssc-planning/agent-overview.md @@ -64,7 +64,7 @@ All state lives in `.copilot-tracking/sssc-plans/{project-slug}/state.json`. The ### State Fields -The state file tracks 17 fields across scoping, analysis, and handoff concerns. +The state file tracks 20 fields across scoping, analysis, handoff, and trust concerns. | Field | Type | Description | |-----------------------------|----------|------------------------------------------------------------| @@ -87,6 +87,9 @@ The state file tracks 17 fields across scoping, analysis, and handoff concerns. | `nextActions` | string[] | Pending actions for the current or next phase | | `userPreferences` | object | Autonomy preference: `full`, `partial`, or `manual` | | `ssscEnabled` | boolean | Whether SSSC planning is active | +| `signingRequested` | boolean | Whether the user opted into Sigstore signing of artifacts | +| `signingManifestPath` | string | Path to the signing manifest produced after Phase 6 | +| `disclaimerShownAt` | string | ISO 8601 timestamp when the full disclaimer was shown | | `securityPlannerLink` | string | Path to the upstream Security Planner state file | | `raiPlannerLink` | string | Path to an associated RAI Planner state file | diff --git a/plugins/hve-core-all/README.md b/plugins/hve-core-all/README.md index edab24775..034748b07 100644 --- a/plugins/hve-core-all/README.md +++ b/plugins/hve-core-all/README.md @@ -412,10 +412,10 @@ copilot plugin install hve-core-all@hve-core | security-review-sbd | Runs a Secure by Design principles assessment based on UK and Australian government guidance - Brought to you by microsoft/hve-core | | security-review-web | Runs an OWASP Top 10 web vulnerability assessment without codebase profiling - Brought to you by microsoft/hve-core | | security-review | Runs an OWASP vulnerability assessment against the current codebase - Brought to you by microsoft/hve-core | -| sssc-capture | Start a new SSSC assessment via guided conversation using the SSSC Planner agent in capture mode | -| sssc-from-brd | Start an SSSC assessment from existing BRD artifacts using the SSSC Planner agent | -| sssc-from-prd | Start an SSSC assessment from existing PRD artifacts using the SSSC Planner agent | -| sssc-from-security-plan | Extend a Security Planner assessment with supply chain coverage using the SSSC Planner agent | +| sssc-capture | Initiate supply chain security planning from existing knowledge using the SSSC Planner agent in capture mode | +| sssc-from-brd | Initiate supply chain security planning from existing BRD artifacts using the SSSC Planner agent in from-brd mode | +| sssc-from-prd | Initiate supply chain security planning from existing PRD artifacts using the SSSC Planner agent in from-prd mode | +| sssc-from-security-plan | Extend a Security Planner assessment with supply chain coverage using the SSSC Planner agent in from-security-plan mode | ## Instructions @@ -520,7 +520,7 @@ copilot plugin install hve-core-all@hve-core | sssc-gap-analysis.instructions | Phase 4 gap comparison, adoption categorization, and effort sizing for SSSC Planner. | | sssc-handoff.instructions | Phase 6 backlog handoff protocol with Scorecard projections and dual-format output for SSSC Planner. | | sssc-identity.instructions | Identity and orchestration instructions for the SSSC Planner agent. Contains six-phase workflow, state.json schema, session recovery, and question cadence. | -| sssc-standards.instructions | Phase 3 OpenSSF Scorecard, SLSA, Best Practices Badge, Sigstore, and SBOM standards mapping for SSSC Planner. | +| sssc-standards.instructions | Phase 3 OpenSSF Scorecard, SLSA v1.0, OpenSSF Best Practices Badge, Sigstore (cosign), and NTIA SBOM minimum elements standards mapping for SSSC Planner. | | standards-mapping.instructions | Embedded OWASP and NIST security standards with researcher subagent delegation for CIS, WAF, CAF, and other runtime lookups - Brought to you by microsoft/hve-core | | disclaimer-language.instructions | Centralized disclaimer language for AI-assisted planning agents requiring professional review acknowledgment | | hve-core-location.instructions | Important: hve-core is the repository containing this instruction file; Guidance: if a referenced prompt, instructions, agent, or script is missing in the current directory, fall back to this hve-core location by walking up this file's directory tree. | diff --git a/plugins/project-planning/README.md b/plugins/project-planning/README.md index 0da6f2bc9..68a0852b6 100644 --- a/plugins/project-planning/README.md +++ b/plugins/project-planning/README.md @@ -118,10 +118,10 @@ copilot plugin install project-planning@hve-core | rai-capture | Initiate responsible AI assessment planning from existing knowledge using the RAI Planner agent in capture mode | | rai-plan-from-prd | Initiate responsible AI assessment planning from PRD/BRD artifacts using the RAI Planner agent in from-prd mode | | rai-plan-from-security-plan | Initiate responsible AI assessment planning from a completed Security Plan using the RAI Planner agent in from-security-plan mode (recommended) | -| sssc-capture | Start a new SSSC assessment via guided conversation using the SSSC Planner agent in capture mode | -| sssc-from-prd | Start an SSSC assessment from existing PRD artifacts using the SSSC Planner agent | -| sssc-from-brd | Start an SSSC assessment from existing BRD artifacts using the SSSC Planner agent | -| sssc-from-security-plan | Extend a Security Planner assessment with supply chain coverage using the SSSC Planner agent | +| sssc-capture | Initiate supply chain security planning from existing knowledge using the SSSC Planner agent in capture mode | +| sssc-from-prd | Initiate supply chain security planning from existing PRD artifacts using the SSSC Planner agent in from-prd mode | +| sssc-from-brd | Initiate supply chain security planning from existing BRD artifacts using the SSSC Planner agent in from-brd mode | +| sssc-from-security-plan | Extend a Security Planner assessment with supply chain coverage using the SSSC Planner agent in from-security-plan mode | ## Instructions @@ -141,7 +141,7 @@ copilot plugin install project-planning@hve-core | backlog-handoff.instructions | Dual-format backlog handoff for ADO and GitHub with content sanitization, autonomy tiers, and work item templates - Brought to you by microsoft/hve-core | | sssc-identity.instructions | Identity and orchestration instructions for the SSSC Planner agent. Contains six-phase workflow, state.json schema, session recovery, and question cadence. | | sssc-assessment.instructions | Phase 2 supply chain assessment protocol with the 27 combined capabilities inventory for SSSC Planner. | -| sssc-standards.instructions | Phase 3 OpenSSF Scorecard, SLSA, Best Practices Badge, Sigstore, and SBOM standards mapping for SSSC Planner. | +| sssc-standards.instructions | Phase 3 OpenSSF Scorecard, SLSA v1.0, OpenSSF Best Practices Badge, Sigstore (cosign), and NTIA SBOM minimum elements standards mapping for SSSC Planner. | | sssc-gap-analysis.instructions | Phase 4 gap comparison, adoption categorization, and effort sizing for SSSC Planner. | | sssc-backlog.instructions | Phase 5 dual-format work item generation with templates and priority derivation for SSSC Planner. | | sssc-handoff.instructions | Phase 6 backlog handoff protocol with Scorecard projections and dual-format output for SSSC Planner. | diff --git a/plugins/security/README.md b/plugins/security/README.md index da25c742b..19f5ddc78 100644 --- a/plugins/security/README.md +++ b/plugins/security/README.md @@ -122,10 +122,10 @@ copilot plugin install security@hve-core | security-review-llm | Runs OWASP LLM and Agentic vulnerability assessments with codebase profiling for context - Brought to you by microsoft/hve-core | | security-review-web | Runs an OWASP Top 10 web vulnerability assessment without codebase profiling - Brought to you by microsoft/hve-core | | security-review-sbd | Runs a Secure by Design principles assessment based on UK and Australian government guidance - Brought to you by microsoft/hve-core | -| sssc-capture | Start a new SSSC assessment via guided conversation using the SSSC Planner agent in capture mode | -| sssc-from-prd | Start an SSSC assessment from existing PRD artifacts using the SSSC Planner agent | -| sssc-from-brd | Start an SSSC assessment from existing BRD artifacts using the SSSC Planner agent | -| sssc-from-security-plan | Extend a Security Planner assessment with supply chain coverage using the SSSC Planner agent | +| sssc-capture | Initiate supply chain security planning from existing knowledge using the SSSC Planner agent in capture mode | +| sssc-from-prd | Initiate supply chain security planning from existing PRD artifacts using the SSSC Planner agent in from-prd mode | +| sssc-from-brd | Initiate supply chain security planning from existing BRD artifacts using the SSSC Planner agent in from-brd mode | +| sssc-from-security-plan | Extend a Security Planner assessment with supply chain coverage using the SSSC Planner agent in from-security-plan mode | | rai-capture | Initiate responsible AI assessment planning from existing knowledge using the RAI Planner agent in capture mode | | rai-plan-from-prd | Initiate responsible AI assessment planning from PRD/BRD artifacts using the RAI Planner agent in from-prd mode | | rai-plan-from-security-plan | Initiate responsible AI assessment planning from a completed Security Plan using the RAI Planner agent in from-security-plan mode (recommended) | @@ -141,7 +141,7 @@ copilot plugin install security@hve-core | backlog-handoff.instructions | Dual-format backlog handoff for ADO and GitHub with content sanitization, autonomy tiers, and work item templates - Brought to you by microsoft/hve-core | | sssc-identity.instructions | Identity and orchestration instructions for the SSSC Planner agent. Contains six-phase workflow, state.json schema, session recovery, and question cadence. | | sssc-assessment.instructions | Phase 2 supply chain assessment protocol with the 27 combined capabilities inventory for SSSC Planner. | -| sssc-standards.instructions | Phase 3 OpenSSF Scorecard, SLSA, Best Practices Badge, Sigstore, and SBOM standards mapping for SSSC Planner. | +| sssc-standards.instructions | Phase 3 OpenSSF Scorecard, SLSA v1.0, OpenSSF Best Practices Badge, Sigstore (cosign), and NTIA SBOM minimum elements standards mapping for SSSC Planner. | | sssc-gap-analysis.instructions | Phase 4 gap comparison, adoption categorization, and effort sizing for SSSC Planner. | | sssc-backlog.instructions | Phase 5 dual-format work item generation with templates and priority derivation for SSSC Planner. | | sssc-handoff.instructions | Phase 6 backlog handoff protocol with Scorecard projections and dual-format output for SSSC Planner. | diff --git a/scripts/linting/schemas/sssc-state.schema.json b/scripts/linting/schemas/sssc-state.schema.json new file mode 100644 index 000000000..805bf4fe0 --- /dev/null +++ b/scripts/linting/schemas/sssc-state.schema.json @@ -0,0 +1,256 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://github.com/microsoft/hve-core/schemas/sssc-state.schema.json", + "title": "SSSC Planner State Schema", + "description": "Schema for SSSC Planner state.json files under .copilot-tracking/sssc-plans/{project-slug}/", + "type": "object", + "required": [ + "projectSlug", + "ssscPlanFile", + "currentPhase", + "entryMode", + "scopingComplete", + "assessmentComplete", + "standardsMapped", + "gapAnalysisComplete", + "backlogGenerated", + "handoffGenerated", + "context", + "referencesProcessed", + "nextActions", + "userPreferences", + "ssscEnabled", + "signingRequested" + ], + "properties": { + "projectSlug": { + "type": "string", + "minLength": 1, + "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$", + "description": "Kebab-case project identifier used as the directory name" + }, + "ssscPlanFile": { + "type": "string", + "description": "Relative path to the SSSC plan markdown file" + }, + "currentPhase": { + "type": "integer", + "minimum": 1, + "maximum": 6, + "description": "Current assessment phase (1-6)" + }, + "entryMode": { + "type": "string", + "enum": ["capture", "from-prd", "from-brd", "from-security-plan"], + "description": "How the assessment was initiated" + }, + "disclaimerShownAt": { + "type": ["string", "null"], + "format": "date-time", + "description": "ISO 8601 timestamp when disclaimer was displayed, or null if not yet shown" + }, + "scopingComplete": { + "type": "boolean", + "description": "Whether Phase 1 scoping is complete" + }, + "assessmentComplete": { + "type": "boolean", + "description": "Whether Phase 2 supply chain assessment is complete" + }, + "standardsMapped": { + "type": "boolean", + "description": "Whether Phase 3 standards mapping is complete" + }, + "gapAnalysisComplete": { + "type": "boolean", + "description": "Whether Phase 4 gap analysis is complete" + }, + "backlogGenerated": { + "type": "boolean", + "description": "Whether Phase 5 backlog generation is complete" + }, + "handoffGenerated": { + "type": "object", + "required": ["ado", "github"], + "properties": { + "ado": { + "type": "boolean", + "description": "Whether ADO backlog handoff has been generated" + }, + "github": { + "type": "boolean", + "description": "Whether GitHub Issues backlog handoff has been generated" + } + }, + "additionalProperties": false, + "description": "Platform-specific handoff generation status" + }, + "context": { + "type": "object", + "required": [ + "techStack", + "packageManagers", + "ciPlatform", + "releaseStrategy", + "complianceTargets" + ], + "properties": { + "techStack": { + "type": "array", + "items": { "type": "string" }, + "description": "Languages, runtimes, and frameworks in scope" + }, + "packageManagers": { + "type": "array", + "items": { "type": "string" }, + "description": "Package managers and dependency ecosystems in use" + }, + "ciPlatform": { + "type": "string", + "description": "Primary CI/CD platform (e.g., github-actions, azure-pipelines)" + }, + "releaseStrategy": { + "type": "string", + "description": "Release cadence and distribution strategy" + }, + "complianceTargets": { + "type": "array", + "items": { "type": "string" }, + "description": "Compliance frameworks or standards targeted (e.g., SLSA L3, OpenSSF Scorecard)" + }, + "deploymentTargets": { + "type": "array", + "items": { "type": "string" }, + "description": "Deployment surfaces (e.g., container registries, package indexes)" + } + }, + "additionalProperties": true, + "description": "Project context discovered during scoping" + }, + "referencesProcessed": { + "type": "array", + "items": { "$ref": "#/$defs/referenceEntry" }, + "description": "User-supplied reference content processed during the assessment" + }, + "nextActions": { + "type": "array", + "items": { "type": "string" }, + "description": "Pending actions for the current phase" + }, + "userPreferences": { "$ref": "#/$defs/userPreferences" }, + "ssscEnabled": { + "type": "boolean", + "description": "Whether SSSC planning is enabled for this session" + }, + "securityPlannerLink": { + "type": ["string", "null"], + "description": "Path to the source security plan when entryMode is from-security-plan" + }, + "raiPlannerLink": { + "type": ["string", "null"], + "description": "Path to a related RAI plan when applicable" + }, + "signingRequested": { + "type": "boolean", + "description": "Whether artifact signing was requested by the user" + }, + "signingManifestPath": { + "type": ["string", "null"], + "description": "Path to the signing manifest file (sssc-manifest.json), or null if signing not requested" + } + }, + "additionalProperties": false, + "$defs": { + "referenceEntry": { + "type": "object", + "required": ["filePath", "type", "sourceDescription", "processedInPhase", "status"], + "properties": { + "filePath": { + "type": "string", + "description": "Path to the processed reference file" + }, + "type": { + "type": "string", + "enum": [ + "standard", + "security-plan", + "prd", + "brd", + "sbom", + "scorecard-result", + "output-format" + ], + "description": "Category of the reference content" + }, + "sourceDescription": { + "type": "string", + "description": "Brief description of the reference source" + }, + "processedInPhase": { + "type": ["integer", "null"], + "minimum": 1, + "maximum": 6, + "description": "Phase in which the reference was processed, or null if pending" + }, + "status": { + "type": "string", + "enum": ["pending", "processed", "error"], + "description": "Processing status of the reference" + } + }, + "additionalProperties": false + }, + "userPreferences": { + "type": "object", + "required": [ + "autonomyTier", + "outputDetailLevel", + "targetSystem", + "audienceProfile", + "includeOptionalArtifacts" + ], + "properties": { + "autonomyTier": { + "type": "string", + "enum": ["guided", "partial", "full"], + "description": "How much autonomy the agent has in proceeding between phases" + }, + "outputDetailLevel": { + "type": "string", + "enum": ["minimal", "standard", "detailed"], + "description": "Level of detail in generated artifacts" + }, + "targetSystem": { + "type": "string", + "enum": ["ado", "github", "both"], + "description": "Target backlog system for handoff" + }, + "audienceProfile": { + "type": "string", + "enum": ["technical", "executive", "mixed"], + "description": "Primary audience for generated artifacts" + }, + "includeOptionalArtifacts": { + "type": "object", + "required": ["sbom", "scorecardProjection", "artifactSigning"], + "properties": { + "sbom": { + "type": "boolean", + "description": "Whether to include SBOM generation guidance" + }, + "scorecardProjection": { + "type": "boolean", + "description": "Whether to include OpenSSF Scorecard score projections" + }, + "artifactSigning": { + "type": "boolean", + "description": "Whether to enable cosign artifact signing" + } + }, + "additionalProperties": false + } + }, + "additionalProperties": false + } + } +} diff --git a/scripts/security/Sign-PlannerArtifacts.ps1 b/scripts/security/Sign-PlannerArtifacts.ps1 index 1e71b612d..5938d26ce 100644 --- a/scripts/security/Sign-PlannerArtifacts.ps1 +++ b/scripts/security/Sign-PlannerArtifacts.ps1 @@ -6,21 +6,31 @@ <# .SYNOPSIS - Generates a SHA-256 manifest for RAI planning artifacts and optionally signs it with cosign. + Generates a SHA-256 manifest for planner artifacts (RAI or SSSC) and optionally signs it with cosign. .DESCRIPTION - Enumerates all files under the RAI planning artifact directory for a given project slug, - computes SHA-256 hashes for each artifact, and writes a JSON manifest file. When cosign - is available and requested, the manifest is signed using Sigstore keyless signing to + Enumerates all files under a planner session directory, computes SHA-256 hashes for each + artifact, and writes a JSON manifest file. Supports RAI sessions via -ProjectSlug (resolved + to .copilot-tracking/rai-plans/{ProjectSlug}/) and arbitrary planner sessions via -SessionPath + (an absolute or repo-relative directory, e.g., .copilot-tracking/sssc-plans/{slug}/). When + cosign is available and requested, the manifest is signed using Sigstore keyless signing to provide cryptographic provenance. .PARAMETER ProjectSlug - The project slug identifying the RAI planning session. Corresponds to the subdirectory - under .copilot-tracking/rai-plans/. + The project slug identifying an RAI planning session. Corresponds to the subdirectory under + .copilot-tracking/rai-plans/. Mutually exclusive with -SessionPath. + +.PARAMETER SessionPath + Direct path to a planner session directory (absolute, or relative to the repository root). + Use this for SSSC sessions or any non-RAI planner. Mutually exclusive with -ProjectSlug. + +.PARAMETER ManifestName + File name for the generated manifest written inside the session directory. Defaults to + 'artifact-manifest.json'. Ignored when -OutputPath is supplied. .PARAMETER OutputPath - Path for the generated manifest file. Defaults to - .copilot-tracking/rai-plans/{ProjectSlug}/artifact-manifest.json. + Full path for the generated manifest file. When omitted, the manifest is written inside the + resolved session directory using -ManifestName. .PARAMETER IncludeCosign When specified, attempts to sign the manifest with cosign keyless signing after @@ -43,17 +53,29 @@ Invokes the script through the npm wrapper with cosign signing enabled. +.EXAMPLE + ./scripts/security/Sign-PlannerArtifacts.ps1 -SessionPath '.copilot-tracking/sssc-plans/contoso-supply-chain' -ManifestName 'sssc-manifest.json' + + Generates a manifest named sssc-manifest.json for an SSSC planner session. + .NOTES - The manifest excludes its own file (artifact-manifest.json) and any cosign signature - files (.sig, .bundle) from the hash inventory to avoid circular references. + The manifest excludes its own file and any cosign signature files (.sig, .bundle) from the + hash inventory to avoid circular references. #> -[CmdletBinding()] +[CmdletBinding(DefaultParameterSetName = 'ByProjectSlug')] param( - [Parameter(Mandatory)] + [Parameter(Mandatory, ParameterSetName = 'ByProjectSlug')] [ValidateNotNullOrEmpty()] [string]$ProjectSlug, + [Parameter(Mandatory, ParameterSetName = 'BySessionPath')] + [ValidateNotNullOrEmpty()] + [string]$SessionPath, + + [Parameter(Mandatory = $false)] + [string]$ManifestName = 'artifact-manifest.json', + [Parameter(Mandatory = $false)] [string]$OutputPath, @@ -93,7 +115,20 @@ if ($MyInvocation.InvocationName -ne '.') { if ($LASTEXITCODE -ne 0 -or [string]::IsNullOrWhiteSpace($repoRoot)) { $repoRoot = $PWD.Path } - $artifactDir = Join-Path -Path $repoRoot -ChildPath ".copilot-tracking/rai-plans/$ProjectSlug" + + if ($PSCmdlet.ParameterSetName -eq 'BySessionPath') { + if ([System.IO.Path]::IsPathRooted($SessionPath)) { + $artifactDir = $SessionPath + } + else { + $artifactDir = Join-Path -Path $repoRoot -ChildPath $SessionPath + } + $sessionLabel = Split-Path -Path $artifactDir -Leaf + } + else { + $artifactDir = Join-Path -Path $repoRoot -ChildPath ".copilot-tracking/rai-plans/$ProjectSlug" + $sessionLabel = $ProjectSlug + } if (-not (Test-Path -Path $artifactDir -PathType Container)) { Write-Host "❌ Artifact directory not found: $artifactDir" -ForegroundColor Red @@ -101,17 +136,19 @@ if ($MyInvocation.InvocationName -ne '.') { } if (-not $OutputPath) { - $OutputPath = Join-Path -Path $artifactDir -ChildPath 'artifact-manifest.json' + $OutputPath = Join-Path -Path $artifactDir -ChildPath $ManifestName } + $manifestFileName = Split-Path -Path $OutputPath -Leaf + # File patterns to exclude from the manifest to avoid circular references $excludePatterns = @( - 'artifact-manifest.json', + $manifestFileName, '*.sig', '*.bundle' ) - Write-Host "🔐 Generating artifact manifest for project: $ProjectSlug" -ForegroundColor Cyan + Write-Host "🔐 Generating artifact manifest for session: $sessionLabel" -ForegroundColor Cyan $artifacts = Get-ChildItem -Path $artifactDir -File -Recurse | Where-Object { @@ -142,7 +179,12 @@ if ($MyInvocation.InvocationName -ne '.') { $manifest = [ordered]@{ version = '1.0' - projectSlug = $ProjectSlug + projectSlug = $sessionLabel + sessionPath = if ($artifactDir.StartsWith($repoRoot, [System.StringComparison]::OrdinalIgnoreCase)) { + ($artifactDir.Substring($repoRoot.Length).TrimStart('\','/') -replace '\\','/') + } else { + ($artifactDir -replace '\\','/') + } generatedAt = [DateTime]::UtcNow.ToString("yyyy-MM-ddTHH:mm:ss.fffffffZ") algorithm = 'SHA256' fileCount = $fileEntries.Count diff --git a/scripts/tests/linting/Validate-PlannerArtifacts.Tests.ps1 b/scripts/tests/linting/Validate-PlannerArtifacts.Tests.ps1 index acbae73d0..e715d77e3 100644 --- a/scripts/tests/linting/Validate-PlannerArtifacts.Tests.ps1 +++ b/scripts/tests/linting/Validate-PlannerArtifacts.Tests.ps1 @@ -20,6 +20,7 @@ BeforeAll { $script:Tier1Text = '> **Note** — The author created this content with assistance from AI. All outputs should be reviewed and validated before use.' $script:CheckboxText = '> - [ ] Reviewed and validated by a human reviewer' $script:DisclaimerText = '> **Disclaimer** — This agent is an assistive tool only. It does not provide legal, regulatory, or compliance advice.' + $script:SsscDisclaimerText = '> **Disclaimer** — This SSSC agent is an assistive tool only. It does not provide security, legal, or compliance advice.' # Create valid footer-with-review.yml $script:FooterConfigContent = @" @@ -52,7 +53,7 @@ artifact-classification: artifacts: - rai-review-summary - human-facing-with-disclaimer: + rai-handoff-with-disclaimer: required-footers: - ai-content-note - human-review-checkbox @@ -60,6 +61,17 @@ artifact-classification: disclaimer-ref: rai-full-disclaimer artifacts: - handoff-summary + + sssc-handoff-with-disclaimer: + scope: + - .github/instructions/security/sssc-*.instructions.md + required-footers: + - ai-content-note + - human-review-checkbox + requires-disclaimer: true + disclaimer-ref: sssc-full-disclaimer + artifacts: + - sssc-handoff-summary "@ # Create valid disclaimers.yml @@ -75,6 +87,15 @@ disclaimers: text: >- > **Disclaimer** — This agent is an assistive tool only. It does not provide legal, regulatory, or compliance advice. + + sssc-planner: + id: sssc-full-disclaimer + label: "SSSC Planner Full Disclaimer" + applies-to: + - sssc-handoff-summary + text: >- + > **Disclaimer** — This SSSC agent is an assistive tool only. It does + not provide security, legal, or compliance advice. "@ $script:FooterConfigPath = Join-Path $script:ConfigDir 'footer-with-review.yml' @@ -203,7 +224,7 @@ Describe 'Find-ArtifactReferences' -Tag 'Unit' { $refs[0].Tier | Should -Be 'agentic' } - It 'Finds human-facing-with-disclaimer artifact references' { + It 'Finds rai-handoff-with-disclaimer artifact references' { $refs = Find-ArtifactReferences -ArtifactClassification $script:FooterConfig.'artifact-classification' -RelativePath 'rai-planning/handoff-summary.md' $refs.Count | Should -Be 1 $refs[0].RequiresDisclaimer | Should -BeTrue @@ -318,7 +339,7 @@ $($script:Tier1Text) } } - Context 'Human-facing-with-disclaimer tier (Tier 1 + checkbox + disclaimer)' { + Context 'Rai-handoff-with-disclaimer tier (Tier 1 + checkbox + disclaimer)' { It 'Passes when all three elements are present' { $filePath = Join-Path $script:InstructionDir 'handoff-summary.instructions.md' $content = @" @@ -364,6 +385,56 @@ $($script:CheckboxText) } } + Context 'SSSC handoff with disclaimer tier (Tier 1 + checkbox + SSSC disclaimer)' { + It 'Passes when all three elements are present in an SSSC handoff' { + $ssscDir = Join-Path $script:TempTestDir '.github/instructions/security' + New-Item -ItemType Directory -Path $ssscDir -Force | Out-Null + $filePath = Join-Path $ssscDir 'sssc-handoff-summary.instructions.md' + $content = @" +--- +description: SSSC handoff +--- + +# Template for sssc-handoff-summary + +Content here. + +$($script:Tier1Text) + +$($script:CheckboxText) + +$($script:SsscDisclaimerText) +"@ + Set-Content -Path $filePath -Value $content -Encoding utf8 + $result = Test-AIArtifactCompliance -FilePath $filePath -FooterConfig $script:FooterConfig -DisclaimerConfig $script:DisclaimerConfig -RepoRoot $script:TempTestDir + $result.Passed | Should -BeTrue + } + + It 'Fails when SSSC disclaimer is missing from an SSSC handoff' { + $ssscDir = Join-Path $script:TempTestDir '.github/instructions/security' + New-Item -ItemType Directory -Path $ssscDir -Force | Out-Null + $filePath = Join-Path $ssscDir 'sssc-handoff-summary.instructions.md' + $content = @" +--- +description: SSSC handoff +--- + +# Template for sssc-handoff-summary + +Content here. + +$($script:Tier1Text) + +$($script:CheckboxText) +"@ + Set-Content -Path $filePath -Value $content -Encoding utf8 + $result = Test-AIArtifactCompliance -FilePath $filePath -FooterConfig $script:FooterConfig -DisclaimerConfig $script:DisclaimerConfig -RepoRoot $script:TempTestDir + $result.Passed | Should -BeFalse + $result.Issues | Should -HaveCount 1 + $result.Issues[0] | Should -BeLike '*SSSC*Disclaimer*' + } + } + Context 'Files without artifact references' { It 'Skips files with no matching artifacts' { $filePath = Join-Path $script:InstructionDir 'unrelated.instructions.md' diff --git a/scripts/tests/security/Sign-PlannerArtifacts.Tests.ps1 b/scripts/tests/security/Sign-PlannerArtifacts.Tests.ps1 index d7d002405..fa293cb20 100644 --- a/scripts/tests/security/Sign-PlannerArtifacts.Tests.ps1 +++ b/scripts/tests/security/Sign-PlannerArtifacts.Tests.ps1 @@ -212,7 +212,7 @@ Describe 'Manifest Generation' -Tag 'Unit' { $manifest = Get-Content $script:outputPath -Raw | ConvertFrom-Json $fields = ($manifest | Get-Member -MemberType NoteProperty).Name | Sort-Object - $expected = @('algorithm', 'artifacts', 'fileCount', 'generatedAt', 'projectSlug', 'version') | Sort-Object + $expected = @('algorithm', 'artifacts', 'fileCount', 'generatedAt', 'projectSlug', 'sessionPath', 'version') | Sort-Object $fields | Should -Be $expected } } From 4572030ef801a4ac426182e957e8f397ff926060 Mon Sep 17 00:00:00 2001 From: Bill Berry Date: Thu, 30 Apr 2026 18:12:07 -0700 Subject: [PATCH 02/21] chore(plugins): regenerate plugin readmes for sssc command and instruction descriptions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 🔧 - Generated by Copilot --- plugins/hve-core-all/README.md | 10 +++++----- plugins/project-planning/README.md | 10 +++++----- plugins/security/README.md | 10 +++++----- 3 files changed, 15 insertions(+), 15 deletions(-) diff --git a/plugins/hve-core-all/README.md b/plugins/hve-core-all/README.md index 0a4172685..ed0f17d26 100644 --- a/plugins/hve-core-all/README.md +++ b/plugins/hve-core-all/README.md @@ -135,10 +135,10 @@ Use this edition when you want access to everything without choosing a focused c | **security-review-llm** | Runs OWASP LLM and Agentic vulnerability assessments with codebase profiling for context | | **security-review-sbd** | Runs a Secure by Design principles assessment based on UK and Australian government guidance | | **security-review-web** | Runs an OWASP Top 10 web vulnerability assessment without codebase profiling | -| **sssc-capture** | Start a new SSSC assessment via guided conversation using the SSSC Planner agent in capture mode | -| **sssc-from-brd** | Start an SSSC assessment from existing BRD artifacts using the SSSC Planner agent | -| **sssc-from-prd** | Start an SSSC assessment from existing PRD artifacts using the SSSC Planner agent | -| **sssc-from-security-plan** | Extend a Security Planner assessment with supply chain coverage using the SSSC Planner agent | +| **sssc-capture** | Initiate supply chain security planning from existing knowledge using the SSSC Planner agent in capture mode | +| **sssc-from-brd** | Initiate supply chain security planning from existing BRD artifacts using the SSSC Planner agent in from-brd mode | +| **sssc-from-prd** | Initiate supply chain security planning from existing PRD artifacts using the SSSC Planner agent in from-prd mode | +| **sssc-from-security-plan** | Extend a Security Planner assessment with supply chain coverage using the SSSC Planner agent in from-security-plan mode | | **synth-data-generate** | Generate comprehensive synthetic data for any specified subject with realistic patterns and relationships | | **task-challenge** | Adversarial What/Why/How interrogation of completed implementation artifacts | | **task-implement** | Locates and executes implementation plans using Task Implementor | @@ -249,7 +249,7 @@ Use this edition when you want access to everything without choosing a focused c | **security/sssc-gap-analysis** | Phase 4 gap comparison, adoption categorization, and effort sizing for SSSC Planner. | | **security/sssc-handoff** | Phase 6 backlog handoff protocol with Scorecard projections and dual-format output for SSSC Planner. | | **security/sssc-identity** | Identity and orchestration instructions for the SSSC Planner agent. Contains six-phase workflow, state.json schema, session recovery, and question cadence. | -| **security/sssc-standards** | Phase 3 OpenSSF Scorecard, SLSA, Best Practices Badge, Sigstore, and SBOM standards mapping for SSSC Planner. | +| **security/sssc-standards** | Phase 3 OpenSSF Scorecard, SLSA v1.0, OpenSSF Best Practices Badge, Sigstore (cosign), and NTIA SBOM minimum elements standards mapping for SSSC Planner. | | **security/standards-mapping** | Embedded OWASP and NIST security standards with researcher subagent delegation for CIS, WAF, CAF, and other runtime lookups | | **shared/disclaimer-language** | Centralized disclaimer language for AI-assisted planning agents requiring professional review acknowledgment | | **shared/hve-core-location** | Important: hve-core is the repository containing this instruction file; Guidance: if a referenced prompt, instructions, agent, or script is missing in the current directory, fall back to this hve-core location by walking up this file's directory tree. | diff --git a/plugins/project-planning/README.md b/plugins/project-planning/README.md index 68a0852b6..35182e222 100644 --- a/plugins/project-planning/README.md +++ b/plugins/project-planning/README.md @@ -44,10 +44,10 @@ Create architecture decision records, requirements documents, and diagrams — a | **risk-register** | Creates a concise and well-structured qualitative risk register using a Probability × Impact (P×I) risk matrix. | | **security-capture** | Initiate security planning from existing notes or knowledge using the Security Planner agent in capture mode | | **security-plan-from-prd** | Initiate security planning from PRD/BRD artifacts using the Security Planner agent in from-prd mode | -| **sssc-capture** | Start a new SSSC assessment via guided conversation using the SSSC Planner agent in capture mode | -| **sssc-from-brd** | Start an SSSC assessment from existing BRD artifacts using the SSSC Planner agent | -| **sssc-from-prd** | Start an SSSC assessment from existing PRD artifacts using the SSSC Planner agent | -| **sssc-from-security-plan** | Extend a Security Planner assessment with supply chain coverage using the SSSC Planner agent | +| **sssc-capture** | Initiate supply chain security planning from existing knowledge using the SSSC Planner agent in capture mode | +| **sssc-from-brd** | Initiate supply chain security planning from existing BRD artifacts using the SSSC Planner agent in from-brd mode | +| **sssc-from-prd** | Initiate supply chain security planning from existing PRD artifacts using the SSSC Planner agent in from-prd mode | +| **sssc-from-security-plan** | Extend a Security Planner assessment with supply chain coverage using the SSSC Planner agent in from-security-plan mode | ### Instructions @@ -69,7 +69,7 @@ Create architecture decision records, requirements documents, and diagrams — a | **security/sssc-gap-analysis** | Phase 4 gap comparison, adoption categorization, and effort sizing for SSSC Planner. | | **security/sssc-handoff** | Phase 6 backlog handoff protocol with Scorecard projections and dual-format output for SSSC Planner. | | **security/sssc-identity** | Identity and orchestration instructions for the SSSC Planner agent. Contains six-phase workflow, state.json schema, session recovery, and question cadence. | -| **security/sssc-standards** | Phase 3 OpenSSF Scorecard, SLSA, Best Practices Badge, Sigstore, and SBOM standards mapping for SSSC Planner. | +| **security/sssc-standards** | Phase 3 OpenSSF Scorecard, SLSA v1.0, OpenSSF Best Practices Badge, Sigstore (cosign), and NTIA SBOM minimum elements standards mapping for SSSC Planner. | | **security/standards-mapping** | Embedded OWASP and NIST security standards with researcher subagent delegation for CIS, WAF, CAF, and other runtime lookups | | **shared/disclaimer-language** | Centralized disclaimer language for AI-assisted planning agents requiring professional review acknowledgment | | **shared/hve-core-location** | Important: hve-core is the repository containing this instruction file; Guidance: if a referenced prompt, instructions, agent, or script is missing in the current directory, fall back to this hve-core location by walking up this file's directory tree. | diff --git a/plugins/security/README.md b/plugins/security/README.md index 19f5ddc78..09c21f6bb 100644 --- a/plugins/security/README.md +++ b/plugins/security/README.md @@ -44,10 +44,10 @@ Security review, planning, incident response, risk assessment, vulnerability ana | **security-review-llm** | Runs OWASP LLM and Agentic vulnerability assessments with codebase profiling for context | | **security-review-sbd** | Runs a Secure by Design principles assessment based on UK and Australian government guidance | | **security-review-web** | Runs an OWASP Top 10 web vulnerability assessment without codebase profiling | -| **sssc-capture** | Start a new SSSC assessment via guided conversation using the SSSC Planner agent in capture mode | -| **sssc-from-brd** | Start an SSSC assessment from existing BRD artifacts using the SSSC Planner agent | -| **sssc-from-prd** | Start an SSSC assessment from existing PRD artifacts using the SSSC Planner agent | -| **sssc-from-security-plan** | Extend a Security Planner assessment with supply chain coverage using the SSSC Planner agent | +| **sssc-capture** | Initiate supply chain security planning from existing knowledge using the SSSC Planner agent in capture mode | +| **sssc-from-brd** | Initiate supply chain security planning from existing BRD artifacts using the SSSC Planner agent in from-brd mode | +| **sssc-from-prd** | Initiate supply chain security planning from existing PRD artifacts using the SSSC Planner agent in from-prd mode | +| **sssc-from-security-plan** | Extend a Security Planner assessment with supply chain coverage using the SSSC Planner agent in from-security-plan mode | ### Instructions @@ -69,7 +69,7 @@ Security review, planning, incident response, risk assessment, vulnerability ana | **security/sssc-gap-analysis** | Phase 4 gap comparison, adoption categorization, and effort sizing for SSSC Planner. | | **security/sssc-handoff** | Phase 6 backlog handoff protocol with Scorecard projections and dual-format output for SSSC Planner. | | **security/sssc-identity** | Identity and orchestration instructions for the SSSC Planner agent. Contains six-phase workflow, state.json schema, session recovery, and question cadence. | -| **security/sssc-standards** | Phase 3 OpenSSF Scorecard, SLSA, Best Practices Badge, Sigstore, and SBOM standards mapping for SSSC Planner. | +| **security/sssc-standards** | Phase 3 OpenSSF Scorecard, SLSA v1.0, OpenSSF Best Practices Badge, Sigstore (cosign), and NTIA SBOM minimum elements standards mapping for SSSC Planner. | | **security/standards-mapping** | Embedded OWASP and NIST security standards with researcher subagent delegation for CIS, WAF, CAF, and other runtime lookups | | **shared/disclaimer-language** | Centralized disclaimer language for AI-assisted planning agents requiring professional review acknowledgment | | **shared/hve-core-location** | Important: hve-core is the repository containing this instruction file; Guidance: if a referenced prompt, instructions, agent, or script is missing in the current directory, fall back to this hve-core location by walking up this file's directory tree. | From cf2081a9f171b109f685191ea38467b42bfa84ae Mon Sep 17 00:00:00 2001 From: Bill Berry Date: Thu, 30 Apr 2026 18:54:50 -0700 Subject: [PATCH 03/21] style(instructions): reformat sssc-gap-analysis tables per markdown-table-formatter MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 🎨 - Generated by Copilot --- .../security/sssc-gap-analysis.instructions.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/.github/instructions/security/sssc-gap-analysis.instructions.md b/.github/instructions/security/sssc-gap-analysis.instructions.md index 909371247..376e1c2f8 100644 --- a/.github/instructions/security/sssc-gap-analysis.instructions.md +++ b/.github/instructions/security/sssc-gap-analysis.instructions.md @@ -11,8 +11,8 @@ Compare the repository's current supply chain security posture against the desir Produce a prioritized gap table sorted by Scorecard risk level (Critical > High > Medium > Low): -| Gap | Scorecard Check | Risk | Concern | Current State | Target State | Adoption Type | Effort | Workflow/Script Reference | -|---------------|-----------------|----------------------------|--------------------------|---------------|--------------|---------------|------------|---------------------------| +| Gap | Scorecard Check | Risk | Concern | Current State | Target State | Adoption Type | Effort | Workflow/Script Reference | +|---------------|-----------------|----------------------------|-------------------------|---------------|--------------|---------------|------------|---------------------------| | {description} | {check_name} | {Critical/High/Medium/Low} | {Low / Moderate / High} | {current} | {target} | {category} | {S/M/L/XL} | {reference} | The `Risk` column carries the OpenSSF Scorecard risk classification. The `Concern` column carries the qualitative residual concern level after considering the repository's current posture and compensating controls (Low, Moderate, or High). Concern is independent from Effort — a small effort may still address a high-concern gap. @@ -74,11 +74,11 @@ Assign T-shirt sizes based on implementation scope: Assign a qualitative concern level to each gap reflecting residual risk after considering the repository's current posture and compensating controls. Concern is independent from Scorecard risk classification and from effort sizing. -| Concern | Criteria | -|----------|-----------------------------------------------------------------------------------------------------------| -| Low | Gap is informational or already partially mitigated by existing controls; minimal residual exposure | -| Moderate | Gap leaves measurable residual exposure but compensating controls reduce immediate impact | -| High | Gap leaves significant residual exposure with no effective compensating controls; prioritize remediation | +| Concern | Criteria | +|----------|----------------------------------------------------------------------------------------------------------| +| Low | Gap is informational or already partially mitigated by existing controls; minimal residual exposure | +| Moderate | Gap leaves measurable residual exposure but compensating controls reduce immediate impact | +| High | Gap leaves significant residual exposure with no effective compensating controls; prioritize remediation | Record concern in the gap table alongside Risk and Effort. Use Concern to break ties when multiple gaps share the same Scorecard risk classification. From ef28214960d95b4a9ec35153669cdc6b285022f6 Mon Sep 17 00:00:00 2001 From: Bill Berry Date: Fri, 1 May 2026 15:17:42 -0700 Subject: [PATCH 04/21] feat(scripts): wire format:tables to Format-MarkdownTables wrapper with Pester coverage MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- package.json | 2 +- scripts/linting/Format-MarkdownTables.ps1 | 99 +++++++ .../Test-Format-MarkdownTables.Tests.ps1 | 271 ++++++++++++++++++ 3 files changed, 371 insertions(+), 1 deletion(-) create mode 100644 scripts/linting/Format-MarkdownTables.ps1 create mode 100644 scripts/tests/linting/Test-Format-MarkdownTables.Tests.ps1 diff --git a/package.json b/package.json index b5ed7a741..7c4d1ab4b 100644 --- a/package.json +++ b/package.json @@ -25,7 +25,7 @@ "rai:sign": "pwsh -NoProfile -File scripts/security/Sign-PlannerArtifacts.ps1", "lint:ai-artifacts": "pwsh -NoProfile -Command \"& './scripts/linting/Validate-PlannerArtifacts.ps1' -FailOnMissing\"", "lint:all": "npm run format:tables && npm run lint:md && npm run lint:ps && npm run lint:yaml && npm run lint:links && npm run lint:frontmatter && npm run lint:collections-metadata && npm run lint:marketplace && npm run lint:version-consistency && npm run lint:permissions && npm run lint:dependency-pinning && npm run lint:ps-module-pins && npm run lint:py && npm run validate:skills && npm run lint:ai-artifacts", - "format:tables": "markdown-table-formatter \"**/*.md\"", + "format:tables": "pwsh -NoProfile -File ./scripts/linting/Format-MarkdownTables.ps1", "extension:prepare": "pwsh ./scripts/extension/Prepare-Extension.ps1", "extension:prepare:prerelease": "pwsh ./scripts/extension/Prepare-Extension.ps1 -Channel PreRelease", "extension:package": "pwsh ./scripts/extension/Package-Extension.ps1", diff --git a/scripts/linting/Format-MarkdownTables.ps1 b/scripts/linting/Format-MarkdownTables.ps1 new file mode 100644 index 000000000..e677dd69f --- /dev/null +++ b/scripts/linting/Format-MarkdownTables.ps1 @@ -0,0 +1,99 @@ +#!/usr/bin/env pwsh +# Copyright (c) Microsoft Corporation. +# SPDX-License-Identifier: MIT +#Requires -Version 7.0 +<# +.SYNOPSIS + Formats Markdown tables across the repository using markdown-table-formatter. + +.DESCRIPTION + Cross-platform wrapper around the markdown-table-formatter Node library. + Enumerates tracked Markdown files via 'git ls-files' (deterministic, respects + .gitignore, and includes dot-prefixed directories such as .github/) and + delegates formatting to the library API. + + The upstream CLI uses 'glob' with the v13 default of dot:false, which + silently skips .github/** and other dot-prefixed paths on Windows. This + wrapper bypasses that bug by passing an explicit file list to the library. + +.PARAMETER Check + Check only; exit with non-zero status if any tables would be reformatted. + +.EXAMPLE + ./scripts/linting/Format-MarkdownTables.ps1 + Reformat Markdown tables in place across the repository. + +.EXAMPLE + ./scripts/linting/Format-MarkdownTables.ps1 -Check + Verify formatting without modifying files; exits non-zero on drift. +#> + +[CmdletBinding()] +param( + [Parameter(Mandatory = $false)] + [switch]$Check +) + +$ErrorActionPreference = 'Stop' + +$repoRoot = (Resolve-Path (Join-Path $PSScriptRoot '..' '..')).Path +$emitVerbose = $VerbosePreference -ne 'SilentlyContinue' + +Push-Location $repoRoot +try { + $gitOutput = & git ls-files -z --cached --others --exclude-standard -- '*.md' + if ($LASTEXITCODE -ne 0) { + Write-Error 'git ls-files failed; not running inside a git checkout?' + exit 2 + } + + $files = if ($gitOutput) { $gitOutput -split "`0" | Where-Object { $_ } } else { @() } + if ($files.Count -eq 0) { + Write-Output 'No markdown files found.' + exit 0 + } + + if ($emitVerbose) { + [System.Console]::Error.WriteLine("Formatting $($files.Count) markdown file(s).") + } + + $tempList = New-TemporaryFile + try { + Set-Content -Path $tempList.FullName -Value $files -Encoding utf8 + + $nodeScript = @' +import { readFileSync } from 'node:fs'; +import pkg from 'markdown-table-formatter/lib/markdown-table-formatter.js'; +const { MarkdownTableFormatter } = pkg; + +const files = readFileSync(process.env.MTF_FILE_LIST, 'utf8') + .split(/\r?\n/) + .filter(Boolean); +const check = process.env.MTF_CHECK === '1'; +const verbose = process.env.MTF_VERBOSE === '1'; + +const formatter = new MarkdownTableFormatter({ check }); +const result = await formatter.run(files, { verbose }); +for (const updated of result.updates) { + console.log(`${check ? 'needs-format' : 'formatted'}: ${updated}`); +} +process.exit(result.status); +'@ + + $env:MTF_FILE_LIST = $tempList.FullName + $env:MTF_CHECK = $(if ($Check) { '1' } else { '0' }) + $env:MTF_VERBOSE = $(if ($emitVerbose) { '1' } else { '0' }) + + & node --input-type=module -e $nodeScript + $exitCode = $LASTEXITCODE + } + finally { + Remove-Item -Path $tempList.FullName -ErrorAction SilentlyContinue + Remove-Item Env:MTF_FILE_LIST, Env:MTF_CHECK, Env:MTF_VERBOSE -ErrorAction SilentlyContinue + } + + exit $exitCode +} +finally { + Pop-Location +} diff --git a/scripts/tests/linting/Test-Format-MarkdownTables.Tests.ps1 b/scripts/tests/linting/Test-Format-MarkdownTables.Tests.ps1 new file mode 100644 index 000000000..00e8188e7 --- /dev/null +++ b/scripts/tests/linting/Test-Format-MarkdownTables.Tests.ps1 @@ -0,0 +1,271 @@ +#Requires -Modules Pester +# Copyright (c) Microsoft Corporation. +# SPDX-License-Identifier: MIT + +BeforeAll { + $script:RealScript = (Resolve-Path (Join-Path $PSScriptRoot '../../linting/Format-MarkdownTables.ps1')).Path + $script:RepoRoot = (Resolve-Path (Join-Path $PSScriptRoot '../../..')).Path + $script:RealNodeModules = Join-Path $script:RepoRoot 'node_modules' + + if (-not (Test-Path $script:RealNodeModules)) { + throw "Cannot run Format-MarkdownTables tests: node_modules missing at $script:RealNodeModules. Run 'npm install' first." + } + + $tempBase = [System.IO.Path]::GetTempPath() + $script:MainTestRoot = Join-Path $tempBase "pester-fmt-tables-$(Get-Random)" + New-Item -ItemType Directory -Path $script:MainTestRoot -Force | Out-Null + + # Junction node_modules at MainTestRoot (one level above each fixture) so the + # ESM resolver walks UP from fixture cwd and finds it. Placing it INSIDE a + # fixture would cause that fixture's `git ls-files` to enumerate junctioned + # content. NODE_PATH is CommonJS-only and does not work for ESM imports. + $script:MainNodeModulesLink = Join-Path $script:MainTestRoot 'node_modules' + if (-not (Test-Path $script:MainNodeModulesLink)) { + if ($IsWindows) { + & cmd /c "mklink /J `"$script:MainNodeModulesLink`" `"$script:RealNodeModules`"" 2>&1 | Out-Null + } + else { + New-Item -ItemType SymbolicLink -Path $script:MainNodeModulesLink -Target $script:RealNodeModules | Out-Null + } + } + + function script:New-FixtureRepo { + param( + [Parameter(Mandatory)] [string] $Name, + [switch] $InitGit + ) + + $fixtureRoot = Join-Path $script:MainTestRoot $Name + $linting = Join-Path $fixtureRoot 'scripts/linting' + New-Item -ItemType Directory -Path $linting -Force | Out-Null + Copy-Item -Path $script:RealScript -Destination (Join-Path $linting 'Format-MarkdownTables.ps1') -Force + + if ($InitGit) { + Push-Location $fixtureRoot + try { + & git init --quiet 2>&1 | Out-Null + & git config user.email 'test@example.com' 2>&1 | Out-Null + & git config user.name 'Test' 2>&1 | Out-Null + & git config core.autocrlf false 2>&1 | Out-Null + & git config core.safecrlf false 2>&1 | Out-Null + } + finally { + Pop-Location + } + } + + # .gitignore (in addition to in-repo init) so git ls-files --others + # --exclude-standard skips the junctioned node_modules tree and the + # captured stdout/stderr files. + $gitignore = @' +node_modules/ +_stdout.txt +_stderr.txt +'@ + Set-Content -Path (Join-Path $fixtureRoot '.gitignore') -Value $gitignore -Encoding utf8 + + return $fixtureRoot + } + + function script:Invoke-SutInFixture { + param( + [Parameter(Mandatory)] [string] $FixtureRoot, + [switch] $Check, + [switch] $WithVerbose + ) + + $sutPath = Join-Path $FixtureRoot 'scripts/linting/Format-MarkdownTables.ps1' + $stdoutPath = Join-Path $FixtureRoot '_stdout.txt' + $stderrPath = Join-Path $FixtureRoot '_stderr.txt' + + $argList = @('-NoProfile', '-File', $sutPath) + if ($Check) { $argList += '-Check' } + if ($WithVerbose) { $argList += '-Verbose' } + + $proc = Start-Process -FilePath 'pwsh' ` + -ArgumentList $argList ` + -WorkingDirectory $FixtureRoot ` + -RedirectStandardOutput $stdoutPath ` + -RedirectStandardError $stderrPath ` + -Wait -PassThru -NoNewWindow + + # Belt-and-suspenders: ensure the process has fully exited and OS file + # buffers have flushed before we read. Tiny stdout payloads under the + # Pester runspace can race the file-handle close. + $proc.WaitForExit() + $stdoutBytes = if (Test-Path $stdoutPath) { (Get-Item $stdoutPath).Length } else { -1 } + $stderrBytes = if (Test-Path $stderrPath) { (Get-Item $stderrPath).Length } else { -1 } + if ($stdoutBytes -eq 0 -and $proc.ExitCode -eq 0) { + Start-Sleep -Milliseconds 100 + $stdoutBytes = (Get-Item $stdoutPath).Length + } + + $stdout = if ($stdoutBytes -gt 0) { [System.IO.File]::ReadAllText($stdoutPath) } else { '' } + $stderr = if ($stderrBytes -gt 0) { [System.IO.File]::ReadAllText($stderrPath) } else { '' } + + return [pscustomobject]@{ + ExitCode = $proc.ExitCode + StdOut = $stdout + StdErr = $stderr + StdOutPath = $stdoutPath + StdErrPath = $stderrPath + StdOutBytes = $stdoutBytes + StdErrBytes = $stderrBytes + } + } + + # Well-formatted table (each cell padded to column width, single space between pipes). + $script:GoodTable = @' +# Good + +| Name | Value | +|------|-------| +| a | 1 | +| b | 2 | +'@ + + # Misformatted: cells flush against pipes, uneven widths. + $script:BadTable = @' +# Bad + +|Name|Value| +|---|---| +|a|1| +|bbb|22| +'@ +} + +AfterAll { + if ($script:MainTestRoot -and (Test-Path $script:MainTestRoot)) { + # CRITICAL: the MainTestRoot/node_modules junction points at the real + # repo's node_modules. Remove it first via the directory-delete API + # (which deletes the link itself, not the target) so the subsequent + # recursive remove cannot follow it into real content. + if ($script:MainNodeModulesLink -and (Test-Path $script:MainNodeModulesLink)) { + try { [System.IO.Directory]::Delete($script:MainNodeModulesLink, $false) } catch { } + } + Remove-Item -Path $script:MainTestRoot -Recurse -Force -ErrorAction SilentlyContinue + } +} + +Describe 'Format-MarkdownTables' -Tag 'Unit' { + + Context 'when no markdown files are tracked' { + BeforeAll { + $script:Fixture = New-FixtureRepo -Name "empty-$(Get-Random)" -InitGit + $script:Result = Invoke-SutInFixture -FixtureRoot $script:Fixture + } + + It 'Exits 0' { + $script:Result.ExitCode | Should -Be 0 + } + + It 'Reports no markdown files found' { + $script:Result.StdOut | Should -Match 'No markdown files found' -Because ( + "ExitCode=$($script:Result.ExitCode); StdOutBytes=$($script:Result.StdOutBytes); " + + "StdErrBytes=$($script:Result.StdErrBytes); StdErr=[$($script:Result.StdErr)]" + ) + } + } + + Context 'when invoked outside a git checkout' { + BeforeAll { + $script:Fixture = New-FixtureRepo -Name "no-git-$(Get-Random)" + $script:Result = Invoke-SutInFixture -FixtureRoot $script:Fixture + } + + It 'Exits with a non-zero code' { + $script:Result.ExitCode | Should -Not -Be 0 + } + + It 'Reports the git ls-files failure on stderr' { + $script:Result.StdErr | Should -Match 'git ls-files failed' + } + } + + Context 'when all markdown tables are already formatted' { + BeforeAll { + $script:Fixture = New-FixtureRepo -Name "good-$(Get-Random)" -InitGit + Set-Content -Path (Join-Path $script:Fixture 'README.md') -Value $script:GoodTable -NoNewline + $script:Result = Invoke-SutInFixture -FixtureRoot $script:Fixture + } + + It 'Exits 0' { + $script:Result.ExitCode | Should -Be 0 + } + + It 'Exits 0 in -Check mode' { + $checkResult = Invoke-SutInFixture -FixtureRoot $script:Fixture -Check + $checkResult.ExitCode | Should -Be 0 + } + } + + Context 'when markdown tables need reformatting' { + BeforeEach { + $script:Fixture = New-FixtureRepo -Name "bad-$(Get-Random)" -InitGit + $script:BadFile = Join-Path $script:Fixture 'README.md' + Set-Content -Path $script:BadFile -Value $script:BadTable -NoNewline + } + + It 'Exits non-zero in -Check mode' { + $result = Invoke-SutInFixture -FixtureRoot $script:Fixture -Check + $result.ExitCode | Should -Not -Be 0 + } + + It 'Leaves files unchanged in -Check mode' { + $before = Get-Content -Path $script:BadFile -Raw + $null = Invoke-SutInFixture -FixtureRoot $script:Fixture -Check + $after = Get-Content -Path $script:BadFile -Raw + $after | Should -BeExactly $before + } + + It 'Exits 0 and rewrites the file in default mode' { + $before = Get-Content -Path $script:BadFile -Raw + $result = Invoke-SutInFixture -FixtureRoot $script:Fixture + $result.ExitCode | Should -Be 0 + $after = Get-Content -Path $script:BadFile -Raw + $after | Should -Not -BeExactly $before + $after | Should -Match '\|\s+Name\s+\|\s+Value\s+\|' + } + } + + Context 'when markdown files live under dot-prefixed directories' { + BeforeEach { + $script:Fixture = New-FixtureRepo -Name "dotpath-$(Get-Random)" -InitGit + $dotDir = Join-Path $script:Fixture '.github' + New-Item -ItemType Directory -Path $dotDir -Force | Out-Null + $script:DotFile = Join-Path $dotDir 'NOTES.md' + Set-Content -Path $script:DotFile -Value $script:BadTable -NoNewline + } + + It 'Detects misformatted tables under .github (regression: glob v13 dot:false)' { + $result = Invoke-SutInFixture -FixtureRoot $script:Fixture -Check + $result.ExitCode | Should -Not -Be 0 + } + + It 'Reformats files under .github in default mode' { + $before = Get-Content -Path $script:DotFile -Raw + $result = Invoke-SutInFixture -FixtureRoot $script:Fixture + $result.ExitCode | Should -Be 0 + $after = Get-Content -Path $script:DotFile -Raw + $after | Should -Not -BeExactly $before + } + } + + Context 'when -Verbose is supplied' { + BeforeAll { + $script:Fixture = New-FixtureRepo -Name "verbose-$(Get-Random)" -InitGit + Set-Content -Path (Join-Path $script:Fixture 'README.md') -Value $script:GoodTable -NoNewline + $script:Result = Invoke-SutInFixture -FixtureRoot $script:Fixture -WithVerbose + } + + It 'Exits 0' { + $script:Result.ExitCode | Should -Be 0 + } + + It 'Emits the file count to the verbose stream' { + # PowerShell verbose output is written to stderr when captured from a child process. + $script:Result.StdErr | Should -Match 'Formatting \d+ markdown file' + } + } +} From d4d5ebbc30493adc445f3b09f55b78f8b9f1573c Mon Sep 17 00:00:00 2001 From: Bill Berry Date: Fri, 1 May 2026 15:19:19 -0700 Subject: [PATCH 05/21] style(docs): reformat markdown tables via Format-MarkdownTables wrapper MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- .github/CUSTOM-AGENTS.md | 68 +++++++-------- .github/instructions/README.md | 84 +++++++++---------- .../instructions/pull-request.instructions.md | 44 +++++----- .../powerpoint/tests/corpus/README.md | 12 +-- .../video-to-gif/examples/README.md | 2 +- .../jira/jira/references/jql-reference.md | 14 ++-- .../references/00-vulnerability-index.md | 24 +++--- .../references/00-vulnerability-index.md | 24 +++--- .../references/00-vulnerability-index.md | 16 ++-- .../references/00-vulnerability-index.md | 24 +++--- .../references/00-vulnerability-index.md | 24 +++--- .../references/00-vulnerability-index.md | 22 ++--- .../references/00-vulnerability-index.md | 24 +++--- .../references/00-principle-index.md | 26 +++--- .../pr-reference/references/REFERENCE.md | 42 +++++----- .github/workflows/README.md | 26 +++--- .github/workflows/doc-update-check.md | 14 ++-- 17 files changed, 245 insertions(+), 245 deletions(-) diff --git a/.github/CUSTOM-AGENTS.md b/.github/CUSTOM-AGENTS.md index 2d22d12e7..630ca1a67 100644 --- a/.github/CUSTOM-AGENTS.md +++ b/.github/CUSTOM-AGENTS.md @@ -38,30 +38,30 @@ Select from the **agent picker dropdown** in the Chat view: The Research-Plan-Implement (RPI) workflow provides a structured approach to complex development tasks. -| Agent | Purpose | Key Constraint | -|----------------------|-------------------------------------------------------------------|------------------------------------------------| -| **rpi-agent** | Autonomous agent with subagent delegation for complex tasks | Requires a subagent tool enabled | -| **task-researcher** | Produces research documents with evidence-based recommendations | Research-only; never plans or implements | -| **task-planner** | Creates 3-file plan sets (plan, details, prompt) | Requires research first; never implements code | -| **task-implementor** | Executes implementation plans with subagent delegation | Requires completed plan files | -| **task-reviewer** | Validates implementation against research and plan specifications | Requires research/plan artifacts | +| Agent | Purpose | Key Constraint | +|----------------------|-------------------------------------------------------------------------------------------------------|-----------------------------------------------------------| +| **rpi-agent** | Autonomous agent with subagent delegation for complex tasks | Requires a subagent tool enabled | +| **task-researcher** | Produces research documents with evidence-based recommendations | Research-only; never plans or implements | +| **task-planner** | Creates 3-file plan sets (plan, details, prompt) | Requires research first; never implements code | +| **task-implementor** | Executes implementation plans with subagent delegation | Requires completed plan files | +| **task-reviewer** | Validates implementation against research and plan specifications | Requires research/plan artifacts | | **task-challenger** | Adversarial questioning agent that interrogates completed implementations with What/Why/How questions | Experimental; no suggestions, hints, or leading questions | ### Documentation and Planning Agents -| Agent | Purpose | Key Constraint | -|----------------------------------|------------------------------------------------------------------------------|-------------------------------------------------------| -| **adr-creation** | Interactive ADR coaching with guided discovery | Socratic coaching approach | -| **brd-builder** | Creates Business Requirements Documents with reference integration | Solution-agnostic requirements focus | -| **doc-ops** | Documentation operations and maintenance | Does not modify source code | -| **meeting-analyst** | Analyzes meeting transcripts to extract product requirements via work-iq-mcp | Experimental; requires work-iq-mcp EULA; transcripts may contain PII and confidential data, analysis files are unencrypted on disk | -| **prd-builder** | Creates Product Requirements Documents through guided Q&A | Iterative questioning; state-tracked sessions | -| **product-manager-advisor** | Requirements discovery, story quality, and prioritization guidance | Principles over format; delegates to prd/brd builders | -| **security-planner** | STRIDE-based security model analysis with standards mapping and backlog handoff | Six-phase conversational workflow; experimental | -| **sssc-planner** | Supply chain security assessment with 6-phase workflow against OpenSSF Scorecard, SLSA, Sigstore, and SBOM | Six-phase conversational workflow; experimental | -| **rai-planner** | Responsible AI assessment with 6-phase workflow against Microsoft Responsible AI Impact Assessment Guide and NIST AI RMF | Six-phase conversational workflow; experimental | -| **system-architecture-reviewer** | Reviews system designs for trade-offs and ADR alignment | Scoped review; delegates security concerns | -| **ux-ui-designer** | JTBD analysis, user journey mapping, and accessibility requirements | Research artifacts only; visual design in Figma | +| Agent | Purpose | Key Constraint | +|----------------------------------|--------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------| +| **adr-creation** | Interactive ADR coaching with guided discovery | Socratic coaching approach | +| **brd-builder** | Creates Business Requirements Documents with reference integration | Solution-agnostic requirements focus | +| **doc-ops** | Documentation operations and maintenance | Does not modify source code | +| **meeting-analyst** | Analyzes meeting transcripts to extract product requirements via work-iq-mcp | Experimental; requires work-iq-mcp EULA; transcripts may contain PII and confidential data, analysis files are unencrypted on disk | +| **prd-builder** | Creates Product Requirements Documents through guided Q&A | Iterative questioning; state-tracked sessions | +| **product-manager-advisor** | Requirements discovery, story quality, and prioritization guidance | Principles over format; delegates to prd/brd builders | +| **security-planner** | STRIDE-based security model analysis with standards mapping and backlog handoff | Six-phase conversational workflow; experimental | +| **sssc-planner** | Supply chain security assessment with 6-phase workflow against OpenSSF Scorecard, SLSA, Sigstore, and SBOM | Six-phase conversational workflow; experimental | +| **rai-planner** | Responsible AI assessment with 6-phase workflow against Microsoft Responsible AI Impact Assessment Guide and NIST AI RMF | Six-phase conversational workflow; experimental | +| **system-architecture-reviewer** | Reviews system designs for trade-offs and ADR alignment | Scoped review; delegates security concerns | +| **ux-ui-designer** | JTBD analysis, user journey mapping, and accessibility requirements | Research artifacts only; visual design in Figma | ### Utility Agents @@ -71,14 +71,14 @@ The Research-Plan-Implement (RPI) workflow provides a structured approach to com ### Code and Review Agents -| Agent | Purpose | Key Constraint | -|--------------------------------|------------------------------------------------------------------|-------------------------------------------------------| -| **pr-review** | 4-phase PR review with tracking artifacts | Review-only; never modifies code | -| **prompt-builder** | Engineers and validates instruction/prompt files | Dual-persona system with auto-testing | -| **security-reviewer** | OWASP vulnerability assessment with subagent-driven verification | Delegates all reference reading to subagents | -| **code-review-functional** | Pre-PR branch diff reviewer for functional correctness and logic gaps | Review-only; five focus areas; optional artifact save | -| **code-review-full** | Orchestrator running functional + standards reviews via subagents | Merges both reports; delegates to subagents; experimental | -| **code-review-standards** | Skills-based standards reviewer for local changes and PRs | Findings must trace to a loaded skill; experimental | +| Agent | Purpose | Key Constraint | +|----------------------------|-----------------------------------------------------------------------|-----------------------------------------------------------| +| **pr-review** | 4-phase PR review with tracking artifacts | Review-only; never modifies code | +| **prompt-builder** | Engineers and validates instruction/prompt files | Dual-persona system with auto-testing | +| **security-reviewer** | OWASP vulnerability assessment with subagent-driven verification | Delegates all reference reading to subagents | +| **code-review-functional** | Pre-PR branch diff reviewer for functional correctness and logic gaps | Review-only; five focus areas; optional artifact save | +| **code-review-full** | Orchestrator running functional + standards reviews via subagents | Merges both reports; delegates to subagents; experimental | +| **code-review-standards** | Skills-based standards reviewer for local changes and PRs | Findings must trace to a loaded skill; experimental | ### Generator Agents @@ -91,12 +91,12 @@ The Research-Plan-Implement (RPI) workflow provides a structured approach to com ### Platform Integration Agents -| Agent | Purpose | Key Constraint | -|--------------------------|------------------------------------------------------------|-------------------------------------------------| -| **github-backlog-manager** | Consolidated GitHub backlog management with community interaction | Uses MCP GitHub tools | -| **jira-backlog-manager** | Consolidated Jira backlog management with workflow dispatch and handoff tracking | Uses Jira skill planning workflows | -| **ado-prd-to-wit** | Analyzes PRDs and plans Azure DevOps work item hierarchies | Planning-only; does not create work items | -| **jira-prd-to-wit** | Analyzes PRDs and plans Jira issue hierarchies | Planning-only; does not mutate Jira | +| Agent | Purpose | Key Constraint | +|----------------------------|----------------------------------------------------------------------------------|-------------------------------------------| +| **github-backlog-manager** | Consolidated GitHub backlog management with community interaction | Uses MCP GitHub tools | +| **jira-backlog-manager** | Consolidated Jira backlog management with workflow dispatch and handoff tracking | Uses Jira skill planning workflows | +| **ado-prd-to-wit** | Analyzes PRDs and plans Azure DevOps work item hierarchies | Planning-only; does not create work items | +| **jira-prd-to-wit** | Analyzes PRDs and plans Jira issue hierarchies | Planning-only; does not mutate Jira | ### Testing Agents diff --git a/.github/instructions/README.md b/.github/instructions/README.md index 8bb9617e6..d56cf5ba4 100644 --- a/.github/instructions/README.md +++ b/.github/instructions/README.md @@ -32,63 +32,63 @@ See [Contributing Instructions](../../docs/contributing/instructions.md) for aut ### Language and Technology -| File | Applies To | Purpose | -|--------------------------------------------------------------------------------------------|----------------------------------------------|------------------------------------------| -| [coding-standards/bash/bash.instructions.md](coding-standards/bash/bash.instructions.md) | `**/*.sh` | Bash script implementation standards | -| [coding-standards/bicep/bicep.instructions.md](coding-standards/bicep/bicep.instructions.md) | `**/bicep/**` | Bicep infrastructure as code patterns | -| [coding-standards/csharp/csharp.instructions.md](coding-standards/csharp/csharp.instructions.md) | `**/*.cs` | C# implementation and coding conventions | -| [coding-standards/csharp/csharp-tests.instructions.md](coding-standards/csharp/csharp-tests.instructions.md) | `**/*.cs` | C# test code standards | -| [coding-standards/rust/rust.instructions.md](coding-standards/rust/rust.instructions.md) | `**/*.rs` | Rust development conventions | -| [coding-standards/rust/rust-tests.instructions.md](coding-standards/rust/rust-tests.instructions.md) | `**/*.rs` | Rust test code standards | -| [coding-standards/python-script.instructions.md](coding-standards/python-script.instructions.md) | `**/*.py` | Python scripting implementation | -| [coding-standards/terraform/terraform.instructions.md](coding-standards/terraform/terraform.instructions.md) | `**/*.tf, **/*.tfvars, **/terraform/**` | Terraform infrastructure as code | -| [coding-standards/uv-projects.instructions.md](coding-standards/uv-projects.instructions.md) | `**/*.py, **/*.ipynb` | Python virtual environments using uv | +| File | Applies To | Purpose | +|--------------------------------------------------------------------------------------------------------------|-----------------------------------------|------------------------------------------| +| [coding-standards/bash/bash.instructions.md](coding-standards/bash/bash.instructions.md) | `**/*.sh` | Bash script implementation standards | +| [coding-standards/bicep/bicep.instructions.md](coding-standards/bicep/bicep.instructions.md) | `**/bicep/**` | Bicep infrastructure as code patterns | +| [coding-standards/csharp/csharp.instructions.md](coding-standards/csharp/csharp.instructions.md) | `**/*.cs` | C# implementation and coding conventions | +| [coding-standards/csharp/csharp-tests.instructions.md](coding-standards/csharp/csharp-tests.instructions.md) | `**/*.cs` | C# test code standards | +| [coding-standards/rust/rust.instructions.md](coding-standards/rust/rust.instructions.md) | `**/*.rs` | Rust development conventions | +| [coding-standards/rust/rust-tests.instructions.md](coding-standards/rust/rust-tests.instructions.md) | `**/*.rs` | Rust test code standards | +| [coding-standards/python-script.instructions.md](coding-standards/python-script.instructions.md) | `**/*.py` | Python scripting implementation | +| [coding-standards/terraform/terraform.instructions.md](coding-standards/terraform/terraform.instructions.md) | `**/*.tf, **/*.tfvars, **/terraform/**` | Terraform infrastructure as code | +| [coding-standards/uv-projects.instructions.md](coding-standards/uv-projects.instructions.md) | `**/*.py, **/*.ipynb` | Python virtual environments using uv | ### Documentation and Content -| File | Applies To | Purpose | -|-------------------------------------------------------------------------------|---------------------------------------------------------------|----------------------------------------| -| [hve-core/markdown.instructions.md](hve-core/markdown.instructions.md) | `**/*.md` | Markdown formatting standards | -| [hve-core/writing-style.instructions.md](hve-core/writing-style.instructions.md) | `**/*.md` | Voice, tone, and language conventions | -| [hve-core/prompt-builder.instructions.md](hve-core/prompt-builder.instructions.md) | `**/*.prompt.md, **/*.agent.md, **/*.instructions.md` | Prompt engineering artifact authoring | +| File | Applies To | Purpose | +|------------------------------------------------------------------------------------|-------------------------------------------------------|---------------------------------------| +| [hve-core/markdown.instructions.md](hve-core/markdown.instructions.md) | `**/*.md` | Markdown formatting standards | +| [hve-core/writing-style.instructions.md](hve-core/writing-style.instructions.md) | `**/*.md` | Voice, tone, and language conventions | +| [hve-core/prompt-builder.instructions.md](hve-core/prompt-builder.instructions.md) | `**/*.prompt.md, **/*.agent.md, **/*.instructions.md` | Prompt engineering artifact authoring | ### Git and Workflow -| File | Applies To | Purpose | -|---------------------------------------------------------------------------|----------------------------------|---------------------------------------| -| [hve-core/commit-message.instructions.md](hve-core/commit-message.instructions.md) | Commit actions | Conventional commit message format | -| [hve-core/git-merge.instructions.md](hve-core/git-merge.instructions.md) | Git operations | Merge, rebase, and conflict handling | -| [hve-core/pull-request.instructions.md](hve-core/pull-request.instructions.md) | `**/.copilot-tracking/pr/**` | PR generation workflow with subagents | -| [pull-request.instructions.md](pull-request.instructions.md) | `**/.copilot-tracking/pr/**` | Repo-specific PR conventions | +| File | Applies To | Purpose | +|------------------------------------------------------------------------------------|------------------------------|---------------------------------------| +| [hve-core/commit-message.instructions.md](hve-core/commit-message.instructions.md) | Commit actions | Conventional commit message format | +| [hve-core/git-merge.instructions.md](hve-core/git-merge.instructions.md) | Git operations | Merge, rebase, and conflict handling | +| [hve-core/pull-request.instructions.md](hve-core/pull-request.instructions.md) | `**/.copilot-tracking/pr/**` | PR generation workflow with subagents | +| [pull-request.instructions.md](pull-request.instructions.md) | `**/.copilot-tracking/pr/**` | Repo-specific PR conventions | ### Azure DevOps Integration -| File | Applies To | Purpose | -|-------------------------------------------------------------------------------------------|---------------------------------------------------------|------------------------------------| -| [ado/ado-create-pull-request.instructions.md](ado/ado-create-pull-request.instructions.md) | `**/.copilot-tracking/pr/new/**` | Pull request creation protocol | -| [ado/ado-get-build-info.instructions.md](ado/ado-get-build-info.instructions.md) | `**/.copilot-tracking/pr/*-build-*.md` | Build status and log retrieval | -| [ado/ado-update-wit-items.instructions.md](ado/ado-update-wit-items.instructions.md) | `**/.copilot-tracking/workitems/**/handoff-logs.md` | Work item creation and updates | -| [ado/ado-wit-discovery.instructions.md](ado/ado-wit-discovery.instructions.md) | `**/.copilot-tracking/workitems/discovery/**` | Work item discovery protocol | -| [ado/ado-wit-planning.instructions.md](ado/ado-wit-planning.instructions.md) | `**/.copilot-tracking/workitems/**` | Work item planning specifications | +| File | Applies To | Purpose | +|--------------------------------------------------------------------------------------------|-----------------------------------------------------|-----------------------------------| +| [ado/ado-create-pull-request.instructions.md](ado/ado-create-pull-request.instructions.md) | `**/.copilot-tracking/pr/new/**` | Pull request creation protocol | +| [ado/ado-get-build-info.instructions.md](ado/ado-get-build-info.instructions.md) | `**/.copilot-tracking/pr/*-build-*.md` | Build status and log retrieval | +| [ado/ado-update-wit-items.instructions.md](ado/ado-update-wit-items.instructions.md) | `**/.copilot-tracking/workitems/**/handoff-logs.md` | Work item creation and updates | +| [ado/ado-wit-discovery.instructions.md](ado/ado-wit-discovery.instructions.md) | `**/.copilot-tracking/workitems/discovery/**` | Work item discovery protocol | +| [ado/ado-wit-planning.instructions.md](ado/ado-wit-planning.instructions.md) | `**/.copilot-tracking/workitems/**` | Work item planning specifications | ### GitHub Integration -| File | Applies To | Purpose | -|-------------------------------------------------------------------------------------------|-------------------------------------------------------|-----------------------------------| -| [github/community-interaction.instructions.md](github/community-interaction.instructions.md) | `**/.github/instructions/github-backlog-*.instructions.md` | GitHub-facing communication patterns | -| [github/github-backlog-discovery.instructions.md](github/github-backlog-discovery.instructions.md) | `**/.copilot-tracking/github-issues/discovery/**` | Issue discovery protocol | -| [github/github-backlog-planning.instructions.md](github/github-backlog-planning.instructions.md) | `**/.copilot-tracking/github-issues/**` | Backlog planning specifications | -| [github/github-backlog-triage.instructions.md](github/github-backlog-triage.instructions.md) | `**/.copilot-tracking/github-issues/triage/**` | Issue triage workflow | -| [github/github-backlog-update.instructions.md](github/github-backlog-update.instructions.md) | `**/.copilot-tracking/github-issues/**/handoff-logs.md` | Issue execution workflow | +| File | Applies To | Purpose | +|----------------------------------------------------------------------------------------------------|------------------------------------------------------------|--------------------------------------| +| [github/community-interaction.instructions.md](github/community-interaction.instructions.md) | `**/.github/instructions/github-backlog-*.instructions.md` | GitHub-facing communication patterns | +| [github/github-backlog-discovery.instructions.md](github/github-backlog-discovery.instructions.md) | `**/.copilot-tracking/github-issues/discovery/**` | Issue discovery protocol | +| [github/github-backlog-planning.instructions.md](github/github-backlog-planning.instructions.md) | `**/.copilot-tracking/github-issues/**` | Backlog planning specifications | +| [github/github-backlog-triage.instructions.md](github/github-backlog-triage.instructions.md) | `**/.copilot-tracking/github-issues/triage/**` | Issue triage workflow | +| [github/github-backlog-update.instructions.md](github/github-backlog-update.instructions.md) | `**/.copilot-tracking/github-issues/**/handoff-logs.md` | Issue execution workflow | ### Jira Integration -| File | Applies To | Purpose | -|-------------------------------------------------------------------------------------------|----------------------------------------------------|------------------------------------------| -| [jira/jira-backlog-discovery.instructions.md](jira/jira-backlog-discovery.instructions.md) | `**/.copilot-tracking/jira-issues/discovery/**` | Jira issue discovery protocol | -| [jira/jira-backlog-planning.instructions.md](jira/jira-backlog-planning.instructions.md) | `**/.copilot-tracking/jira-issues/**` | Jira backlog planning specifications | -| [jira/jira-backlog-triage.instructions.md](jira/jira-backlog-triage.instructions.md) | `**/.copilot-tracking/jira-issues/triage/**` | Jira issue triage workflow | -| [jira/jira-backlog-update.instructions.md](jira/jira-backlog-update.instructions.md) | `**/.copilot-tracking/jira-issues/**/handoff-logs.md` | Jira issue execution workflow | +| File | Applies To | Purpose | +|--------------------------------------------------------------------------------------------|-------------------------------------------------------|--------------------------------------| +| [jira/jira-backlog-discovery.instructions.md](jira/jira-backlog-discovery.instructions.md) | `**/.copilot-tracking/jira-issues/discovery/**` | Jira issue discovery protocol | +| [jira/jira-backlog-planning.instructions.md](jira/jira-backlog-planning.instructions.md) | `**/.copilot-tracking/jira-issues/**` | Jira backlog planning specifications | +| [jira/jira-backlog-triage.instructions.md](jira/jira-backlog-triage.instructions.md) | `**/.copilot-tracking/jira-issues/triage/**` | Jira issue triage workflow | +| [jira/jira-backlog-update.instructions.md](jira/jira-backlog-update.instructions.md) | `**/.copilot-tracking/jira-issues/**/handoff-logs.md` | Jira issue execution workflow | ### GitLab Workflow Entry Points diff --git a/.github/instructions/pull-request.instructions.md b/.github/instructions/pull-request.instructions.md index b9799c1e3..adfa148ca 100644 --- a/.github/instructions/pull-request.instructions.md +++ b/.github/instructions/pull-request.instructions.md @@ -29,12 +29,12 @@ These sections require human verification. The agent does not modify them: When AI artifact changes are detected (`.instructions.md`, `.prompt.md`, `.agent.md`, `SKILL.md`), fill sub-sections from pr-reference-log.md analysis: -| Sub-section | Content Source | -|--------------------|-------------------------------------------------------------| -| User Request | Describe how to trigger or invoke the modified artifact | -| Execution Flow | Summarize key steps, tool usage, and decision points | -| Output Artifacts | List files or content created with brief previews | -| Success Indicators | Describe how users verify correct operation | +| Sub-section | Content Source | +|--------------------|---------------------------------------------------------| +| User Request | Describe how to trigger or invoke the modified artifact | +| Execution Flow | Summarize key steps, tool usage, and decision points | +| Output Artifacts | List files or content created with brief previews | +| Success Indicators | Describe how users verify correct operation | > [!NOTE] > Human review is recommended for agent-populated Sample Prompts content. @@ -64,21 +64,21 @@ Single authoritative reference for all checkbox handling in the PR template. All > [!NOTE] > Review this table when the PR template changes to ensure checkbox purposes and template locations remain accurate. -| Template Location | Checkbox Purpose | Handling | Step | Rule Summary | -|---|---|---|---|---| -| Type of Change | Auto-detected change type categories | Agent (auto) | Step 5 | Check via Change Type Detection pattern match | -| Type of Change | Prompt-builder review attestation | Manual | N/A | Human verification; never checked by agent | -| Type of Change | Free-form other type | Manual | N/A | Human verification; never checked by agent | -| Security Considerations | Sensitive data attestation | Agent (auto) | Step 5 | Check when customer data and secrets analysis both pass | -| Security Considerations | Dependency security review | Agent (conditional) | Step 5 | Evaluate only when dependency changes exist | -| Security Considerations | Privilege scope attestation | Agent (conditional) | Step 5 | Evaluate only when security scripts are modified | -| Checklist > Required Checks | Documentation update verification | Agent (assessed) | Step 5 | Check when docs/ changes accompany code changes | -| Checklist > Required Checks | Naming convention compliance | Agent (assessed) | Step 5 | Check when changed files follow repository patterns | -| Checklist > Required Checks | Backwards compatibility verification | Agent (assessed) | Step 5 | Check only when diff shows no removal of public API surfaces | -| Checklist > Required Checks | Test coverage verification | Agent (assessed) | Step 5 | Check only when test files are in changes | -| Checklist > AI Artifact Contributions | AI artifact contribution verification | Manual | N/A | Human verification; never checked by agent | -| Checklist > Required Automated Checks | Validation command results | Agent (automated) | Step 6 | Check for each command that passed in Step 6B | -| GHCP Maturity (inserted) | Non-stable artifact acknowledgment | Manual | N/A | Inserted only when non-stable GHCP artifacts detected; left unchecked | +| Template Location | Checkbox Purpose | Handling | Step | Rule Summary | +|---------------------------------------|---------------------------------------|---------------------|--------|-----------------------------------------------------------------------| +| Type of Change | Auto-detected change type categories | Agent (auto) | Step 5 | Check via Change Type Detection pattern match | +| Type of Change | Prompt-builder review attestation | Manual | N/A | Human verification; never checked by agent | +| Type of Change | Free-form other type | Manual | N/A | Human verification; never checked by agent | +| Security Considerations | Sensitive data attestation | Agent (auto) | Step 5 | Check when customer data and secrets analysis both pass | +| Security Considerations | Dependency security review | Agent (conditional) | Step 5 | Evaluate only when dependency changes exist | +| Security Considerations | Privilege scope attestation | Agent (conditional) | Step 5 | Evaluate only when security scripts are modified | +| Checklist > Required Checks | Documentation update verification | Agent (assessed) | Step 5 | Check when docs/ changes accompany code changes | +| Checklist > Required Checks | Naming convention compliance | Agent (assessed) | Step 5 | Check when changed files follow repository patterns | +| Checklist > Required Checks | Backwards compatibility verification | Agent (assessed) | Step 5 | Check only when diff shows no removal of public API surfaces | +| Checklist > Required Checks | Test coverage verification | Agent (assessed) | Step 5 | Check only when test files are in changes | +| Checklist > AI Artifact Contributions | AI artifact contribution verification | Manual | N/A | Human verification; never checked by agent | +| Checklist > Required Automated Checks | Validation command results | Agent (automated) | Step 6 | Check for each command that passed in Step 6B | +| GHCP Maturity (inserted) | Non-stable artifact acknowledgment | Manual | N/A | Inserted only when non-stable GHCP artifacts detected; left unchecked | When a conditional checkbox's trigger condition is not met, annotate the checkbox inline with `(N/A — {brief reason})` to distinguish skipped-as-not-applicable from evaluated-and-failed. @@ -104,7 +104,7 @@ Analyze changed files from the pr-reference-log.md analysis. This table maps fil | Copilot prompt | `.*\.prompt\.md$` | N/A | N/A | | Copilot agent | `.*\.agent\.md$` | N/A | N/A | | Copilot skill | `.*/SKILL\.md$` | N/A | N/A | -| Script or automation | `.*\.(ps1\|sh\|py)$` | N/A | N/A | +| Script or automation | `.*\.(ps1\|sh\|py)$` | N/A | N/A | Priority rules: diff --git a/.github/skills/experimental/powerpoint/tests/corpus/README.md b/.github/skills/experimental/powerpoint/tests/corpus/README.md index ee918c36e..f3973215d 100644 --- a/.github/skills/experimental/powerpoint/tests/corpus/README.md +++ b/.github/skills/experimental/powerpoint/tests/corpus/README.md @@ -23,12 +23,12 @@ Seed inputs for the Atheris fuzz harness. Each file is raw bytes consumed by `{target_index}_{description}` where `target_index` matches the FUZZ_TARGETS array position: -| Index | Target | -|-------|-------------------------------| -| 0 | `fuzz_resolve_color` | -| 1 | `fuzz_hex_brightness` | -| 2 | `fuzz_max_severity` | -| 3 | `fuzz_has_formatting_variation`| +| Index | Target | +|-------|---------------------------------| +| 0 | `fuzz_resolve_color` | +| 1 | `fuzz_hex_brightness` | +| 2 | `fuzz_max_severity` | +| 3 | `fuzz_has_formatting_variation` | ## Usage diff --git a/.github/skills/experimental/video-to-gif/examples/README.md b/.github/skills/experimental/video-to-gif/examples/README.md index 6f1316ad4..1c7cbbeba 100644 --- a/.github/skills/experimental/video-to-gif/examples/README.md +++ b/.github/skills/experimental/video-to-gif/examples/README.md @@ -99,7 +99,7 @@ done Expected results: | Algorithm | File Size | Visual Quality | Processing Time | -| --------------- | --------- | -------------- | --------------- | +|-----------------|-----------|----------------|-----------------| | sierra2_4a | Medium | High | Medium | | floyd_steinberg | Medium | Highest | Slow | | bayer | Smaller | Medium | Fast | diff --git a/.github/skills/jira/jira/references/jql-reference.md b/.github/skills/jira/jira/references/jql-reference.md index 017a5b727..f0dc0f5e3 100644 --- a/.github/skills/jira/jira/references/jql-reference.md +++ b/.github/skills/jira/jira/references/jql-reference.md @@ -44,14 +44,14 @@ slower, noisier, and harder to review in agent workflows. ## Common Filters -| Goal | JQL pattern | -|------|-------------| -| My active work | `assignee = currentUser() AND resolution = Unresolved` | -| Project backlog | `project = PROJ AND statusCategory != Done` | +| Goal | JQL pattern | +|-----------------------|------------------------------------------------------------| +| My active work | `assignee = currentUser() AND resolution = Unresolved` | +| Project backlog | `project = PROJ AND statusCategory != Done` | | Recently updated bugs | `project = PROJ AND issuetype = Bug ORDER BY updated DESC` | -| Sprint work | `project = PROJ AND sprint in openSprints()` | -| Label slice | `project = PROJ AND labels = backend` | -| Team ownership | `project = PROJ AND component = API` | +| Sprint work | `project = PROJ AND sprint in openSprints()` | +| Label slice | `project = PROJ AND labels = backend` | +| Team ownership | `project = PROJ AND component = API` | ## Common Search Commands diff --git a/.github/skills/security/owasp-agentic/references/00-vulnerability-index.md b/.github/skills/security/owasp-agentic/references/00-vulnerability-index.md index f1c5e6e19..cb8b5db12 100644 --- a/.github/skills/security/owasp-agentic/references/00-vulnerability-index.md +++ b/.github/skills/security/owasp-agentic/references/00-vulnerability-index.md @@ -10,18 +10,18 @@ Each entry includes its identifier, title, and primary category. ## Vulnerability catalog -| ID | Title | Category | -|---|---|---| -| ASI01:2026 | Agent Goal Hijack | Goal Integrity | -| ASI02:2026 | Tool Misuse and Exploitation | Tool Security | -| ASI03:2026 | Identity and Privilege Abuse | Access Control | -| ASI04:2026 | Agentic Supply Chain Vulnerabilities | Supply Chain | -| ASI05:2026 | Unexpected Code Execution | Execution Safety | -| ASI06:2026 | Memory and Context Poisoning | Data Integrity | -| ASI07:2026 | Insecure Inter-Agent Communication | Communication Security | -| ASI08:2026 | Cascading Failures | Resilience | -| ASI09:2026 | Human-Agent Trust Exploitation | Human Factors | -| ASI10:2026 | Rogue Agents | Behavioral Integrity | +| ID | Title | Category | +|------------|--------------------------------------|------------------------| +| ASI01:2026 | Agent Goal Hijack | Goal Integrity | +| ASI02:2026 | Tool Misuse and Exploitation | Tool Security | +| ASI03:2026 | Identity and Privilege Abuse | Access Control | +| ASI04:2026 | Agentic Supply Chain Vulnerabilities | Supply Chain | +| ASI05:2026 | Unexpected Code Execution | Execution Safety | +| ASI06:2026 | Memory and Context Poisoning | Data Integrity | +| ASI07:2026 | Insecure Inter-Agent Communication | Communication Security | +| ASI08:2026 | Cascading Failures | Resilience | +| ASI09:2026 | Human-Agent Trust Exploitation | Human Factors | +| ASI10:2026 | Rogue Agents | Behavioral Integrity | ## Cross-reference matrix diff --git a/.github/skills/security/owasp-cicd/references/00-vulnerability-index.md b/.github/skills/security/owasp-cicd/references/00-vulnerability-index.md index 0f6156e2b..ee6a6b0e1 100644 --- a/.github/skills/security/owasp-cicd/references/00-vulnerability-index.md +++ b/.github/skills/security/owasp-cicd/references/00-vulnerability-index.md @@ -10,18 +10,18 @@ Each entry includes its identifier, title, and primary category. ## Vulnerability catalog -| ID | Title | Category | -|---|---|---| -| CICD-SEC-1:2025 | Insufficient Flow Control Mechanisms | Flow Control | -| CICD-SEC-2:2025 | Inadequate Identity and Access Management | Identity Management | -| CICD-SEC-3:2025 | Dependency Chain Abuse | Supply Chain | -| CICD-SEC-4:2025 | Poisoned Pipeline Execution | Pipeline Security | -| CICD-SEC-5:2025 | Insufficient PBAC | Access Controls | -| CICD-SEC-6:2025 | Insufficient Credential Hygiene | Credential Management | -| CICD-SEC-7:2025 | Insecure System Configuration | Configuration Management | -| CICD-SEC-8:2025 | Ungoverned Usage of 3rd Party Services | Third-Party Governance | -| CICD-SEC-9:2025 | Improper Artifact Integrity Validation | Artifact Integrity | -| CICD-SEC-10:2025 | Insufficient Logging and Visibility | Logging and Visibility | +| ID | Title | Category | +|------------------|-------------------------------------------|--------------------------| +| CICD-SEC-1:2025 | Insufficient Flow Control Mechanisms | Flow Control | +| CICD-SEC-2:2025 | Inadequate Identity and Access Management | Identity Management | +| CICD-SEC-3:2025 | Dependency Chain Abuse | Supply Chain | +| CICD-SEC-4:2025 | Poisoned Pipeline Execution | Pipeline Security | +| CICD-SEC-5:2025 | Insufficient PBAC | Access Controls | +| CICD-SEC-6:2025 | Insufficient Credential Hygiene | Credential Management | +| CICD-SEC-7:2025 | Insecure System Configuration | Configuration Management | +| CICD-SEC-8:2025 | Ungoverned Usage of 3rd Party Services | Third-Party Governance | +| CICD-SEC-9:2025 | Improper Artifact Integrity Validation | Artifact Integrity | +| CICD-SEC-10:2025 | Insufficient Logging and Visibility | Logging and Visibility | ## Cross-reference matrix diff --git a/.github/skills/security/owasp-docker/references/00-vulnerability-index.md b/.github/skills/security/owasp-docker/references/00-vulnerability-index.md index d4bc5cda8..c6e2ee37d 100644 --- a/.github/skills/security/owasp-docker/references/00-vulnerability-index.md +++ b/.github/skills/security/owasp-docker/references/00-vulnerability-index.md @@ -10,14 +10,14 @@ Each entry includes its identifier, title, and primary category. ## Vulnerability catalog -| ID | Title | Category | -|---|---|---| -| D01 | Secure User Mapping | Privilege Management | -| D02 | Patch Management Strategy | Patch Management | -| D03 | Network Segmentation and Firewalling | Network Security | -| D04 | Secure Defaults and Hardening | Configuration Management | -| D05 | Maintain Security Contexts | Isolation | -| D07 | Resource Protection | Resource Management | +| ID | Title | Category | +|-----|--------------------------------------|--------------------------| +| D01 | Secure User Mapping | Privilege Management | +| D02 | Patch Management Strategy | Patch Management | +| D03 | Network Segmentation and Firewalling | Network Security | +| D04 | Secure Defaults and Hardening | Configuration Management | +| D05 | Maintain Security Contexts | Isolation | +| D07 | Resource Protection | Resource Management | ## Cross-reference matrix diff --git a/.github/skills/security/owasp-infrastructure/references/00-vulnerability-index.md b/.github/skills/security/owasp-infrastructure/references/00-vulnerability-index.md index 35f400c51..2ac502d6b 100644 --- a/.github/skills/security/owasp-infrastructure/references/00-vulnerability-index.md +++ b/.github/skills/security/owasp-infrastructure/references/00-vulnerability-index.md @@ -10,18 +10,18 @@ Each entry includes its identifier, title, and primary category. ## Vulnerability catalog -| ID | Title | Category | -|---|---|---| -| ISR01:2024 | Outdated Software | Patch Management | -| ISR02:2024 | Insufficient Threat Detection | Observability | -| ISR03:2024 | Insecure Configurations | Configuration Management | -| ISR04:2024 | Insecure Resource and User Management | Access Control | -| ISR05:2024 | Insecure Use of Cryptography | Data Protection | -| ISR06:2024 | Insecure Network Access Management | Network Security | -| ISR07:2024 | Insecure Authentication Methods and Default Credentials | Credential Hygiene | -| ISR08:2024 | Information Leakage | Data Protection | -| ISR09:2024 | Insecure Access to Resources and Management Components | Access Control | -| ISR10:2024 | Insufficient Asset Management and Documentation | Governance | +| ID | Title | Category | +|------------|---------------------------------------------------------|--------------------------| +| ISR01:2024 | Outdated Software | Patch Management | +| ISR02:2024 | Insufficient Threat Detection | Observability | +| ISR03:2024 | Insecure Configurations | Configuration Management | +| ISR04:2024 | Insecure Resource and User Management | Access Control | +| ISR05:2024 | Insecure Use of Cryptography | Data Protection | +| ISR06:2024 | Insecure Network Access Management | Network Security | +| ISR07:2024 | Insecure Authentication Methods and Default Credentials | Credential Hygiene | +| ISR08:2024 | Information Leakage | Data Protection | +| ISR09:2024 | Insecure Access to Resources and Management Components | Access Control | +| ISR10:2024 | Insufficient Asset Management and Documentation | Governance | ## Cross-reference matrix diff --git a/.github/skills/security/owasp-llm/references/00-vulnerability-index.md b/.github/skills/security/owasp-llm/references/00-vulnerability-index.md index d647d4ef8..cce2217ee 100644 --- a/.github/skills/security/owasp-llm/references/00-vulnerability-index.md +++ b/.github/skills/security/owasp-llm/references/00-vulnerability-index.md @@ -10,18 +10,18 @@ Each entry includes its identifier, title, and primary category. ## Vulnerability catalog -| ID | Title | Category | -|---|---|---| -| LLM01:2025 | Prompt Injection | Input Integrity | -| LLM02:2025 | Sensitive Information Disclosure | Data Protection | -| LLM03:2025 | Supply Chain | Supply Chain | -| LLM04:2025 | Data and Model Poisoning | Data Integrity | -| LLM05:2025 | Improper Output Handling | Output Safety | -| LLM06:2025 | Excessive Agency | Access Control | -| LLM07:2025 | System Prompt Leakage | Configuration Security | -| LLM08:2025 | Vector and Embedding Weaknesses | Data Integrity | -| LLM09:2025 | Misinformation | Output Reliability | -| LLM10:2025 | Unbounded Consumption | Resource Management | +| ID | Title | Category | +|------------|----------------------------------|------------------------| +| LLM01:2025 | Prompt Injection | Input Integrity | +| LLM02:2025 | Sensitive Information Disclosure | Data Protection | +| LLM03:2025 | Supply Chain | Supply Chain | +| LLM04:2025 | Data and Model Poisoning | Data Integrity | +| LLM05:2025 | Improper Output Handling | Output Safety | +| LLM06:2025 | Excessive Agency | Access Control | +| LLM07:2025 | System Prompt Leakage | Configuration Security | +| LLM08:2025 | Vector and Embedding Weaknesses | Data Integrity | +| LLM09:2025 | Misinformation | Output Reliability | +| LLM10:2025 | Unbounded Consumption | Resource Management | ## Cross-reference matrix diff --git a/.github/skills/security/owasp-mcp/references/00-vulnerability-index.md b/.github/skills/security/owasp-mcp/references/00-vulnerability-index.md index cec3cc2f0..e9750d994 100644 --- a/.github/skills/security/owasp-mcp/references/00-vulnerability-index.md +++ b/.github/skills/security/owasp-mcp/references/00-vulnerability-index.md @@ -10,18 +10,18 @@ Each entry includes its identifier, title, and primary attack category. ## Vulnerability catalog -| ID | Title | Category | -|---|---|---| -| MCP01:2025 | Token Mismanagement and Secret Exposure | Credential Hygiene | -| MCP02:2025 | Privilege Escalation via Scope Creep | Access Control | -| MCP03:2025 | Tool Poisoning | Supply Chain / Integrity | +| ID | Title | Category | +|------------|--------------------------------------------------------|--------------------------| +| MCP01:2025 | Token Mismanagement and Secret Exposure | Credential Hygiene | +| MCP02:2025 | Privilege Escalation via Scope Creep | Access Control | +| MCP03:2025 | Tool Poisoning | Supply Chain / Integrity | | MCP04:2025 | Software Supply Chain Attacks and Dependency Tampering | Supply Chain / Integrity | -| MCP05:2025 | Command Injection and Execution | Injection | -| MCP06:2025 | Prompt Injection via Contextual Payloads | Injection | -| MCP07:2025 | Insufficient Authentication and Authorization | Access Control | -| MCP08:2025 | Lack of Audit and Telemetry | Observability | -| MCP09:2025 | Shadow MCP Servers | Governance | -| MCP10:2025 | Context Injection and Over-Sharing | Data Isolation | +| MCP05:2025 | Command Injection and Execution | Injection | +| MCP06:2025 | Prompt Injection via Contextual Payloads | Injection | +| MCP07:2025 | Insufficient Authentication and Authorization | Access Control | +| MCP08:2025 | Lack of Audit and Telemetry | Observability | +| MCP09:2025 | Shadow MCP Servers | Governance | +| MCP10:2025 | Context Injection and Over-Sharing | Data Isolation | ## Cross-reference matrix diff --git a/.github/skills/security/owasp-top-10/references/00-vulnerability-index.md b/.github/skills/security/owasp-top-10/references/00-vulnerability-index.md index 13d274f74..95c42224c 100644 --- a/.github/skills/security/owasp-top-10/references/00-vulnerability-index.md +++ b/.github/skills/security/owasp-top-10/references/00-vulnerability-index.md @@ -10,18 +10,18 @@ Each entry includes its identifier, title, and primary category. ## Vulnerability catalog -| ID | Title | Category | -|---|---|---| -| A01:2025 | Broken Access Control | Access Control | -| A02:2025 | Security Misconfiguration | Configuration Management | -| A03:2025 | Software Supply Chain Failures | Supply Chain | -| A04:2025 | Cryptographic Failures | Cryptography | -| A05:2025 | Injection | Input Validation | -| A06:2025 | Insecure Design | Architecture and Design | -| A07:2025 | Authentication Failures | Authentication | -| A08:2025 | Software or Data Integrity Failures | Data Integrity | -| A09:2025 | Security Logging and Alerting Failures | Logging and Monitoring | -| A10:2025 | Mishandling of Exceptional Conditions | Error Handling | +| ID | Title | Category | +|----------|----------------------------------------|--------------------------| +| A01:2025 | Broken Access Control | Access Control | +| A02:2025 | Security Misconfiguration | Configuration Management | +| A03:2025 | Software Supply Chain Failures | Supply Chain | +| A04:2025 | Cryptographic Failures | Cryptography | +| A05:2025 | Injection | Input Validation | +| A06:2025 | Insecure Design | Architecture and Design | +| A07:2025 | Authentication Failures | Authentication | +| A08:2025 | Software or Data Integrity Failures | Data Integrity | +| A09:2025 | Security Logging and Alerting Failures | Logging and Monitoring | +| A10:2025 | Mishandling of Exceptional Conditions | Error Handling | ## Cross-reference matrix diff --git a/.github/skills/security/secure-by-design/references/00-principle-index.md b/.github/skills/security/secure-by-design/references/00-principle-index.md index 334307916..fb9e4c51b 100644 --- a/.github/skills/security/secure-by-design/references/00-principle-index.md +++ b/.github/skills/security/secure-by-design/references/00-principle-index.md @@ -11,19 +11,19 @@ Australian ASD/ACSC Secure by Design Foundations into a unified principle area. ## Principle catalog -| ID | Title | Category | UK Principle | AU Foundation | -|---|---|---|---|---| -| SBD-01 | Security Governance | Governance | P1: Create responsibility for cyber security risk | F1: Holistic secure organisation | -| SBD-02 | Risk-Driven Approach | Risk Management | P3: Adopt a risk-driven approach | F2: Early and sustained security | -| SBD-03 | Secure Product Development | Secure Development | P10: Make changes securely | F3: Secure product development | -| SBD-04 | Supply Chain Security | Supply Chain | P2: Source secure technology products | F3: Secure product development (supply chain) | -| SBD-05 | Usable Security Controls | Usability | P4: Design usable security controls | F3: Secure by Default | -| SBD-06 | Detect and Respond | Detection and Response | P5: Build in detect and respond security | F5: Continuous assurance (monitoring) | -| SBD-07 | Flexible Architecture | Architecture | P6: Design flexible architectures | — | -| SBD-08 | Minimize Attack Surface | Attack Surface | P7: Minimise the attack surface | F3: Secure product development (surface reduction) | -| SBD-09 | Defense in Depth | Layered Defense | P8: Defend in depth | F2: Early and sustained security (defence in depth) | -| SBD-10 | Continuous Assurance | Assurance and Testing | P9: Embed continuous assurance | F4: Testing, F5: Continuous assurance | -| SBD-11 | Secure Deprecation | Deprecation | P7: Minimise the attack surface (retire securely) | F6: Secure deprecation | +| ID | Title | Category | UK Principle | AU Foundation | +|--------|----------------------------|------------------------|---------------------------------------------------|-----------------------------------------------------| +| SBD-01 | Security Governance | Governance | P1: Create responsibility for cyber security risk | F1: Holistic secure organisation | +| SBD-02 | Risk-Driven Approach | Risk Management | P3: Adopt a risk-driven approach | F2: Early and sustained security | +| SBD-03 | Secure Product Development | Secure Development | P10: Make changes securely | F3: Secure product development | +| SBD-04 | Supply Chain Security | Supply Chain | P2: Source secure technology products | F3: Secure product development (supply chain) | +| SBD-05 | Usable Security Controls | Usability | P4: Design usable security controls | F3: Secure by Default | +| SBD-06 | Detect and Respond | Detection and Response | P5: Build in detect and respond security | F5: Continuous assurance (monitoring) | +| SBD-07 | Flexible Architecture | Architecture | P6: Design flexible architectures | — | +| SBD-08 | Minimize Attack Surface | Attack Surface | P7: Minimise the attack surface | F3: Secure product development (surface reduction) | +| SBD-09 | Defense in Depth | Layered Defense | P8: Defend in depth | F2: Early and sustained security (defence in depth) | +| SBD-10 | Continuous Assurance | Assurance and Testing | P9: Embed continuous assurance | F4: Testing, F5: Continuous assurance | +| SBD-11 | Secure Deprecation | Deprecation | P7: Minimise the attack surface (retire securely) | F6: Secure deprecation | ## Cross-reference matrix diff --git a/.github/skills/shared/pr-reference/references/REFERENCE.md b/.github/skills/shared/pr-reference/references/REFERENCE.md index 3d40314ea..ccc8d0e3f 100644 --- a/.github/skills/shared/pr-reference/references/REFERENCE.md +++ b/.github/skills/shared/pr-reference/references/REFERENCE.md @@ -60,7 +60,7 @@ index 0000000..a1b2c3d ### Element Reference | Element | Description | -| ------------------ | -------------------------------------------------------------- | +|--------------------|----------------------------------------------------------------| | `` | Active git branch name or `detached@` in CI environments | | `` | Comparison branch provided via `--base-branch` / `-BaseBranch` | | `` | Ordered commit entries with hash, date, subject, and body | @@ -144,12 +144,12 @@ Use a custom filename for work item discovery workflows that analyze branch chan Different workflows use different output paths and filenames: -| Workflow | Output Filename | Output Path | -| --------------------- | -------------------- | --------------------------------------------------------------- | -| Default PR generation | `pr-reference.xml` | `.copilot-tracking/pr/pr-reference.xml` | -| PR review | `pr-reference.xml` | `.copilot-tracking/pr/review/{{branch}}/pr-reference.xml` | -| New PR creation | `pr-reference.xml` | `.copilot-tracking/pr/new/{{branch}}/pr-reference.xml` | -| Work item discovery | `git-branch-diff.xml`| `.copilot-tracking/workitems/discovery/{{folder}}/git-branch-diff.xml` | +| Workflow | Output Filename | Output Path | +|-----------------------|-----------------------|------------------------------------------------------------------------| +| Default PR generation | `pr-reference.xml` | `.copilot-tracking/pr/pr-reference.xml` | +| PR review | `pr-reference.xml` | `.copilot-tracking/pr/review/{{branch}}/pr-reference.xml` | +| New PR creation | `pr-reference.xml` | `.copilot-tracking/pr/new/{{branch}}/pr-reference.xml` | +| Work item discovery | `git-branch-diff.xml` | `.copilot-tracking/workitems/discovery/{{folder}}/git-branch-diff.xml` | ## Utility Script Reference @@ -157,25 +157,25 @@ Different workflows use different output paths and filenames: Extracts file paths from the PR reference XML diff headers. -| Parameter | Flag (bash) | Flag (PowerShell) | Default | Description | -| --------------- | -------------- | ----------------- | --------------------------------------- | ---------------------------------------- | -| Input path | `--input, -i` | `-InputPath` | `.copilot-tracking/pr/pr-reference.xml` | Path to the PR reference XML | -| Change type | `--type, -t` | `-Type` | `all` | Filter: all, added, deleted, modified, renamed | -| Output format | `--format, -f` | `-Format` | `plain` | Output: plain, json, or markdown | +| Parameter | Flag (bash) | Flag (PowerShell) | Default | Description | +|---------------|----------------|-------------------|-----------------------------------------|------------------------------------------------| +| Input path | `--input, -i` | `-InputPath` | `.copilot-tracking/pr/pr-reference.xml` | Path to the PR reference XML | +| Change type | `--type, -t` | `-Type` | `all` | Filter: all, added, deleted, modified, renamed | +| Output format | `--format, -f` | `-Format` | `plain` | Output: plain, json, or markdown | ### read-diff Reads diff content with chunking and file filtering support. -| Parameter | Flag (bash) | Flag (PowerShell) | Default | Description | -| --------------- | ----------------- | ----------------- | --------------------------------------- | ---------------------------------------- | -| Input path | `--input, -i` | `-InputPath` | `.copilot-tracking/pr/pr-reference.xml` | Path to the PR reference XML | -| Chunk number | `--chunk, -c` | `-Chunk` | - | 1-based chunk number to read | -| Chunk size | `--chunk-size, -s`| `-ChunkSize` | 500 | Lines per chunk | -| Line range | `--lines, -l` | `-Lines` | - | Range format: START,END or START-END | -| File path | `--file, -f` | `-File` | - | Extract diff for specific file | -| Summary | `--summary` | `-Summary` | - | Show file list with change stats | -| Info | `--info` | `-Info` | - | Show chunk breakdown without content | +| Parameter | Flag (bash) | Flag (PowerShell) | Default | Description | +|--------------|--------------------|-------------------|-----------------------------------------|--------------------------------------| +| Input path | `--input, -i` | `-InputPath` | `.copilot-tracking/pr/pr-reference.xml` | Path to the PR reference XML | +| Chunk number | `--chunk, -c` | `-Chunk` | - | 1-based chunk number to read | +| Chunk size | `--chunk-size, -s` | `-ChunkSize` | 500 | Lines per chunk | +| Line range | `--lines, -l` | `-Lines` | - | Range format: START,END or START-END | +| File path | `--file, -f` | `-File` | - | Extract diff for specific file | +| Summary | `--summary` | `-Summary` | - | Show file list with change stats | +| Info | `--info` | `-Info` | - | Show chunk breakdown without content | ## Semantic Invocation diff --git a/.github/workflows/README.md b/.github/workflows/README.md index f0f0befec..253c4dce4 100644 --- a/.github/workflows/README.md +++ b/.github/workflows/README.md @@ -248,13 +248,13 @@ This architecture ensures: Workflow Execution Matrix: -| Event | Workflows That Run | CodeQL Included | -|--------------------------------------|----------------------------------------------------------|-----------------------| -| Open PR to main/develop | `pr-validation.yml` (9 jobs) | ✅ Yes | -| Push to PR branch | `pr-validation.yml` (9 jobs) | ✅ Yes | -| Merge to main | `release-stable.yml` (5 jobs) | ✅ Yes | -| Sunday 4AM UTC | `codeql-analysis.yml`, `weekly-security-maintenance.yml` | ✅ Yes (standalone) | -| Feature branch push (no open PR)[^1] | None | ❌ No | +| Event | Workflows That Run | CodeQL Included | +|--------------------------------------|----------------------------------------------------------|---------------------| +| Open PR to main/develop | `pr-validation.yml` (9 jobs) | ✅ Yes | +| Push to PR branch | `pr-validation.yml` (9 jobs) | ✅ Yes | +| Merge to main | `release-stable.yml` (5 jobs) | ✅ Yes | +| Sunday 4AM UTC | `codeql-analysis.yml`, `weekly-security-maintenance.yml` | ✅ Yes (standalone) | +| Feature branch push (no open PR)[^1] | None | ❌ No | [^1]: Feature branches without an open PR are not validated. Open a PR to main or develop to trigger validation workflows. @@ -549,12 +549,12 @@ Use `continue-on-error: true` to prevent workflow failure on SARIF upload issues ## Configuration Files -| File | Purpose | Used By | -|-------------------------------------------------------|------------------------------|-----------------------------| -| `scripts/linting/PSScriptAnalyzer.psd1` | PowerShell linting rules | `ps-script-analyzer.yml` | -| `.markdownlint.json` | Markdown formatting rules | `markdown-lint.yml` | -| `scripts/linting/markdown-link-check.config.json` | Link checking configuration | `markdown-link-check.yml` | -| `.cspell.json` | Spell checking configuration | `spell-check.yml` | +| File | Purpose | Used By | +|----------------------------------------------------------------|------------------------------|-----------------------------| +| `scripts/linting/PSScriptAnalyzer.psd1` | PowerShell linting rules | `ps-script-analyzer.yml` | +| `.markdownlint.json` | Markdown formatting rules | `markdown-lint.yml` | +| `scripts/linting/markdown-link-check.config.json` | Link checking configuration | `markdown-link-check.yml` | +| `.cspell.json` | Spell checking configuration | `spell-check.yml` | | `.github/instructions/hve-core/markdown.instructions.md` | Markdown style guide | All markdown workflows | | `.github/instructions/hve-core/commit-message.instructions.md` | Commit message standards | All workflows (informative) | diff --git a/.github/workflows/doc-update-check.md b/.github/workflows/doc-update-check.md index e222b6971..20c221bcd 100644 --- a/.github/workflows/doc-update-check.md +++ b/.github/workflows/doc-update-check.md @@ -84,13 +84,13 @@ When creating issues, use the **bug-report** template structure from `.github/IS ### Bug-Report Template Field Mapping -| Template Field | Content | -|--------------------|----------------------------------------------------------------------| -| Component | Always `Documentation` | -| Bug Description | Describe what documentation is stale and what changed in code | -| Expected Behavior | Describe what the documentation should say after the update | -| Steps to Reproduce | Reference the specific commit or PR that introduced the change | -| Additional Context | Link to the specific documentation file(s) and code file(s) | +| Template Field | Content | +|--------------------|----------------------------------------------------------------| +| Component | Always `Documentation` | +| Bug Description | Describe what documentation is stale and what changed in code | +| Expected Behavior | Describe what the documentation should say after the update | +| Steps to Reproduce | Reference the specific commit or PR that introduced the change | +| Additional Context | Link to the specific documentation file(s) and code file(s) | ## Constraints From ec02addf7703b017f9565607d551df1138e9e034 Mon Sep 17 00:00:00 2001 From: Bill Berry Date: Fri, 1 May 2026 18:02:22 -0700 Subject: [PATCH 06/21] fix(prompts): align SSSC capture/from-* prompts with sssc-state schema MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Replace removed outputPreferences references with userPreferences.targetSystem to match sssc-state.schema.json 🔒 - Generated by Copilot --- .github/prompts/security/sssc-capture.prompt.md | 2 +- .github/prompts/security/sssc-from-brd.prompt.md | 2 +- .github/prompts/security/sssc-from-prd.prompt.md | 2 +- .github/prompts/security/sssc-from-security-plan.prompt.md | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/prompts/security/sssc-capture.prompt.md b/.github/prompts/security/sssc-capture.prompt.md index 5be7aa2ac..d170e4730 100644 --- a/.github/prompts/security/sssc-capture.prompt.md +++ b/.github/prompts/security/sssc-capture.prompt.md @@ -40,7 +40,7 @@ Present pre-scan results as a checklist: ### Output Preferences -Ask the user up front whether they have output preferences for backlog generation in Phase 5: dual-format ADO and GitHub work items, single-platform output, or a custom template stored under `.copilot-tracking/sssc-plans/references/`. Capture the answer in `state.json` under `outputPreferences` so later phases honor the choice without re-asking. +Ask the user up front whether they have output preferences for backlog generation in Phase 5: dual-format ADO and GitHub work items (`both`), ADO-only (`ado`), or GitHub-only (`github`). Capture the answer in `state.json` under `userPreferences.targetSystem` (allowed values: `ado`, `github`, `both`) so later phases honor the choice without re-asking. When the user supplies a custom backlog template, store it under `.copilot-tracking/sssc-plans/references/` and still record the closest matching `targetSystem` value. ### Initialization diff --git a/.github/prompts/security/sssc-from-brd.prompt.md b/.github/prompts/security/sssc-from-brd.prompt.md index b5772a6c3..ed919505c 100644 --- a/.github/prompts/security/sssc-from-brd.prompt.md +++ b/.github/prompts/security/sssc-from-brd.prompt.md @@ -49,7 +49,7 @@ If zero BRD artifacts are found, fall back to capture mode and explain the switc ### Output Preferences -Ask the user up front whether they have output preferences for backlog generation in Phase 5: dual-format ADO and GitHub work items, single-platform output, or a custom template stored under `.copilot-tracking/sssc-plans/references/`. Capture the answer in `state.json` under `outputPreferences` so later phases honor the choice without re-asking. +Ask the user up front whether they have output preferences for backlog generation in Phase 5: dual-format ADO and GitHub work items (`both`), ADO-only (`ado`), or GitHub-only (`github`). Capture the answer in `state.json` under `userPreferences.targetSystem` (allowed values: `ado`, `github`, `both`) so later phases honor the choice without re-asking. When the user supplies a custom backlog template, store it under `.copilot-tracking/sssc-plans/references/` and still record the closest matching `targetSystem` value. ### Scope Extraction diff --git a/.github/prompts/security/sssc-from-prd.prompt.md b/.github/prompts/security/sssc-from-prd.prompt.md index fda147b5b..977ed0306 100644 --- a/.github/prompts/security/sssc-from-prd.prompt.md +++ b/.github/prompts/security/sssc-from-prd.prompt.md @@ -49,7 +49,7 @@ If zero PRD artifacts are found, fall back to capture mode and explain the switc ### Output Preferences -Ask the user up front whether they have output preferences for backlog generation in Phase 5: dual-format ADO and GitHub work items, single-platform output, or a custom template stored under `.copilot-tracking/sssc-plans/references/`. Capture the answer in `state.json` under `outputPreferences` so later phases honor the choice without re-asking. +Ask the user up front whether they have output preferences for backlog generation in Phase 5: dual-format ADO and GitHub work items (`both`), ADO-only (`ado`), or GitHub-only (`github`). Capture the answer in `state.json` under `userPreferences.targetSystem` (allowed values: `ado`, `github`, `both`) so later phases honor the choice without re-asking. When the user supplies a custom backlog template, store it under `.copilot-tracking/sssc-plans/references/` and still record the closest matching `targetSystem` value. ### Scope Extraction diff --git a/.github/prompts/security/sssc-from-security-plan.prompt.md b/.github/prompts/security/sssc-from-security-plan.prompt.md index 7bc7581eb..383899bd2 100644 --- a/.github/prompts/security/sssc-from-security-plan.prompt.md +++ b/.github/prompts/security/sssc-from-security-plan.prompt.md @@ -45,7 +45,7 @@ If zero Security Planner artifacts are found, fall back to capture mode and expl ### Output Preferences -Ask the user up front whether they have output preferences for backlog generation in Phase 5: dual-format ADO and GitHub work items, single-platform output, or a custom template stored under `.copilot-tracking/sssc-plans/references/`. Capture the answer in `state.json` under `outputPreferences` so later phases honor the choice without re-asking. +Ask the user up front whether they have output preferences for backlog generation in Phase 5: dual-format ADO and GitHub work items (`both`), ADO-only (`ado`), or GitHub-only (`github`). Capture the answer in `state.json` under `userPreferences.targetSystem` (allowed values: `ado`, `github`, `both`) so later phases honor the choice without re-asking. When the user supplies a custom backlog template, store it under `.copilot-tracking/sssc-plans/references/` and still record the closest matching `targetSystem` value. ### Scope Extraction From 902d9ce65b3682f7e195f6c144db4f52b59ea52d Mon Sep 17 00:00:00 2001 From: Bill Berry Date: Fri, 1 May 2026 18:02:31 -0700 Subject: [PATCH 07/21] fix(agents): align sssc-planner agent with sssc-state schema (sbom/scorecardProjection) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Replace removed adoptionPlaybook/executiveSummary references with the current sbom and scorecardProjection state slots 🔒 - Generated by Copilot --- .github/agents/security/sssc-planner.agent.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/agents/security/sssc-planner.agent.md b/.github/agents/security/sssc-planner.agent.md index 129e41ca0..6b93c3608 100644 --- a/.github/agents/security/sssc-planner.agent.md +++ b/.github/agents/security/sssc-planner.agent.md @@ -142,8 +142,8 @@ State JSON schema for `state.json`: "targetSystem": "both", "audienceProfile": "mixed", "includeOptionalArtifacts": { - "adoptionPlaybook": false, - "executiveSummary": false, + "sbom": false, + "scorecardProjection": false, "artifactSigning": false } }, From 147973bc4084cfd85a22f2fde0f2ba070811895f Mon Sep 17 00:00:00 2001 From: Bill Berry Date: Fri, 1 May 2026 18:02:41 -0700 Subject: [PATCH 08/21] fix(instructions): align SSSC handoff/identity instructions with sssc-state schema MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Move signingRequested under state and expand userPreferences to the five fields defined by sssc-state.schema.json 🔒 - Generated by Copilot --- .../security/sssc-handoff.instructions.md | 2 +- .../security/sssc-identity.instructions.md | 12 +++++++++++- 2 files changed, 12 insertions(+), 2 deletions(-) diff --git a/.github/instructions/security/sssc-handoff.instructions.md b/.github/instructions/security/sssc-handoff.instructions.md index a124237c7..7223f140d 100644 --- a/.github/instructions/security/sssc-handoff.instructions.md +++ b/.github/instructions/security/sssc-handoff.instructions.md @@ -102,7 +102,7 @@ After both platform-specific handoff files are written, sign the SSSC planner ar pwsh scripts/security/Sign-PlannerArtifacts.ps1 -SessionPath '.copilot-tracking/sssc-plans/' -ManifestName 'sssc-manifest.json' ``` -Append `-IncludeCosign` when the user has opted in to cosign keyless signing via `userPreferences.signingRequested`. Cosign keyless signing requires `cosign` in PATH and a Sigstore-compatible OIDC identity provider; the script gracefully skips signing with a warning when cosign is unavailable. +Append `-IncludeCosign` when the user has opted in to cosign keyless signing via the top-level `signingRequested` field in `state.json`. Cosign keyless signing requires `cosign` in PATH and a Sigstore-compatible OIDC identity provider; the script gracefully skips signing with a warning when cosign is unavailable. The parameter contract for `Sign-PlannerArtifacts.ps1` exposes two mutually exclusive parameter sets: diff --git a/.github/instructions/security/sssc-identity.instructions.md b/.github/instructions/security/sssc-identity.instructions.md index 742514d76..bd70fc459 100644 --- a/.github/instructions/security/sssc-identity.instructions.md +++ b/.github/instructions/security/sssc-identity.instructions.md @@ -117,7 +117,17 @@ State persists across sessions in a JSON file at `.copilot-tracking/sssc-plans/{ }, "referencesProcessed": [], "nextActions": [], - "userPreferences": { "autonomyTier": "partial" }, + "userPreferences": { + "autonomyTier": "partial", + "outputDetailLevel": "standard", + "targetSystem": "both", + "audienceProfile": "mixed", + "includeOptionalArtifacts": { + "sbom": false, + "scorecardProjection": false, + "artifactSigning": false + } + }, "ssscEnabled": true, "signingRequested": false, "signingManifestPath": null, From dfba547a5a9cca1f8a3c6cfdf9fe6f78cbfa6a41 Mon Sep 17 00:00:00 2001 From: Bill Berry Date: Fri, 1 May 2026 18:02:55 -0700 Subject: [PATCH 09/21] fix(scripts): tighten Sign-PlannerArtifacts repo-root guard and silence test cleanup catch MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- scripts/security/Sign-PlannerArtifacts.ps1 | 7 +++++-- scripts/tests/linting/Test-Format-MarkdownTables.Tests.ps1 | 2 +- 2 files changed, 6 insertions(+), 3 deletions(-) diff --git a/scripts/security/Sign-PlannerArtifacts.ps1 b/scripts/security/Sign-PlannerArtifacts.ps1 index 5938d26ce..985bd3e38 100644 --- a/scripts/security/Sign-PlannerArtifacts.ps1 +++ b/scripts/security/Sign-PlannerArtifacts.ps1 @@ -177,11 +177,14 @@ if ($MyInvocation.InvocationName -ne '.') { Write-Host " ✅ $relativePath" -ForegroundColor Green } + $repoRootBoundary = if ($repoRoot.EndsWith([IO.Path]::DirectorySeparatorChar)) { $repoRoot } else { $repoRoot + [IO.Path]::DirectorySeparatorChar } $manifest = [ordered]@{ version = '1.0' projectSlug = $sessionLabel - sessionPath = if ($artifactDir.StartsWith($repoRoot, [System.StringComparison]::OrdinalIgnoreCase)) { - ($artifactDir.Substring($repoRoot.Length).TrimStart('\','/') -replace '\\','/') + sessionPath = if ($artifactDir.Equals($repoRoot, [System.StringComparison]::OrdinalIgnoreCase)) { + '' + } elseif ($artifactDir.StartsWith($repoRootBoundary, [System.StringComparison]::OrdinalIgnoreCase)) { + ($artifactDir.Substring($repoRootBoundary.Length) -replace '\\','/') } else { ($artifactDir -replace '\\','/') } diff --git a/scripts/tests/linting/Test-Format-MarkdownTables.Tests.ps1 b/scripts/tests/linting/Test-Format-MarkdownTables.Tests.ps1 index 00e8188e7..a015c850b 100644 --- a/scripts/tests/linting/Test-Format-MarkdownTables.Tests.ps1 +++ b/scripts/tests/linting/Test-Format-MarkdownTables.Tests.ps1 @@ -142,7 +142,7 @@ AfterAll { # (which deletes the link itself, not the target) so the subsequent # recursive remove cannot follow it into real content. if ($script:MainNodeModulesLink -and (Test-Path $script:MainNodeModulesLink)) { - try { [System.IO.Directory]::Delete($script:MainNodeModulesLink, $false) } catch { } + try { [System.IO.Directory]::Delete($script:MainNodeModulesLink, $false) } catch { Write-Verbose "junction cleanup ignored: $_" } } Remove-Item -Path $script:MainTestRoot -Recurse -Force -ErrorAction SilentlyContinue } From dcee8644db54561ce65c376bbb5d12de8aebfcd4 Mon Sep 17 00:00:00 2001 From: Bill Berry Date: Fri, 1 May 2026 18:03:18 -0700 Subject: [PATCH 10/21] ci(workflows): install npm dependencies before running Pester tests MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- .github/workflows/pester-tests.yml | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/.github/workflows/pester-tests.yml b/.github/workflows/pester-tests.yml index 1756d809e..ee811cd51 100644 --- a/.github/workflows/pester-tests.yml +++ b/.github/workflows/pester-tests.yml @@ -36,6 +36,15 @@ jobs: persist-credentials: false fetch-depth: 0 + - name: Set up Node.js + uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0 + with: + node-version: "24" + cache: "npm" + + - name: Install JavaScript dependencies + run: npm ci + - name: Install Pester shell: pwsh run: | From c99e5bab91121a93acabef5778e78e0bd5a28f98 Mon Sep 17 00:00:00 2001 From: Bill Berry Date: Fri, 1 May 2026 18:06:27 -0700 Subject: [PATCH 11/21] chore: refresh stale ms.date on workflows and video-to-gif example READMEs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Bump ms.date to 2026-05-01 to clear freshness check warnings on these long-stable docs 🔒 - Generated by Copilot --- .github/skills/experimental/video-to-gif/examples/README.md | 2 +- .github/workflows/README.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/skills/experimental/video-to-gif/examples/README.md b/.github/skills/experimental/video-to-gif/examples/README.md index 1c7cbbeba..acbd9edf1 100644 --- a/.github/skills/experimental/video-to-gif/examples/README.md +++ b/.github/skills/experimental/video-to-gif/examples/README.md @@ -2,7 +2,7 @@ title: Video-to-GIF Examples description: Usage examples and test data generation for video-to-gif skill author: Microsoft -ms.date: 2026-01-18 +ms.date: 2026-05-01 ms.topic: reference keywords: - video diff --git a/.github/workflows/README.md b/.github/workflows/README.md index 253c4dce4..6f6d4cb96 100644 --- a/.github/workflows/README.md +++ b/.github/workflows/README.md @@ -2,7 +2,7 @@ title: GitHub Actions Workflows description: Modular CI/CD workflow architecture for validation, security scanning, and automated maintenance author: HVE Core Team -ms.date: 2025-11-12 +ms.date: 2026-05-01 ms.topic: reference keywords: - github actions From b79e02ab4cf6e5cac94e95c2d4f436bb25cf3afb Mon Sep 17 00:00:00 2001 From: Bill Berry Date: Sat, 16 May 2026 13:27:17 -0700 Subject: [PATCH 12/21] fix(security): align sssc planner validation guidance MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 🔒 - Generated by Copilot --- .github/config/disclaimers.yml | 4 + .../security/sssc-backlog.instructions.md | 4 +- .../security/sssc-identity.instructions.md | 58 ++++- .../prompts/security/sssc-capture.prompt.md | 23 +- .../prompts/security/sssc-from-brd.prompt.md | 21 +- .../prompts/security/sssc-from-prd.prompt.md | 21 +- .../sssc-from-security-plan.prompt.md | 21 +- docs/agents/sssc-planning/agent-overview.md | 67 ++--- scripts/linting/Format-MarkdownTables.ps1 | 102 +++++--- .../schemas/ai-artifact-config.schema.json | 6 + scripts/linting/schemas/rai-state.schema.json | 2 + .../linting/schemas/sssc-state.schema.json | 4 +- .../Test-Format-MarkdownTables.Tests.ps1 | 243 +++++++++++------- .../security/Sign-PlannerArtifacts.Tests.ps1 | 70 +++++ 14 files changed, 389 insertions(+), 257 deletions(-) diff --git a/.github/config/disclaimers.yml b/.github/config/disclaimers.yml index aa451fc0d..5d0b117b5 100644 --- a/.github/config/disclaimers.yml +++ b/.github/config/disclaimers.yml @@ -11,6 +11,8 @@ disclaimers: rai-planner: id: rai-full-disclaimer label: "RAI Planner Full Disclaimer" + scope: + - .github/instructions/rai-planning/** applies-to: - handoff-summary - compact-handoff-summary @@ -30,6 +32,8 @@ disclaimers: sssc-planner: id: sssc-full-disclaimer label: "SSSC Planner Full Disclaimer" + scope: + - .github/instructions/security/sssc-*.instructions.md applies-to: - handoff-summary - compact-handoff-summary diff --git a/.github/instructions/security/sssc-backlog.instructions.md b/.github/instructions/security/sssc-backlog.instructions.md index 5d9d893a5..a495b85b0 100644 --- a/.github/instructions/security/sssc-backlog.instructions.md +++ b/.github/instructions/security/sssc-backlog.instructions.md @@ -150,9 +150,9 @@ Three tiers control how work items reach the target backlog system: * **Full autonomy**: Create work items directly via backlog manager. User pre-approves batch creation. * **Partial autonomy** (default): Present each batch of 5-10 items for user review before creation. User can modify, skip, or approve individual items. -* **Manual**: Produce output file without invoking backlog tools. User imports items independently. +* **Guided autonomy**: Produce output file without invoking backlog tools. User imports items independently. -Ask the user which tier they prefer. Default to partial autonomy on first use. +Ask the user which tier they prefer: guided, partial, or full. Default to partial autonomy on first use. ## Output diff --git a/.github/instructions/security/sssc-identity.instructions.md b/.github/instructions/security/sssc-identity.instructions.md index bd70fc459..cbbc612fd 100644 --- a/.github/instructions/security/sssc-identity.instructions.md +++ b/.github/instructions/security/sssc-identity.instructions.md @@ -19,6 +19,22 @@ Core responsibilities: Voice: clear, methodical, and supply-chain-security-focused. Communicate with professional authority while keeping guidance accessible and actionable. +## Disclaimer and Attribution Protocol + +### Session Start Display + +At the start of every SSSC Planning session, display the SSSC Planning disclaimer from `.github/instructions/shared/disclaimer-language.instructions.md` verbatim before collecting project details, asking scoping questions, or generating artifacts. + +If `disclaimerShownAt` is `null`, display the disclaimer and set `disclaimerShownAt` to the current ISO 8601 timestamp before writing `state.json`. If `disclaimerShownAt` already contains a timestamp, do not repeat the full disclaimer during normal continuation unless the user asks to see it again. + +### Standards Attribution + +When introducing standards mappings, assessments, gap analyses, or handoff materials, attribute the underlying supply chain security references clearly. SSSC Planning guidance may reference OpenSSF Scorecard, SLSA Build Levels, OpenSSF Best Practices Badge, Sigstore, CycloneDX, and SPDX. Treat generated mappings and recommendations as planning support that requires independent review by qualified security and compliance reviewers. + +### Exit Point Reminder + +Before final handoff or backlog export, remind the user that SSSC outputs are assistive planning artifacts. They do not constitute security approval, compliance certification, regulatory sign-off, or professional legal advice. + ## Six-Phase Definitions Each phase has entry criteria, activities, exit criteria, artifacts produced, and a defined transition. @@ -74,6 +90,22 @@ Each phase has entry criteria, activities, exit criteria, artifacts produced, an Four entry modes determine Phase 1 initialization. All modes converge at Phase 2 once supply chain scoping completes. +### Shared entry prompt requirements + +All entry prompts scan these supporting context sources alongside their mode-specific primary artifacts: + +* `package.json`, `pyproject.toml`, `*.csproj`, `Cargo.toml`, and `go.mod` for language and package manager inventory +* `.github/workflows/`, `.azure-pipelines/`, `azure-pipelines*.yml`, `Jenkinsfile`, and `.gitlab-ci.yml` for CI/CD platform details +* `release-please-config.json`, `.releaserc*`, and `CHANGELOG.md` for release strategy +* `Dockerfile`, `compose.yaml`, `helm/`, `k8s/`, `terraform/`, and `bicep/` for deployment surfaces +* `SECURITY.md`, `.github/dependabot.yml`, CodeQL configuration, and secret-scanning configuration for existing security tooling +* `.copilot-tracking/security-plans/`, `.copilot-tracking/rai-plans/`, `.copilot-tracking/prd-sessions/`, and `.copilot-tracking/brd-sessions/` for sibling planner artifacts to cross-link +* `.copilot-tracking/sssc-plans/references/` for user-supplied evaluation standards, workflow inventories, and output format requirements + +During Phase 1, ask whether the user has backlog output preferences: dual-format ADO and GitHub work items (`both`), ADO-only (`ado`), or GitHub-only (`github`). Capture the answer in `state.json` under `userPreferences.targetSystem` using the allowed values `ado`, `github`, or `both`. When the user supplies a custom backlog template, store it under `.copilot-tracking/sssc-plans/references/` and still record the closest matching `targetSystem` value. + +Before Phase 1 scoping is complete, ask whether the user has evaluation standards, workflow inventories, or output format requirements to store in `.copilot-tracking/sssc-plans/references/`. + ### `capture` Fresh assessment. Initialize blank `state.json` with `entryMode: "capture"`. Conduct a scoping interview to discover project scope, technology stack, package managers, CI/CD platform, release strategy, deployment targets, and compliance targets. @@ -175,24 +207,26 @@ Phase advancement updates `currentPhase` and sets phase-specific completion flag ## Resume Protocol -### Four-Step Resume Sequence +### Session Resume When returning to an existing session: -1. Read `state.json` to determine the current phase and progress -2. Identify which phase activities remain incomplete (unanswered questions, unassessed capabilities, missing mappings) -3. Check for incomplete artifacts: partially written assessments, incomplete standards mappings, or draft gap tables -4. Present a status summary to the user with an emoji checklist showing completed (✅) and remaining (❓) items +1. Read `state.json` from the project slug directory. +2. If `disclaimerShownAt` is `null`, display the SSSC Planning disclaimer verbatim and set `disclaimerShownAt` to the current ISO 8601 timestamp. +3. Display current phase progress and checklist status. +4. Summarize what was completed and what remains. +5. Continue from the last incomplete action. -### Five-Step Post-Summarization Recovery +### Post-Summarization Recovery -When context has been lost (new conversation or context window exceeded): +When context has been lost through a new conversation or context compaction: -1. Read `state.json` for project slug and current phase -2. Read existing artifacts (`supply-chain-assessment.md`, `standards-mapping.md`, `gap-analysis.md`, `sssc-backlog.md`) for accumulated findings -3. Reconstruct context from existing artifacts: capability assessments, standards mappings, gap tables -4. Identify the next incomplete task within the current phase -5. Resume with a brief summary of recovered state and the next action to take +1. Read `state.json` to restore phase context. +2. If `disclaimerShownAt` is `null`, display the SSSC Planning disclaimer verbatim and set `disclaimerShownAt` to the current ISO 8601 timestamp. +3. Read existing artifacts: `supply-chain-assessment.md`, `standards-mapping.md`, `gap-analysis.md`, and `sssc-backlog.md`. +4. Re-derive the current question set from the active phase. +5. Present a brief `Welcome back` summary with phase status. +6. Continue with the next question set. ## Question Cadence diff --git a/.github/prompts/security/sssc-capture.prompt.md b/.github/prompts/security/sssc-capture.prompt.md index d170e4730..febc1d7f1 100644 --- a/.github/prompts/security/sssc-capture.prompt.md +++ b/.github/prompts/security/sssc-capture.prompt.md @@ -2,19 +2,13 @@ description: >- Initiate supply chain security planning from existing knowledge using the SSSC Planner agent in capture mode -agent: sssc-planner +agent: SSSC Planner --- # SSSC Capture Activate the SSSC Planner in **capture mode** for project slug `${input:project-slug}`. -## Startup - -Before any phase work, check `state.json` for `disclaimerShownAt`. If `disclaimerShownAt` is `null` or `state.json` does not yet exist, display the SSSC Planning CAUTION block from #file:../../instructions/shared/disclaimer-language.instructions.md verbatim and set `disclaimerShownAt` to the current ISO 8601 timestamp in `state.json`. - -After the disclaimer, announce the SSSC Planner standards baseline following the Disclaimer and Attribution Protocol in #file:../../instructions/security/sssc-identity.instructions.md: OpenSSF Scorecard, SLSA Build Levels, OpenSSF Best Practices Badge, Sigstore, and SBOM standards (CycloneDX, SPDX). - ## Inputs * `${input:project-slug}`: (Optional) Kebab-case project identifier for the artifact directory. When omitted, ask for a suitable project name and derive the slug. @@ -23,25 +17,13 @@ After the disclaimer, announce the SSSC Planner standards baseline following the ### Pre-Scan -Before initialization, scan the workspace for context that can pre-populate Phase 1: - -* `package.json`, `pyproject.toml`, `*.csproj`, `Cargo.toml`, `go.mod` — language and package manager inventory. -* `.github/workflows/`, `.azure-pipelines/`, `azure-pipelines*.yml`, `Jenkinsfile`, `.gitlab-ci.yml` — CI/CD platform. -* `release-please-config.json`, `.releaserc*`, `CHANGELOG.md` — release strategy. -* `Dockerfile`, `compose.yaml`, `helm/`, `k8s/`, `terraform/`, `bicep/` — deployment surfaces. -* `SECURITY.md`, `.github/dependabot.yml`, CodeQL or secret-scanning configuration — existing security tooling. -* `.copilot-tracking/security-plans/`, `.copilot-tracking/rai-plans/`, `.copilot-tracking/prd-sessions/`, `.copilot-tracking/brd-sessions/` — sibling planner artifacts to cross-link. -* `.copilot-tracking/sssc-plans/references/` — user-supplied evaluation standards, workflow inventories, or output format requirements. +Before initialization, scan the shared supporting context sources defined in `sssc-identity.instructions.md` to pre-populate Phase 1. Present pre-scan results as a checklist: * ✅ Discovered context with file paths and brief descriptions * ❌ Expected sources that were not found -### Output Preferences - -Ask the user up front whether they have output preferences for backlog generation in Phase 5: dual-format ADO and GitHub work items (`both`), ADO-only (`ado`), or GitHub-only (`github`). Capture the answer in `state.json` under `userPreferences.targetSystem` (allowed values: `ado`, `github`, `both`) so later phases honor the choice without re-asking. When the user supplies a custom backlog template, store it under `.copilot-tracking/sssc-plans/references/` and still record the closest matching `targetSystem` value. - ### Initialization Create the project directory at `.copilot-tracking/sssc-plans/${input:project-slug}/`. @@ -61,6 +43,5 @@ Present a short summary sentence describing the assessment scope, then invite th * Deployment targets and registry destinations * Existing security tooling (Dependabot, CodeQL, secret scanning, signing) * Compliance targets (Scorecard threshold, SLSA Build level, Best Practices Badge tier) -* User-supplied evaluation standards, workflow inventories, or output format requirements to store in `.copilot-tracking/sssc-plans/references/` Use facilitative phrasing — invite confirmation and refinement rather than dictating answers — and mark each question with ❓ pending, ✅ complete, or ❌ blocked or skipped as the conversation progresses. diff --git a/.github/prompts/security/sssc-from-brd.prompt.md b/.github/prompts/security/sssc-from-brd.prompt.md index ed919505c..f2119d531 100644 --- a/.github/prompts/security/sssc-from-brd.prompt.md +++ b/.github/prompts/security/sssc-from-brd.prompt.md @@ -2,19 +2,13 @@ description: >- Initiate supply chain security planning from existing BRD artifacts using the SSSC Planner agent in from-brd mode -agent: sssc-planner +agent: SSSC Planner --- # SSSC from BRD Activate the SSSC Planner in **from-brd mode** for project slug `${input:project-slug}`. -## Startup - -Before any phase work, check `state.json` for `disclaimerShownAt`. If `disclaimerShownAt` is `null` or `state.json` does not yet exist, display the SSSC Planning CAUTION block from #file:../../instructions/shared/disclaimer-language.instructions.md verbatim and set `disclaimerShownAt` to the current ISO 8601 timestamp in `state.json`. - -After the disclaimer, announce the SSSC Planner standards baseline following the Disclaimer and Attribution Protocol in #file:../../instructions/security/sssc-identity.instructions.md: OpenSSF Scorecard, SLSA Build Levels, OpenSSF Best Practices Badge, Sigstore, and SBOM standards (CycloneDX, SPDX). - ## Inputs * `${input:project-slug}`: (Optional) Project slug for the SSSC plan directory. When omitted, derive from the discovered BRD project name. @@ -33,12 +27,7 @@ Scan the workspace for BRD artifacts and supporting context: * `.copilot-tracking/` for files matching `brd-*.md`, `*-brd.md`, or `business-requirements*.md`. Exclude generic matches like `requirements.txt` or files outside business-scoping contexts. -**Supporting context:** - -* `package.json`, `pyproject.toml`, `*.csproj`, `Cargo.toml`, `go.mod` — language and package manager inventory. -* `.github/workflows/`, `.azure-pipelines/`, `Jenkinsfile`, `.gitlab-ci.yml` — CI/CD platform. -* `.copilot-tracking/security-plans/`, `.copilot-tracking/rai-plans/`, `.copilot-tracking/prd-sessions/` — sibling planner artifacts to cross-link. -* `.copilot-tracking/sssc-plans/references/` — user-supplied evaluation standards or output format requirements. +Also scan the shared supporting context sources defined in `sssc-identity.instructions.md`. Present pre-scan results as a checklist: @@ -47,10 +36,6 @@ Present pre-scan results as a checklist: If zero BRD artifacts are found, fall back to capture mode and explain the switch. -### Output Preferences - -Ask the user up front whether they have output preferences for backlog generation in Phase 5: dual-format ADO and GitHub work items (`both`), ADO-only (`ado`), or GitHub-only (`github`). Capture the answer in `state.json` under `userPreferences.targetSystem` (allowed values: `ado`, `github`, `both`) so later phases honor the choice without re-asking. When the user supplies a custom backlog template, store it under `.copilot-tracking/sssc-plans/references/` and still record the closest matching `targetSystem` value. - ### Scope Extraction Extract from the discovered BRD artifacts: @@ -75,5 +60,3 @@ Present the extracted scope as a checklist with markers: * ❓ Items that need clarification or are missing Then invite the user into a Phase 1 conversation with 3 to 5 facilitative clarifying questions targeting supply chain gaps not covered by the BRD, such as package manager inventory, CI/CD topology, signing strategy, SBOM tooling, and Best Practices Badge readiness. Use confirmation-and-refinement phrasing rather than directives. - -Also ask whether the user has evaluation standards, workflow inventories, or output format requirements to supply for storage in `.copilot-tracking/sssc-plans/references/`. diff --git a/.github/prompts/security/sssc-from-prd.prompt.md b/.github/prompts/security/sssc-from-prd.prompt.md index 977ed0306..46d54c553 100644 --- a/.github/prompts/security/sssc-from-prd.prompt.md +++ b/.github/prompts/security/sssc-from-prd.prompt.md @@ -2,19 +2,13 @@ description: >- Initiate supply chain security planning from existing PRD artifacts using the SSSC Planner agent in from-prd mode -agent: sssc-planner +agent: SSSC Planner --- # SSSC from PRD Activate the SSSC Planner in **from-prd mode** for project slug `${input:project-slug}`. -## Startup - -Before any phase work, check `state.json` for `disclaimerShownAt`. If `disclaimerShownAt` is `null` or `state.json` does not yet exist, display the SSSC Planning CAUTION block from #file:../../instructions/shared/disclaimer-language.instructions.md verbatim and set `disclaimerShownAt` to the current ISO 8601 timestamp in `state.json`. - -After the disclaimer, announce the SSSC Planner standards baseline following the Disclaimer and Attribution Protocol in #file:../../instructions/security/sssc-identity.instructions.md: OpenSSF Scorecard, SLSA Build Levels, OpenSSF Best Practices Badge, Sigstore, and SBOM standards (CycloneDX, SPDX). - ## Inputs * `${input:project-slug}`: (Optional) Project slug for the SSSC plan directory. When omitted, derive from the discovered PRD project name. @@ -33,12 +27,7 @@ Scan the workspace for PRD artifacts and supporting context: * `.copilot-tracking/` for files matching `prd-*.md`, `*-prd.md`, or `product-definition*.md`. Exclude generic matches like `requirements.txt` or files outside product-scoping contexts. -**Supporting context:** - -* `package.json`, `pyproject.toml`, `*.csproj`, `Cargo.toml`, `go.mod` — language and package manager inventory. -* `.github/workflows/`, `.azure-pipelines/`, `Jenkinsfile`, `.gitlab-ci.yml` — CI/CD platform. -* `.copilot-tracking/security-plans/`, `.copilot-tracking/rai-plans/` — sibling planner artifacts to cross-link. -* `.copilot-tracking/sssc-plans/references/` — user-supplied evaluation standards or output format requirements. +Also scan the shared supporting context sources defined in `sssc-identity.instructions.md`. Present pre-scan results as a checklist: @@ -47,10 +36,6 @@ Present pre-scan results as a checklist: If zero PRD artifacts are found, fall back to capture mode and explain the switch. -### Output Preferences - -Ask the user up front whether they have output preferences for backlog generation in Phase 5: dual-format ADO and GitHub work items (`both`), ADO-only (`ado`), or GitHub-only (`github`). Capture the answer in `state.json` under `userPreferences.targetSystem` (allowed values: `ado`, `github`, `both`) so later phases honor the choice without re-asking. When the user supplies a custom backlog template, store it under `.copilot-tracking/sssc-plans/references/` and still record the closest matching `targetSystem` value. - ### Scope Extraction Extract from the discovered PRD artifacts: @@ -75,5 +60,3 @@ Present the extracted scope as a checklist with markers: * ❓ Items that need clarification or are missing Then invite the user into a Phase 1 conversation with 3 to 5 facilitative clarifying questions targeting supply chain gaps not covered by the PRD, such as runner topology, signing strategy, SBOM tooling, and Best Practices Badge readiness. Use confirmation-and-refinement phrasing rather than directives. - -Also ask whether the user has evaluation standards, workflow inventories, or output format requirements to supply for storage in `.copilot-tracking/sssc-plans/references/`. diff --git a/.github/prompts/security/sssc-from-security-plan.prompt.md b/.github/prompts/security/sssc-from-security-plan.prompt.md index 383899bd2..a5af36377 100644 --- a/.github/prompts/security/sssc-from-security-plan.prompt.md +++ b/.github/prompts/security/sssc-from-security-plan.prompt.md @@ -2,19 +2,13 @@ description: >- Extend a Security Planner assessment with supply chain coverage using the SSSC Planner agent in from-security-plan mode -agent: sssc-planner +agent: SSSC Planner --- # SSSC from Security Plan Activate the SSSC Planner in **from-security-plan mode** for project slug `${input:project-slug}`. -## Startup - -Before any phase work, check `state.json` for `disclaimerShownAt`. If `disclaimerShownAt` is `null` or `state.json` does not yet exist, display the SSSC Planning CAUTION block from #file:../../instructions/shared/disclaimer-language.instructions.md verbatim and set `disclaimerShownAt` to the current ISO 8601 timestamp in `state.json`. - -After the disclaimer, announce the SSSC Planner standards baseline following the Disclaimer and Attribution Protocol in #file:../../instructions/security/sssc-identity.instructions.md: OpenSSF Scorecard, SLSA Build Levels, OpenSSF Best Practices Badge, Sigstore, and SBOM standards (CycloneDX, SPDX). - ## Inputs * `${input:project-slug}`: (Optional) Project slug for the SSSC plan directory. When omitted, derive from the discovered security plan project name. @@ -29,12 +23,7 @@ Scan the workspace for Security Planner artifacts and supporting context: * `.copilot-tracking/security-plans/` for Security Planner project subdirectories. Look for `state.json` within each subdirectory. If multiple plans exist, present all candidates to the user for selection. -**Supporting context:** - -* `package.json`, `pyproject.toml`, `*.csproj`, `Cargo.toml`, `go.mod` — language and package manager inventory. -* `.github/workflows/`, `.azure-pipelines/`, `Jenkinsfile`, `.gitlab-ci.yml` — CI/CD platform. -* `.copilot-tracking/rai-plans/`, `.copilot-tracking/prd-sessions/`, `.copilot-tracking/brd-sessions/` — sibling planner artifacts to cross-link. -* `.copilot-tracking/sssc-plans/references/` — user-supplied evaluation standards or output format requirements. +Also scan the shared supporting context sources defined in `sssc-identity.instructions.md`. Present pre-scan results as a checklist: @@ -43,10 +32,6 @@ Present pre-scan results as a checklist: If zero Security Planner artifacts are found, fall back to capture mode and explain the switch. -### Output Preferences - -Ask the user up front whether they have output preferences for backlog generation in Phase 5: dual-format ADO and GitHub work items (`both`), ADO-only (`ado`), or GitHub-only (`github`). Capture the answer in `state.json` under `userPreferences.targetSystem` (allowed values: `ado`, `github`, `both`) so later phases honor the choice without re-asking. When the user supplies a custom backlog template, store it under `.copilot-tracking/sssc-plans/references/` and still record the closest matching `targetSystem` value. - ### Scope Extraction Read the selected Security Planner `state.json` and completed artifacts. Extract: @@ -71,5 +56,3 @@ Present the extracted scope as a checklist with markers: * ❓ Items that need clarification or are missing Then invite the user into a Phase 1 conversation with 3 to 5 facilitative clarifying questions targeting supply chain gaps not covered by the security plan, such as package manager inventory, CI/CD pipeline topology, release strategy, signing posture, SBOM tooling, and Best Practices Badge readiness. Use confirmation-and-refinement phrasing rather than directives. - -Also ask whether the user has evaluation standards, workflow inventories, or output format requirements to supply for storage in `.copilot-tracking/sssc-plans/references/`. diff --git a/docs/agents/sssc-planning/agent-overview.md b/docs/agents/sssc-planning/agent-overview.md index bed93a0d9..89ff9814a 100644 --- a/docs/agents/sssc-planning/agent-overview.md +++ b/docs/agents/sssc-planning/agent-overview.md @@ -64,34 +64,34 @@ All state lives in `.copilot-tracking/sssc-plans/{project-slug}/state.json`. The ### State Fields -The state file tracks 20 fields across scoping, analysis, handoff, and trust concerns. - -| Field | Type | Description | -|-----------------------------|----------|------------------------------------------------------------| -| `projectSlug` | string | Kebab-case project identifier | -| `ssscPlanFile` | string | Path to the main SSSC plan markdown file | -| `currentPhase` | number | Current phase (1-6) | -| `entryMode` | string | `capture`, `from-prd`, `from-brd`, or `from-security-plan` | -| `scopingComplete` | boolean | Whether Phase 1 scoping has been completed | -| `assessmentComplete` | boolean | Whether Phase 2 capability inventory is complete | -| `standardsMapped` | boolean | Whether Phase 3 standards mapping is complete | -| `gapAnalysisComplete` | boolean | Whether Phase 4 gap analysis is complete | -| `backlogGenerated` | boolean | Whether Phase 5 backlog generation is complete | -| `handoffGenerated` | object | `{ado: boolean, github: boolean}` | -| `context.techStack` | string[] | Target repository technology stack | -| `context.packageManagers` | string[] | Package managers in use | -| `context.ciPlatform` | string | CI/CD platform (GitHub Actions, Azure Pipelines, etc.) | -| `context.releaseStrategy` | string | Release strategy (tags, branches, etc.) | -| `context.complianceTargets` | string[] | Compliance frameworks being targeted | -| `referencesProcessed` | string[] | Paths to PRD/BRD/security-plan artifacts consumed | -| `nextActions` | string[] | Pending actions for the current or next phase | -| `userPreferences` | object | Autonomy preference: `full`, `partial`, or `manual` | -| `ssscEnabled` | boolean | Whether SSSC planning is active | -| `signingRequested` | boolean | Whether the user opted into Sigstore signing of artifacts | -| `signingManifestPath` | string | Path to the signing manifest produced after Phase 6 | -| `disclaimerShownAt` | string | ISO 8601 timestamp when the full disclaimer was shown | -| `securityPlannerLink` | string | Path to the upstream Security Planner state file | -| `raiPlannerLink` | string | Path to an associated RAI Planner state file | +The state file tracks fields across scoping, analysis, handoff, and trust concerns. + +| Field | Type | Description | +|-----------------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------| +| `projectSlug` | string | Kebab-case project identifier | +| `ssscPlanFile` | string | Path to the main SSSC plan markdown file | +| `currentPhase` | number | Current phase (1-6) | +| `entryMode` | string | `capture`, `from-prd`, `from-brd`, or `from-security-plan` | +| `scopingComplete` | boolean | Whether Phase 1 scoping has been completed | +| `assessmentComplete` | boolean | Whether Phase 2 capability inventory is complete | +| `standardsMapped` | boolean | Whether Phase 3 standards mapping is complete | +| `gapAnalysisComplete` | boolean | Whether Phase 4 gap analysis is complete | +| `backlogGenerated` | boolean | Whether Phase 5 backlog generation is complete | +| `handoffGenerated` | object | `{ado: boolean, github: boolean}` | +| `context.techStack` | string[] | Target repository technology stack | +| `context.packageManagers` | string[] | Package managers in use | +| `context.ciPlatform` | string | CI/CD platform (GitHub Actions, Azure Pipelines, etc.) | +| `context.releaseStrategy` | string | Release strategy (tags, branches, etc.) | +| `context.complianceTargets` | string[] | Compliance frameworks being targeted | +| `referencesProcessed` | string[] | Paths to PRD/BRD/security-plan artifacts consumed | +| `nextActions` | string[] | Pending actions for the current or next phase | +| `userPreferences` | object | Autonomy tier (`guided`, `partial`, or `full`), output detail level, target system, audience profile, and optional artifact toggles | +| `ssscEnabled` | boolean | Whether SSSC planning is active | +| `signingRequested` | boolean | Whether the user opted into Sigstore signing of artifacts | +| `signingManifestPath` | string | Path to the signing manifest produced after Phase 6 | +| `disclaimerShownAt` | string | ISO 8601 timestamp when the full disclaimer was shown | +| `securityPlannerLink` | string | Path to the upstream Security Planner state file | +| `raiPlannerLink` | string | Path to an associated RAI Planner state file | ## Interaction Model @@ -105,14 +105,15 @@ The agent follows strict question rules during each phase: ## Session Resume -When a conversation resumes from a prior session, the agent follows a four-step recovery protocol: +When a conversation resumes from a prior session, the agent follows a five-step recovery protocol: 1. Read the state file from `.copilot-tracking/sssc-plans/{project-slug}/`. -2. Validate that the state schema matches the expected version. -3. Present a summary of completed phases and pending work. -4. Continue from the current phase without re-asking answered questions. +2. Display the SSSC Planning disclaimer when `disclaimerShownAt` is missing, then record the timestamp in state. +3. Present current phase progress and checklist status. +4. Summarize completed work and remaining actions. +5. Continue from the last incomplete action. -A five-step post-summarization recovery handles cases where conversation context was compacted by the chat system. +When conversation context was compacted by the chat system, the agent also reads existing assessment, standards mapping, gap analysis, and backlog artifacts before rebuilding the active question set. ## Operational Constraints diff --git a/scripts/linting/Format-MarkdownTables.ps1 b/scripts/linting/Format-MarkdownTables.ps1 index e677dd69f..074f576ec 100644 --- a/scripts/linting/Format-MarkdownTables.ps1 +++ b/scripts/linting/Format-MarkdownTables.ps1 @@ -16,6 +16,8 @@ silently skips .github/** and other dot-prefixed paths on Windows. This wrapper bypasses that bug by passing an explicit file list to the library. + File discovery includes tracked Markdown files only. + .PARAMETER Check Check only; exit with non-zero status if any tables would be reformatted. @@ -35,33 +37,45 @@ param( ) $ErrorActionPreference = 'Stop' +$script:MarkdownTableFormatterExitCode = 0 -$repoRoot = (Resolve-Path (Join-Path $PSScriptRoot '..' '..')).Path -$emitVerbose = $VerbosePreference -ne 'SilentlyContinue' - -Push-Location $repoRoot -try { - $gitOutput = & git ls-files -z --cached --others --exclude-standard -- '*.md' - if ($LASTEXITCODE -ne 0) { - Write-Error 'git ls-files failed; not running inside a git checkout?' - exit 2 - } +#region Functions +function Invoke-MarkdownTableFormatter { + [CmdletBinding()] + param( + [Parameter(Mandatory = $false)] + [switch]$Check + ) - $files = if ($gitOutput) { $gitOutput -split "`0" | Where-Object { $_ } } else { @() } - if ($files.Count -eq 0) { - Write-Output 'No markdown files found.' - exit 0 - } + $repoRoot = (Resolve-Path (Join-Path $PSScriptRoot '..' '..')).Path + $emitVerbose = $VerbosePreference -ne 'SilentlyContinue' + $script:MarkdownTableFormatterExitCode = 0 - if ($emitVerbose) { - [System.Console]::Error.WriteLine("Formatting $($files.Count) markdown file(s).") - } - - $tempList = New-TemporaryFile + Push-Location $repoRoot try { - Set-Content -Path $tempList.FullName -Value $files -Encoding utf8 - - $nodeScript = @' + $gitOutput = & git ls-files -z --cached -- '*.md' + if ($LASTEXITCODE -ne 0) { + [System.Console]::Error.WriteLine('git ls-files failed; not running inside a git checkout?') + $script:MarkdownTableFormatterExitCode = 2 + return + } + + $files = if ($gitOutput) { $gitOutput -split "`0" | Where-Object { $_ } } else { @() } + if ($files.Count -eq 0) { + Write-Output 'No markdown files found.' + $script:MarkdownTableFormatterExitCode = 0 + return + } + + if ($emitVerbose) { + [System.Console]::Error.WriteLine("Formatting $($files.Count) markdown file(s).") + } + + $tempList = New-TemporaryFile + try { + Set-Content -Path $tempList.FullName -Value $files -Encoding utf8 + + $nodeScript = @' import { readFileSync } from 'node:fs'; import pkg from 'markdown-table-formatter/lib/markdown-table-formatter.js'; const { MarkdownTableFormatter } = pkg; @@ -80,20 +94,38 @@ for (const updated of result.updates) { process.exit(result.status); '@ - $env:MTF_FILE_LIST = $tempList.FullName - $env:MTF_CHECK = $(if ($Check) { '1' } else { '0' }) - $env:MTF_VERBOSE = $(if ($emitVerbose) { '1' } else { '0' }) - - & node --input-type=module -e $nodeScript - $exitCode = $LASTEXITCODE + $env:MTF_FILE_LIST = $tempList.FullName + $env:MTF_CHECK = $(if ($Check) { '1' } else { '0' }) + $env:MTF_VERBOSE = $(if ($emitVerbose) { '1' } else { '0' }) + + & node --input-type=module -e $nodeScript + $script:MarkdownTableFormatterExitCode = $LASTEXITCODE + return + } + finally { + Remove-Item -Path $tempList.FullName -ErrorAction SilentlyContinue + Remove-Item Env:MTF_FILE_LIST, Env:MTF_CHECK, Env:MTF_VERBOSE -ErrorAction SilentlyContinue + } } finally { - Remove-Item -Path $tempList.FullName -ErrorAction SilentlyContinue - Remove-Item Env:MTF_FILE_LIST, Env:MTF_CHECK, Env:MTF_VERBOSE -ErrorAction SilentlyContinue + Pop-Location } - - exit $exitCode } -finally { - Pop-Location +#endregion + +#region Main +if ($MyInvocation.InvocationName -ne '.') { + try { + Invoke-MarkdownTableFormatter -Check:$Check + $exitCode = $script:MarkdownTableFormatterExitCode + if ($null -eq $exitCode) { + $exitCode = 0 + } + exit $exitCode + } + catch { + Write-Error -ErrorAction Continue "Format-MarkdownTables failed: $($_.Exception.Message)" + exit 1 + } } +#endregion diff --git a/scripts/linting/schemas/ai-artifact-config.schema.json b/scripts/linting/schemas/ai-artifact-config.schema.json index 25ce1cece..65719527f 100644 --- a/scripts/linting/schemas/ai-artifact-config.schema.json +++ b/scripts/linting/schemas/ai-artifact-config.schema.json @@ -77,6 +77,12 @@ "properties": { "id": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, + "scope": { + "type": "array", + "items": { "type": "string", "minLength": 1 }, + "minItems": 1, + "description": "Glob patterns disambiguating where this disclaimer applies" + }, "applies-to": { "type": "array", "items": { "type": "string", "minLength": 1 }, diff --git a/scripts/linting/schemas/rai-state.schema.json b/scripts/linting/schemas/rai-state.schema.json index 08eefaa11..5212a66e2 100644 --- a/scripts/linting/schemas/rai-state.schema.json +++ b/scripts/linting/schemas/rai-state.schema.json @@ -23,6 +23,8 @@ "referencesProcessed", "nextActions", "signingRequested", + "signingManifestPath", + "disclaimerShownAt", "userPreferences" ], "properties": { diff --git a/scripts/linting/schemas/sssc-state.schema.json b/scripts/linting/schemas/sssc-state.schema.json index 805bf4fe0..768ea34d2 100644 --- a/scripts/linting/schemas/sssc-state.schema.json +++ b/scripts/linting/schemas/sssc-state.schema.json @@ -20,7 +20,9 @@ "nextActions", "userPreferences", "ssscEnabled", - "signingRequested" + "signingRequested", + "signingManifestPath", + "disclaimerShownAt" ], "properties": { "projectSlug": { diff --git a/scripts/tests/linting/Test-Format-MarkdownTables.Tests.ps1 b/scripts/tests/linting/Test-Format-MarkdownTables.Tests.ps1 index a015c850b..79cb0e64b 100644 --- a/scripts/tests/linting/Test-Format-MarkdownTables.Tests.ps1 +++ b/scripts/tests/linting/Test-Format-MarkdownTables.Tests.ps1 @@ -2,13 +2,30 @@ # Copyright (c) Microsoft Corporation. # SPDX-License-Identifier: MIT -BeforeAll { +function script:Initialize-FormatterTestPaths { + if ($script:RealScript -and $script:RepoRoot -and $script:RealNodeModules) { + $script:SkipFormatterTests = -not (Test-Path $script:RealNodeModules) + return + } + $script:RealScript = (Resolve-Path (Join-Path $PSScriptRoot '../../linting/Format-MarkdownTables.ps1')).Path $script:RepoRoot = (Resolve-Path (Join-Path $PSScriptRoot '../../..')).Path $script:RealNodeModules = Join-Path $script:RepoRoot 'node_modules' + $script:SkipFormatterTests = -not (Test-Path $script:RealNodeModules) +} + +Initialize-FormatterTestPaths - if (-not (Test-Path $script:RealNodeModules)) { - throw "Cannot run Format-MarkdownTables tests: node_modules missing at $script:RealNodeModules. Run 'npm install' first." +function script:Initialize-FormatterTestRoot { + Initialize-FormatterTestPaths + + if ($script:MainTestRoot) { + return + } + + if ($script:SkipFormatterTests) { + Write-Warning "Skipping Format-MarkdownTables tests: node_modules missing at $script:RealNodeModules. Run 'npm install' first." + return } $tempBase = [System.IO.Path]::GetTempPath() @@ -28,92 +45,125 @@ BeforeAll { New-Item -ItemType SymbolicLink -Path $script:MainNodeModulesLink -Target $script:RealNodeModules | Out-Null } } +} + +function script:New-FixtureRepo { + param( + [Parameter(Mandatory)] [string] $Name, + [switch] $InitGit + ) + + Initialize-FormatterTestRoot + if (-not $script:MainTestRoot) { + throw "Format-MarkdownTables fixture root was not initialized. node_modules path: $script:RealNodeModules" + } - function script:New-FixtureRepo { - param( - [Parameter(Mandatory)] [string] $Name, - [switch] $InitGit - ) - - $fixtureRoot = Join-Path $script:MainTestRoot $Name - $linting = Join-Path $fixtureRoot 'scripts/linting' - New-Item -ItemType Directory -Path $linting -Force | Out-Null - Copy-Item -Path $script:RealScript -Destination (Join-Path $linting 'Format-MarkdownTables.ps1') -Force - - if ($InitGit) { - Push-Location $fixtureRoot - try { - & git init --quiet 2>&1 | Out-Null - & git config user.email 'test@example.com' 2>&1 | Out-Null - & git config user.name 'Test' 2>&1 | Out-Null - & git config core.autocrlf false 2>&1 | Out-Null - & git config core.safecrlf false 2>&1 | Out-Null - } - finally { - Pop-Location - } + $fixtureRoot = Join-Path $script:MainTestRoot $Name + $linting = Join-Path $fixtureRoot 'scripts/linting' + New-Item -ItemType Directory -Path $linting -Force | Out-Null + Initialize-FormatterTestPaths + Copy-Item -Path $script:RealScript -Destination (Join-Path $linting 'Format-MarkdownTables.ps1') -Force + + if ($InitGit) { + Push-Location $fixtureRoot + try { + & git init --quiet 2>&1 | Out-Null + & git config user.email 'test@example.com' 2>&1 | Out-Null + & git config user.name 'Test' 2>&1 | Out-Null + & git config core.autocrlf false 2>&1 | Out-Null + & git config core.safecrlf false 2>&1 | Out-Null + } + finally { + Pop-Location } + } - # .gitignore (in addition to in-repo init) so git ls-files --others - # --exclude-standard skips the junctioned node_modules tree and the - # captured stdout/stderr files. - $gitignore = @' + # Keep generated process captures and the dependency junction out of + # fixture repositories. + $gitignore = @' node_modules/ _stdout.txt _stderr.txt '@ - Set-Content -Path (Join-Path $fixtureRoot '.gitignore') -Value $gitignore -Encoding utf8 + Set-Content -Path (Join-Path $fixtureRoot '.gitignore') -Value $gitignore -Encoding utf8 + + return $fixtureRoot +} - return $fixtureRoot +function script:Add-TrackedFixtureFile { + param( + [Parameter(Mandatory)] [string] $FixtureRoot, + [Parameter(Mandatory)] [string] $RelativePath, + [Parameter(Mandatory)] [string] $Content + ) + + $targetPath = Join-Path $FixtureRoot $RelativePath + $targetDirectory = Split-Path -Path $targetPath -Parent + if (-not (Test-Path $targetDirectory)) { + New-Item -ItemType Directory -Path $targetDirectory -Force | Out-Null } - function script:Invoke-SutInFixture { - param( - [Parameter(Mandatory)] [string] $FixtureRoot, - [switch] $Check, - [switch] $WithVerbose - ) - - $sutPath = Join-Path $FixtureRoot 'scripts/linting/Format-MarkdownTables.ps1' - $stdoutPath = Join-Path $FixtureRoot '_stdout.txt' - $stderrPath = Join-Path $FixtureRoot '_stderr.txt' - - $argList = @('-NoProfile', '-File', $sutPath) - if ($Check) { $argList += '-Check' } - if ($WithVerbose) { $argList += '-Verbose' } - - $proc = Start-Process -FilePath 'pwsh' ` - -ArgumentList $argList ` - -WorkingDirectory $FixtureRoot ` - -RedirectStandardOutput $stdoutPath ` - -RedirectStandardError $stderrPath ` - -Wait -PassThru -NoNewWindow - - # Belt-and-suspenders: ensure the process has fully exited and OS file - # buffers have flushed before we read. Tiny stdout payloads under the - # Pester runspace can race the file-handle close. - $proc.WaitForExit() - $stdoutBytes = if (Test-Path $stdoutPath) { (Get-Item $stdoutPath).Length } else { -1 } - $stderrBytes = if (Test-Path $stderrPath) { (Get-Item $stderrPath).Length } else { -1 } - if ($stdoutBytes -eq 0 -and $proc.ExitCode -eq 0) { - Start-Sleep -Milliseconds 100 - $stdoutBytes = (Get-Item $stdoutPath).Length - } + Set-Content -Path $targetPath -Value $Content -NoNewline - $stdout = if ($stdoutBytes -gt 0) { [System.IO.File]::ReadAllText($stdoutPath) } else { '' } - $stderr = if ($stderrBytes -gt 0) { [System.IO.File]::ReadAllText($stderrPath) } else { '' } - - return [pscustomobject]@{ - ExitCode = $proc.ExitCode - StdOut = $stdout - StdErr = $stderr - StdOutPath = $stdoutPath - StdErrPath = $stderrPath - StdOutBytes = $stdoutBytes - StdErrBytes = $stderrBytes - } + Push-Location $FixtureRoot + try { + & git add -- $RelativePath 2>&1 | Out-Null + } + finally { + Pop-Location + } + + return $targetPath +} + +function script:Invoke-SutInFixture { + param( + [Parameter(Mandatory)] [string] $FixtureRoot, + [switch] $Check, + [switch] $WithVerbose + ) + + $sutPath = Join-Path $FixtureRoot 'scripts/linting/Format-MarkdownTables.ps1' + $stdoutPath = Join-Path $FixtureRoot '_stdout.txt' + $stderrPath = Join-Path $FixtureRoot '_stderr.txt' + + $argList = @('-NoProfile', '-File', $sutPath) + if ($Check) { $argList += '-Check' } + if ($WithVerbose) { $argList += '-Verbose' } + + $proc = Start-Process -FilePath 'pwsh' ` + -ArgumentList $argList ` + -WorkingDirectory $FixtureRoot ` + -RedirectStandardOutput $stdoutPath ` + -RedirectStandardError $stderrPath ` + -Wait -PassThru -NoNewWindow + + # Belt-and-suspenders: ensure the process has fully exited and OS file + # buffers have flushed before we read. Tiny stdout payloads under the + # Pester runspace can race the file-handle close. + $proc.WaitForExit() + $stdoutBytes = if (Test-Path $stdoutPath) { (Get-Item $stdoutPath).Length } else { -1 } + $stderrBytes = if (Test-Path $stderrPath) { (Get-Item $stderrPath).Length } else { -1 } + if ($stdoutBytes -eq 0 -and $proc.ExitCode -eq 0) { + Start-Sleep -Milliseconds 100 + $stdoutBytes = (Get-Item $stdoutPath).Length } + $stdout = if ($stdoutBytes -gt 0) { [System.IO.File]::ReadAllText($stdoutPath) } else { '' } + $stderr = if ($stderrBytes -gt 0) { [System.IO.File]::ReadAllText($stderrPath) } else { '' } + + return [pscustomobject]@{ + ExitCode = $proc.ExitCode + StdOut = $stdout + StdErr = $stderr + StdOutPath = $stdoutPath + StdErrPath = $stderrPath + StdOutBytes = $stdoutBytes + StdErrBytes = $stderrBytes + } +} + +function script:Initialize-FormatterTestContent { # Well-formatted table (each cell padded to column width, single space between pipes). $script:GoodTable = @' # Good @@ -135,20 +185,25 @@ _stderr.txt '@ } -AfterAll { - if ($script:MainTestRoot -and (Test-Path $script:MainTestRoot)) { - # CRITICAL: the MainTestRoot/node_modules junction points at the real - # repo's node_modules. Remove it first via the directory-delete API - # (which deletes the link itself, not the target) so the subsequent - # recursive remove cannot follow it into real content. - if ($script:MainNodeModulesLink -and (Test-Path $script:MainNodeModulesLink)) { - try { [System.IO.Directory]::Delete($script:MainNodeModulesLink, $false) } catch { Write-Verbose "junction cleanup ignored: $_" } - } - Remove-Item -Path $script:MainTestRoot -Recurse -Force -ErrorAction SilentlyContinue +# This suite launches subprocesses and fixture git repositories, but keeps the +# Unit tag because the repository test runner excludes Integration by default. +Describe 'Format-MarkdownTables' -Tag 'Unit' -Skip:$script:SkipFormatterTests { + BeforeAll { + Initialize-FormatterTestRoot + Initialize-FormatterTestContent } -} -Describe 'Format-MarkdownTables' -Tag 'Unit' { + AfterAll { + if ($script:MainTestRoot -and (Test-Path $script:MainTestRoot)) { + # The MainTestRoot/node_modules junction points at the real repo's + # node_modules. Delete the link before recursive cleanup so removal + # cannot follow it into real content. + if ($script:MainNodeModulesLink -and (Test-Path $script:MainNodeModulesLink)) { + try { [System.IO.Directory]::Delete($script:MainNodeModulesLink, $false) } catch { Write-Verbose "junction cleanup ignored: $_" } + } + Remove-Item -Path $script:MainTestRoot -Recurse -Force -ErrorAction SilentlyContinue + } + } Context 'when no markdown files are tracked' { BeforeAll { @@ -186,7 +241,7 @@ Describe 'Format-MarkdownTables' -Tag 'Unit' { Context 'when all markdown tables are already formatted' { BeforeAll { $script:Fixture = New-FixtureRepo -Name "good-$(Get-Random)" -InitGit - Set-Content -Path (Join-Path $script:Fixture 'README.md') -Value $script:GoodTable -NoNewline + $null = Add-TrackedFixtureFile -FixtureRoot $script:Fixture -RelativePath 'README.md' -Content $script:GoodTable $script:Result = Invoke-SutInFixture -FixtureRoot $script:Fixture } @@ -203,8 +258,7 @@ Describe 'Format-MarkdownTables' -Tag 'Unit' { Context 'when markdown tables need reformatting' { BeforeEach { $script:Fixture = New-FixtureRepo -Name "bad-$(Get-Random)" -InitGit - $script:BadFile = Join-Path $script:Fixture 'README.md' - Set-Content -Path $script:BadFile -Value $script:BadTable -NoNewline + $script:BadFile = Add-TrackedFixtureFile -FixtureRoot $script:Fixture -RelativePath 'README.md' -Content $script:BadTable } It 'Exits non-zero in -Check mode' { @@ -232,10 +286,7 @@ Describe 'Format-MarkdownTables' -Tag 'Unit' { Context 'when markdown files live under dot-prefixed directories' { BeforeEach { $script:Fixture = New-FixtureRepo -Name "dotpath-$(Get-Random)" -InitGit - $dotDir = Join-Path $script:Fixture '.github' - New-Item -ItemType Directory -Path $dotDir -Force | Out-Null - $script:DotFile = Join-Path $dotDir 'NOTES.md' - Set-Content -Path $script:DotFile -Value $script:BadTable -NoNewline + $script:DotFile = Add-TrackedFixtureFile -FixtureRoot $script:Fixture -RelativePath '.github/NOTES.md' -Content $script:BadTable } It 'Detects misformatted tables under .github (regression: glob v13 dot:false)' { @@ -255,7 +306,7 @@ Describe 'Format-MarkdownTables' -Tag 'Unit' { Context 'when -Verbose is supplied' { BeforeAll { $script:Fixture = New-FixtureRepo -Name "verbose-$(Get-Random)" -InitGit - Set-Content -Path (Join-Path $script:Fixture 'README.md') -Value $script:GoodTable -NoNewline + $null = Add-TrackedFixtureFile -FixtureRoot $script:Fixture -RelativePath 'README.md' -Content $script:GoodTable $script:Result = Invoke-SutInFixture -FixtureRoot $script:Fixture -WithVerbose } diff --git a/scripts/tests/security/Sign-PlannerArtifacts.Tests.ps1 b/scripts/tests/security/Sign-PlannerArtifacts.Tests.ps1 index fa293cb20..18d6a72d2 100644 --- a/scripts/tests/security/Sign-PlannerArtifacts.Tests.ps1 +++ b/scripts/tests/security/Sign-PlannerArtifacts.Tests.ps1 @@ -217,6 +217,76 @@ Describe 'Manifest Generation' -Tag 'Unit' { } } + Context 'when SessionPath is specified' { + It 'Generates a manifest for a repo-relative session path' { + $relativeSessionPath = '.copilot-tracking/sssc-plans/test-sssc-session' + $sessionDir = Join-Path $TestDrive $relativeSessionPath + New-Item -ItemType Directory -Path $sessionDir -Force | Out-Null + Set-Content -Path (Join-Path $sessionDir 'state.json') -Value '{}' -Encoding utf8NoBOM + + $originalPWD = $PWD + try { + Set-Location $TestDrive + & $script:ScriptPath -SessionPath $relativeSessionPath + } + finally { + Set-Location $originalPWD + } + + $outputPath = Join-Path $sessionDir 'artifact-manifest.json' + Test-Path $outputPath | Should -BeTrue + $manifest = Get-Content $outputPath -Raw | ConvertFrom-Json + $manifest.projectSlug | Should -Be 'test-sssc-session' + $manifest.sessionPath | Should -Be '.copilot-tracking/sssc-plans/test-sssc-session' + $manifest.fileCount | Should -Be 1 + } + + It 'Generates a manifest for an absolute session path' { + $sessionDir = Join-Path $TestDrive '.copilot-tracking/sssc-plans/absolute-session' + New-Item -ItemType Directory -Path $sessionDir -Force | Out-Null + Set-Content -Path (Join-Path $sessionDir 'state.json') -Value '{}' -Encoding utf8NoBOM + + $originalPWD = $PWD + try { + Set-Location (Split-Path -Path $script:ScriptPath -Parent) + & $script:ScriptPath -SessionPath $sessionDir + } + finally { + Set-Location $originalPWD + } + + $outputPath = Join-Path $sessionDir 'artifact-manifest.json' + Test-Path $outputPath | Should -BeTrue + $manifest = Get-Content $outputPath -Raw | ConvertFrom-Json + $manifest.projectSlug | Should -Be 'absolute-session' + $manifest.sessionPath | Should -Be ($sessionDir -replace '\\','/') + $manifest.fileCount | Should -Be 1 + } + + It 'Uses a custom manifest name and excludes it from artifact inventory' { + $relativeSessionPath = '.copilot-tracking/sssc-plans/custom-manifest-session' + $sessionDir = Join-Path $TestDrive $relativeSessionPath + New-Item -ItemType Directory -Path $sessionDir -Force | Out-Null + Set-Content -Path (Join-Path $sessionDir 'state.json') -Value '{}' -Encoding utf8NoBOM + Set-Content -Path (Join-Path $sessionDir 'sssc-manifest.json') -Value '{}' -Encoding utf8NoBOM + + $originalPWD = $PWD + try { + Set-Location $TestDrive + & $script:ScriptPath -SessionPath $relativeSessionPath -ManifestName 'sssc-manifest.json' + } + finally { + Set-Location $originalPWD + } + + $outputPath = Join-Path $sessionDir 'sssc-manifest.json' + Test-Path $outputPath | Should -BeTrue + $manifest = Get-Content $outputPath -Raw | ConvertFrom-Json + $manifest.fileCount | Should -Be 1 + $manifest.artifacts[0].path | Should -Be 'state.json' + } + } + Context 'exclude patterns' { It 'Excludes artifact-manifest.json from the inventory' { Set-Content -Path (Join-Path $script:artifactDir 'state.json') -Value '{}' -Encoding utf8NoBOM From 9dca881e51bf90ee1de68913088c4831dfce2df1 Mon Sep 17 00:00:00 2001 From: Bill Berry Date: Thu, 21 May 2026 09:17:39 -0700 Subject: [PATCH 13/21] docs(skills): bump pr-reference REFERENCE ms.date to 2026-05-21 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 🔒 - Generated by Copilot --- .github/skills/shared/pr-reference/references/REFERENCE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/skills/shared/pr-reference/references/REFERENCE.md b/.github/skills/shared/pr-reference/references/REFERENCE.md index ccc8d0e3f..ecededbfd 100644 --- a/.github/skills/shared/pr-reference/references/REFERENCE.md +++ b/.github/skills/shared/pr-reference/references/REFERENCE.md @@ -2,7 +2,7 @@ title: PR Reference Skill Reference description: XML output format, usage scenarios, output path variations, and semantic invocation patterns author: Microsoft -ms.date: 2026-02-18 +ms.date: 2026-05-21 ms.topic: reference keywords: - pr-reference From 047c389fccac2215156ee103c0d67ffced0b6927 Mon Sep 17 00:00:00 2001 From: Bill Berry Date: Fri, 22 May 2026 23:04:33 -0700 Subject: [PATCH 14/21] feat(instructions): add shared coaching-patterns instruction for exploration-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. --- .../shared/coaching-patterns.instructions.md | 135 ++++++++++++++++++ collections/hve-core-all.collection.md | 1 + collections/hve-core-all.collection.yml | 2 + collections/project-planning.collection.md | 1 + collections/project-planning.collection.yml | 2 + collections/security.collection.md | 1 + collections/security.collection.yml | 2 + plugins/hve-core-all/README.md | 12 +- .../shared/coaching-patterns.instructions.md | 1 + plugins/project-planning/README.md | 12 +- .../shared/coaching-patterns.instructions.md | 1 + plugins/security/README.md | 12 +- .../shared/coaching-patterns.instructions.md | 1 + .../Test-SharedCoachingPatterns.Tests.ps1 | 54 +++++++ 14 files changed, 222 insertions(+), 15 deletions(-) create mode 100644 .github/instructions/shared/coaching-patterns.instructions.md create mode 120000 plugins/hve-core-all/instructions/shared/coaching-patterns.instructions.md create mode 120000 plugins/project-planning/instructions/shared/coaching-patterns.instructions.md create mode 120000 plugins/security/instructions/shared/coaching-patterns.instructions.md create mode 100644 scripts/tests/linting/Test-SharedCoachingPatterns.Tests.ps1 diff --git a/.github/instructions/shared/coaching-patterns.instructions.md b/.github/instructions/shared/coaching-patterns.instructions.md new file mode 100644 index 000000000..b300a5501 --- /dev/null +++ b/.github/instructions/shared/coaching-patterns.instructions.md @@ -0,0 +1,135 @@ +--- +description: "Shared exploration-first coaching patterns for planning agents (RAI, security, SSSC) adapted from Design Thinking research methods - Brought to you by microsoft/hve-core" +applyTo: '**/.copilot-tracking/rai-plans/**, **/.copilot-tracking/security-plans/**, **/.copilot-tracking/sssc-plans/**' +--- + +# Shared Coaching Patterns + +These patterns apply to any planner agent operating in `capture`, discovery, or Phase 1-style entry modes where the agent gathers context from the user before classification, analysis, or remediation. Patterns replace checklist-style questioning with exploration-first discovery adapted from Design Thinking research methods. Planner-specific instructions may extend or override these defaults. + +## Coaching Framework + +Apply the Think/Speak/Empower pattern on every turn during entry-mode conversations: + +* **Think**: Assess what the user has revealed so far. Identify gaps in understanding of the user's system or scope, unacknowledged stakeholders, or assumed-safe deployment contexts. This reasoning stays internal. +* **Speak**: Use natural observations rather than clinical prompts. Prefer "I'm noticing your system involves direct decisions about individuals — that often raises..." over "Does your system make decisions about individuals?" +* **Empower**: Offer the user agency over exploration direction. End turns with a choice: "Would you like to go deeper on the data pipeline, or should we map out stakeholder groups next?" + +## Context Pre-Scan + +When materials are attached (PRDs, security plans, design documents, source code, architecture diagrams), scan them before asking the first question: + +1. Identify the system name, purpose, and primary users. +2. Note any explicitly stated concerns or focus areas. +3. Detect potential classification indicators from the description. +4. Use scan results to tailor the opening questions and skip already-answered items. +5. Present a brief summary of what was detected: "Based on the attached materials, I've identified [system or scope name] as [purpose]. I noticed [observations]. Let me start with [first question based on context]." + +## Scope Assessment + +At the start of the entry-mode conversation, assess whether the user arrives with a fixed or open view of the system or scope under analysis: + +* **Fixed view**: The user has a specific, detailed picture of the system and its concerns. Validate their understanding while probing gently for blind spots. Use targeted questions to explore areas they haven't mentioned. +* **Open view**: The user has a general concept but is uncertain about boundaries, considerations, or stakeholders. Explore broadly with open-ended questions. Let the conversation reveal the system's shape. + +Adjust questioning depth and breadth based on this assessment. Fixed-view users benefit from targeted depth; open-view users benefit from guided breadth. + +## Exploration-First Questioning + +### Opening Questions + +Begin entry-mode conversations with curiosity-driven questions that let the user describe their system or scope naturally: + +* "Walk me through what your system does from a user's perspective." +* "Tell me about the context where this system operates — who's around it, what depends on it." +* "What problem were you trying to solve when this project started?" + +Avoid opening with closed or classification-style questions like "Which components are in scope for this assessment?" until the user has described the system in their own words. + +### Deepening with Laddering + +Use laddering to move from surface descriptions to core considerations: + +| Level | Focus | Example Prompt | +|---------------------|---------------------------------|----------------------------------------------------------------------------------------------------------| +| Surface | What the system does | "Walk me through how someone uses this day to day." | +| Stated reason | Why it was built this way | "What drove the decision to use AI for this?" | +| Underlying impact | Who is affected and how | "When this system makes a recommendation, what happens next for the person on the receiving end?" | +| Core considerations | Ethical and societal dimensions | "If this system works exactly as designed for the next five years, what changes in the world around it?" | + +Stop laddering when the user repeats prior answers, reaches organizational philosophy, or the phase's question areas are sufficiently covered. + +### Critical Incident Anchoring + +Anchor abstract discussions in specific real events: + +* "Can you walk me through a time when someone used the system in a way you didn't expect?" +* "Tell me about the last time a decision from this system was questioned." +* "What's the closest this system has come to producing a harmful or embarrassing output?" + +Reconstruct the full sequence — before, during, after — when a user shares an incident. Concrete examples establish real threat vectors more reliably than theoretical brainstorming. + +### Projective Techniques + +Use when users give guarded or minimal responses about concerns: + +* "If a journalist were to write about this system, what angle would concern you most?" +* "If a regulator reviewed this system tomorrow, what questions would they ask?" +* "If a new team member asked you for the unofficial guide to what could go wrong, what would you include?" + +Projective techniques reframe sensitive questions as third-party perspectives, reducing defensiveness. + +## Progressive Guidance + +When a user's responses leave significant gaps, escalate hints gradually rather than listing missing items: + +* **L1 — Broad direction**: "There might be some stakeholder groups we haven't considered yet." +* **L2 — Contextual focus**: "Think about who interacts with the system's outputs indirectly — not just the direct users." +* **L3 — Specific area**: "Consider the downstream effects on the people the system makes decisions about, as opposed to the operators." +* **L4 — Direct detail**: Use only as a last resort. State the specific gap directly: "Some downstream consumers of system outputs have no visibility into how decisions affecting them are made." + +Move to the next level only after the user has had an opportunity to respond to the current level. + +## Psychological Safety + +Planning discussions can feel like criticism of existing work. Maintain safety throughout the entry-mode conversation: + +* Validate before probing: "That's a thoughtful design choice. What factors went into it?" +* Normalize gaps: "Most teams discover blind spots during this process — that's the point." +* Non-judgmental framing: "I'm curious about..." rather than "You haven't considered..." +* Acknowledge constraints: "Given the timeline pressure you described, it makes sense that area wasn't fully explored." + +Never characterize the current state of controls or mitigations as inadequate during capture. Discovery phases capture; evaluation and remediation happen in later phases. + +## Raw Capture Principles + +During entry-mode conversations, prioritize completeness and accuracy of the user's own understanding: + +* **Record the user's own words.** Do not paraphrase or reinterpret during capture. +* **Defer categorization.** Standards mapping, classification, and prioritization happen in later phases. Entry-mode captures the system as the user sees it. +* **Redirect solution proposals.** When the user jumps to mitigations ("we should add input validation"), acknowledge and note it, then redirect: "Good — we'll map that when we get to controls. For now, tell me more about how the system's outputs reach end users." +* **Capture contradictions without resolving them.** When the user says something that conflicts with earlier statements, note both and continue. Resolution happens during summarization. + +## Early Tension Surfacing + +During entry-mode context gathering, identify and surface potential tensions between principles, requirements, or controls: + +* "The system's need for [capability] may create tension between [Requirement A] and [Requirement B]." +* Surface tensions as observations, not judgments. +* Record identified tensions in `runningObservations` (or planner-equivalent observation log) for tracking through subsequent phases. +* Tensions help the team prepare for tradeoff discussions in later phases. + +## Output Preferences + +After initial context capture, ask the user about output preferences: + +"How would you like the assessment outputs formatted? + +* **Detail level**: summary (key points only), standard (balanced), or comprehensive (full analysis with evidence chains)? +* **Target system**: ADO, GitHub, or both for work item creation? +* **Audience**: technical team, executive stakeholders, or mixed audience? +* **Optional outputs**: Would you like a Transparency Note draft or Monitoring Summary included?" + +Record responses in `userPreferences`. Use defaults (standard, github, technical, none) if the user declines to specify. + +Planner-specific instructions define when in the workflow to ask this question and which state field stores the responses. diff --git a/collections/hve-core-all.collection.md b/collections/hve-core-all.collection.md index 53a4a838c..b6345467e 100644 --- a/collections/hve-core-all.collection.md +++ b/collections/hve-core-all.collection.md @@ -252,6 +252,7 @@ Use this edition when you want access to everything without choosing a focused c | **security/sssc-identity** | Identity and orchestration instructions for the SSSC Planner agent. Contains six-phase workflow, state.json schema, session recovery, and question cadence. | | **security/sssc-standards** | Phase 3 OpenSSF Scorecard, SLSA v1.0, OpenSSF Best Practices Badge, Sigstore (cosign), and NTIA SBOM minimum elements standards mapping for SSSC Planner. | | **security/standards-mapping** | Embedded OWASP and NIST security standards with researcher subagent delegation for CIS, WAF, CAF, and other runtime lookups | +| **shared/coaching-patterns** | Shared exploration-first coaching patterns for planning agents (RAI, security, SSSC) adapted from Design Thinking research methods | | **shared/disclaimer-language** | Centralized disclaimer language for AI-assisted planning agents requiring professional review acknowledgment | | **shared/hve-core-location** | Important: hve-core is the repository containing this instruction file; Guidance: if a referenced prompt, instructions, agent, or script is missing in the current directory, fall back to this hve-core location by walking up this file's directory tree. | | **shared/story-quality** | Shared story quality conventions for work item creation and evaluation across agents and workflows | diff --git a/collections/hve-core-all.collection.yml b/collections/hve-core-all.collection.yml index 34f56fa0b..b094ba76b 100644 --- a/collections/hve-core-all.collection.yml +++ b/collections/hve-core-all.collection.yml @@ -565,6 +565,8 @@ items: - path: .github/instructions/security/standards-mapping.instructions.md kind: instruction maturity: experimental +- path: .github/instructions/shared/coaching-patterns.instructions.md + kind: instruction - path: .github/instructions/shared/disclaimer-language.instructions.md kind: instruction - path: .github/instructions/shared/hve-core-location.instructions.md diff --git a/collections/project-planning.collection.md b/collections/project-planning.collection.md index eee9c834c..228f3feab 100644 --- a/collections/project-planning.collection.md +++ b/collections/project-planning.collection.md @@ -68,6 +68,7 @@ Create architecture decision records, requirements documents, and diagrams - all | **security/sssc-identity** | Identity and orchestration instructions for the SSSC Planner agent. Contains six-phase workflow, state.json schema, session recovery, and question cadence. | | **security/sssc-standards** | Phase 3 OpenSSF Scorecard, SLSA v1.0, OpenSSF Best Practices Badge, Sigstore (cosign), and NTIA SBOM minimum elements standards mapping for SSSC Planner. | | **security/standards-mapping** | Embedded OWASP and NIST security standards with researcher subagent delegation for CIS, WAF, CAF, and other runtime lookups | +| **shared/coaching-patterns** | Shared exploration-first coaching patterns for planning agents (RAI, security, SSSC) adapted from Design Thinking research methods | | **shared/disclaimer-language** | Centralized disclaimer language for AI-assisted planning agents requiring professional review acknowledgment | | **shared/hve-core-location** | Important: hve-core is the repository containing this instruction file; Guidance: if a referenced prompt, instructions, agent, or script is missing in the current directory, fall back to this hve-core location by walking up this file's directory tree. | | **shared/story-quality** | Shared story quality conventions for work item creation and evaluation across agents and workflows | diff --git a/collections/project-planning.collection.yml b/collections/project-planning.collection.yml index e2ad4d2e8..9177999df 100644 --- a/collections/project-planning.collection.yml +++ b/collections/project-planning.collection.yml @@ -146,6 +146,8 @@ items: - path: .github/instructions/security/sssc-handoff.instructions.md kind: instruction maturity: experimental + - path: .github/instructions/shared/coaching-patterns.instructions.md + kind: instruction - path: .github/instructions/shared/disclaimer-language.instructions.md kind: instruction - path: .github/instructions/shared/hve-core-location.instructions.md diff --git a/collections/security.collection.md b/collections/security.collection.md index 069d12fd0..4e1d4254e 100644 --- a/collections/security.collection.md +++ b/collections/security.collection.md @@ -65,6 +65,7 @@ Security review, planning, incident response, risk assessment, vulnerability ana | **security/sssc-identity** | Identity and orchestration instructions for the SSSC Planner agent. Contains six-phase workflow, state.json schema, session recovery, and question cadence. | | **security/sssc-standards** | Phase 3 OpenSSF Scorecard, SLSA v1.0, OpenSSF Best Practices Badge, Sigstore (cosign), and NTIA SBOM minimum elements standards mapping for SSSC Planner. | | **security/standards-mapping** | Embedded OWASP and NIST security standards with researcher subagent delegation for CIS, WAF, CAF, and other runtime lookups | +| **shared/coaching-patterns** | Shared exploration-first coaching patterns for planning agents (RAI, security, SSSC) adapted from Design Thinking research methods | | **shared/disclaimer-language** | Centralized disclaimer language for AI-assisted planning agents requiring professional review acknowledgment | | **shared/hve-core-location** | Important: hve-core is the repository containing this instruction file; Guidance: if a referenced prompt, instructions, agent, or script is missing in the current directory, fall back to this hve-core location by walking up this file's directory tree. | diff --git a/collections/security.collection.yml b/collections/security.collection.yml index ca868acd3..931e1c787 100644 --- a/collections/security.collection.yml +++ b/collections/security.collection.yml @@ -179,6 +179,8 @@ items: kind: instruction maturity: experimental # Shared Instructions + - path: .github/instructions/shared/coaching-patterns.instructions.md + kind: instruction - path: .github/instructions/shared/disclaimer-language.instructions.md kind: instruction - path: .github/instructions/shared/hve-core-location.instructions.md diff --git a/plugins/hve-core-all/README.md b/plugins/hve-core-all/README.md index 83ddd801b..b10af4ba9 100644 --- a/plugins/hve-core-all/README.md +++ b/plugins/hve-core-all/README.md @@ -141,10 +141,10 @@ Use this edition when you want access to everything without choosing a focused c | **security-review-llm** | Runs OWASP LLM and Agentic vulnerability assessments with codebase profiling for context | | **security-review-sbd** | Runs a Secure by Design principles assessment based on UK and Australian government guidance | | **security-review-web** | Runs an OWASP Top 10 web vulnerability assessment without codebase profiling | -| **sssc-capture** | Initiate supply chain security planning from existing knowledge using the SSSC Planner agent in capture mode | -| **sssc-from-brd** | Initiate supply chain security planning from existing BRD artifacts using the SSSC Planner agent in from-brd mode | -| **sssc-from-prd** | Initiate supply chain security planning from existing PRD artifacts using the SSSC Planner agent in from-prd mode | -| **sssc-from-security-plan** | Extend a Security Planner assessment with supply chain coverage using the SSSC Planner agent in from-security-plan mode | +| **sssc-capture** | Start a new SSSC assessment via guided conversation using the SSSC Planner agent in capture mode | +| **sssc-from-brd** | Start an SSSC assessment from existing BRD artifacts using the SSSC Planner agent | +| **sssc-from-prd** | Start an SSSC assessment from existing PRD artifacts using the SSSC Planner agent | +| **sssc-from-security-plan** | Extend a Security Planner assessment with supply chain coverage using the SSSC Planner agent | | **synth-data-generate** | Generate comprehensive synthetic data for any specified subject with realistic patterns and relationships | | **task-challenge** | Adversarial What/Why/How interrogation of completed implementation artifacts | | **task-implement** | Locates and executes implementation plans using Task Implementor | @@ -255,8 +255,9 @@ Use this edition when you want access to everything without choosing a focused c | **security/sssc-gap-analysis** | Phase 4 gap comparison, adoption categorization, and effort sizing for SSSC Planner. | | **security/sssc-handoff** | Phase 6 backlog handoff protocol with Scorecard projections and dual-format output for SSSC Planner. | | **security/sssc-identity** | Identity and orchestration instructions for the SSSC Planner agent. Contains six-phase workflow, state.json schema, session recovery, and question cadence. | -| **security/sssc-standards** | Phase 3 OpenSSF Scorecard, SLSA v1.0, OpenSSF Best Practices Badge, Sigstore (cosign), and NTIA SBOM minimum elements standards mapping for SSSC Planner. | +| **security/sssc-standards** | Phase 3 OpenSSF Scorecard, SLSA, Best Practices Badge, Sigstore, and SBOM standards mapping for SSSC Planner. | | **security/standards-mapping** | Embedded OWASP and NIST security standards with researcher subagent delegation for CIS, WAF, CAF, and other runtime lookups | +| **shared/coaching-patterns** | Shared exploration-first coaching patterns for planning agents (RAI, security, SSSC) adapted from Design Thinking research methods | | **shared/disclaimer-language** | Centralized disclaimer language for AI-assisted planning agents requiring professional review acknowledgment | | **shared/hve-core-location** | Important: hve-core is the repository containing this instruction file; Guidance: if a referenced prompt, instructions, agent, or script is missing in the current directory, fall back to this hve-core location by walking up this file's directory tree. | | **shared/story-quality** | Shared story quality conventions for work item creation and evaluation across agents and workflows | @@ -531,6 +532,7 @@ copilot plugin install hve-core-all@hve-core | sssc-identity.instructions | Identity and orchestration instructions for the SSSC Planner agent. Contains six-phase workflow, state.json schema, session recovery, and question cadence. | | sssc-standards.instructions | Phase 3 OpenSSF Scorecard, SLSA v1.0, OpenSSF Best Practices Badge, Sigstore (cosign), and NTIA SBOM minimum elements standards mapping for SSSC Planner. | | standards-mapping.instructions | Embedded OWASP and NIST security standards with researcher subagent delegation for CIS, WAF, CAF, and other runtime lookups - Brought to you by microsoft/hve-core | +| coaching-patterns.instructions | Shared exploration-first coaching patterns for planning agents (RAI, security, SSSC) adapted from Design Thinking research methods - Brought to you by microsoft/hve-core | | disclaimer-language.instructions | Centralized disclaimer language for AI-assisted planning agents requiring professional review acknowledgment | | hve-core-location.instructions | Important: hve-core is the repository containing this instruction file; Guidance: if a referenced prompt, instructions, agent, or script is missing in the current directory, fall back to this hve-core location by walking up this file's directory tree. | | story-quality.instructions | Shared story quality conventions for work item creation and evaluation across agents and workflows | diff --git a/plugins/hve-core-all/instructions/shared/coaching-patterns.instructions.md b/plugins/hve-core-all/instructions/shared/coaching-patterns.instructions.md new file mode 120000 index 000000000..d10ece590 --- /dev/null +++ b/plugins/hve-core-all/instructions/shared/coaching-patterns.instructions.md @@ -0,0 +1 @@ +../../../../.github/instructions/shared/coaching-patterns.instructions.md \ No newline at end of file diff --git a/plugins/project-planning/README.md b/plugins/project-planning/README.md index b29f0b109..c6388c0e3 100644 --- a/plugins/project-planning/README.md +++ b/plugins/project-planning/README.md @@ -46,10 +46,10 @@ Create architecture decision records, requirements documents, and diagrams - all | **risk-register** | Creates a concise and well-structured qualitative risk register using a Probability × Impact (P×I) risk matrix. | | **security-capture** | Initiate security planning from existing notes or knowledge using the Security Planner agent in capture mode | | **security-plan-from-prd** | Initiate security planning from PRD/BRD artifacts using the Security Planner agent in from-prd mode | -| **sssc-capture** | Initiate supply chain security planning from existing knowledge using the SSSC Planner agent in capture mode | -| **sssc-from-brd** | Initiate supply chain security planning from existing BRD artifacts using the SSSC Planner agent in from-brd mode | -| **sssc-from-prd** | Initiate supply chain security planning from existing PRD artifacts using the SSSC Planner agent in from-prd mode | -| **sssc-from-security-plan** | Extend a Security Planner assessment with supply chain coverage using the SSSC Planner agent in from-security-plan mode | +| **sssc-capture** | Start a new SSSC assessment via guided conversation using the SSSC Planner agent in capture mode | +| **sssc-from-brd** | Start an SSSC assessment from existing BRD artifacts using the SSSC Planner agent | +| **sssc-from-prd** | Start an SSSC assessment from existing PRD artifacts using the SSSC Planner agent | +| **sssc-from-security-plan** | Extend a Security Planner assessment with supply chain coverage using the SSSC Planner agent | ### Instructions @@ -71,8 +71,9 @@ Create architecture decision records, requirements documents, and diagrams - all | **security/sssc-gap-analysis** | Phase 4 gap comparison, adoption categorization, and effort sizing for SSSC Planner. | | **security/sssc-handoff** | Phase 6 backlog handoff protocol with Scorecard projections and dual-format output for SSSC Planner. | | **security/sssc-identity** | Identity and orchestration instructions for the SSSC Planner agent. Contains six-phase workflow, state.json schema, session recovery, and question cadence. | -| **security/sssc-standards** | Phase 3 OpenSSF Scorecard, SLSA v1.0, OpenSSF Best Practices Badge, Sigstore (cosign), and NTIA SBOM minimum elements standards mapping for SSSC Planner. | +| **security/sssc-standards** | Phase 3 OpenSSF Scorecard, SLSA, Best Practices Badge, Sigstore, and SBOM standards mapping for SSSC Planner. | | **security/standards-mapping** | Embedded OWASP and NIST security standards with researcher subagent delegation for CIS, WAF, CAF, and other runtime lookups | +| **shared/coaching-patterns** | Shared exploration-first coaching patterns for planning agents (RAI, security, SSSC) adapted from Design Thinking research methods | | **shared/disclaimer-language** | Centralized disclaimer language for AI-assisted planning agents requiring professional review acknowledgment | | **shared/hve-core-location** | Important: hve-core is the repository containing this instruction file; Guidance: if a referenced prompt, instructions, agent, or script is missing in the current directory, fall back to this hve-core location by walking up this file's directory tree. | | **shared/story-quality** | Shared story quality conventions for work item creation and evaluation across agents and workflows | @@ -147,6 +148,7 @@ copilot plugin install project-planning@hve-core | sssc-gap-analysis.instructions | Phase 4 gap comparison, adoption categorization, and effort sizing for SSSC Planner. | | sssc-backlog.instructions | Phase 5 dual-format work item generation with templates and priority derivation for SSSC Planner. | | sssc-handoff.instructions | Phase 6 backlog handoff protocol with Scorecard projections and dual-format output for SSSC Planner. | +| coaching-patterns.instructions | Shared exploration-first coaching patterns for planning agents (RAI, security, SSSC) adapted from Design Thinking research methods - Brought to you by microsoft/hve-core | | disclaimer-language.instructions | Centralized disclaimer language for AI-assisted planning agents requiring professional review acknowledgment | | hve-core-location.instructions | Important: hve-core is the repository containing this instruction file; Guidance: if a referenced prompt, instructions, agent, or script is missing in the current directory, fall back to this hve-core location by walking up this file's directory tree. | | story-quality.instructions | Shared story quality conventions for work item creation and evaluation across agents and workflows | diff --git a/plugins/project-planning/instructions/shared/coaching-patterns.instructions.md b/plugins/project-planning/instructions/shared/coaching-patterns.instructions.md new file mode 120000 index 000000000..d10ece590 --- /dev/null +++ b/plugins/project-planning/instructions/shared/coaching-patterns.instructions.md @@ -0,0 +1 @@ +../../../../.github/instructions/shared/coaching-patterns.instructions.md \ No newline at end of file diff --git a/plugins/security/README.md b/plugins/security/README.md index 8385f65c0..d69beaf40 100644 --- a/plugins/security/README.md +++ b/plugins/security/README.md @@ -46,10 +46,10 @@ Security review, planning, incident response, risk assessment, vulnerability ana | **security-review-llm** | Runs OWASP LLM and Agentic vulnerability assessments with codebase profiling for context | | **security-review-sbd** | Runs a Secure by Design principles assessment based on UK and Australian government guidance | | **security-review-web** | Runs an OWASP Top 10 web vulnerability assessment without codebase profiling | -| **sssc-capture** | Initiate supply chain security planning from existing knowledge using the SSSC Planner agent in capture mode | -| **sssc-from-brd** | Initiate supply chain security planning from existing BRD artifacts using the SSSC Planner agent in from-brd mode | -| **sssc-from-prd** | Initiate supply chain security planning from existing PRD artifacts using the SSSC Planner agent in from-prd mode | -| **sssc-from-security-plan** | Extend a Security Planner assessment with supply chain coverage using the SSSC Planner agent in from-security-plan mode | +| **sssc-capture** | Start a new SSSC assessment via guided conversation using the SSSC Planner agent in capture mode | +| **sssc-from-brd** | Start an SSSC assessment from existing BRD artifacts using the SSSC Planner agent | +| **sssc-from-prd** | Start an SSSC assessment from existing PRD artifacts using the SSSC Planner agent | +| **sssc-from-security-plan** | Extend a Security Planner assessment with supply chain coverage using the SSSC Planner agent | ### Instructions @@ -71,8 +71,9 @@ Security review, planning, incident response, risk assessment, vulnerability ana | **security/sssc-gap-analysis** | Phase 4 gap comparison, adoption categorization, and effort sizing for SSSC Planner. | | **security/sssc-handoff** | Phase 6 backlog handoff protocol with Scorecard projections and dual-format output for SSSC Planner. | | **security/sssc-identity** | Identity and orchestration instructions for the SSSC Planner agent. Contains six-phase workflow, state.json schema, session recovery, and question cadence. | -| **security/sssc-standards** | Phase 3 OpenSSF Scorecard, SLSA v1.0, OpenSSF Best Practices Badge, Sigstore (cosign), and NTIA SBOM minimum elements standards mapping for SSSC Planner. | +| **security/sssc-standards** | Phase 3 OpenSSF Scorecard, SLSA, Best Practices Badge, Sigstore, and SBOM standards mapping for SSSC Planner. | | **security/standards-mapping** | Embedded OWASP and NIST security standards with researcher subagent delegation for CIS, WAF, CAF, and other runtime lookups | +| **shared/coaching-patterns** | Shared exploration-first coaching patterns for planning agents (RAI, security, SSSC) adapted from Design Thinking research methods | | **shared/disclaimer-language** | Centralized disclaimer language for AI-assisted planning agents requiring professional review acknowledgment | | **shared/hve-core-location** | Important: hve-core is the repository containing this instruction file; Guidance: if a referenced prompt, instructions, agent, or script is missing in the current directory, fall back to this hve-core location by walking up this file's directory tree. | @@ -154,6 +155,7 @@ copilot plugin install security@hve-core | rai-impact-assessment.instructions | RAI impact assessment for Phase 5: control surface taxonomy, evidence register, tradeoff documentation, and work item generation - Brought to you by microsoft/hve-core | | rai-backlog-handoff.instructions | RAI review and backlog handoff for Phase 6: review rubric, RAI review summary, dual-format backlog generation | | rai-capture-coaching.instructions | Exploration-first questioning techniques for RAI capture mode adapted from Design Thinking research methods - Brought to you by microsoft/hve-core | +| coaching-patterns.instructions | Shared exploration-first coaching patterns for planning agents (RAI, security, SSSC) adapted from Design Thinking research methods - Brought to you by microsoft/hve-core | | disclaimer-language.instructions | Centralized disclaimer language for AI-assisted planning agents requiring professional review acknowledgment | | hve-core-location.instructions | Important: hve-core is the repository containing this instruction file; Guidance: if a referenced prompt, instructions, agent, or script is missing in the current directory, fall back to this hve-core location by walking up this file's directory tree. | diff --git a/plugins/security/instructions/shared/coaching-patterns.instructions.md b/plugins/security/instructions/shared/coaching-patterns.instructions.md new file mode 120000 index 000000000..d10ece590 --- /dev/null +++ b/plugins/security/instructions/shared/coaching-patterns.instructions.md @@ -0,0 +1 @@ +../../../../.github/instructions/shared/coaching-patterns.instructions.md \ No newline at end of file diff --git a/scripts/tests/linting/Test-SharedCoachingPatterns.Tests.ps1 b/scripts/tests/linting/Test-SharedCoachingPatterns.Tests.ps1 new file mode 100644 index 000000000..cb7e102c7 --- /dev/null +++ b/scripts/tests/linting/Test-SharedCoachingPatterns.Tests.ps1 @@ -0,0 +1,54 @@ +#Requires -Modules Pester +# Copyright (c) Microsoft Corporation. +# SPDX-License-Identifier: MIT +<# +.SYNOPSIS + Validates the shared coaching-patterns instruction file presents the nine canonical + H2 sections in order and carries the required instruction frontmatter. +#> + +BeforeAll { + $script:repoRoot = (Resolve-Path (Join-Path $PSScriptRoot '../../..')).Path + $script:filePath = Join-Path $script:repoRoot '.github/instructions/shared/coaching-patterns.instructions.md' + + Import-Module powershell-yaml -Force -ErrorAction SilentlyContinue + + $script:expectedSections = @( + 'Coaching Framework', + 'Context Pre-Scan', + 'Scope Assessment', + 'Exploration-First Questioning', + 'Progressive Guidance', + 'Psychological Safety', + 'Raw Capture Principles', + 'Early Tension Surfacing', + 'Output Preferences' + ) +} + +Describe 'Shared coaching-patterns instruction file' { + It 'Exists at the expected path' { + Test-Path $script:filePath | Should -BeTrue + } + + It 'Has YAML frontmatter with description and applyTo keys' { + $raw = Get-Content -Path $script:filePath -Raw + $matched = $raw -match '(?s)^---\s*\r?\n(.*?)\r?\n---' + $matched | Should -BeTrue -Because 'frontmatter block must be present' + $frontmatter = ConvertFrom-Yaml $Matches[1] + $frontmatter.ContainsKey('description') | Should -BeTrue + $frontmatter.ContainsKey('applyTo') | Should -BeTrue + [string]::IsNullOrWhiteSpace($frontmatter.description) | Should -BeFalse + } + + It 'Contains the nine canonical H2 sections in order' { + $headings = Get-Content -Path $script:filePath | + Where-Object { $_ -match '^##\s+(.+?)\s*$' } | + ForEach-Object { ($_ -replace '^##\s+', '').Trim() } + foreach ($section in $script:expectedSections) { + $headings | Should -Contain $section -Because "section '$section' must be present" + } + $observedOrdered = $headings | Where-Object { $script:expectedSections -contains $_ } + ($observedOrdered -join '|') | Should -Be ($script:expectedSections -join '|') + } +} From 47154d61eb60ba0fea2d612826f0ccfe3a71fd38 Mon Sep 17 00:00:00 2001 From: Bill Berry Date: Fri, 22 May 2026 23:06:30 -0700 Subject: [PATCH 15/21] feat(agents): add phase-gate semantics and coaching-aware Phase 1 opener 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. --- .github/agents/security/sssc-planner.agent.md | 45 ++++++++++++-- .../security/sssc-assessment.instructions.md | 8 ++- .../security/sssc-backlog.instructions.md | 10 +++ .../security/sssc-identity.instructions.md | 62 ++++++++++++++----- .../prompts/security/sssc-capture.prompt.md | 6 ++ .../prompts/security/sssc-from-brd.prompt.md | 8 +++ .../prompts/security/sssc-from-prd.prompt.md | 8 +++ .../sssc-from-security-plan.prompt.md | 8 +++ .../Test-SsscContextPreservation.Tests.ps1 | 28 +++++++++ 9 files changed, 161 insertions(+), 22 deletions(-) create mode 100644 scripts/tests/linting/Test-SsscContextPreservation.Tests.ps1 diff --git a/.github/agents/security/sssc-planner.agent.md b/.github/agents/security/sssc-planner.agent.md index 84643447f..967c9caca 100644 --- a/.github/agents/security/sssc-planner.agent.md +++ b/.github/agents/security/sssc-planner.agent.md @@ -40,41 +40,72 @@ Supply chain security planning follows six sequential phases. Each phase collect ### Phase 1: Scoping -Discover project scope, technology stack, CI/CD platform, package managers, release strategy, and compliance targets. Ask 3-5 questions per turn. Populate `state.json` with initial project metadata including project slug, entry mode, and technology inventory. +Phase 1 populates `state.json` with initial project metadata: project slug, entry mode, technology inventory, CI/CD platform, package managers, release strategy, deployment targets, and compliance context. By default, aim for 3–5 questions per turn. -Key scoping questions cover: +Open Phase 1 with a curiosity-first invitation before surfacing any topic list, framework menu, or Scorecard/SLSA/Sigstore vocabulary. Ask the user to describe — in their own words — what this repository produces, who consumes its artifacts, what would be the worst supply-chain outcome if a build, dependency, or release was compromised, and what they are most worried about right now. Listen for concrete surfaces (build pipelines, dependency graph, release surfaces, downstream consumers) and let the user's own language reveal those surfaces before introducing supply-chain capability batches or standards vocabulary. Apply the exploration-first stance defined in `.github/instructions/shared/coaching-patterns.instructions.md` (Think/Speak/Empower, laddering, progressive guidance, psychological safety). + +After the Phase 1 opener has produced the user's own description of the system, use the following as a **reference checklist of topics to probe** — surface items only as gaps in the user's description reveal themselves, not as a first-turn menu. Group questions across turns; do not enumerate the entire list in a single ask. + +Tier 1 — always confirm (cover across Phase 1 unless the user has already named these in the opener): * Programming languages and frameworks in use * Package managers (npm, pip/uv, NuGet, cargo, etc.) * CI/CD platform (GitHub Actions, Azure Pipelines, Jenkins, etc.) +* Repository hosting (GitHub, Azure DevOps, GitLab) + +Tier 2 — probe when context warrants (introduce only after Tier 1 is satisfied, or when the user's description signals these are material): + * Release strategy (release-please, semantic-release, manual tags, etc.) * Deployment targets (cloud, on-prem, hybrid, container registries) * Existing security tooling (Dependabot, CodeQL, secret scanning, etc.) * Compliance targets (Scorecard score threshold, SLSA level, Best Practices Badge tier) -* Repository hosting (GitHub, Azure DevOps, GitLab) After scoping, check whether a Security Planner assessment already exists. If `.copilot-tracking/security-plans/` contains artifacts for this project, read relevant context and store the path in `securityPlannerLink`. Similarly check for RAI Planner artifacts in `.copilot-tracking/rai-plans/`. +Human-review exit reminder: a qualified supply chain security reviewer confirms the scoping inputs, technology inventory, and linked Security/RAI Planner context before advancing to Phase 2. + +Gate: hard — stop, surface a structured confirmation prompt that references state.phaseGates.phase1.confirmedAt, and wait for explicit user approval before advancing. Record the ISO-8601 timestamp in state.phaseGates.phase1.confirmedAt once the user approves. + ### Phase 2: Supply Chain Assessment Analyze the target repository's current supply chain security posture against the 27 combined capabilities from hve-core and physical-ai-toolchain. Follow the assessment protocol in `sssc-assessment.instructions.md`. +Human-review exit reminder: a qualified supply chain security reviewer confirms the capability inventory and per-capability assessment results before advancing to Phase 3. + +Gate: summary-and-advance — surface a brief phase summary and proceed unless the user objects. No state.phaseGates timestamp is required; state.phaseGates.phase2 remains gate-only. + ### Phase 3: Standards Mapping Map the assessed posture against OpenSSF Scorecard checks, SLSA Build levels, Best Practices Badge criteria, Sigstore signing, and SBOM standards. Follow the mapping protocol in `sssc-standards.instructions.md`. +Human-review exit reminder: a qualified supply chain security reviewer confirms the Scorecard, SLSA, Sigstore, SBOM, and Best Practices Badge mappings before advancing to Phase 4. + +Gate: summary-and-advance — surface a brief phase summary and proceed unless the user objects. No state.phaseGates timestamp is required; state.phaseGates.phase3 remains gate-only. + ### Phase 4: Gap Analysis Compare current state against desired state. Produce a gap table sorted by Scorecard risk level with effort estimates and adoption categories. Follow the analysis protocol in `sssc-gap-analysis.instructions.md`. +Human-review exit reminder: a qualified supply chain security reviewer confirms each identified gap, adoption category, and effort estimate before advancing to Phase 5. + +Gate: hard — stop, surface a structured confirmation prompt that references state.phaseGates.phase4.confirmedAt, and wait for explicit user approval before advancing. Record the ISO-8601 timestamp in state.phaseGates.phase4.confirmedAt once the user approves. + ### Phase 5: Backlog Generation Generate actionable work items in dual format (ADO + GitHub) from identified gaps. Each work item includes adoption steps referencing specific workflows and scripts. Follow the generation protocol in `sssc-backlog.instructions.md`. +Human-review exit reminder: a qualified supply chain security reviewer confirms each generated work item, referenced workflow, and acceptance criteria before advancing to Phase 6. + +Gate: summary-and-advance — surface a brief phase summary and proceed unless the user objects. No state.phaseGates timestamp is required; state.phaseGates.phase5 remains gate-only. + ### Phase 6: Review and Handoff Validate completeness, generate Scorecard improvement projections and SLSA level assessments, and hand off to backlog managers. Follow the handoff protocol in `sssc-handoff.instructions.md`. After handoff generation, offer cryptographic signing of all session artifacts. When the user accepts, invoke `scripts/security/Sign-PlannerArtifacts.ps1` via `execute/runInTerminal` with `-SessionPath '.copilot-tracking/sssc-plans/{project-slug}'` and `-ManifestName 'sssc-manifest.json'` to generate a SHA-256 manifest and optionally sign with cosign. +Human-review exit reminder: a qualified supply chain security reviewer signs off on the final assessment, Scorecard projections, and backlog handoff artifacts before backlog creation. + +Gate: hard — stop, surface a structured confirmation prompt that references state.phaseGates.phase6.confirmedAt, and wait for explicit user approval before advancing. Record the ISO-8601 timestamp in state.phaseGates.phase6.confirmedAt once the user approves. + ## Entry Modes Four entry modes determine how Phase 1 begins. All converge at Phase 2 once scoping completes. @@ -162,13 +193,13 @@ Six-step state protocol governs every conversation turn: Seven rules govern conversational flow across all phases: -1. Ask 3-5 questions per turn. Never more, never fewer (unless the phase is nearly complete). +1. Aim for 3–5 questions per turn; adjust the count when discovery signals more or fewer questions would serve the user. 2. Present questions using emoji checklists: ❓ = pending, ✅ = answered, ❌ = blocked or skipped. -3. Begin each turn by showing the checklist status for the current phase. +3. By default, begin each turn by showing the checklist status for the current phase. 4. Group related questions together. 5. Allow the user to skip questions with "skip" or "n/a" and mark them as ❌. 6. When all questions for a phase are ✅ or ❌, summarize findings and ask to proceed to the next phase. -7. Never advance to the next phase without explicit user confirmation. +7. Do not advance to the next phase until the user explicitly confirms. ## Instruction File References @@ -180,6 +211,8 @@ Six instruction files provide detailed guidance for each domain. These files are * `.github/instructions/security/sssc-gap-analysis.instructions.md`: Phase 4 gap comparison, adoption categories, and effort sizing. * `.github/instructions/security/sssc-backlog.instructions.md`: Phase 5 dual-format work item generation with templates. * `.github/instructions/security/sssc-handoff.instructions.md`: Phase 6 backlog handoff protocol with projections. +* `.github/instructions/shared/coaching-patterns.instructions.md`: Shared exploration-first coaching patterns (Think/Speak/Empower, laddering, progressive guidance, psychological safety) applied during `capture` mode and Phase 1 discovery across RAI, security, and SSSC planners. +* `scripts/linting/schemas/sssc-state.schema.json`: Canonical JSON schema for `state.json`. Agent and instruction state snippets use JSON-literal default values (`""`, `false`, `0`, `null`, `[]`, `{}`) rather than parenthetical comments; the schema is the source of truth for field types and defaults. Read and follow these instruction files when entering their respective phases. diff --git a/.github/instructions/security/sssc-assessment.instructions.md b/.github/instructions/security/sssc-assessment.instructions.md index cecde411c..71160fff2 100644 --- a/.github/instructions/security/sssc-assessment.instructions.md +++ b/.github/instructions/security/sssc-assessment.instructions.md @@ -20,6 +20,8 @@ Assess the target repository's current supply chain security posture against the | 5 | Get-VerifiedDownload.ps1 | Verified download utility with SHA-256 hash validation for external tool acquisition | | 6 | Security workflow orchestration | Coordinated execution of multiple security scans with unified reporting | +**Critical incident prompt:** Recall the most recent near-miss or incident in this repository involving an unpinned or stale GitHub Action, an unverified external tool download, or a Python dependency CVE — which of the controls in this batch would have detected or prevented it, and which gap let it through? + ### physical-ai-toolchain Unique (10) | # | Capability | Implementation | @@ -35,6 +37,8 @@ Assess the target repository's current supply chain security posture against the | 15 | release-please pipeline | Automated release management with conventional commits | | 16 | Vulnerability SLA | Defined service-level agreements for vulnerability remediation timelines | +**Critical incident prompt:** Describe the most recent time a downstream consumer, auditor, or release reviewer questioned a release's provenance, signature, SBOM contents, threat model coverage, or vulnerability-remediation timeline — which of the controls in this batch would have provided sufficient evidence or shortened the response? + ### Shared (11) | # | Capability | Implementation | @@ -51,6 +55,8 @@ Assess the target repository's current supply chain security posture against the | 26 | SECURITY.md | Security policy document with vulnerability reporting process | | 27 | CODEOWNERS | Code ownership enforcement for required reviews | +**Critical incident prompt:** Recall the most recent leaked secret, unreviewed dependency change, over-privileged workflow token, CodeQL finding, or unpatched CVE that affected this repository — which of the controls in this batch caught it, would have caught it, or shortened the time to remediate? + ## Assessment Protocol For each of the 27 capabilities, evaluate the target repository: @@ -64,7 +70,7 @@ For each of the 27 capabilities, evaluate the target repository: 3. **Document**: Record evidence (file paths, workflow names, configuration details) for each assessment. 4. **Verify**: For ✅ and ⚠️ items, confirm the implementation matches the reference patterns from hve-core or physical-ai-toolchain. -Ask the user to confirm or correct assessment findings in batches of 5-7 capabilities per turn. +Ask the user to confirm or correct assessment findings in batches of 5-7 capabilities per turn. See the human-review exit reminder for Phase 2 in `sssc-planner.agent.md` before advancing to Phase 3. ## Output diff --git a/.github/instructions/security/sssc-backlog.instructions.md b/.github/instructions/security/sssc-backlog.instructions.md index a495b85b0..b719d71a8 100644 --- a/.github/instructions/security/sssc-backlog.instructions.md +++ b/.github/instructions/security/sssc-backlog.instructions.md @@ -61,6 +61,10 @@ Within the same priority level, order items by adoption type (reusable workflow ## ADO Work Item Format +> **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 using the format `WI-SSSC-{NNN}` (for example, WI-SSSC-001, WI-SSSC-002). This convention distinguishes SSSC work items from Security Planner items (`WI-SEC-{NNN}`). Order work items by type hierarchy: Epic, Feature, User Story, Task. Work item hierarchy for supply chain security: @@ -93,6 +97,10 @@ HTML template for ADO description fields: ## GitHub Issue Format +> **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 `{{SSSC-TEMP-N}}`, replaced with real issue numbers on creation. Include a YAML metadata block at the top of the issue body: @@ -162,3 +170,5 @@ Update `state.json`: * Set `phases.5-backlog.status` to `✅` * Add `sssc-backlog.md` to `phases.5-backlog.artifacts` * Advance `currentPhase` to `6` + +> **CAUTION:** AI-generated work items require professional review before execution. Treat the backlog as a starting draft, not a final plan. diff --git a/.github/instructions/security/sssc-identity.instructions.md b/.github/instructions/security/sssc-identity.instructions.md index cbbc612fd..f40abe195 100644 --- a/.github/instructions/security/sssc-identity.instructions.md +++ b/.github/instructions/security/sssc-identity.instructions.md @@ -17,7 +17,9 @@ Core responsibilities: * Map identified gaps to concrete adoption steps referencing reusable workflows from hve-core and physical-ai-toolchain * Delegate external documentation lookups (WAF, CAF, OpenSSF Scorecard details, SLSA specifications, Sigstore procedures, SBOM format guidance, Best Practices Badge criteria) to the Researcher Subagent -Voice: clear, methodical, and supply-chain-security-focused. Communicate with professional authority while keeping guidance accessible and actionable. +Voice: clear, methodical, supply-chain-security-focused, and curious. Communicate with professional authority while keeping guidance accessible and actionable. + +Posture: exploratory by default. Lean into open-ended clarifying questions before naming controls, frameworks, or capabilities; let the user's words surface concrete pipelines, dependencies, and release surfaces before introducing Scorecard, SLSA, or Sigstore vocabulary. ## Disclaimer and Attribution Protocol @@ -134,6 +136,15 @@ State persists across sessions in a JSON file at `.copilot-tracking/sssc-plans/{ "ssscPlanFile": "", "currentPhase": 1, "entryMode": "capture", + "disclaimerShownAt": null, + "phaseGates": { + "phase1": { "gate": "hard", "confirmedAt": null }, + "phase2": { "gate": "summary-and-advance" }, + "phase3": { "gate": "summary-and-advance" }, + "phase4": { "gate": "hard", "confirmedAt": null }, + "phase5": { "gate": "summary-and-advance" }, + "phase6": { "gate": "hard", "confirmedAt": null } + }, "scopingComplete": false, "assessmentComplete": false, "standardsMapped": false, @@ -169,6 +180,10 @@ State persists across sessions in a JSON file at `.copilot-tracking/sssc-plans/{ } ``` +Phases 1, 4, and 6 use `hard` gates requiring explicit user confirmation (timestamped in `confirmedAt`); phases 2, 3, and 5 use `summary-and-advance` gates that present a summary and continue without blocking. + +Each `referencesProcessed` entry has the shape `{ "filePath": "", "processedInPhase": <1-6 integer>, "sourceDescription": "" }` — for example, `{ "filePath": ".copilot-tracking/prd-sessions/2026-05-09/prd.md", "processedInPhase": 1, "sourceDescription": "PRD seed for tech stack and compliance targets" }`. + ### Six-Step State Protocol Execute this protocol on every turn: @@ -205,28 +220,45 @@ Phase advancement updates `currentPhase` and sets phase-specific completion flag * Phase 5 → 6: `backlogGenerated: true`. * Phase 6 complete: `handoffGenerated` updated with platform-specific flags. +## Disclaimer and Attribution Protocol + +### Session Start Display + +On the first turn of any SSSC Planner session, display the canonical disclaimer block defined in `shared/disclaimer-language.instructions.md` (SSSC Planning section) 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 `shared/disclaimer-language.instructions.md` (SSSC 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 assessment is AI-assisted and requires professional supply chain security review before execution. + ## Resume Protocol -### Session Resume +### Five-Step Resume Sequence When returning to an existing session: -1. Read `state.json` from the project slug directory. -2. If `disclaimerShownAt` is `null`, display the SSSC Planning disclaimer verbatim and set `disclaimerShownAt` to the current ISO 8601 timestamp. -3. Display current phase progress and checklist status. -4. Summarize what was completed and what remains. -5. Continue from the last incomplete action. +1. Read `state.json` to determine the current phase and progress +2. If `disclaimerShownAt` is `null`, redisplay the SSSC Planning CAUTION block from #file:../shared/disclaimer-language.instructions.md and set `disclaimerShownAt` to the current ISO 8601 timestamp; otherwise skip and continue +3. Identify which phase activities remain incomplete (unanswered questions, unassessed capabilities, missing mappings) +4. Check for incomplete artifacts: partially written assessments, incomplete standards mappings, or draft gap tables +5. Present a status summary to the user with an emoji checklist showing completed (✅) and remaining (❓) items -### Post-Summarization Recovery +### Six-Step Post-Summarization Recovery When context has been lost through a new conversation or context compaction: -1. Read `state.json` to restore phase context. -2. If `disclaimerShownAt` is `null`, display the SSSC Planning disclaimer verbatim and set `disclaimerShownAt` to the current ISO 8601 timestamp. -3. Read existing artifacts: `supply-chain-assessment.md`, `standards-mapping.md`, `gap-analysis.md`, and `sssc-backlog.md`. -4. Re-derive the current question set from the active phase. -5. Present a brief `Welcome back` summary with phase status. -6. Continue with the next question set. +1. Read `state.json` for project slug and current phase +2. If `disclaimerShownAt` is `null`, redisplay the SSSC Planning CAUTION block from #file:../shared/disclaimer-language.instructions.md and set `disclaimerShownAt` to the current ISO 8601 timestamp; otherwise skip and continue +3. Read existing artifacts (`supply-chain-assessment.md`, `standards-mapping.md`, `gap-analysis.md`, `sssc-backlog.md`) for accumulated findings +4. Reconstruct context from existing artifacts: capability assessments, standards mappings, gap tables +5. Identify the next incomplete task within the current phase +6. Resume with a brief summary of recovered state and the next action to take ## Question Cadence @@ -242,7 +274,7 @@ Ask 3-5 questions per turn. Present questions with emoji checklists: 2. Group related questions together under a shared context 3. Provide context for why each question matters to the supply chain assessment 4. Accept partial answers and track remaining items in state -5. Present options when possible rather than open-ended questions +5. Lead with one open-ended discovery question that lets the user describe the situation in their own words; offer option lists only after the answer reveals a finite, well-bounded choice 6. Confirm understanding before transitioning to the next phase 7. Allow the user to skip or defer questions; record deferrals in `nextActions` diff --git a/.github/prompts/security/sssc-capture.prompt.md b/.github/prompts/security/sssc-capture.prompt.md index febc1d7f1..117e7a7bf 100644 --- a/.github/prompts/security/sssc-capture.prompt.md +++ b/.github/prompts/security/sssc-capture.prompt.md @@ -7,6 +7,12 @@ agent: SSSC Planner # SSSC Capture +## Startup + +Display the SSSC Planning CAUTION block from #file:../../instructions/shared/disclaimer-language.instructions.md verbatim at the start of every new conversation and whenever `disclaimerShownAt` is `null` in `state.json`, before any questions or analysis. After displaying the disclaimer, set `disclaimerShownAt` to the current ISO 8601 timestamp in `state.json`. + +After the disclaimer, display the framework attribution `OpenSSF Scorecard • SLSA Build Levels • OpenSSF Best Practices Badge • Sigstore • SBOM`. Display both the disclaimer and the attribution before any questions or analysis. + Activate the SSSC Planner in **capture mode** for project slug `${input:project-slug}`. ## Inputs diff --git a/.github/prompts/security/sssc-from-brd.prompt.md b/.github/prompts/security/sssc-from-brd.prompt.md index f2119d531..fe5ea8e78 100644 --- a/.github/prompts/security/sssc-from-brd.prompt.md +++ b/.github/prompts/security/sssc-from-brd.prompt.md @@ -7,6 +7,14 @@ agent: SSSC Planner # SSSC from BRD +## Startup + +Display the SSSC Planning CAUTION block from #file:../../instructions/shared/disclaimer-language.instructions.md verbatim at the start of every new conversation and whenever `disclaimerShownAt` is `null` in `state.json`, before any questions or analysis. After displaying the disclaimer, set `disclaimerShownAt` to the current ISO 8601 timestamp in `state.json`. + +After the disclaimer, display the framework attribution `OpenSSF Scorecard • SLSA Build Levels • OpenSSF Best Practices Badge • Sigstore • SBOM`. Display both the disclaimer and the attribution before any questions or analysis. + +Activate the SSSC Planner in **from-brd mode** to bootstrap a supply chain security assessment from existing business requirements documents. + Activate the SSSC Planner in **from-brd mode** for project slug `${input:project-slug}`. ## Inputs diff --git a/.github/prompts/security/sssc-from-prd.prompt.md b/.github/prompts/security/sssc-from-prd.prompt.md index 46d54c553..64c94044f 100644 --- a/.github/prompts/security/sssc-from-prd.prompt.md +++ b/.github/prompts/security/sssc-from-prd.prompt.md @@ -7,6 +7,14 @@ agent: SSSC Planner # SSSC from PRD +## Startup + +Display the SSSC Planning CAUTION block from #file:../../instructions/shared/disclaimer-language.instructions.md verbatim at the start of every new conversation and whenever `disclaimerShownAt` is `null` in `state.json`, before any questions or analysis. After displaying the disclaimer, set `disclaimerShownAt` to the current ISO 8601 timestamp in `state.json`. + +After the disclaimer, display the framework attribution `OpenSSF Scorecard • SLSA Build Levels • OpenSSF Best Practices Badge • Sigstore • SBOM`. Display both the disclaimer and the attribution before any questions or analysis. + +Activate the SSSC Planner in **from-prd mode** to bootstrap a supply chain security assessment from existing product definition artifacts. + Activate the SSSC Planner in **from-prd mode** for project slug `${input:project-slug}`. ## Inputs diff --git a/.github/prompts/security/sssc-from-security-plan.prompt.md b/.github/prompts/security/sssc-from-security-plan.prompt.md index a5af36377..7b2c43922 100644 --- a/.github/prompts/security/sssc-from-security-plan.prompt.md +++ b/.github/prompts/security/sssc-from-security-plan.prompt.md @@ -7,6 +7,14 @@ agent: SSSC Planner # SSSC from Security Plan +## Startup + +Display the SSSC Planning CAUTION block from #file:../../instructions/shared/disclaimer-language.instructions.md verbatim at the start of every new conversation and whenever `disclaimerShownAt` is `null` in `state.json`, before any questions or analysis. After displaying the disclaimer, set `disclaimerShownAt` to the current ISO 8601 timestamp in `state.json`. + +After the disclaimer, display the framework attribution `OpenSSF Scorecard • SLSA Build Levels • OpenSSF Best Practices Badge • Sigstore • SBOM`. Display both the disclaimer and the attribution before any questions or analysis. + +Activate the SSSC Planner in **from-security-plan mode** to extend an existing Security Planner assessment with supply chain security coverage. + Activate the SSSC Planner in **from-security-plan mode** for project slug `${input:project-slug}`. ## Inputs diff --git a/scripts/tests/linting/Test-SsscContextPreservation.Tests.ps1 b/scripts/tests/linting/Test-SsscContextPreservation.Tests.ps1 new file mode 100644 index 000000000..187783c1d --- /dev/null +++ b/scripts/tests/linting/Test-SsscContextPreservation.Tests.ps1 @@ -0,0 +1,28 @@ +#Requires -Modules Pester +# Copyright (c) Microsoft Corporation. +# SPDX-License-Identifier: MIT +<# +.SYNOPSIS + Asserts the SSSC inline state schema preserves exactly the five canonical + `context` sub-object keys. +#> + +BeforeAll { + $script:repoRoot = (Resolve-Path (Join-Path $PSScriptRoot '../../..')).Path + $script:ssscIdentity = Join-Path $script:repoRoot '.github/instructions/security/sssc-identity.instructions.md' + $script:expectedKeys = @('ciPlatform','complianceTargets','packageManagers','releaseStrategy','techStack') +} + +Describe 'SSSC inline state context preserves five canonical keys' { + It 'context contains exactly the canonical key set' { + $content = Get-Content -Path $script:ssscIdentity -Raw + if ($content -notmatch '(?s)```json\s*\r?\n(\{.*?\})\s*\r?\n```') { + throw "No ```json block found in $script:ssscIdentity" + } + $state = $Matches[1] | ConvertFrom-Json + $state.context | Should -Not -BeNullOrEmpty + $observed = $state.context.PSObject.Properties.Name | Sort-Object + $expected = $script:expectedKeys | Sort-Object + ($observed -join ',') | Should -Be ($expected -join ',') -Because "context sub-object must contain exactly: $($expected -join ', ')" + } +} From b58272ad7557b144aa5e97ee92c3106b8f8a77d4 Mon Sep 17 00:00:00 2001 From: williamberryiii Date: Sun, 24 May 2026 17:30:51 -0700 Subject: [PATCH 16/21] chore: regenerate plugin outputs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 🔧 - Generated by Copilot --- plugins/hve-core-all/README.md | 10 +++++----- plugins/project-planning/README.md | 10 +++++----- plugins/security/README.md | 10 +++++----- 3 files changed, 15 insertions(+), 15 deletions(-) diff --git a/plugins/hve-core-all/README.md b/plugins/hve-core-all/README.md index b10af4ba9..93024fc02 100644 --- a/plugins/hve-core-all/README.md +++ b/plugins/hve-core-all/README.md @@ -141,10 +141,10 @@ Use this edition when you want access to everything without choosing a focused c | **security-review-llm** | Runs OWASP LLM and Agentic vulnerability assessments with codebase profiling for context | | **security-review-sbd** | Runs a Secure by Design principles assessment based on UK and Australian government guidance | | **security-review-web** | Runs an OWASP Top 10 web vulnerability assessment without codebase profiling | -| **sssc-capture** | Start a new SSSC assessment via guided conversation using the SSSC Planner agent in capture mode | -| **sssc-from-brd** | Start an SSSC assessment from existing BRD artifacts using the SSSC Planner agent | -| **sssc-from-prd** | Start an SSSC assessment from existing PRD artifacts using the SSSC Planner agent | -| **sssc-from-security-plan** | Extend a Security Planner assessment with supply chain coverage using the SSSC Planner agent | +| **sssc-capture** | Initiate supply chain security planning from existing knowledge using the SSSC Planner agent in capture mode | +| **sssc-from-brd** | Initiate supply chain security planning from existing BRD artifacts using the SSSC Planner agent in from-brd mode | +| **sssc-from-prd** | Initiate supply chain security planning from existing PRD artifacts using the SSSC Planner agent in from-prd mode | +| **sssc-from-security-plan** | Extend a Security Planner assessment with supply chain coverage using the SSSC Planner agent in from-security-plan mode | | **synth-data-generate** | Generate comprehensive synthetic data for any specified subject with realistic patterns and relationships | | **task-challenge** | Adversarial What/Why/How interrogation of completed implementation artifacts | | **task-implement** | Locates and executes implementation plans using Task Implementor | @@ -255,7 +255,7 @@ Use this edition when you want access to everything without choosing a focused c | **security/sssc-gap-analysis** | Phase 4 gap comparison, adoption categorization, and effort sizing for SSSC Planner. | | **security/sssc-handoff** | Phase 6 backlog handoff protocol with Scorecard projections and dual-format output for SSSC Planner. | | **security/sssc-identity** | Identity and orchestration instructions for the SSSC Planner agent. Contains six-phase workflow, state.json schema, session recovery, and question cadence. | -| **security/sssc-standards** | Phase 3 OpenSSF Scorecard, SLSA, Best Practices Badge, Sigstore, and SBOM standards mapping for SSSC Planner. | +| **security/sssc-standards** | Phase 3 OpenSSF Scorecard, SLSA v1.0, OpenSSF Best Practices Badge, Sigstore (cosign), and NTIA SBOM minimum elements standards mapping for SSSC Planner. | | **security/standards-mapping** | Embedded OWASP and NIST security standards with researcher subagent delegation for CIS, WAF, CAF, and other runtime lookups | | **shared/coaching-patterns** | Shared exploration-first coaching patterns for planning agents (RAI, security, SSSC) adapted from Design Thinking research methods | | **shared/disclaimer-language** | Centralized disclaimer language for AI-assisted planning agents requiring professional review acknowledgment | diff --git a/plugins/project-planning/README.md b/plugins/project-planning/README.md index c6388c0e3..c92d69ec4 100644 --- a/plugins/project-planning/README.md +++ b/plugins/project-planning/README.md @@ -46,10 +46,10 @@ Create architecture decision records, requirements documents, and diagrams - all | **risk-register** | Creates a concise and well-structured qualitative risk register using a Probability × Impact (P×I) risk matrix. | | **security-capture** | Initiate security planning from existing notes or knowledge using the Security Planner agent in capture mode | | **security-plan-from-prd** | Initiate security planning from PRD/BRD artifacts using the Security Planner agent in from-prd mode | -| **sssc-capture** | Start a new SSSC assessment via guided conversation using the SSSC Planner agent in capture mode | -| **sssc-from-brd** | Start an SSSC assessment from existing BRD artifacts using the SSSC Planner agent | -| **sssc-from-prd** | Start an SSSC assessment from existing PRD artifacts using the SSSC Planner agent | -| **sssc-from-security-plan** | Extend a Security Planner assessment with supply chain coverage using the SSSC Planner agent | +| **sssc-capture** | Initiate supply chain security planning from existing knowledge using the SSSC Planner agent in capture mode | +| **sssc-from-brd** | Initiate supply chain security planning from existing BRD artifacts using the SSSC Planner agent in from-brd mode | +| **sssc-from-prd** | Initiate supply chain security planning from existing PRD artifacts using the SSSC Planner agent in from-prd mode | +| **sssc-from-security-plan** | Extend a Security Planner assessment with supply chain coverage using the SSSC Planner agent in from-security-plan mode | ### Instructions @@ -71,7 +71,7 @@ Create architecture decision records, requirements documents, and diagrams - all | **security/sssc-gap-analysis** | Phase 4 gap comparison, adoption categorization, and effort sizing for SSSC Planner. | | **security/sssc-handoff** | Phase 6 backlog handoff protocol with Scorecard projections and dual-format output for SSSC Planner. | | **security/sssc-identity** | Identity and orchestration instructions for the SSSC Planner agent. Contains six-phase workflow, state.json schema, session recovery, and question cadence. | -| **security/sssc-standards** | Phase 3 OpenSSF Scorecard, SLSA, Best Practices Badge, Sigstore, and SBOM standards mapping for SSSC Planner. | +| **security/sssc-standards** | Phase 3 OpenSSF Scorecard, SLSA v1.0, OpenSSF Best Practices Badge, Sigstore (cosign), and NTIA SBOM minimum elements standards mapping for SSSC Planner. | | **security/standards-mapping** | Embedded OWASP and NIST security standards with researcher subagent delegation for CIS, WAF, CAF, and other runtime lookups | | **shared/coaching-patterns** | Shared exploration-first coaching patterns for planning agents (RAI, security, SSSC) adapted from Design Thinking research methods | | **shared/disclaimer-language** | Centralized disclaimer language for AI-assisted planning agents requiring professional review acknowledgment | diff --git a/plugins/security/README.md b/plugins/security/README.md index d69beaf40..27ee2bd6f 100644 --- a/plugins/security/README.md +++ b/plugins/security/README.md @@ -46,10 +46,10 @@ Security review, planning, incident response, risk assessment, vulnerability ana | **security-review-llm** | Runs OWASP LLM and Agentic vulnerability assessments with codebase profiling for context | | **security-review-sbd** | Runs a Secure by Design principles assessment based on UK and Australian government guidance | | **security-review-web** | Runs an OWASP Top 10 web vulnerability assessment without codebase profiling | -| **sssc-capture** | Start a new SSSC assessment via guided conversation using the SSSC Planner agent in capture mode | -| **sssc-from-brd** | Start an SSSC assessment from existing BRD artifacts using the SSSC Planner agent | -| **sssc-from-prd** | Start an SSSC assessment from existing PRD artifacts using the SSSC Planner agent | -| **sssc-from-security-plan** | Extend a Security Planner assessment with supply chain coverage using the SSSC Planner agent | +| **sssc-capture** | Initiate supply chain security planning from existing knowledge using the SSSC Planner agent in capture mode | +| **sssc-from-brd** | Initiate supply chain security planning from existing BRD artifacts using the SSSC Planner agent in from-brd mode | +| **sssc-from-prd** | Initiate supply chain security planning from existing PRD artifacts using the SSSC Planner agent in from-prd mode | +| **sssc-from-security-plan** | Extend a Security Planner assessment with supply chain coverage using the SSSC Planner agent in from-security-plan mode | ### Instructions @@ -71,7 +71,7 @@ Security review, planning, incident response, risk assessment, vulnerability ana | **security/sssc-gap-analysis** | Phase 4 gap comparison, adoption categorization, and effort sizing for SSSC Planner. | | **security/sssc-handoff** | Phase 6 backlog handoff protocol with Scorecard projections and dual-format output for SSSC Planner. | | **security/sssc-identity** | Identity and orchestration instructions for the SSSC Planner agent. Contains six-phase workflow, state.json schema, session recovery, and question cadence. | -| **security/sssc-standards** | Phase 3 OpenSSF Scorecard, SLSA, Best Practices Badge, Sigstore, and SBOM standards mapping for SSSC Planner. | +| **security/sssc-standards** | Phase 3 OpenSSF Scorecard, SLSA v1.0, OpenSSF Best Practices Badge, Sigstore (cosign), and NTIA SBOM minimum elements standards mapping for SSSC Planner. | | **security/standards-mapping** | Embedded OWASP and NIST security standards with researcher subagent delegation for CIS, WAF, CAF, and other runtime lookups | | **shared/coaching-patterns** | Shared exploration-first coaching patterns for planning agents (RAI, security, SSSC) adapted from Design Thinking research methods | | **shared/disclaimer-language** | Centralized disclaimer language for AI-assisted planning agents requiring professional review acknowledgment | From f0d7f60ffc313ad28fe2d103e2773bac9b8fcc43 Mon Sep 17 00:00:00 2001 From: Bill Berry Date: Wed, 27 May 2026 16:13:47 -0700 Subject: [PATCH 17/21] fix(instructions, prompts): collapse duplicate disclaimer protocol and activation lines MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - remove redundant Disclaimer and Attribution Protocol H2 in sssc-identity - drop duplicate disclaimerShownAt key in state.json schema example - collapse two-line Activate sentence in sssc-from-* prompts 🔒 - Generated by Copilot --- .../security/sssc-identity.instructions.md | 23 +++++-------------- .../prompts/security/sssc-from-brd.prompt.md | 4 +--- .../prompts/security/sssc-from-prd.prompt.md | 4 +--- .../sssc-from-security-plan.prompt.md | 4 +--- 4 files changed, 9 insertions(+), 26 deletions(-) diff --git a/.github/instructions/security/sssc-identity.instructions.md b/.github/instructions/security/sssc-identity.instructions.md index f40abe195..e0a669ba9 100644 --- a/.github/instructions/security/sssc-identity.instructions.md +++ b/.github/instructions/security/sssc-identity.instructions.md @@ -21,22 +21,6 @@ Voice: clear, methodical, supply-chain-security-focused, and curious. Communicat Posture: exploratory by default. Lean into open-ended clarifying questions before naming controls, frameworks, or capabilities; let the user's words surface concrete pipelines, dependencies, and release surfaces before introducing Scorecard, SLSA, or Sigstore vocabulary. -## Disclaimer and Attribution Protocol - -### Session Start Display - -At the start of every SSSC Planning session, display the SSSC Planning disclaimer from `.github/instructions/shared/disclaimer-language.instructions.md` verbatim before collecting project details, asking scoping questions, or generating artifacts. - -If `disclaimerShownAt` is `null`, display the disclaimer and set `disclaimerShownAt` to the current ISO 8601 timestamp before writing `state.json`. If `disclaimerShownAt` already contains a timestamp, do not repeat the full disclaimer during normal continuation unless the user asks to see it again. - -### Standards Attribution - -When introducing standards mappings, assessments, gap analyses, or handoff materials, attribute the underlying supply chain security references clearly. SSSC Planning guidance may reference OpenSSF Scorecard, SLSA Build Levels, OpenSSF Best Practices Badge, Sigstore, CycloneDX, and SPDX. Treat generated mappings and recommendations as planning support that requires independent review by qualified security and compliance reviewers. - -### Exit Point Reminder - -Before final handoff or backlog export, remind the user that SSSC outputs are assistive planning artifacts. They do not constitute security approval, compliance certification, regulatory sign-off, or professional legal advice. - ## Six-Phase Definitions Each phase has entry criteria, activities, exit criteria, artifacts produced, and a defined transition. @@ -136,7 +120,6 @@ State persists across sessions in a JSON file at `.copilot-tracking/sssc-plans/{ "ssscPlanFile": "", "currentPhase": 1, "entryMode": "capture", - "disclaimerShownAt": null, "phaseGates": { "phase1": { "gate": "hard", "confirmedAt": null }, "phase2": { "gate": "summary-and-advance" }, @@ -226,6 +209,12 @@ Phase advancement updates `currentPhase` and sets phase-specific completion flag On the first turn of any SSSC Planner session, display the canonical disclaimer block defined in `shared/disclaimer-language.instructions.md` (SSSC Planning section) 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. +If `state.disclaimerShownAt` already contains a timestamp on session resume, do not repeat the full disclaimer during normal continuation unless the user asks to see it again. + +### Standards Attribution + +When introducing standards mappings, assessments, gap analyses, or handoff materials, attribute the underlying supply chain security references clearly. SSSC Planning guidance may reference OpenSSF Scorecard, SLSA Build Levels, OpenSSF Best Practices Badge, Sigstore, CycloneDX, and SPDX. Treat generated mappings and recommendations as planning support that requires independent review by qualified security and compliance reviewers. + ### Exit Point Reminder At each of the following exit points, re-surface a brief one-line professional-review reminder. Use the canonical wording in `shared/disclaimer-language.instructions.md` (SSSC Planning section) for the reminder text. diff --git a/.github/prompts/security/sssc-from-brd.prompt.md b/.github/prompts/security/sssc-from-brd.prompt.md index fe5ea8e78..115ce40cd 100644 --- a/.github/prompts/security/sssc-from-brd.prompt.md +++ b/.github/prompts/security/sssc-from-brd.prompt.md @@ -13,9 +13,7 @@ Display the SSSC Planning CAUTION block from #file:../../instructions/shared/dis After the disclaimer, display the framework attribution `OpenSSF Scorecard • SLSA Build Levels • OpenSSF Best Practices Badge • Sigstore • SBOM`. Display both the disclaimer and the attribution before any questions or analysis. -Activate the SSSC Planner in **from-brd mode** to bootstrap a supply chain security assessment from existing business requirements documents. - -Activate the SSSC Planner in **from-brd mode** for project slug `${input:project-slug}`. +Activate the SSSC Planner in **from-brd mode** for project slug `${input:project-slug}` to bootstrap a supply chain security assessment from existing business requirements documents. ## Inputs diff --git a/.github/prompts/security/sssc-from-prd.prompt.md b/.github/prompts/security/sssc-from-prd.prompt.md index 64c94044f..cdbb89d8f 100644 --- a/.github/prompts/security/sssc-from-prd.prompt.md +++ b/.github/prompts/security/sssc-from-prd.prompt.md @@ -13,9 +13,7 @@ Display the SSSC Planning CAUTION block from #file:../../instructions/shared/dis After the disclaimer, display the framework attribution `OpenSSF Scorecard • SLSA Build Levels • OpenSSF Best Practices Badge • Sigstore • SBOM`. Display both the disclaimer and the attribution before any questions or analysis. -Activate the SSSC Planner in **from-prd mode** to bootstrap a supply chain security assessment from existing product definition artifacts. - -Activate the SSSC Planner in **from-prd mode** for project slug `${input:project-slug}`. +Activate the SSSC Planner in **from-prd mode** for project slug `${input:project-slug}` to bootstrap a supply chain security assessment from existing product definition artifacts. ## Inputs diff --git a/.github/prompts/security/sssc-from-security-plan.prompt.md b/.github/prompts/security/sssc-from-security-plan.prompt.md index 7b2c43922..ef0b235e6 100644 --- a/.github/prompts/security/sssc-from-security-plan.prompt.md +++ b/.github/prompts/security/sssc-from-security-plan.prompt.md @@ -13,9 +13,7 @@ Display the SSSC Planning CAUTION block from #file:../../instructions/shared/dis After the disclaimer, display the framework attribution `OpenSSF Scorecard • SLSA Build Levels • OpenSSF Best Practices Badge • Sigstore • SBOM`. Display both the disclaimer and the attribution before any questions or analysis. -Activate the SSSC Planner in **from-security-plan mode** to extend an existing Security Planner assessment with supply chain security coverage. - -Activate the SSSC Planner in **from-security-plan mode** for project slug `${input:project-slug}`. +Activate the SSSC Planner in **from-security-plan mode** for project slug `${input:project-slug}` to extend an existing Security Planner assessment with supply chain security coverage. ## Inputs From 9702416327dbebe186d194c6f51974efa2966fa5 Mon Sep 17 00:00:00 2001 From: Bill Berry Date: Wed, 27 May 2026 16:31:45 -0700 Subject: [PATCH 18/21] fix(scripts): document projectSlug semantics under -SessionPath MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - clarify projectSlug field is populated from session directory leaf - note retention for back-compat with RAI manifest consumers - direct callers needing canonical slug to use sessionPath instead 🔒 - Generated by Copilot --- scripts/security/Sign-PlannerArtifacts.ps1 | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/scripts/security/Sign-PlannerArtifacts.ps1 b/scripts/security/Sign-PlannerArtifacts.ps1 index 985bd3e38..d7ac668c3 100644 --- a/scripts/security/Sign-PlannerArtifacts.ps1 +++ b/scripts/security/Sign-PlannerArtifacts.ps1 @@ -61,6 +61,11 @@ .NOTES The manifest excludes its own file and any cosign signature files (.sig, .bundle) from the hash inventory to avoid circular references. + + Under the BySessionPath parameter set, the manifest's projectSlug field is populated from + the session directory leaf rather than a canonical project slug. The field name is retained + for back-compatibility with existing RAI manifest consumers; callers that distinguish + between project slug and session label should rely on sessionPath instead. #> [CmdletBinding(DefaultParameterSetName = 'ByProjectSlug')] From 0c60168fbc23dc15435d2cd6ed1a518284f5ce00 Mon Sep 17 00:00:00 2001 From: Bill Berry Date: Wed, 27 May 2026 16:49:39 -0700 Subject: [PATCH 19/21] feat(scripts, instructions): close phaseGates parity gap between sssc-state and rai-state MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - add $defs.hardGate and $defs.summaryGate to both state schemas - require phaseGates with phase1-phase6 mappings in both schemas - mirror phaseGates template in rai-identity state schema example - SSSC: phases 1/4/6 hard, 2/3/5 summary; RAI: 2/3/6 hard, 1/4/5 summary 🔒 - Generated by Copilot --- .../rai-planning/rai-identity.instructions.md | 8 ++++ scripts/linting/schemas/rai-state.schema.json | 40 ++++++++++++++++++- .../linting/schemas/sssc-state.schema.json | 40 ++++++++++++++++++- 3 files changed, 86 insertions(+), 2 deletions(-) diff --git a/.github/instructions/rai-planning/rai-identity.instructions.md b/.github/instructions/rai-planning/rai-identity.instructions.md index 29ea412ac..9626d93b6 100644 --- a/.github/instructions/rai-planning/rai-identity.instructions.md +++ b/.github/instructions/rai-planning/rai-identity.instructions.md @@ -102,6 +102,14 @@ The formal JSON Schema definition is at `scripts/linting/schemas/rai-state.schem "impactAssessmentGenerated": false, "evidenceRegisterComplete": false, "handoffGenerated": { "ado": false, "github": false }, + "phaseGates": { + "phase1": { "gate": "summary-and-advance" }, + "phase2": { "gate": "hard", "confirmedAt": null }, + "phase3": { "gate": "hard", "confirmedAt": null }, + "phase4": { "gate": "summary-and-advance" }, + "phase5": { "gate": "summary-and-advance" }, + "phase6": { "gate": "hard", "confirmedAt": null } + }, "gateResults": { "prohibitedUsesGate": { "status": "pending", diff --git a/scripts/linting/schemas/rai-state.schema.json b/scripts/linting/schemas/rai-state.schema.json index 5212a66e2..ae6a60505 100644 --- a/scripts/linting/schemas/rai-state.schema.json +++ b/scripts/linting/schemas/rai-state.schema.json @@ -25,7 +25,8 @@ "signingRequested", "signingManifestPath", "disclaimerShownAt", - "userPreferences" + "userPreferences", + "phaseGates" ], "properties": { "projectSlug": { @@ -168,10 +169,47 @@ }, "userPreferences": { "$ref": "#/$defs/userPreferences" + }, + "phaseGates": { + "type": "object", + "required": ["phase1", "phase2", "phase3", "phase4", "phase5", "phase6"], + "properties": { + "phase1": { "$ref": "#/$defs/summaryGate" }, + "phase2": { "$ref": "#/$defs/hardGate" }, + "phase3": { "$ref": "#/$defs/hardGate" }, + "phase4": { "$ref": "#/$defs/summaryGate" }, + "phase5": { "$ref": "#/$defs/summaryGate" }, + "phase6": { "$ref": "#/$defs/hardGate" } + }, + "additionalProperties": false, + "description": "Per-phase gate model: phases 2, 3, and 6 are hard gates requiring explicit user confirmation; phases 1, 4, and 5 are summary-and-advance gates" } }, "additionalProperties": false, "$defs": { + "hardGate": { + "type": "object", + "required": ["gate", "confirmedAt"], + "properties": { + "gate": { "const": "hard" }, + "confirmedAt": { + "type": ["string", "null"], + "format": "date-time", + "description": "ISO 8601 timestamp when the user confirmed the gate, or null before confirmation" + } + }, + "additionalProperties": false, + "description": "Hard gate requiring explicit user confirmation before advancing" + }, + "summaryGate": { + "type": "object", + "required": ["gate"], + "properties": { + "gate": { "const": "summary-and-advance" } + }, + "additionalProperties": false, + "description": "Summary-and-advance gate that presents a summary and continues unless the user objects" + }, "prohibitedUsesGate": { "type": "object", "required": ["status"], diff --git a/scripts/linting/schemas/sssc-state.schema.json b/scripts/linting/schemas/sssc-state.schema.json index 768ea34d2..a6a7ae129 100644 --- a/scripts/linting/schemas/sssc-state.schema.json +++ b/scripts/linting/schemas/sssc-state.schema.json @@ -22,7 +22,8 @@ "ssscEnabled", "signingRequested", "signingManifestPath", - "disclaimerShownAt" + "disclaimerShownAt", + "phaseGates" ], "properties": { "projectSlug": { @@ -159,10 +160,47 @@ "signingManifestPath": { "type": ["string", "null"], "description": "Path to the signing manifest file (sssc-manifest.json), or null if signing not requested" + }, + "phaseGates": { + "type": "object", + "required": ["phase1", "phase2", "phase3", "phase4", "phase5", "phase6"], + "properties": { + "phase1": { "$ref": "#/$defs/hardGate" }, + "phase2": { "$ref": "#/$defs/summaryGate" }, + "phase3": { "$ref": "#/$defs/summaryGate" }, + "phase4": { "$ref": "#/$defs/hardGate" }, + "phase5": { "$ref": "#/$defs/summaryGate" }, + "phase6": { "$ref": "#/$defs/hardGate" } + }, + "additionalProperties": false, + "description": "Per-phase gate model: phases 1, 4, and 6 are hard gates requiring explicit user confirmation; phases 2, 3, and 5 are summary-and-advance gates" } }, "additionalProperties": false, "$defs": { + "hardGate": { + "type": "object", + "required": ["gate", "confirmedAt"], + "properties": { + "gate": { "const": "hard" }, + "confirmedAt": { + "type": ["string", "null"], + "format": "date-time", + "description": "ISO 8601 timestamp when the user confirmed the gate, or null before confirmation" + } + }, + "additionalProperties": false, + "description": "Hard gate requiring explicit user confirmation before advancing" + }, + "summaryGate": { + "type": "object", + "required": ["gate"], + "properties": { + "gate": { "const": "summary-and-advance" } + }, + "additionalProperties": false, + "description": "Summary-and-advance gate that presents a summary and continues unless the user objects" + }, "referenceEntry": { "type": "object", "required": ["filePath", "type", "sourceDescription", "processedInPhase", "status"], From b159f43c3474bdbd14e8b535657da6e620808600 Mon Sep 17 00:00:00 2001 From: Bill Berry Date: Thu, 28 May 2026 21:13:15 -0700 Subject: [PATCH 20/21] fix(agents): align SSSC planner inline state schema with canonical source MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - add phaseGates block and reorder signing fields in inline state.json to match sssc-identity schema - extend Test-SsscContextPreservation to guard both identity and agent files - assert JSON validity, phaseGates, userPreferences, and handoffGenerated - resolves RI-1 and RI-3 from PR #1497 review 🔒 - Generated by Copilot --- .github/agents/security/sssc-planner.agent.md | 14 +++- .../Test-SsscContextPreservation.Tests.ps1 | 69 +++++++++++++++---- 2 files changed, 68 insertions(+), 15 deletions(-) diff --git a/.github/agents/security/sssc-planner.agent.md b/.github/agents/security/sssc-planner.agent.md index 967c9caca..ae5cbe31b 100644 --- a/.github/agents/security/sssc-planner.agent.md +++ b/.github/agents/security/sssc-planner.agent.md @@ -145,6 +145,14 @@ State JSON schema for `state.json`: "ssscPlanFile": "", "currentPhase": 1, "entryMode": "capture", + "phaseGates": { + "phase1": { "gate": "hard", "confirmedAt": null }, + "phase2": { "gate": "summary-and-advance" }, + "phase3": { "gate": "summary-and-advance" }, + "phase4": { "gate": "hard", "confirmedAt": null }, + "phase5": { "gate": "summary-and-advance" }, + "phase6": { "gate": "hard", "confirmedAt": null } + }, "scopingComplete": false, "assessmentComplete": false, "standardsMapped": false, @@ -160,9 +168,6 @@ State JSON schema for `state.json`: }, "referencesProcessed": [], "nextActions": [], - "signingRequested": false, - "signingManifestPath": null, - "disclaimerShownAt": null, "userPreferences": { "autonomyTier": "partial", "outputDetailLevel": "standard", @@ -175,6 +180,9 @@ State JSON schema for `state.json`: } }, "ssscEnabled": true, + "signingRequested": false, + "signingManifestPath": null, + "disclaimerShownAt": null, "securityPlannerLink": null, "raiPlannerLink": null } diff --git a/scripts/tests/linting/Test-SsscContextPreservation.Tests.ps1 b/scripts/tests/linting/Test-SsscContextPreservation.Tests.ps1 index 187783c1d..3c7df06b9 100644 --- a/scripts/tests/linting/Test-SsscContextPreservation.Tests.ps1 +++ b/scripts/tests/linting/Test-SsscContextPreservation.Tests.ps1 @@ -3,26 +3,71 @@ # SPDX-License-Identifier: MIT <# .SYNOPSIS - Asserts the SSSC inline state schema preserves exactly the five canonical - `context` sub-object keys. + Asserts the SSSC inline state schema stays consistent across the canonical + identity instructions and the agent definition that copies it. +.DESCRIPTION + The canonical SSSC `state.json` schema lives in sssc-identity.instructions.md + and is duplicated inline in sssc-planner.agent.md. This test guards both + copies against drift by validating that each inline block parses as JSON and + preserves the canonical `context` keys, `phaseGates`, `userPreferences`, and + `handoffGenerated` structures. #> -BeforeAll { - $script:repoRoot = (Resolve-Path (Join-Path $PSScriptRoot '../../..')).Path - $script:ssscIdentity = Join-Path $script:repoRoot '.github/instructions/security/sssc-identity.instructions.md' - $script:expectedKeys = @('ciPlatform','complianceTargets','packageManagers','releaseStrategy','techStack') +BeforeDiscovery { + $repoRoot = (Resolve-Path (Join-Path $PSScriptRoot '../../..')).Path + $script:stateSchemaFiles = @( + @{ Name = 'sssc-identity.instructions.md'; Path = (Join-Path $repoRoot '.github/instructions/security/sssc-identity.instructions.md') } + @{ Name = 'sssc-planner.agent.md'; Path = (Join-Path $repoRoot '.github/agents/security/sssc-planner.agent.md') } + ) } -Describe 'SSSC inline state context preserves five canonical keys' { - It 'context contains exactly the canonical key set' { - $content = Get-Content -Path $script:ssscIdentity -Raw +BeforeAll { + $script:expectedContextKeys = @('ciPlatform','complianceTargets','packageManagers','releaseStrategy','techStack') + $script:expectedPhaseGates = @('phase1','phase2','phase3','phase4','phase5','phase6') + + function Get-InlineStateSchema { + param([string]$Path) + + $content = Get-Content -Path $Path -Raw if ($content -notmatch '(?s)```json\s*\r?\n(\{.*?\})\s*\r?\n```') { - throw "No ```json block found in $script:ssscIdentity" + throw "No ```json block found in $Path" } - $state = $Matches[1] | ConvertFrom-Json + $json = $Matches[1] + $json | Should -Not -BeNullOrEmpty + ($json | Test-Json) | Should -BeTrue -Because "the inline state schema in $Path must be valid JSON" + $json | ConvertFrom-Json + } +} + +Describe 'SSSC inline state schema stays consistent across copies' { + It ' context contains exactly the canonical key set' -TestCases $script:stateSchemaFiles { + param($Name, $Path) + + $state = Get-InlineStateSchema -Path $Path $state.context | Should -Not -BeNullOrEmpty $observed = $state.context.PSObject.Properties.Name | Sort-Object - $expected = $script:expectedKeys | Sort-Object + $expected = $script:expectedContextKeys | Sort-Object ($observed -join ',') | Should -Be ($expected -join ',') -Because "context sub-object must contain exactly: $($expected -join ', ')" } + + It ' defines all canonical phaseGates' -TestCases $script:stateSchemaFiles { + param($Name, $Path) + + $state = Get-InlineStateSchema -Path $Path + $state.phaseGates | Should -Not -BeNullOrEmpty -Because 'the canonical schema declares a phaseGates block' + $observed = $state.phaseGates.PSObject.Properties.Name | Sort-Object + $expected = $script:expectedPhaseGates | Sort-Object + ($observed -join ',') | Should -Be ($expected -join ',') -Because "phaseGates must contain exactly: $($expected -join ', ')" + } + + It ' defines userPreferences and handoffGenerated' -TestCases $script:stateSchemaFiles { + param($Name, $Path) + + $state = Get-InlineStateSchema -Path $Path + $state.userPreferences | Should -Not -BeNullOrEmpty -Because 'the canonical schema declares a userPreferences block' + $state.userPreferences.outputDetailLevel | Should -Not -BeNullOrEmpty + $state.handoffGenerated | Should -Not -BeNullOrEmpty -Because 'the canonical schema declares a handoffGenerated block' + $observed = $state.handoffGenerated.PSObject.Properties.Name | Sort-Object + ($observed -join ',') | Should -Be 'ado,github' -Because 'handoffGenerated tracks both ado and github' + } } From d467b0ab8fa1690955aba06f3a330b7f00677075 Mon Sep 17 00:00:00 2001 From: Bill Berry Date: Thu, 28 May 2026 21:17:04 -0700 Subject: [PATCH 21/21] fix(instructions): align coaching-patterns detail level vocabulary with state schema enum MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - replace summary/comprehensive with minimal/detailed to match the outputDetailLevel enum shared by rai-state and sssc-state schemas - prevents schema validation failure or silent rewrite of user-confirmed preferences - resolves RI-2 from PR #1497 review 🔒 - Generated by Copilot --- .github/instructions/shared/coaching-patterns.instructions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/instructions/shared/coaching-patterns.instructions.md b/.github/instructions/shared/coaching-patterns.instructions.md index b300a5501..036d309dc 100644 --- a/.github/instructions/shared/coaching-patterns.instructions.md +++ b/.github/instructions/shared/coaching-patterns.instructions.md @@ -125,7 +125,7 @@ After initial context capture, ask the user about output preferences: "How would you like the assessment outputs formatted? -* **Detail level**: summary (key points only), standard (balanced), or comprehensive (full analysis with evidence chains)? +* **Detail level**: minimal (key points only), standard (balanced), or detailed (full analysis with evidence chains)? * **Target system**: ADO, GitHub, or both for work item creation? * **Audience**: technical team, executive stakeholders, or mixed audience? * **Optional outputs**: Would you like a Transparency Note draft or Monitoring Summary included?"