diff --git a/.cspell.json b/.cspell.json index e24c76563..3e809a9bb 100644 --- a/.cspell.json +++ b/.cspell.json @@ -82,7 +82,15 @@ "subcat", "vally", "whiteboarding", - "πρᾶξις" + "ˈpræksɪs", + "πρᾶξις", + "agentic", + "sssc", + "SSSC", + "SLSA", + "Sigstore", + "cosign", + "scorecard" ], "reporters": [ "default", 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/agents/security/security-planner.agent.md b/.github/agents/security/security-planner.agent.md index a69cf11d2..d7eb20f34 100644 --- a/.github/agents/security/security-planner.agent.md +++ b/.github/agents/security/security-planner.agent.md @@ -38,32 +38,58 @@ Security planning follows six sequential phases. Each phase collects input throu ### Phase 1: Scoping -Discover project scope, technology stack, deployment targets, data classification, and compliance requirements. 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, deployment targets, data classification, and compliance context. By default, aim for 3–5 questions per turn. + +Open Phase 1 with a curiosity-first invitation before surfacing any topic list, framework menu, or standards vocabulary. Ask the user to describe — in their own words — what the system does, who depends on it, what would be the worst outcome if it failed or was compromised, and what they are most worried about right now. Listen for concrete surfaces (data flows, integrations, user roles, deployment boundaries) and let the user's own language surface those surfaces before introducing technology categories or compliance frameworks. Apply the exploration-first stance defined in `.github/instructions/shared/coaching-patterns.instructions.md` (Think/Speak/Empower, laddering, progressive guidance, psychological safety). After completing the standard scoping questionnaire, assess for AI/ML components. When the system description mentions ML models, LLMs, AI services, embeddings, RAG, agent frameworks, inference endpoints, or training pipelines, follow the AI Component Detection logic defined in `identity.instructions.md` to set RAI state fields (`raiEnabled`, `raiScope`, `raiTier`, `aiComponents`). When AI components are detected, inform the user that a dedicated RAI assessment is recommended after security planning completes. +Human-review exit reminder: a qualified security reviewer confirms the scoping inputs, technology inventory, and AI/ML detection results 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: Bucket Analysis Classify components into seven operational buckets: infrastructure, DevOps/platform-ops, build, messaging, data, web/UI/reporting, and identity/auth. Governance and security (GS) is a cross-cutting overlay applied to all buckets. Map each component to its primary bucket and note cross-cutting concerns. +Human-review exit reminder: a qualified security reviewer confirms the bucket classifications and cross-cutting concerns 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 controls from OWASP Top 10, NIST 800-53, and CIS Benchmarks to each bucket. Delegate WAF and CAF lookups to Researcher Subagent at runtime rather than embedding those standards directly. +Human-review exit reminder: a qualified security reviewer confirms the standards-to-bucket mappings and any deferred lookups 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: Security Model Analysis -Apply STRIDE per bucket. Identify threats using `T-{BUCKET}-{NNN}` format. Build data flow diagrams. Calculate risk using the likelihood-impact matrix: H×H=Critical, H×M or M×H=High, M×M=Medium, L×any=Low. +Apply STRIDE per bucket. Identify threats using `T-{BUCKET}-{NNN}` format. Build data flow diagrams. Rate risk using the named Likelihood-Impact bucket grid in `.github/instructions/security/security-model.instructions.md` (buckets: Critical, High, Medium, Low, Informational). + +Human-review exit reminder: a qualified security reviewer confirms each identified threat, data flow, and risk rating 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 work items for each identified threat and control gap. Use ADO format (`WI-SEC-{NNN}`) or GitHub format (`{{SEC-TEMP-N}}`). Apply three-tier autonomy: Full, Partial (default), or Manual. +Human-review exit reminder: a qualified security reviewer confirms each generated work item, its autonomy tier, 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 Present a summary of all findings, validate completeness, generate the final security plan artifact, and hand off to the ADO or GitHub backlog. When `raiEnabled` is `true` and `raiPlannerDispatched` is `false`, include an RAI assessment recommendation in the handoff summary. Provide the RAI Planner agent path (`.github/agents/rai-planning/rai-planner.agent.md`) and suggest `from-security-plan` entry mode. Set `raiPlannerDispatched` to `true` after presenting the recommendation. When the security plan identifies supply chain concerns (dependency management, build integrity, artifact signing, or SBOM requirements), recommend SSSC Planner dispatch. Provide the SSSC Planner agent path (`.github/agents/security/sssc-planner.agent.md`) and suggest `from-security-plan` entry mode. +Human-review exit reminder: a qualified security reviewer signs off on the final plan, handoff artifacts, and any RAI or SSSC dispatch recommendations 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 Two entry modes determine how Phase 1 begins. Both converge at Phase 2 once scoping completes. @@ -116,13 +142,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 @@ -133,6 +159,8 @@ Five instruction files provide detailed guidance for each domain. These files ar * `.github/instructions/security/standards-mapping.instructions.md`: Embedded OWASP Top 10 (2025), NIST SP 800-53, and CIS Critical Security Controls v8 standards with Researcher Subagent delegation for Microsoft WAF/CAF runtime lookups. * `.github/instructions/security/security-model.instructions.md`: STRIDE-based security model analysis per bucket with threat tables. * `.github/instructions/security/backlog-handoff.instructions.md`: Dual-format backlog handoff with sanitization and autonomy tiers. +* `.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/security-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/agents/security/sssc-planner.agent.md b/.github/agents/security/sssc-planner.agent.md index ef881d980..967c9caca 100644 --- a/.github/agents/security/sssc-planner.agent.md +++ b/.github/agents/security/sssc-planner.agent.md @@ -30,7 +30,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 @@ -38,40 +40,71 @@ 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. + +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. -Key scoping questions cover: +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`. +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 @@ -127,7 +160,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": { + "sbom": false, + "scorecardProjection": false, + "artifactSigning": false + } + }, "ssscEnabled": true, "securityPlannerLink": null, "raiPlannerLink": null @@ -147,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 @@ -165,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. @@ -193,22 +241,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 @@ -235,7 +285,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..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 @@ -26,3 +28,25 @@ 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" + scope: + - .github/instructions/security/sssc-*.instructions.md + 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/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/instructions/rai-planning/rai-capture-coaching.instructions.md b/.github/instructions/rai-planning/rai-capture-coaching.instructions.md index f2025ac68..3f7986800 100644 --- a/.github/instructions/rai-planning/rai-capture-coaching.instructions.md +++ b/.github/instructions/rai-planning/rai-capture-coaching.instructions.md @@ -5,131 +5,28 @@ applyTo: '**/.copilot-tracking/rai-plans/**' # RAI Capture Mode Coaching -Governs conversational behavior during `capture` entry mode, primarily in Phase 1 (AI System Scoping). These techniques replace checklist-style questioning with exploration-first discovery adapted from Design Thinking research methods. +Governs conversational behavior during the RAI Planner `capture` entry mode, primarily Phase 1 (AI System Scoping). The shared coaching patterns at [.github/instructions/shared/coaching-patterns.instructions.md](../shared/coaching-patterns.instructions.md) define the core Think/Speak/Empower framework, exploration-first questioning, progressive guidance, psychological safety, raw capture principles, early tension surfacing, and output preferences. This file documents the RAI-specific extensions and applications of those patterns. -## Coaching Framework +## Shared Patterns -Apply the Think/Speak/Empower pattern on every turn during capture mode: +Refer to the shared coaching-patterns file for: -* **Think**: Assess what the user has revealed so far. Identify gaps in system understanding, 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?" +* Coaching Framework (Think/Speak/Empower) +* Context Pre-Scan +* Scope Assessment +* Exploration-First Questioning (Opening Questions, Laddering, Critical Incident Anchoring, Projective Techniques) +* Progressive Guidance +* Psychological Safety +* Raw Capture Principles +* Early Tension Surfacing +* Output Preferences -## Context Pre-Scan +Apply all shared patterns by default during capture mode. The RAI-specific guidance below extends or specializes them. -When materials are attached (PRD, security plan, design documents), scan them before asking the first question: +## RAI-Specific Extensions -1. Identify the system name, purpose, and primary users. -2. Note any explicitly stated RAI concerns or risk areas. -3. Detect potential risk 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 name] as [purpose]. I noticed [observations]. Let me start with [first question based on context]." +* **Risk classification context**: Use scan results to detect potential risk classification indicators (depth tier signals) and tailor opening questions accordingly. Tier assignment itself happens in Phase 2. +* **AI-system framing**: Frame the opening prompts around the AI system specifically — surface model type, training data origin, decision automation, and human-in-the-loop placement during natural conversation rather than as a checklist. +* **Tension surfacing target**: Record identified RAI principle tensions in `runningObservations` for tracking through Phases 2–6. +* **Output preferences timing**: In `from-prd` mode, ask preference questions after the PRD pre-scan summary, before Phase 2. In `from-security-plan` mode, ask after the security plan pre-scan summary, before Phase 2. Record responses in `userPreferences` with defaults `{detail: standard, target: github, audience: technical, optional: none}` if the user declines to specify. -## Scope Assessment - -At the start of capture, assess whether the user arrives with a fixed or open view of their AI system: - -* **Fixed view**: The user has a specific, detailed picture of the system and its risks. 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, risks, 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 capture mode with curiosity-driven questions that let the user describe their system naturally: - -* "Walk me through what your AI 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 "What type of AI model does your system use?" 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 risk 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 risk brainstorming. - -### Projective Techniques - -Use when users give guarded or minimal responses about system risks: - -* "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 risk 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: "The credit scoring outputs affect loan applicants who have no visibility into or control over the model." - -Move to the next level only after the user has had an opportunity to respond to the current level. - -## Psychological Safety - -RAI discussions can feel like criticism of existing work. Maintain safety throughout capture: - -* 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 mitigations as inadequate during capture. Capture is for discovery; evaluation happens in later phases. - -## Raw Capture Principles - -During capture mode, 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 and threat classification happen in Phases 2 and 3. Phase 1 captures the system as the user sees it. -* **Redirect solution proposals.** When the user jumps to mitigations ("we should add fairness testing"), acknowledge and note it, then redirect: "Good — we'll map that when we get to controls. For now, tell me more about how the model'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 Phase 1 context gathering, identify and surface potential tensions between RAI principles: - -* "The system's need for [capability] may create tension between [Principle A] and [Principle B]." -* Surface tensions as observations, not judgments. -* Record identified tensions in `runningObservations` for tracking through subsequent phases. -* Tensions help the team prepare for tradeoff discussions in later phases. - -## Output Preferences - -During Phase 1, 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. - -In `from-prd` mode, ask preference questions after the PRD pre-scan summary, before Phase 2. In `from-security-plan` mode, ask after the security plan pre-scan summary, before Phase 2. The preferences inform all subsequent output formatting. diff --git a/.github/instructions/security/backlog-handoff.instructions.md b/.github/instructions/security/backlog-handoff.instructions.md index 7bacc8608..1dc4871a4 100644 --- a/.github/instructions/security/backlog-handoff.instructions.md +++ b/.github/instructions/security/backlog-handoff.instructions.md @@ -18,6 +18,10 @@ Generate formatted work items from security model mitigations and standards gaps ## ADO Work Item Template +> **Note:** This work item was generated by the Security Planner AI agent. Review for accuracy and adjust before assigning to a person. + +- [ ] Reviewed by a human security professional before execution + Assign sequential IDs within the security plan using the format `WI-SEC-{NNN}` (for example, WI-SEC-001, WI-SEC-002). Order work items by type hierarchy: Epic, Feature, User Story, Task, Bug. Required fields per work item: @@ -60,6 +64,10 @@ Five MCP tool categories support ADO operations: work item creation, work item u ## GitHub Issue Template +> **Note:** This work item was generated by the Security Planner AI agent. Review for accuracy and adjust before assigning to a person. + +- [ ] Reviewed by a human security professional before execution + Assign temporary IDs using the format `{{SEC-TEMP-N}}`, replaced with real issue numbers on creation. Order operations by type: create, update, comment, label, close. Required fields per issue: @@ -187,3 +195,5 @@ After generating all work items, produce a summary covering: * Items by risk level. * Items by STRIDE category. * Items that could not be generated, with the reason for each failure. + +> **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/identity.instructions.md b/.github/instructions/security/identity.instructions.md index 505e5c0cd..8e0bbfdc5 100644 --- a/.github/instructions/security/identity.instructions.md +++ b/.github/instructions/security/identity.instructions.md @@ -14,7 +14,9 @@ Core responsibilities: * Produce actionable artifacts at each phase: bucket inventories, standards mappings, STRIDE threat tables, and formatted backlog items * Delegate external documentation lookups (WAF, CAF) to the Researcher Subagent -Voice: clear, methodical, and security-focused. Communicate with professional authority while keeping guidance accessible and actionable. +Voice: clear, methodical, 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 threats; let the user's words surface concrete surfaces, data flows, and risks before introducing standards vocabulary. ## Six-Phase Definitions @@ -110,27 +112,46 @@ State persists across sessions in a JSON file at `.copilot-tracking/security-pla ### State Schema +The canonical starting state is shown below as JSON-literal defaults. Phases 1, 4, and 6 are hard gates that require explicit user confirmation (recorded in `phaseGates.phaseN.confirmedAt`); Phases 2, 3, and 5 are summary-and-advance gates. + ```json { - "projectSlug": "string", - "securityPlanFile": "string (path to plan markdown)", - "currentPhase": "number (1-6)", - "entryMode": "capture | from-prd", - "bucketsCompleted": ["string (bucket names)"], - "standardsMapped": ["string (bucket names that have completed standards mapping)"], - "riskSurfaceStarted": "boolean", - "handoffGenerated": { "ado": "boolean", "github": "boolean" }, - "referencesProcessed": ["string (file paths)"], - "nextActions": ["string"], - "userPreferences": { "autonomyTier": "string (full|partial|manual), default: partial" }, - "raiEnabled": "boolean, default: false", - "raiScope": "string (none|lightweight|full), default: none", - "raiTier": "string (none|basic|standard|comprehensive), default: none", - "raiPlannerDispatched": "boolean, default: false", - "aiComponents": ["string (detected AI component types)"] + "projectSlug": "", + "securityPlanFile": "", + "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 } + }, + "bucketsCompleted": [], + "standardsMapped": [], + "riskSurfaceStarted": false, + "handoffGenerated": { "ado": false, "github": false }, + "context": { + "techStack": [], + "deploymentModel": "", + "dataClassification": "", + "complianceTargets": [] + }, + "referencesProcessed": [], + "nextActions": [], + "userPreferences": { "autonomyTier": "partial" }, + "raiEnabled": false, + "raiScope": "none", + "raiTier": "none", + "raiPlannerDispatched": false, + "aiComponents": [] } ``` +`referencesProcessed` is an object array. Each element captures `{ "filePath": "", "processedInPhase": <1-6 integer>, "sourceDescription": "" }`. Example: `{ "filePath": "docs/architecture/overview.md", "processedInPhase": 1, "sourceDescription": "Architecture overview" }`. + ### Six-Step State Protocol Execute this protocol on every turn: @@ -191,7 +212,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 security plan 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/instructions/security/security-model.instructions.md b/.github/instructions/security/security-model.instructions.md index b6a12c14f..c0179c337 100644 --- a/.github/instructions/security/security-model.instructions.md +++ b/.github/instructions/security/security-model.instructions.md @@ -15,7 +15,7 @@ Apply all six STRIDE categories to each component within a bucket. Evaluate cate Pretending to be something or someone else. -* Guiding question: "Can an attacker impersonate a user, service, or component?" +* User-facing question: "Where do we verify identity claims in this bucket, and what would change if those checks failed or were bypassed?" * Commonly affected buckets: identity/auth, web, messaging * Typical mitigations: strong authentication, certificate validation, mutual TLS, token verification @@ -23,7 +23,7 @@ Pretending to be something or someone else. Modifying data or code without authorization. -* Guiding question: "Can data be modified in transit or at rest?" +* User-facing question: "Which data flows or stored artifacts in this bucket would cause the greatest harm if silently modified, and how would we detect the modification?" * Commonly affected buckets: data, build, devops, messaging * Typical mitigations: integrity checks, digital signatures, access controls, immutable infrastructure @@ -31,7 +31,7 @@ Modifying data or code without authorization. Denying an action occurred without proof to the contrary. -* Guiding question: "Can a user deny performing an action?" +* User-facing question: "Which actions in this bucket need to be irrefutably attributable to a specific user, service, or build step, and what audit evidence do we currently retain?" * Commonly affected buckets: data, messaging, identity/auth * Typical mitigations: audit logging, non-repudiation controls, tamper-proof logs, centralized log aggregation @@ -39,7 +39,7 @@ Denying an action occurred without proof to the contrary. Exposing data to unauthorized parties. -* Guiding question: "Can sensitive data leak to unauthorized parties?" +* User-facing question: "What sensitive data flows through or is stored in this bucket, and which paths could expose it to an unintended audience?" * Commonly affected buckets: data, web, build, infra * Typical mitigations: encryption at rest and in transit, access controls, data classification, secure defaults @@ -47,7 +47,7 @@ Exposing data to unauthorized parties. Making a resource unavailable to legitimate users. -* Guiding question: "Can the system be made unavailable?" +* User-facing question: "Which components in this bucket would cause the most user-visible impact if exhausted, throttled, or crashed, and what limits or fallbacks exist today?" * Commonly affected buckets: infra, web, messaging * Typical mitigations: rate limiting, resource quotas, redundancy, auto-scaling, circuit breakers @@ -55,7 +55,7 @@ Making a resource unavailable to legitimate users. Gaining unauthorized access levels beyond assigned permissions. -* Guiding question: "Can an attacker escalate their permissions?" +* User-facing question: "Where could a low-trust principal in this bucket gain capabilities reserved for a higher-trust role, and what gates that boundary?" * Commonly affected buckets: identity/auth, infra, devops * Typical mitigations: least privilege, RBAC/ABAC, privilege separation, input validation, boundary enforcement @@ -136,12 +136,13 @@ When `raiEnabled` is true, AI-specific threats in existing buckets use `T-{BUCKE ### Risk Matrix -Calculate risk from the combination of Likelihood and Impact: +Derive the risk rating by locating the Likelihood row and the Impact column in the named-bucket grid below. Buckets are `Critical`, `High`, `Medium`, `Low`, and `Informational`; no numeric multiplication is used. -* High x High = **Critical** -* High x Medium or Medium x High = **High** -* Medium x Medium = **Medium** -* Low x any or any x Low = **Low** +| | Impact: Low | Impact: Medium | Impact: High | +|--------------------|---------------|----------------|--------------| +| Likelihood: High | Low | High | Critical | +| Likelihood: Medium | Low | Medium | High | +| Likelihood: Low | Informational | Low | Low | ### Assessment Guidance diff --git a/.github/instructions/security/sssc-assessment.instructions.md b/.github/instructions/security/sssc-assessment.instructions.md index 3646ce1d5..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 @@ -91,6 +97,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..b719d71a8 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 @@ -58,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: @@ -90,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: @@ -127,6 +138,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 @@ -144,9 +158,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 @@ -156,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-gap-analysis.instructions.md b/.github/instructions/security/sssc-gap-analysis.instructions.md index 8a6a48048..376e1c2f8 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..7223f140d 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 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: + +* `-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..f40abe195 100644 --- a/.github/instructions/security/sssc-identity.instructions.md +++ b/.github/instructions/security/sssc-identity.instructions.md @@ -17,7 +17,25 @@ 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 + +### 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 @@ -74,6 +92,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. @@ -102,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, @@ -117,13 +160,30 @@ 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, + "disclaimerShownAt": null, "securityPlannerLink": null, "raiPlannerLink": null } ``` +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: @@ -145,6 +205,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 @@ -157,26 +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 -### Four-Step Resume Sequence +### Five-Step Resume Sequence 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 +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 -### Five-Step Post-Summarization Recovery +### Six-Step 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 +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 @@ -192,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/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/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/.github/prompts/security/security-capture.prompt.md b/.github/prompts/security/security-capture.prompt.md index 25e8d2420..9bf45245d 100644 --- a/.github/prompts/security/security-capture.prompt.md +++ b/.github/prompts/security/security-capture.prompt.md @@ -5,6 +5,12 @@ agent: security-planner # Security Capture +## Startup + +Display the Security 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 `OWASP ASVS • OWASP Top 10 • NIST SSDF`. Display both the disclaimer and the attribution before any questions or analysis. + ## 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. diff --git a/.github/prompts/security/security-plan-from-prd.prompt.md b/.github/prompts/security/security-plan-from-prd.prompt.md index afccc3ec4..bdd8591f4 100644 --- a/.github/prompts/security/security-plan-from-prd.prompt.md +++ b/.github/prompts/security/security-plan-from-prd.prompt.md @@ -5,6 +5,12 @@ agent: security-planner # Security Plan from PRD/BRD +## Startup + +Display the Security 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 `OWASP ASVS • OWASP Top 10 • NIST SSDF`. Display both the disclaimer and the attribution before any questions or analysis. + Activate the Security Planner in **from-prd mode** to bootstrap a security plan from existing product definition artifacts. ## Inputs diff --git a/.github/prompts/security/sssc-capture.prompt.md b/.github/prompts/security/sssc-capture.prompt.md index b840f0b4a..117e7a7bf 100644 --- a/.github/prompts/security/sssc-capture.prompt.md +++ b/.github/prompts/security/sssc-capture.prompt.md @@ -1,20 +1,53 @@ --- -description: "Start a new SSSC assessment via guided conversation using the SSSC Planner agent in capture mode" -agent: sssc-planner +description: >- + Initiate supply chain security planning from existing knowledge using the + SSSC Planner agent in capture mode +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 -* ${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 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 + +### 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) -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..fe5ea8e78 100644 --- a/.github/prompts/security/sssc-from-brd.prompt.md +++ b/.github/prompts/security/sssc-from-brd.prompt.md @@ -1,34 +1,70 @@ --- -description: "Start an SSSC assessment from existing BRD artifacts using the SSSC Planner agent" -agent: sssc-planner +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 +## 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 -* ${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. + +Also scan the shared supporting context sources defined in `sssc-identity.instructions.md`. + +Present pre-scan results as a checklist: -Present all discovery results to the user for confirmation before proceeding. +* ✅ Discovered BRD artifacts and supporting context with file paths and brief descriptions +* ❌ Expected sources that were not found + +If zero BRD artifacts are found, fall back to capture mode and explain the switch. + +### 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: -## Entry Behavior +* ✅ Items confirmed from the BRD +* ❓ Items that need clarification or are missing -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. +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. diff --git a/.github/prompts/security/sssc-from-prd.prompt.md b/.github/prompts/security/sssc-from-prd.prompt.md index 00ab44eed..64c94044f 100644 --- a/.github/prompts/security/sssc-from-prd.prompt.md +++ b/.github/prompts/security/sssc-from-prd.prompt.md @@ -1,34 +1,70 @@ --- -description: "Start an SSSC assessment from existing PRD artifacts using the SSSC Planner agent" -agent: sssc-planner +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 +## 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 -* ${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. + +Also scan the shared supporting context sources defined in `sssc-identity.instructions.md`. + +Present pre-scan results as a checklist: -Present all discovery results to the user for confirmation before proceeding. +* ✅ Discovered PRD artifacts and supporting context with file paths and brief descriptions +* ❌ Expected sources that were not found + +If zero PRD artifacts are found, fall back to capture mode and explain the switch. + +### 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: -## Entry Behavior +* ✅ Items confirmed from the PRD +* ❓ Items that need clarification or are missing -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. +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. diff --git a/.github/prompts/security/sssc-from-security-plan.prompt.md b/.github/prompts/security/sssc-from-security-plan.prompt.md index 6b807a476..7b2c43922 100644 --- a/.github/prompts/security/sssc-from-security-plan.prompt.md +++ b/.github/prompts/security/sssc-from-security-plan.prompt.md @@ -1,33 +1,66 @@ --- -description: "Extend a Security Planner assessment with supply chain coverage using the SSSC Planner agent" -agent: sssc-planner +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 +## 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 -* ${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. -Scan these directories as the primary discovery path: +Also scan the shared supporting context sources defined in `sssc-identity.instructions.md`. -* `.copilot-tracking/security-plans/` for Security Planner artifacts +Present pre-scan results as a checklist: -Look for existing `state.json` files within subdirectories. If multiple security plans exist, present all candidates to the user for selection. +* ✅ Discovered security plans and supporting context with file paths and brief descriptions +* ❌ Expected sources that were not found + +If zero Security Planner artifacts are found, fall back to capture mode and explain the switch. + +### 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: -## Entry Behavior +* ✅ Items confirmed from the Security Planner artifacts +* ❓ Items that need clarification or are missing -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. +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. 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..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 @@ -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..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 @@ -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..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 @@ -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 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: | diff --git a/collections/hve-core-all.collection.md b/collections/hve-core-all.collection.md index dbc9553f5..b6345467e 100644 --- a/collections/hve-core-all.collection.md +++ b/collections/hve-core-all.collection.md @@ -136,10 +136,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 | @@ -250,8 +250,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, 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 | | **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 e8101e894..228f3feab 100644 --- a/collections/project-planning.collection.md +++ b/collections/project-planning.collection.md @@ -41,10 +41,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 @@ -66,8 +66,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, 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 | | **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 c79394f43..4e1d4254e 100644 --- a/collections/security.collection.md +++ b/collections/security.collection.md @@ -38,10 +38,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 @@ -63,8 +63,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, 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 | | **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/docs/agents/sssc-planning/agent-overview.md b/docs/agents/sssc-planning/agent-overview.md index 08c2f7e9e..89ff9814a 100644 --- a/docs/agents/sssc-planning/agent-overview.md +++ b/docs/agents/sssc-planning/agent-overview.md @@ -64,31 +64,34 @@ 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. - -| 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 | -| `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 @@ -102,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/docs/rpi/task-reviewer.md b/docs/rpi/task-reviewer.md index 893e9ec94..f67a52790 100644 --- a/docs/rpi/task-reviewer.md +++ b/docs/rpi/task-reviewer.md @@ -148,11 +148,12 @@ Task Reviewer categorizes findings by impact: ## Common Pitfalls -| Pitfall | Solution | -|---------------------|----------------------------------------------------------| -| No artifacts found | Complete implementation first; verify changes log exists | -| Research not linked | Ensure plan references research document | -| Too many findings | Break implementation into smaller phases | +| Pitfall | Solution | +|------------------------|-----------------------------------------------------------------------------------------------------------------------| +| No artifacts found | Complete implementation first; verify changes log exists | +| Research not linked | Ensure plan references research document | +| Too many findings | Break implementation into smaller phases | +| Pester test counts off | Expand `-ForEach` parametrization arity before flagging suite size; effective case count is not raw `It` block count. | ## Next Steps diff --git a/plugins/hve-core-all/README.md b/plugins/hve-core-all/README.md index 410cc4519..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,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, 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 | | **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 | @@ -421,10 +422,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 @@ -529,8 +530,9 @@ 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 | +| 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 1f0f91ade..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,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, 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 | | **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 | @@ -120,10 +121,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 @@ -143,10 +144,11 @@ 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. | +| 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 0375c5824..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,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, 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 | | **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. | @@ -124,10 +125,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) | @@ -143,7 +144,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. | @@ -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/linting/Format-MarkdownTables.ps1 b/scripts/linting/Format-MarkdownTables.ps1 new file mode 100644 index 000000000..074f576ec --- /dev/null +++ b/scripts/linting/Format-MarkdownTables.ps1 @@ -0,0 +1,131 @@ +#!/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. + + File discovery includes tracked Markdown files only. + +.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' +$script:MarkdownTableFormatterExitCode = 0 + +#region Functions +function Invoke-MarkdownTableFormatter { + [CmdletBinding()] + param( + [Parameter(Mandatory = $false)] + [switch]$Check + ) + + $repoRoot = (Resolve-Path (Join-Path $PSScriptRoot '..' '..')).Path + $emitVerbose = $VerbosePreference -ne 'SilentlyContinue' + $script:MarkdownTableFormatterExitCode = 0 + + Push-Location $repoRoot + try { + $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; + +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 + $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 { + 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..0019b2740 100644 --- a/scripts/linting/schemas/ai-artifact-config.schema.json +++ b/scripts/linting/schemas/ai-artifact-config.schema.json @@ -2,95 +2,56 @@ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://github.com/microsoft/hve-core/schemas/ai-artifact-config.schema.json", "title": "Footer Configuration Schema", - "description": "Validates footer-with-review.yml and disclaimers.yml config files", + "description": "Validates footer-with-review.yml config file", "type": "object", - "definitions": { - "footerConfig": { + "required": ["version", "footers", "artifact-classification"], + "additionalProperties": false, + "properties": { + "version": { + "type": "string", + "pattern": "^\\d+\\.\\d+$" + }, + "footers": { "type": "object", - "required": ["version", "footers", "artifact-classification"], - "additionalProperties": false, - "properties": { - "version": { - "type": "string", - "pattern": "^\\d+\\.\\d+$" - }, - "footers": { - "type": "object", - "minProperties": 1, - "additionalProperties": { - "type": "object", - "required": ["id", "label", "text"], - "additionalProperties": false, - "properties": { - "id": { "type": "string", "minLength": 1 }, - "label": { "type": "string", "minLength": 1 }, - "text": { "type": "string", "minLength": 1 } - } - } - }, - "artifact-classification": { - "type": "object", - "minProperties": 1, - "additionalProperties": { - "type": "object", - "required": ["required-footers", "artifacts"], - "additionalProperties": false, - "properties": { - "scope": { - "type": "array", - "items": { "type": "string", "minLength": 1 }, - "description": "Glob patterns limiting which files this tier applies to" - }, - "required-footers": { - "type": "array", - "items": { "type": "string", "minLength": 1 }, - "minItems": 1 - }, - "artifacts": { - "type": "array", - "items": { "type": "string", "minLength": 1 }, - "minItems": 1 - }, - "requires-disclaimer": { "type": "boolean" }, - "disclaimer-ref": { "type": "string", "minLength": 1 } - } - } + "minProperties": 1, + "additionalProperties": { + "type": "object", + "required": ["id", "label", "text"], + "additionalProperties": false, + "properties": { + "id": { "type": "string", "minLength": 1 }, + "label": { "type": "string", "minLength": 1 }, + "text": { "type": "string", "minLength": 1 } } } }, - "disclaimerConfig": { + "artifact-classification": { "type": "object", - "required": ["version", "disclaimers"], - "additionalProperties": false, - "properties": { - "version": { - "type": "string", - "pattern": "^\\d+\\.\\d+$" - }, - "disclaimers": { - "type": "object", - "minProperties": 1, - "additionalProperties": { - "type": "object", - "required": ["id", "label", "applies-to", "text"], - "additionalProperties": false, - "properties": { - "id": { "type": "string", "minLength": 1 }, - "label": { "type": "string", "minLength": 1 }, - "applies-to": { - "type": "array", - "items": { "type": "string", "minLength": 1 }, - "minItems": 1 - }, - "text": { "type": "string", "minLength": 1 } - } - } + "minProperties": 1, + "additionalProperties": { + "type": "object", + "required": ["required-footers", "artifacts"], + "additionalProperties": false, + "properties": { + "scope": { + "type": "array", + "items": { "type": "string", "minLength": 1 }, + "description": "Glob patterns limiting which files this tier applies to" + }, + "required-footers": { + "type": "array", + "items": { "type": "string", "minLength": 1 }, + "minItems": 1 + }, + "artifacts": { + "type": "array", + "items": { "type": "string", "minLength": 1 }, + "minItems": 1 + }, + "requires-disclaimer": { "type": "boolean" }, + "disclaimer-ref": { "type": "string", "minLength": 1 } } } } - }, - "oneOf": [ - { "$ref": "#/definitions/footerConfig" }, - { "$ref": "#/definitions/disclaimerConfig" } - ] + } } 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/security-state.schema.json b/scripts/linting/schemas/security-state.schema.json new file mode 100644 index 000000000..807271c26 --- /dev/null +++ b/scripts/linting/schemas/security-state.schema.json @@ -0,0 +1,226 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://github.com/microsoft/hve-core/schemas/security-state.schema.json", + "title": "Security Planner State Schema", + "description": "Schema for Security Planner state.json files under .copilot-tracking/security-plans/{project-slug}/", + "type": "object", + "required": [ + "projectSlug", + "securityPlanFile", + "currentPhase", + "entryMode", + "phaseGates", + "bucketsCompleted", + "standardsMapped", + "riskSurfaceStarted", + "handoffGenerated", + "context", + "referencesProcessed", + "nextActions", + "disclaimerShownAt", + "userPreferences", + "raiEnabled", + "raiScope", + "raiTier", + "raiPlannerDispatched", + "aiComponents" + ], + "properties": { + "projectSlug": { + "type": "string", + "minLength": 1, + "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$", + "description": "Kebab-case project identifier used as the directory name" + }, + "securityPlanFile": { + "type": "string", + "description": "Relative path to the security plan markdown file" + }, + "currentPhase": { + "type": "integer", + "minimum": 1, + "maximum": 6, + "description": "Current assessment phase (1-6)" + }, + "entryMode": { + "type": "string", + "enum": ["capture", "from-prd"], + "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" + }, + "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": "Tiered gate status per phase. Phases 1, 4, 6 are hard gates requiring explicit user confirmation; Phases 2, 3, 5 are summary-and-advance gates." + }, + "bucketsCompleted": { + "type": "array", + "items": { "type": "string" }, + "description": "Operational buckets completed during Phase 2" + }, + "standardsMapped": { + "type": "array", + "items": { "type": "string" }, + "description": "Standards mapped during Phase 3 (e.g., OWASP Top 10, NIST SSDF)" + }, + "riskSurfaceStarted": { + "type": "boolean", + "description": "Whether Phase 4 risk surface analysis has begun" + }, + "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", "deploymentModel", "dataClassification", "complianceTargets"], + "properties": { + "techStack": { + "type": "array", + "items": { "type": "string" }, + "description": "Technology stack components" + }, + "deploymentModel": { + "type": "string", + "description": "Deployment model (e.g., cloud-native, on-premises, hybrid)" + }, + "dataClassification": { + "type": "string", + "description": "Highest data classification handled by the system" + }, + "complianceTargets": { + "type": "array", + "items": { "type": "string" }, + "description": "Compliance frameworks the system targets" + } + }, + "additionalProperties": false, + "description": "Security-specific project context discovered during Phase 1" + }, + "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": { + "type": "object", + "required": ["autonomyTier"], + "properties": { + "autonomyTier": { + "type": "string", + "enum": ["guided", "partial", "full"], + "description": "How much autonomy the agent has in proceeding between phases" + } + }, + "additionalProperties": false + }, + "raiEnabled": { + "type": "boolean", + "description": "Whether an RAI assessment is enabled alongside the security plan" + }, + "raiScope": { + "type": "string", + "enum": ["none", "embedded", "delegated"], + "description": "Scope of RAI coverage within or adjacent to this security plan" + }, + "raiTier": { + "type": "string", + "enum": ["none", "basic", "standard", "comprehensive"], + "description": "RAI assessment depth tier when raiEnabled is true" + }, + "raiPlannerDispatched": { + "type": "boolean", + "description": "Whether a dispatch to the RAI Planner has been issued" + }, + "aiComponents": { + "type": "array", + "items": { "type": "string" }, + "description": "AI/ML components identified during scoping" + } + }, + "additionalProperties": false, + "$defs": { + "hardGate": { + "type": "object", + "required": ["gate", "confirmedAt"], + "properties": { + "gate": { + "type": "string", + "const": "hard", + "description": "Hard gate requiring explicit user confirmation before advancing" + }, + "confirmedAt": { + "type": ["string", "null"], + "format": "date-time", + "description": "ISO 8601 timestamp recorded when the user explicitly approves phase advancement, or null until confirmation" + } + }, + "additionalProperties": false + }, + "summaryGate": { + "type": "object", + "required": ["gate"], + "properties": { + "gate": { + "type": "string", + "const": "summary-and-advance", + "description": "Summary-and-advance gate; planner surfaces a brief summary and proceeds unless the user objects" + } + }, + "additionalProperties": false + }, + "referenceEntry": { + "type": "object", + "required": ["filePath", "processedInPhase", "sourceDescription"], + "properties": { + "filePath": { + "type": "string", + "minLength": 1, + "description": "Workspace-relative path to the processed reference file" + }, + "processedInPhase": { + "type": "integer", + "minimum": 1, + "maximum": 6, + "description": "Phase in which the reference was processed" + }, + "sourceDescription": { + "type": "string", + "minLength": 1, + "description": "Short human-readable label describing the reference source" + } + }, + "additionalProperties": false + } + } +} diff --git a/scripts/linting/schemas/sssc-state.schema.json b/scripts/linting/schemas/sssc-state.schema.json new file mode 100644 index 000000000..768ea34d2 --- /dev/null +++ b/scripts/linting/schemas/sssc-state.schema.json @@ -0,0 +1,258 @@ +{ + "$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", + "signingManifestPath", + "disclaimerShownAt" + ], + "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..985bd3e38 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 { @@ -140,9 +177,17 @@ 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 = $ProjectSlug + projectSlug = $sessionLabel + sessionPath = if ($artifactDir.Equals($repoRoot, [System.StringComparison]::OrdinalIgnoreCase)) { + '' + } elseif ($artifactDir.StartsWith($repoRootBoundary, [System.StringComparison]::OrdinalIgnoreCase)) { + ($artifactDir.Substring($repoRootBoundary.Length) -replace '\\','/') + } else { + ($artifactDir -replace '\\','/') + } generatedAt = [DateTime]::UtcNow.ToString("yyyy-MM-ddTHH:mm:ss.fffffffZ") algorithm = 'SHA256' fileCount = $fileEntries.Count diff --git a/scripts/tests/fixtures/security-state/phase-1-minimal.json b/scripts/tests/fixtures/security-state/phase-1-minimal.json new file mode 100644 index 000000000..fed4a6235 --- /dev/null +++ b/scripts/tests/fixtures/security-state/phase-1-minimal.json @@ -0,0 +1,65 @@ +{ + "projectSlug": "example-project", + "securityPlanFile": "security/plan.md", + "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 } + }, + "bucketsCompleted": [], + "standardsMapped": [], + "riskSurfaceStarted": false, + "handoffGenerated": { "ado": false, "github": false }, + "context": { + "techStack": ["dotnet"], + "deploymentModel": "cloud-native", + "dataClassification": "internal", + "complianceTargets": [] + }, + "referencesProcessed": [], + "nextActions": [], + "userPreferences": { "autonomyTier": "guided" }, + "raiEnabled": false, + "raiScope": "none", + "raiTier": "none", + "raiPlannerDispatched": false, + "aiComponents": [] +} +{ + "projectSlug": "example-project", + "securityPlanFile": ".copilot-tracking/security-plans/example-project/security-plan.md", + "currentPhase": 1, + "entryMode": "capture", + "disclaimerShownAt": "2026-05-09T14:32:00Z", + "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 } + }, + "bucketsCompleted": [], + "standardsMapped": [], + "riskSurfaceStarted": false, + "handoffGenerated": { "ado": false, "github": false }, + "context": { + "techStack": [], + "deploymentModel": "", + "dataClassification": "", + "complianceTargets": [] + }, + "referencesProcessed": [], + "nextActions": ["Complete scoping interview"], + "userPreferences": { "autonomyTier": "partial" }, + "raiEnabled": false, + "raiScope": "none", + "raiTier": "none", + "raiPlannerDispatched": false, + "aiComponents": [] +} diff --git a/scripts/tests/fixtures/security-state/phase-4-mid.json b/scripts/tests/fixtures/security-state/phase-4-mid.json new file mode 100644 index 000000000..d0c33a28a --- /dev/null +++ b/scripts/tests/fixtures/security-state/phase-4-mid.json @@ -0,0 +1,76 @@ +{ + "projectSlug": "example-project", + "securityPlanFile": "security/plan.md", + "currentPhase": 4, + "entryMode": "capture", + "phaseGates": { + "phase1": { "gate": "hard", "confirmedAt": "2025-01-01T12:00:00Z" }, + "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 } + }, + "bucketsCompleted": ["networking"], + "standardsMapped": ["OWASP Top 10"], + "riskSurfaceStarted": true, + "handoffGenerated": { "ado": false, "github": false }, + "context": { + "techStack": ["nodejs", "aws"], + "deploymentModel": "cloud-native", + "dataClassification": "confidential", + "complianceTargets": ["NIST"] + }, + "referencesProcessed": [], + "nextActions": ["run-scan"], + "userPreferences": { "autonomyTier": "partial" }, + "raiEnabled": true, + "raiScope": "embedded", + "raiTier": "standard", + "raiPlannerDispatched": true, + "aiComponents": ["recommendation-service"] +} +{ + "projectSlug": "example-project", + "securityPlanFile": ".copilot-tracking/security-plans/example-project/security-plan.md", + "currentPhase": 4, + "entryMode": "from-prd", + "disclaimerShownAt": "2026-05-09T14:32:00Z", + "phaseGates": { + "phase1": { "gate": "hard", "confirmedAt": "2026-05-09T15:10:00Z" }, + "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 } + }, + "bucketsCompleted": ["identity", "data", "compute", "network"], + "standardsMapped": ["owasp-top-10", "nist-ssdf"], + "riskSurfaceStarted": true, + "handoffGenerated": { "ado": false, "github": false }, + "context": { + "techStack": ["node.js", "typescript", "azure-functions", "cosmos-db"], + "deploymentModel": "cloud-native", + "dataClassification": "confidential", + "complianceTargets": ["soc2", "iso-27001"] + }, + "referencesProcessed": [ + { + "filePath": "README.md", + "processedInPhase": 1, + "sourceDescription": "Repository overview" + }, + { + "filePath": "SECURITY.md", + "processedInPhase": 3, + "sourceDescription": "Security policy" + } + ], + "nextActions": ["Confirm Phase 4 hard gate before advancing to Phase 5"], + "userPreferences": { "autonomyTier": "guided" }, + "raiEnabled": true, + "raiScope": "delegated", + "raiTier": "standard", + "raiPlannerDispatched": true, + "aiComponents": ["llm-summarizer"] +} diff --git a/scripts/tests/fixtures/security-state/phase-6-complete.json b/scripts/tests/fixtures/security-state/phase-6-complete.json new file mode 100644 index 000000000..7e6418813 --- /dev/null +++ b/scripts/tests/fixtures/security-state/phase-6-complete.json @@ -0,0 +1,86 @@ +{ + "projectSlug": "example-project", + "securityPlanFile": "security/plan.md", + "currentPhase": 6, + "entryMode": "from-prd", + "phaseGates": { + "phase1": { "gate": "hard", "confirmedAt": "2025-01-01T12:00:00Z" }, + "phase2": { "gate": "summary-and-advance" }, + "phase3": { "gate": "summary-and-advance" }, + "phase4": { "gate": "hard", "confirmedAt": "2025-03-01T09:00:00Z" }, + "phase5": { "gate": "summary-and-advance" }, + "phase6": { "gate": "hard", "confirmedAt": "2025-04-01T10:00:00Z" } + }, + "bucketsCompleted": ["networking", "identity"], + "standardsMapped": ["OWASP Top 10", "NIST SSDF"], + "riskSurfaceStarted": true, + "handoffGenerated": { "ado": true, "github": true }, + "context": { + "techStack": ["python", "azure"], + "deploymentModel": "hybrid", + "dataClassification": "restricted", + "complianceTargets": ["SOC2", "ISO27001"] + }, + "referencesProcessed": [ { "filePath": "docs/architecture.md", "processedInPhase": 2, "sourceDescription": "Architecture" } ], + "nextActions": [], + "userPreferences": { "autonomyTier": "full" }, + "raiEnabled": true, + "raiScope": "delegated", + "raiTier": "comprehensive", + "raiPlannerDispatched": true, + "aiComponents": ["ml-inference", "nlp-indexer"] +} +{ + "projectSlug": "example-project", + "securityPlanFile": ".copilot-tracking/security-plans/example-project/security-plan.md", + "currentPhase": 6, + "entryMode": "from-prd", + "disclaimerShownAt": "2026-05-09T14:32:00Z", + "phaseGates": { + "phase1": { "gate": "hard", "confirmedAt": "2026-05-09T15:10:00Z" }, + "phase2": { "gate": "summary-and-advance" }, + "phase3": { "gate": "summary-and-advance" }, + "phase4": { "gate": "hard", "confirmedAt": "2026-05-09T17:45:00Z" }, + "phase5": { "gate": "summary-and-advance" }, + "phase6": { "gate": "hard", "confirmedAt": "2026-05-09T19:20:00Z" } + }, + "bucketsCompleted": ["identity", "data", "compute", "network", "supply-chain", "observability"], + "standardsMapped": ["owasp-top-10", "owasp-llm", "nist-ssdf", "cis-benchmarks"], + "riskSurfaceStarted": true, + "handoffGenerated": { "ado": true, "github": true }, + "context": { + "techStack": ["node.js", "typescript", "azure-functions", "cosmos-db", "openai"], + "deploymentModel": "cloud-native", + "dataClassification": "confidential", + "complianceTargets": ["soc2", "iso-27001", "hipaa"] + }, + "referencesProcessed": [ + { + "filePath": "README.md", + "processedInPhase": 1, + "sourceDescription": "Repository overview" + }, + { + "filePath": "SECURITY.md", + "processedInPhase": 3, + "sourceDescription": "Security policy" + }, + { + "filePath": "CONTRIBUTING.md", + "processedInPhase": 5, + "sourceDescription": "Contribution guidelines" + }, + { + "filePath": "CODE_OF_CONDUCT.md", + "processedInPhase": 6, + "sourceDescription": "Code of conduct" + } + ], + "nextActions": [], + "userPreferences": { "autonomyTier": "full" }, + "raiEnabled": true, + "raiScope": "delegated", + "raiTier": "comprehensive", + "raiPlannerDispatched": true, + "aiComponents": ["llm-summarizer", "embedding-index", "agentic-orchestrator"] +} diff --git a/scripts/tests/linting/Test-CadenceRule5Ordering.Tests.ps1 b/scripts/tests/linting/Test-CadenceRule5Ordering.Tests.ps1 new file mode 100644 index 000000000..4d142b1ea --- /dev/null +++ b/scripts/tests/linting/Test-CadenceRule5Ordering.Tests.ps1 @@ -0,0 +1,45 @@ +#Requires -Modules Pester +# Copyright (c) Microsoft Corporation. +# SPDX-License-Identifier: MIT +<# +.SYNOPSIS + Asserts Cadence Rule 5 in both planner identity files leads with open-ended + discovery before any mention of option lists. +.NOTES + Effective case count: 2 (1 `It` block × `-ForEach $script:files` arity 2). +#> + +$script:repoRoot = (Resolve-Path (Join-Path $PSScriptRoot '../../..')).Path +$script:files = @( + (Join-Path $script:repoRoot '.github/instructions/security/identity.instructions.md'), + (Join-Path $script:repoRoot '.github/instructions/security/sssc-identity.instructions.md') +) + +Describe 'Cadence Rule 5 enforces discovery-first ordering' { + BeforeAll { + function Get-Rule5Text { + param([string]$Path) + $lines = Get-Content -Path $Path + $inCadence = $false + foreach ($line in $lines) { + if ($line -match '^###\s+Seven Rules\b') { $inCadence = $true; continue } + if ($inCadence -and $line -match '^##\s+') { break } + if ($inCadence -and $line -match '^\s*5\.\s+') { + return ($line -replace '^\s*5\.\s+','').Trim() + } + } + return '' + } + } + + It 'Identity file <_> states discovery before option lists' -ForEach $script:files { + Test-Path $_ | Should -BeTrue + $text = Get-Rule5Text -Path $_ + $text | Should -Not -BeNullOrEmpty -Because "Rule 5 must be present in $_" + $text | Should -Match '(?i)discover' -Because "Rule 5 must mention discovery" + $discoverIdx = $text.ToLower().IndexOf('discover') + $optionIdx = $text.ToLower().IndexOf('option') + $discoverIdx | Should -BeGreaterOrEqual 0 + $optionIdx | Should -BeGreaterThan $discoverIdx -Because "discovery wording must precede option-list wording in Rule 5" + } +} 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..79cb0e64b --- /dev/null +++ b/scripts/tests/linting/Test-Format-MarkdownTables.Tests.ps1 @@ -0,0 +1,322 @@ +#Requires -Modules Pester +# Copyright (c) Microsoft Corporation. +# SPDX-License-Identifier: MIT + +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 + +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() + $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 + ) + + Initialize-FormatterTestRoot + if (-not $script:MainTestRoot) { + throw "Format-MarkdownTables fixture root was not initialized. node_modules path: $script:RealNodeModules" + } + + $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 + } + } + + # 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 + + 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 + } + + Set-Content -Path $targetPath -Value $Content -NoNewline + + 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 + +| Name | Value | +|------|-------| +| a | 1 | +| b | 2 | +'@ + + # Misformatted: cells flush against pipes, uneven widths. + $script:BadTable = @' +# Bad + +|Name|Value| +|---|---| +|a|1| +|bbb|22| +'@ +} + +# 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 + } + + 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 { + $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 + $null = Add-TrackedFixtureFile -FixtureRoot $script:Fixture -RelativePath 'README.md' -Content $script:GoodTable + $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 = Add-TrackedFixtureFile -FixtureRoot $script:Fixture -RelativePath 'README.md' -Content $script:BadTable + } + + 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 + $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)' { + $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 + $null = Add-TrackedFixtureFile -FixtureRoot $script:Fixture -RelativePath 'README.md' -Content $script:GoodTable + $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' + } + } +} diff --git a/scripts/tests/linting/Test-PlannerStartupBlocks.Tests.ps1 b/scripts/tests/linting/Test-PlannerStartupBlocks.Tests.ps1 new file mode 100644 index 000000000..799aca773 --- /dev/null +++ b/scripts/tests/linting/Test-PlannerStartupBlocks.Tests.ps1 @@ -0,0 +1,38 @@ +#Requires -Modules Pester +# Copyright (c) Microsoft Corporation. +# SPDX-License-Identifier: MIT +<# +.SYNOPSIS + Asserts every Security / SSSC entry prompt has a `## Startup` block and the correct + framework attribution string. +.NOTES + Effective case count: 6 (1 `It` block × `-ForEach $script:prompts` arity 6). +#> + +$script:repoRoot = (Resolve-Path (Join-Path $PSScriptRoot '../../..')).Path + +$securityAttribution = 'OWASP ASVS • OWASP Top 10 • NIST SSDF' +$ssscAttribution = 'OpenSSF Scorecard • SLSA Build Levels • OpenSSF Best Practices Badge • Sigstore • SBOM' + +$script:prompts = @( + @{ Name = 'security-capture'; Attribution = $securityAttribution } + @{ Name = 'security-plan-from-prd'; Attribution = $securityAttribution } + @{ Name = 'sssc-capture'; Attribution = $ssscAttribution } + @{ Name = 'sssc-from-brd'; Attribution = $ssscAttribution } + @{ Name = 'sssc-from-prd'; Attribution = $ssscAttribution } + @{ Name = 'sssc-from-security-plan'; Attribution = $ssscAttribution } +) + +Describe 'Planner entry prompts expose Startup block + framework attribution' { + BeforeAll { + $script:repoRoot = (Resolve-Path (Join-Path $PSScriptRoot '../../..')).Path + } + + It 'Prompt contains ## Startup and expected attribution' -ForEach $script:prompts { + $path = Join-Path $script:repoRoot ".github/prompts/security/$Name.prompt.md" + Test-Path $path | Should -BeTrue -Because "$Name.prompt.md must exist" + $content = Get-Content -Path $path -Raw + $content | Should -Match '(?m)^##\s+Startup\s*$' -Because "$Name must have a ## Startup heading" + $content | Should -BeLike "*$Attribution*" -Because "$Name must reference its framework attribution" + } +} diff --git a/scripts/tests/linting/Test-PlannerStateSchema.Tests.ps1 b/scripts/tests/linting/Test-PlannerStateSchema.Tests.ps1 new file mode 100644 index 000000000..151b7b810 --- /dev/null +++ b/scripts/tests/linting/Test-PlannerStateSchema.Tests.ps1 @@ -0,0 +1,61 @@ +#Requires -Modules Pester +# Copyright (c) Microsoft Corporation. +# SPDX-License-Identifier: MIT +<# +.SYNOPSIS + Asserts tiered phase gates, `disclaimerShownAt`, and `referencesProcessed` defaults + in the inline JSON-literal state block of both planner identity files. +.NOTES + Effective case count: 8 (4 `It` blocks × `-ForEach $script:identityFiles` arity 2). +#> + +$script:repoRoot = (Resolve-Path (Join-Path $PSScriptRoot '../../..')).Path + +$script:identityFiles = @( + (Join-Path $script:repoRoot '.github/instructions/security/identity.instructions.md'), + (Join-Path $script:repoRoot '.github/instructions/security/sssc-identity.instructions.md') +) + +Describe 'Inline planner state schema defaults' { + BeforeAll { + function Get-InlineStateJson { + 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 $Path" + } + return $Matches[1] | ConvertFrom-Json + } + } + + It 'Identity <_> defines disclaimerShownAt as null' -ForEach $script:identityFiles { + $state = Get-InlineStateJson -Path $_ + $state.PSObject.Properties.Name | Should -Contain 'disclaimerShownAt' + $state.disclaimerShownAt | Should -BeNullOrEmpty + } + + It 'Identity <_> defines tiered hard gates on phases 1, 4, 6 with confirmedAt null' -ForEach $script:identityFiles { + $state = Get-InlineStateJson -Path $_ + foreach ($phase in 'phase1','phase4','phase6') { + $gate = $state.phaseGates.$phase + $gate | Should -Not -BeNullOrEmpty -Because "$phase must be present in phaseGates" + $gate.gate | Should -Be 'hard' + $gate.confirmedAt | Should -BeNullOrEmpty + } + } + + It 'Identity <_> defines summary-and-advance gates on phases 2, 3, 5' -ForEach $script:identityFiles { + $state = Get-InlineStateJson -Path $_ + foreach ($phase in 'phase2','phase3','phase5') { + $gate = $state.phaseGates.$phase + $gate | Should -Not -BeNullOrEmpty + $gate.gate | Should -Be 'summary-and-advance' + } + } + + It 'Identity <_> defines referencesProcessed as empty array' -ForEach $script:identityFiles { + $state = Get-InlineStateJson -Path $_ + $state.PSObject.Properties.Name | Should -Contain 'referencesProcessed' + @($state.referencesProcessed).Count | Should -Be 0 + } +} diff --git a/scripts/tests/linting/Test-PlannerStateSchemas.Tests.ps1 b/scripts/tests/linting/Test-PlannerStateSchemas.Tests.ps1 new file mode 100644 index 000000000..ab7b1f31b --- /dev/null +++ b/scripts/tests/linting/Test-PlannerStateSchemas.Tests.ps1 @@ -0,0 +1,67 @@ +#Requires -Modules Pester +# Copyright (c) Microsoft Corporation. +# SPDX-License-Identifier: MIT +<# +.SYNOPSIS + Validates `disclaimerShownAt` schema field shape across both inline planner state schemas. +.DESCRIPTION + For each identity file (security/identity, security/sssc-identity), the inline JSON-literal + schema block must declare `disclaimerShownAt` with default `null` and the canonical state + schemas must declare type `["string","null"]`, format `date-time`, and keep the key in + `required` for cross-planner uniformity (see plan DD-06/ID-02). +.NOTES + Effective case count: 4 (2 inline-default + 2 canonical-schema), not parametrized; each + identity / schema pair is asserted in its own `It` block by design. +#> + +BeforeAll { + $script:repoRoot = (Resolve-Path (Join-Path $PSScriptRoot '../../..')).Path + + function Get-InlineStateJson { + 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 $Path" + } + return $Matches[1] | ConvertFrom-Json + } + + $script:secIdentity = Join-Path $script:repoRoot '.github/instructions/security/identity.instructions.md' + $script:ssscIdentity = Join-Path $script:repoRoot '.github/instructions/security/sssc-identity.instructions.md' + $script:secSchema = Join-Path $script:repoRoot 'scripts/linting/schemas/security-state.schema.json' + $script:raiSchema = Join-Path $script:repoRoot 'scripts/linting/schemas/rai-state.schema.json' +} + +Describe 'Planner state inline JSON-literal defaults' { + It 'Security identity inline state includes disclaimerShownAt default null' { + $state = Get-InlineStateJson -Path $script:secIdentity + $state.PSObject.Properties.Name | Should -Contain 'disclaimerShownAt' + $state.disclaimerShownAt | Should -BeNullOrEmpty + } + + It 'SSSC identity inline state includes disclaimerShownAt default null' { + $state = Get-InlineStateJson -Path $script:ssscIdentity + $state.PSObject.Properties.Name | Should -Contain 'disclaimerShownAt' + $state.disclaimerShownAt | Should -BeNullOrEmpty + } +} + +Describe 'Canonical state schemas declare disclaimerShownAt with nullable string + date-time format' { + It 'security-state.schema.json declares disclaimerShownAt correctly' { + $schema = Get-Content -Path $script:secSchema -Raw | ConvertFrom-Json + $prop = $schema.properties.disclaimerShownAt + $prop | Should -Not -BeNullOrEmpty + $prop.type | Should -Be @('string','null') + $prop.format | Should -Be 'date-time' + $schema.required | Should -Contain 'disclaimerShownAt' + } + + It 'rai-state.schema.json declares disclaimerShownAt correctly' { + $schema = Get-Content -Path $script:raiSchema -Raw | ConvertFrom-Json + $prop = $schema.properties.disclaimerShownAt + $prop | Should -Not -BeNullOrEmpty + $prop.type | Should -Be @('string','null') + $prop.format | Should -Be 'date-time' + $schema.required | Should -Contain 'disclaimerShownAt' + } +} diff --git a/scripts/tests/linting/Test-RiskGridGrammar.Tests.ps1 b/scripts/tests/linting/Test-RiskGridGrammar.Tests.ps1 new file mode 100644 index 000000000..530599b84 --- /dev/null +++ b/scripts/tests/linting/Test-RiskGridGrammar.Tests.ps1 @@ -0,0 +1,39 @@ +#Requires -Modules Pester +# Copyright (c) Microsoft Corporation. +# SPDX-License-Identifier: MIT +<# +.SYNOPSIS + Asserts the Security Planner has no risk multiplication notation and the + security-model named-bucket grid markers are present. +.NOTES + Effective case count: 7 (2 multiplication-notation cases via `-ForEach $script:files` + + 5 bucket-name cases via `-ForEach $script:bucketNames`). +#> + +$script:repoRoot = (Resolve-Path (Join-Path $PSScriptRoot '../../..')).Path +$script:files = @( + (Join-Path $script:repoRoot '.github/instructions/security/security-model.instructions.md'), + (Join-Path $script:repoRoot '.github/agents/security/security-planner.agent.md') +) +$script:gridFile = Join-Path $script:repoRoot '.github/instructions/security/security-model.instructions.md' +$script:bucketNames = @('Critical','High','Medium','Low','Informational') + +Describe 'Risk multiplication notation is forbidden' { + It 'File <_> has no Likelihood × Impact / numeric multiplication notation' -ForEach $script:files { + Test-Path $_ | Should -BeTrue -Because "fixture file must exist: $_" + $content = Get-Content -Path $_ -Raw + $content | Should -Not -Match 'Likelihood\s*[\u00d7x\*]\s*Impact' + $content | Should -Not -Match '(?i)risk\s*=\s*likelihood\s*[\u00d7x\*]\s*impact' + } +} + +Describe 'Named-bucket risk grid is present' { + BeforeAll { + $script:gridFile = Join-Path (Resolve-Path (Join-Path $PSScriptRoot '../../..')).Path '.github/instructions/security/security-model.instructions.md' + } + + It 'security-model.instructions.md lists every named bucket: <_>' -ForEach $script:bucketNames { + $content = Get-Content -Path $script:gridFile -Raw + $content | Should -Match "\b$_\b" + } +} diff --git a/scripts/tests/linting/Test-SecurityStateSchema.Tests.ps1 b/scripts/tests/linting/Test-SecurityStateSchema.Tests.ps1 new file mode 100644 index 000000000..396cc3071 --- /dev/null +++ b/scripts/tests/linting/Test-SecurityStateSchema.Tests.ps1 @@ -0,0 +1,47 @@ +#Requires -Modules Pester +# Copyright (c) Microsoft Corporation. +# SPDX-License-Identifier: MIT +<# +.SYNOPSIS + Validates the canonical Security Planner state schema against the fixture corpus + and asserts cross-schema parity for `disclaimerShownAt` against the sister RAI schema. +#> + +BeforeAll { + $script:repoRoot = (Resolve-Path (Join-Path $PSScriptRoot '../../..')).Path + $script:schemaPath = Join-Path $script:repoRoot 'scripts/linting/schemas/security-state.schema.json' + $script:raiSchemaPath = Join-Path $script:repoRoot 'scripts/linting/schemas/rai-state.schema.json' + $script:fixturesDir = Join-Path $script:repoRoot 'scripts/tests/fixtures/security-state' + + $script:schemaJson = Get-Content -Path $script:schemaPath -Raw + $script:fixtureCases = Get-ChildItem -Path $script:fixturesDir -Filter '*.json' -File | ForEach-Object { + @{ Name = $_.Name; Path = $_.FullName } + } +} + +Describe 'Canonical security-state schema validates fixture corpus' { + It 'Schema file parses as JSON' { + { Get-Content -Path $script:schemaPath -Raw | ConvertFrom-Json } | Should -Not -Throw + } + + It 'Fixture validates against security-state schema' -ForEach $script:fixtureCases { + $fixtureJson = Get-Content -Path $Path -Raw + { $fixtureJson | ConvertFrom-Json } | Should -Not -Throw + $result = Test-Json -Json $fixtureJson -Schema $script:schemaJson -ErrorAction SilentlyContinue -ErrorVariable testErrors + if (-not $result) { + $detail = ($testErrors | ForEach-Object { $_.ToString() }) -join "; " + throw "Fixture $Name failed schema validation: $detail" + } + $result | Should -BeTrue + } +} + +Describe 'Cross-schema parity for disclaimerShownAt' { + It 'security-state and rai-state declare byte-identical disclaimerShownAt definitions' { + $sec = Get-Content -Path $script:schemaPath -Raw | ConvertFrom-Json + $rai = Get-Content -Path $script:raiSchemaPath -Raw | ConvertFrom-Json + $secProp = $sec.properties.disclaimerShownAt | ConvertTo-Json -Depth 10 -Compress + $raiProp = $rai.properties.disclaimerShownAt | ConvertTo-Json -Depth 10 -Compress + $secProp | Should -Be $raiProp -Because 'disclaimerShownAt definitions must remain in lockstep across schemas' + } +} 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 '|') + } +} 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 ', ')" + } +} 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..18d6a72d2 100644 --- a/scripts/tests/security/Sign-PlannerArtifacts.Tests.ps1 +++ b/scripts/tests/security/Sign-PlannerArtifacts.Tests.ps1 @@ -212,11 +212,81 @@ 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 } } + 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