@shiftleftpt/sbd-toe-mcp 0.6.3 → 0.7.2

package/assets/agent-guide.md

@@ -49,32 +49,116 @@ Use when the user asks *what the manual says*, what applies, how to classify a p
 what controls or artefacts are required, or whether something is aligned with the manual.
 
 ```
-search_sbd_toe_manual       ← conceptual questions, narrative context
-map_sbd_toe_applicability   ← which chapters/controls apply to this project
-get_sbd_toe_chapter_brief   ← what a specific chapter covers (phases, artefacts, topics)
-list_sbd_toe_chapters       ← chapter discovery and navigation
-query_sbd_toe_entities      ← specific controls (CTRL-*), artefacts (ART-*), practices
+search_sbd_toe_manual            ← conceptual questions, narrative context
+map_sbd_toe_applicability        ← which chapters/controls apply to this project
+get_sbd_toe_chapter_brief        ← what a specific chapter covers (phases, artefacts, topics)
+list_sbd_toe_chapters            ← chapter discovery and navigation
+query_sbd_toe_entities           ← specific controls (CTRL-*), artefacts (ART-*), practices
+
+consult_security_requirements    ← deterministic: requirements + controls for a risk level
+                                    params: risk_level (L1|L2|L3), concerns? (string[])
+                                    returns: requirements[], controls[], active_domains[],
+                                             active_categories[], rule_trace[]
+
+resolve_entities                 ← low-level ontology filter engine
+                                    params: record_type, filters? (dot-notation), limit?
+                                    use for: enumerating roles, finding controls by domain,
+                                    listing requirements by category, exploring the ontology
 ```
 
+**Prefer `consult_security_requirements` over `search_sbd_toe_manual`** when the question
+is structured ("what requirements apply at L2?", "which controls are active for auth?").
+Use `search_sbd_toe_manual` for narrative/conceptual questions.
+
+#### Valid `concerns` values (ontology-controlled vocabulary)
+
+| concern | Categories resolved | Meaning |
+|---|---|---|
+| `auth` | AUT, ACC, SES | Authentication, access control, sessions |
+| `logging` | LOG | Audit logging, monitoring |
+| `validation` | VAL, ERR | Input validation, error handling |
+| `api` | API | API security |
+| `config` | CFG | Configuration & environment hardening |
+| `integrity` | INT | Integrity & integration |
+| `distribution` | DST | Supply chain, packaging |
+| `ide` | IDE | Development environment |
+| `requirements` | REQ | Security requirements in SDLC |
+| `architecture` | ARC | Secure architecture |
+| `iac` | IAC | Infrastructure-as-Code |
+| `encryption` | ENC | Cryptography & sensitive data |
+
+Pass concerns as exact lowercase strings from the table above.
+
 ### GUIDE mode
 Use when the user asks *how to implement, design, structure, document, or review* something
 according to the manual.
 
 ```
 1. Obtain applicable guidance first (CONSULT mode)
-2. Then apply it to generate, structure, or review the artefact
+2. Then apply that guidance to generate, structure, or review the artefact
 
-generate_document            ← structured document skeleton for a type + risk level
-plan_sbd_toe_repo_governance ← governance plan for a repository
+plan_sbd_toe_repo_governance ← list artefacts the manual identifies, grouped by chapter
 map_sbd_toe_review_scope     ← which SbD-ToE bundles to review given changed files
+
+get_guide_by_role            ← deterministic: practice assignments + user stories
+                                params: risk_level (L1|L2|L3), role? (string), phase? (string)
+                                returns: assignments[], by_role{}, by_phase{}, user stories joined
+                                use for: "what should a developer do at L2?",
+                                         "what practices apply in the design phase?"
+
+get_threat_landscape         ← deterministic: threats relevant to a risk level / concern set
+                                params: risk_level (L1|L2|L3), concerns? (string[])
+                                returns: threats[] with mitigation_confidence + mitigated_by[]
+                                NOTE: runs consult internally — do NOT call consult first
+                                use for: threat modelling context, "what threats apply to auth?"
 ```
 
