microsoft
diff --git a/‎.github/agents/security/security-planner.agent.md‎
Lines changed: 38 additions & 6 deletions b/‎.github/agents/security/security-planner.agent.md‎
Lines changed: 38 additions & 6 deletions
diff --git a/‎.github/agents/security/sssc-planner.agent.md‎
Lines changed: 1 addition & 1 deletion b/‎.github/agents/security/sssc-planner.agent.md‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎.github/instructions/rai-planning/rai-capture-coaching.instructions.md‎
Lines changed: 18 additions & 121 deletions b/‎.github/instructions/rai-planning/rai-capture-coaching.instructions.md‎
Lines changed: 18 additions & 121 deletions
diff --git a/‎.github/instructions/security/backlog-handoff.instructions.md‎
Lines changed: 2 additions & 0 deletions b/‎.github/instructions/security/backlog-handoff.instructions.md‎
Lines changed: 2 additions & 0 deletions
@@ -52,20 +52,26 @@ Map controls from OWASP Top 10, NIST 800-53, and CIS Benchmarks to each bucket.
 
 ### 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. Derive risk ratings from the named-bucket Risk Matrix grid in `security-model.instructions.md` (buckets: `Critical`, `High`, `Medium`, `Low`, `Informational`); no numeric multiplication is used.
 
 ### 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.
 
+Do not advance to Phase 6 until a qualified security reviewer confirms each generated work item, referenced control, and acceptance criteria.
+
 ### 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.
+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 `raiRecommendationShown` 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`), suggest `from-security-plan` entry mode, and point `securityPlanRef` at the Security Planner `state.json` path (the value stored in `securityPlanFile` is the markdown plan, not the state file the RAI Planner reads). Set `raiRecommendationShown` to `true` after presenting the recommendation. Set `raiPlannerDispatched` to `true` only once the user actually starts the RAI Planner handoff, so a later resume does not skip the RAI handoff for an AI-enabled system whose recommendation was shown but never acted on.
 
 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.
 
 If the security plan introduced architectural mitigations, trust-boundary changes, or control-placement decisions worth preserving, you may want to capture them as ADRs. The `@adr-creation` agent (`from-planner-handoff` entry mode) accepts a Security Planner handoff directly.
 
+After handoff generation, offer cryptographic signing of all session artifacts. When the user accepts, invoke `npm run security:sign -- -SessionPath '.copilot-tracking/security-plans/{project-slug}' -ManifestName 'security-manifest.json'` via `execute/runInTerminal` to generate a SHA-256 manifest and optionally sign with cosign. Set `signingRequested` to `true` and record the manifest location in `signingManifestPath`.
+
+The security plan is not final until a qualified security reviewer signs off on the assessment, the generated work items, and their acceptance criteria before backlog creation.
+
 ## Entry Modes
 
 Two entry modes determine how Phase 1 begins. Both converge at Phase 2 once scoping completes.
@@ -90,16 +96,42 @@ State JSON schema for `state.json`:
   "securityPlanFile": "string (path to plan markdown)",
   "currentPhase": "number (1-6)",
   "entryMode": "from-prd | capture",
+  "phaseGates": {
+    "phase1": { "gate": "hard", "confirmedAt": "string (ISO 8601) | null" },
+    "phase2": { "gate": "summary-and-advance" },
+    "phase3": { "gate": "summary-and-advance" },
+    "phase4": { "gate": "hard", "confirmedAt": "string (ISO 8601) | null" },
+    "phase5": { "gate": "summary-and-advance" },
+    "phase6": { "gate": "hard", "confirmedAt": "string (ISO 8601) | null" }
+  },
   "bucketsCompleted": ["string (bucket names)"],
   "standardsMapped": "string[] (bucket names that have completed standards mapping)",
   "riskSurfaceStarted": "boolean",
   "handoffGenerated": { "ado": "boolean", "github": "boolean" },
-  "referencesProcessed": ["string (file paths)"],
+  "context": {
+    "techStack": ["string"],
+    "deploymentModel": "string (e.g., cloud-native, on-premises, hybrid)",
+    "dataClassification": "string (highest data classification handled)",
+    "complianceTargets": ["string (compliance frameworks targeted)"]
+  },
+  "referencesProcessed": [
+    {
+      "filePath": "string (workspace-relative path)",
+      "type": "standard | security-plan | prd | brd | output-format",
+      "processedInPhase": "number (1-6) | null",
+      "sourceDescription": "string",
+      "status": "pending | processed | error"
+    }
+  ],
   "nextActions": ["string"],
-  "userPreferences": { "autonomyTier": "string (full|partial|manual), default: partial" },
+  "disclaimerShownAt": "string (ISO 8601) | null",
+  "signingRequested": "boolean, default: false",
+  "signingManifestPath": "string (path to signing manifest) | null",
+  "userPreferences": { "autonomyTier": "guided | partial | full, default: partial", "includeOptionalArtifacts": { "artifactSigning": "boolean, default: false" } },
   "raiEnabled": "boolean, default: false",
-  "raiScope": "string (none|lightweight|full), default: none",
-  "raiTier": "string (none|basic|standard|comprehensive), default: none",
+  "raiScope": "none | embedded | delegated, default: none",
+  "raiTier": "none | basic | standard | comprehensive, default: none",
+  "raiRecommendationShown": "boolean, default: false",
   "raiPlannerDispatched": "boolean, default: false",
   "aiComponents": ["string (detected AI component types)"]
 }
 
@@ -100,7 +100,7 @@ Gate: summary-and-advance — surface a brief phase summary and proceed unless t
 
 ### Phase 6: Review and Handoff
 
-Validate completeness, generate Scorecard improvement projections and SLSA level assessments, and hand off to backlog managers. Follow the handoff protocol in `sssc-handoff.instructions.md`. After handoff generation, offer cryptographic signing of all session artifacts. When the user accepts, invoke `scripts/security/Sign-PlannerArtifacts.ps1` via `execute/runInTerminal` with `-SessionPath '.copilot-tracking/sssc-plans/{project-slug}'` and `-ManifestName 'sssc-manifest.json'` to generate a SHA-256 manifest and optionally sign with cosign.
+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 `npm run sssc:sign -- -SessionPath '.copilot-tracking/sssc-plans/{project-slug}' -ManifestName 'sssc-manifest.json'` via `execute/runInTerminal` 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.
 
 
@@ -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` using the schema field names, defaulting to `{outputDetailLevel: standard, targetSystem: github, audienceProfile: technical, includeOptionalArtifacts: {transparencyNote: false, monitoringSummary: false, artifactSigning: false}}` 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.
@@ -195,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.