+#### Valid `role` values for `get_guide_by_role`
+
+Canonical role IDs (pass exact or common alias — resolved automatically):
+
+`developer` · `appsec` · `devops` · `grc` · `qa` · `security_champion` · `software_architect`
+· `product_owner` · `scrum_master` · `team_lead` · `ciso` · `executive_management`
+· `ops` · `pentester` · `compliance` · `auditor` · `ir` · `sre`
+
+#### Interpreting tool output
+
+| Field | What to communicate |
+|---|---|
+| `rule_trace` contains `CONCERNS_FILTER_REQUIREMENTS` | Tell user scope was narrowed to the specified concerns |
+| `mitigation_confidence: "heuristic"` | Flag as inferred linkage — not structural evidence |
+| `mitigation_confidence: "derived"` | Structural chapter-match — reliable |
+| `assignments: []` / `threats: []` | Say "manual-grounded: not applicable in this scope" — do not invent |
+| `active_domains` | List the security domains active at this risk level |
+
+#### Pattern for complex answers (threat model / security plan / checklist)
+
+1. `consult_security_requirements(risk_level, concerns?)` — anchor active requirements & controls
+2. `get_threat_landscape(risk_level, concerns?)` — relevant threats + mitigating controls
+3. `get_guide_by_role(risk_level, role?, phase?)` — practices per role/phase
+4. Generate document grounded on steps 1–3 — label each claim as manual-grounded
+
+> **The MCP surfaces what the manual says — the LLM generates content.**
+> Use CONSULT tools to retrieve artefact descriptions, required sections, and controls.
+> Then generate the actual document, template, or checklist based on that grounded context.
+
 > In governance, assessment, or planning tasks: **present the target artefact plan before
 > modifying any files.**
 >
 > In implementation tasks: **obtain applicable secure implementation guidance before
 > generating code** when security-relevant behaviour is involved.
 
+### SETUP mode
+Use when the user wants to configure their AI client to use SbD-ToE natively.
+
+```
+generate_sbd_toe_skill  ← returns canonical skill/instructions content from sbd://toe/agent-guide
+                           save to the appropriate file for the client:
+                           Claude Code  → .claude/skills/sbd-toe.md
+                           GitHub Copilot → .github/copilot-instructions.md
+                           Cursor       → .cursorrules
+```
+
 ---
 
 ## Epistemic standards
@@ -132,16 +216,26 @@ Always distinguish between:
 
 ### By question type
 
-| Question | Tool |
+| Question | Approach |
 |---|---|
 | "What is X?" / "How does Y work?" | `search_sbd_toe_manual` |
 | "What applies to my project?" | `map_sbd_toe_applicability` → `get_sbd_toe_chapter_brief` |
 | "What does chapter N cover?" | `get_sbd_toe_chapter_brief` |
 | "List all chapters" | `list_sbd_toe_chapters` |
 | "Find control / artefact / practice" | `query_sbd_toe_entities` |
-| "Generate a threat model / checklist / plan" | `generate_document` |
-| "Governance plan for this repo" | `plan_sbd_toe_repo_governance` |
+| "What requirements apply at L1/L2/L3?" | `consult_security_requirements(risk_level)` |
+| "Which controls are active for auth / logging / …?" | `consult_security_requirements(risk_level, concerns=[…])` |
+| "What threats apply to this project?" | `get_threat_landscape(risk_level)` |
+| "What threats are relevant for auth / logging / …?" | `get_threat_landscape(risk_level, concerns=[…])` |
+| "What should a developer / architect / … do?" | `get_guide_by_role(risk_level, role=…)` |
+| "What practices apply in design / implement / …?" | `get_guide_by_role(risk_level, phase=…)` |
+| "What roles exist in the manual?" | `resolve_entities(record_type="role")` |
+| "List all controls in domain X" | `resolve_entities(record_type="control", filters={domain: X})` |
+| "Generate a threat model / checklist / plan" | `get_threat_landscape` + `get_guide_by_role` → then generate content |
+| "What artefacts does the manual require?" | `plan_sbd_toe_repo_governance` |
+| "Governance plan for this repo" | `plan_sbd_toe_repo_governance` → generate plan from returned artefact list |
 | "What to review given these changed files?" | `map_sbd_toe_review_scope` |
+| "Set up SbD-ToE for this client / create a skill" | `generate_sbd_toe_skill` |
 
 ---
 
@@ -151,8 +245,8 @@ Always distinguish between:
 |---|---|
 | `sbd://toe/agent-guide` | This document — full operational guide |
 | `sbd://toe/index-compact` | Full chapter map as JSON — fast structured lookup |
-| `sbd://toe/skill-template/{riskLevel}/{projectRole}` | Role + risk specific instructions |
 | `sbd://toe/chapter-applicability/{riskLevel}` | Active/excluded chapters for a risk level |
+| `sbd://toe/ontology` | Full ontology YAML — domain_mapping, concerns, inference rules |
 
 ---
 
@@ -165,18 +259,6 @@ Always distinguish between:
 
 ---
 
-## `generate_document` types
-
-| type | Description |
-|---|---|
-| `classification-template` | Application risk classification document |
-| `threat-model-template` | Threat model with required sections per risk level |
-| `checklist` | Security checklist for the risk level |
-| `training-plan` | Security training plan |
-| `secure-config` | Secure configuration reference |
-
----
-
 ## Chapter reference
 
 | chapterId | Title | Min level | Domains |