@securityreviewai/securityreview-kit 0.1.51 → 0.1.52

package/src/generators/rules/guardrails-selection/references/category-threat-map.md

@@ -0,0 +1,232 @@
+# Guardrail Selection Threat Map
+
+Use this file when deciding which guardrail categories apply to the current task and which threat families should influence the shortlist.
+
+The intent is not to produce a full threat model here. The intent is to make sure likely exploit paths influence which guardrails are fetched by id and enforced during implementation.
+
+## How to use this map
+
+1. Start from the feature or code change.
+2. Infer the categories involved in the implementation.
+3. Use the mappings below to identify likely threat families.
+4. Shortlist guardrails that directly or adjacently mitigate those threats.
+5. Fetch those guardrails with `get_guardrail_by_id`.
+
+## STRIDE-style mappings for guardrail selection
+
+### Spoofing
+
+Usually maps to authentication and session-related controls.
+
+Threat patterns to consider:
+
+- identity-related attacks
+- session and token attacks
+- business-logic attacks leading to authentication bypass
+- injection attacks leading to authentication bypass
+- serialization attacks leading to authentication bypass
+- cryptographic attacks leading to authentication bypass
+- lapses in logging leading to authentication bypass
+- client-side trust leading to authentication bypass
+
+Categories commonly shortlisted:
+
+- `authentication`
+- `session_management`
+- `cryptography`
+- `logging`
+- `client_side`
+- `business_logic`
+- `input_validation`
+- `deserialization`
+
+### Tampering
+
+Usually maps to authorization, integrity, and unsafe state change controls.
+
+Threat patterns to consider:
+
+- broken object level access control patterns
+- broken functional level access control patterns
+- injection-driven authorization bypass
+- serialization-driven authorization bypass
+- business-logic-driven authorization bypass
+- client-side trust leading to unauthorized state changes
+
+Categories commonly shortlisted:
+
+- `authorization`
+- `tenant_isolation`
+- `data_access`
+- `business_logic`
+- `logging`
+- `input_validation`
+- `deserialization`
+- `client_side`
+
+### Repudiation
+
+Usually appears when spoofing and tampering are possible but the system cannot prove what happened.
+
+Threat patterns to consider:
+
+- weak or missing audit trails for auth and authorization decisions
+- missing actor attribution on sensitive state changes
+- mutable or incomplete event records
+- inability to correlate session, actor, and resource changes
+
+Categories commonly shortlisted:
+
+- `logging`
+- `monitoring`
+- `authentication`
+- `authorization`
+- `admin_workflows`
+
+### Information Disclosure
+
+Usually maps to authorization, data exposure, logging, and unsafe client-side trust.
+
+Threat patterns to consider:
+
+- broken object level access control patterns
+- broken functional level access control patterns
+- injection-driven information disclosure
+- serialization-driven information disclosure
+- business-logic-driven information disclosure
+- lapses in logging leading to disclosure
+- client-side trust causing exposure of protected data
+
+Categories commonly shortlisted:
+
+- `authorization`
+- `tenant_isolation`
+- `data_access`
+- `logging`
+- `input_validation`
+- `deserialization`
+- `client_side`
+- `output_encoding`
+
+### Denial of Service
+
+Usually maps to workload protection, parsing safety, quota controls, and expensive query behavior.
+
+Threat patterns to consider:
+
+- broken access control patterns that expose heavy operations
+- injection or data-access paths that amplify resource consumption
+- serialization-driven memory or parser exhaustion
+- business-logic-driven abuse of expensive workflows
+- logging lapses that hide repeated abuse
+
+Categories commonly shortlisted:
+
+- `rate_limiting`
+- `input_validation`
+- `file_uploads`
+- `deserialization`
+- `data_access`
+- `network`
+- `monitoring`
+- `logging`
+- `business_logic`
+
+### Elevation of Privilege
+
+Usually maps to authorization, role boundaries, trust decisions, and privileged workflow controls.
+
+Threat patterns to consider:
+
+- access control bypasses from broken object or function level access
+- injection-based privilege escalation
+- client-side induced privilege escalation
+- serialization-induced privilege escalation
+- business-logic-triggered privilege escalation
+- logging lapses that conceal privilege abuse
+
+Categories commonly shortlisted:
+
+- `authorization`
+- `tenant_isolation`
+- `admin_workflows`
+- `business_logic`
+- `client_side`
+- `input_validation`
+- `deserialization`
+- `logging`
+
+## Fast examples
+
+### Add password reset flow
+
+Likely categories:
+
+- `authentication`
+- `session_management`
+- `cryptography`
+- `logging`
+- `rate_limiting`
+
+Likely threat families:
+
+- spoofing
+- repudiation
+- information disclosure
+
+### Add admin endpoint to change user role
+
+Likely categories:
+
+- `authorization`
+- `tenant_isolation`
+- `admin_workflows`
+- `logging`
+- `business_logic`
+
+Likely threat families:
+
+- tampering
+- repudiation
+- elevation of privilege
+- information disclosure
+
+### Add bulk import endpoint
+
+Likely categories:
+
+- `input_validation`
+- `file_uploads`
+- `deserialization`
+- `data_access`
+- `logging`
+- `rate_limiting`
+
+Likely threat families:
+
+- tampering
+- information disclosure
+- denial of service
+
+### Move entitlement checks to the frontend
+
+Likely categories:
+
+- `authorization`
+- `client_side`
+- `tenant_isolation`
+- `logging`
+
+Likely threat families:
+
+- tampering
+- information disclosure
+- elevation of privilege
+
+## Selection reminders
+
+- A feature can require guardrails from multiple categories.
+- Shortlist for exploit chains, not isolated weaknesses.
+- Logging often matters because poor auditability can turn spoofing, tampering, or privilege abuse into repudiation.
+- Client-side logic often needs server-side guardrails even if the visible change is in the UI.
+- If no existing guardrail covers a realistic recurring threat, create an `ide_generated` guardrail and carry it into the final VibeReview markdown sync.

package/src/generators/rules/guardrails_rule.md

@@ -0,0 +1,94 @@
+# Vibe Guardrails — Secure by Code
+
+**Enforce project-specific security guardrails during every code-generation task.**
+
+This rule complements the PWNISMS threat model ("secure by design") with concrete, project-level coding dos and don'ts ("secure by code"). Guardrails are maintained in SRAI and fetched via `security-review-mcp`.
+
+---
+
+## When this rule applies
+
+This rule is **active for every code-generation or code-modification task** — including:
+
+- Implementing new features or endpoints
+- Fixing bugs that touch security-relevant code
+- Refactoring code that handles auth, input, secrets, data storage, or network
+- Generating boilerplate, scaffolding, or templates that will run in production
+
+### When to skip
+
+Skip guardrail enforcement for tasks with **no code output** (documentation, Q&A, formatting, renaming).
+
+---
+
+## Required behavior
+
+### 1. Use the guardrails-selection skill at the start of every code task
+
+Before writing or modifying code, you must read and follow `{{GUARDRAILS_SELECTION_SKILL_DIR}}/SKILL.md`.
+
+That skill is mandatory because the IDE must not leave guardrail selection to chance. The required workflow is:
+
+- **Analyze the task first** — infer what the user is actually building, what components are touched, what categories are involved, and what threats might occur.
+- **Resolve the project** — use `find_project_by_name` with `name="<SRAI_PROJECT_NAME>"` to obtain `project_id`.
+- **Load the broad catalog** — call `get_guardrails` with `project_id`.
+- **Shortlist intentionally** — choose only the guardrails that mitigate the categories and likely threats for the current task.
+- **Hydrate the exact shortlist** — call `get_guardrail_by_id` for the shortlisted guardrail ids so implementation uses the exact selected guardrails, not a vague reading of the full catalog.
+- **Preserve the shortlist** — keep the selected existing guardrails in context so the final VibeReview markdown can include the same guardrails later without re-querying.
+
+The broad `get_guardrails` result is only the candidate catalog. The active implementation guardrails must come from the shortlisted `get_guardrail_by_id` result.
+
+Each guardrail used for implementation should preserve these fields:
+
+| Field | Description |
+|---|---|
+| `id` | Stable guardrail identifier used with `get_guardrail_by_id` |
+| `title` | Short name of the guardrail |
+| `rule_type` | `must` (mandatory) or `must_not` (prohibition) |
+| `category` | Grouping label (e.g. `authentication`, `input_validation`, `secrets`) or `null` |
+| `instruction` | The actionable coding directive |
+
+If `get_guardrails` returns additional metadata such as `source_ref`, use it as supporting context during selection.
+
+### 2. Apply guardrails during code generation
+
+- **`must` rules (DOs):** Treat as mandatory implementation requirements. Every line of generated code must satisfy all applicable `must` guardrails.
+- **`must_not` rules (DON'Ts):** Treat as hard prohibitions. Generated code must never violate a `must_not` guardrail.
+- If a guardrail conflicts with the user's explicit instruction, **flag the conflict** to the user and ask for confirmation before proceeding.
+- If no guardrails are returned (empty list), proceed normally using baseline PWNISMS controls.
+
+### 3. Cross-reference with PWNISMS
+
+Guardrails and PWNISMS are complementary:
+
+- Guardrails provide **project-specific, concrete rules** derived from prior threat reviews, compliance requirements, and team decisions.
+- PWNISMS provides **universal threat-category coverage** to catch gaps that guardrails may not yet cover.
+- When PWNISMS analysis reveals a gap not covered by any existing guardrail, **create a new guardrail on the fly** and apply it immediately (marked `source: "ide_generated"` in the VibeReview markdown).
+
+### 4. Report guardrail compliance
+
+After code generation, include a brief guardrails compliance summary:
+
+- List which guardrails were applied (by title), distinguishing existing vs IDE-generated.
+- Flag any guardrails that could not be fully satisfied and explain why.
+- Do not drop shortlisted existing guardrails from session context. The final VibeReview markdown must include the same shortlist, including any unsatisfied items with notes.
+
+---
+
+## Guardrail lifecycle — updates and new guardrails
+
+Guardrails are living artifacts. The IDE agent can create, apply, and update them:
+
+- **New guardrail**: When threat modeling or code review reveals a recurring security pattern not yet captured, the IDE agent creates and applies a new guardrail on the fly. These are reported to SRAI in the final VibeReview markdown with `source: "ide_generated"`.
+- **Edit suggestion**: When an existing guardrail is too broad, too narrow, or outdated, suggest an update to the user.
+- All guardrails — existing and IDE-generated — must be preserved in the VibeReview markdown under a single `Guardrails Applied` section that the server can normalize into `guardrails_applied`.
+
+---
+
+## Tool Reference
+
+| Tool | Purpose |
+|---|---|
+| `get_guardrails` | Fetch the broad project guardrails catalog (requires `project_id`) |
+| `get_guardrail_by_id` | Fetch the exact shortlisted guardrails that will govern implementation |
+| `find_project_by_name` | Resolve project by name to get `project_id` |

package/src/generators/rules/hooks.json

@@ -0,0 +1,11 @@
+{
+  "version": 1,
+  "hooks": {
+    "sessionStart": [
+      {
+        "command": "printf '%s\\n' '{\"additional_context\":\"## MANDATORY SECURITY GATE (Session Policy)\\n\\nFor ANY user request that has security impact (auth, crypto, input handling, secrets, network, data storage, dependencies, new APIs/endpoints, or any code handling untrusted data):\\n\\n**Plan order:**\\n1. **Fetch Vibe Guardrails (first)** - Use .cursor/skills/guardrails-selection/SKILL.md. Analyze the task, call get_guardrails from security-review-mcp to load the broad catalog, shortlist the relevant guardrails, then call get_guardrail_by_id for the shortlist. These exact shortlisted guardrails are the hard constraints on generated code.\\n2. **PWNISMS threat modeling (second)** - Run threat modeling as a guide before writing code. Use .cursor/skills/threat-modelling/SKILL.md. Cross-reference guardrails with PWNISMS findings to identify gaps. Document findings to inform secure implementation.\\n3. **Implement secure code (third)** - Use the threat model findings AND shortlisted guardrails as guides to create secure code. Every must guardrail must be satisfied; no must_not guardrail may be violated.\\n4. **VibeReview sync (last)** - Read .cursor/skills/vibereview-sync/SKILL.md. The main agent must write a structured `.md` artifact under `vibereview/`, must not read sibling markdown files there just to infer format, must validate that all required metadata and sections are present, and must call `sync_ai_ide_markdown` directly after implementation is done. Include the exact shortlisted guardrails from earlier plus any IDE-generated guardrails in the markdown; do not query guardrails again during sync.\\n\\nNo blocking. No deferral. Guardrails enforce secure code; threat modeling guides the design; the main agent owns the final markdown sync to SRAI. Both sync and guardrail compliance are mandatory and should be part of your to-do.\"}'",
+        "timeout": 5
+      }
+    ]
+  }
+}

package/{templates/shared/threat-modelling.md → src/generators/rules/skill.md}

@@ -1,13 +1,12 @@
 ---
 name: PWNISMS Threat Modelling
-description: Security-first threat modelling workflow for code and architecture tasks. Walks all 7 PWNISMS categories, enforces vibe guardrails (secure by code), and synchronizes findings via a direct VibeReview markdown sync. Use after guardrail selection and before implementation.
+description: Security-first threat modelling workflow for code and architecture tasks. Walks all 7 PWNISMS categories, enforces vibe guardrails (secure by code), and synchronizes findings via a direct VibeReview markdown sync. Use before, during, and after implementation.
 ---
 
 # PWNISMS — Security-First Threat Modelling
 
 For EVERY security-relevant task (feature, bug fix, refactor, infra change, architecture design), run a threat model with PWNISMS.
 
-- This is a pre-implementation gate. Do not write, edit, patch, or generate implementation code until guardrail selection has completed and this PWNISMS pass has been completed.
 - Walk through all 7 categories explicitly.
 - If a category is not applicable, state it briefly and move on.
 - Anchor analysis to linked files, diffs, PRs, API specs, and diagrams whenever available.
@@ -21,7 +20,7 @@ Before deep analysis, ensure the project-specific guardrail shortlist exists:
 
 1. Use `{{GUARDRAILS_SELECTION_SKILL_DIR}}/SKILL.md`.
 2. Resolve the project with `find_project_by_name` using `name="<SRAI_PROJECT_NAME>"`.
-3. Call `get_guardrails`, shortlist intentionally for this task, then preserve the exact returned guardrail records in context.
+3. Call `get_guardrails`, shortlist intentionally for this task, then hydrate the exact shortlist with `get_guardrail_by_id`.
 4. Keep the shortlisted existing guardrails in context for implementation and the final VibeReview markdown sync.
 
 Do not perform project-profile exploration as part of PWNISMS. The old profile tools are not part of this workflow. Ground the threat model in the user request, repository code, diffs, architecture docs the user provides, and the shortlisted guardrails.
@@ -155,7 +154,7 @@ Dependency and delivery threats:
 
 After completing the PWNISMS analysis and before writing code:
 
-1. **Review the exact shortlisted guardrails** produced by `{{GUARDRAILS_SELECTION_SKILL_DIR}}/SKILL.md`.
+1. **Review the shortlisted hydrated guardrails** produced by `{{GUARDRAILS_SELECTION_SKILL_DIR}}/SKILL.md`.
 2. **Classify applicability** — For each shortlisted guardrail, determine if it applies to the current task.
 3. **Apply during code generation:**
    - `must` rules → mandatory implementation requirements. Every applicable `must` guardrail must be satisfied.
@@ -200,7 +199,7 @@ When discussing designs before code exists:
 
 ## Phase 5 — VibeReview Sync (Post Threat Modelling)
 
-**MANDATORY:** After every threat modeling step that produces or modifies threat content, the main agent must update the `.vibreview/scans/*.md` artifact and call `sync_ai_ide_markdown` directly with raw markdown content.
+**MANDATORY:** After every threat modeling step that produces or modifies threat content, the main agent must update the `vibereview/*.md` artifact and call `sync_ai_ide_markdown` directly.
 
 ### What triggers the VibeReview sync
 
@@ -208,22 +207,20 @@ When discussing designs before code exists:
 - Existing threat model updated or extended (new threats, refined mitigations, additional components)
 - Guardrails applied during a code-generation task (existing or IDE-generated)
 
-Do not call sync before implementation is complete unless the user explicitly asked only for threat modelling/design output. For coding tasks, the order is guardrail selection, PWNISMS, implementation, markdown sync.
-
 ### What the VibeReview markdown must contain
 
-The main agent writes a structured `.md` artifact under `.vibreview/scans/` and uploads the raw markdown string through `sync_ai_ide_markdown`. That markdown should contain:
+The main agent writes a structured `.md` artifact under `vibereview/` and uploads it through `sync_ai_ide_markdown`. That markdown should contain:
 
 - **Threat model findings**: threats mitigated, PWNISMS categories, severities, mitigations applied
 - **Best practices achieved**: structured practice entries with `practice_name`, `description`, and `category`
 - **Secure code snippets**: security-relevant code with explanations
-- **Guardrails applied**: all guardrails enforced during this session — both existing ones shortlisted earlier via `get_guardrails` (`source: "existing"`) and new ones the IDE agent created on the fly (`source: "ide_generated"`), each with satisfaction status
+- **Guardrails applied**: all guardrails enforced during this session — both existing ones shortlisted earlier via `get_guardrails` + `get_guardrail_by_id` (`source: "existing"`) and new ones the IDE agent created on the fly (`source: "ide_generated"`), each with satisfaction status
 - **Workflow metadata**: `chat_session_id`, `event_name` or `title`, required `summary`, and optional `workflow_name` / `workflow_description`
 
 ### How to sync
 
 1. Read and follow `{{VIBEREVIEW_SYNC_SKILL_DIR}}/SKILL.md`.
-2. Write or update a file under `.vibreview/scans/`, ideally `.vibreview/scans/<chat_session_id>-<slugified-title-or-event-name>.md`.
+2. Write or update a file under `vibereview/`, ideally `vibereview/<chat_session_id>-<slugified-title-or-event-name>.md`.
 3. Put `chat_session_id`, `summary`, and either `title` or `event_name` in frontmatter.
 4. Include the required sections:
    - `Best Practices Achieved`
@@ -237,9 +234,9 @@ The main agent writes a structured `.md` artifact under `.vibreview/scans/` and
    - every guardrail includes `title`, `rule_type`, `source`, and `satisfied`
    - OWASP mappings use exact IDs and names
    - snippets are grounded in actual code, not invented text
-   - no sibling `.md` files in `.vibreview/scans/` were read just to infer format or content
-6. Call `sync_ai_ide_markdown` directly with the finished raw markdown content. Do not pass JSON, extracted event objects, or summaries as the markdown.
-7. If sync fails, leave the artifact in `.vibreview/scans/` and report the failure clearly.
+   - no sibling `.md` files in `vibereview/` were read just to infer format or content
+6. Call `sync_ai_ide_markdown` directly with the finished markdown artifact.
+7. If sync fails, leave the artifact in `vibereview/` and report the failure clearly.
 
 ---
 
@@ -254,6 +251,6 @@ Before finalizing output, confirm:
 - [ ] Residual risk and follow-up actions are stated.
 - [ ] Vibe guardrails were fetched and enforced (all applicable `must`/`must_not` rules satisfied).
 - [ ] Guardrail compliance summary is included in the response (existing + IDE-generated).
-- [ ] The VibeReview markdown was written under `.vibreview/scans/` and `sync_ai_ide_markdown` was called successfully with raw markdown content.
+- [ ] The VibeReview markdown was written under `vibereview/` and `sync_ai_ide_markdown` was called successfully.
 
 If ANY box cannot be checked, you MUST flag the gap to the user with a specific remediation recommendation before finalizing the code.

package/src/generators/rules/srai-profile.md

@@ -0,0 +1,32 @@
+---
+name: srai-profile
+description: Create and upload a SecurityReviewAI code profile using security-review-mcp
+---
+
+# SRAI Profile Uploader
+
+Create a code profile from the current request and upload it to SRAI using `security-review-mcp`.
+
+Configured SRAI project name: `<SRAI_PROJECT_NAME>`
+
+## Steps
+
+1. Determine scope from the user prompt.
+   - If the request is about a specific capability/module/endpoint, produce a **Feature Code Profile**.
+   - If the request is broad, exploratory, or architecture-level, produce a **Codebase Code Profile**.
+2. Build detailed profile content before any upload call.
+   - Include purpose, boundaries, entry points, sensitive data, trust boundaries, integrations, threats, controls, and open risks.
+3. Resolve the SRAI project.
+   - Use the configured project name by default; if it is missing or ambiguous, ask the user to confirm it.
+   - Call `find_project_by_name` with `name="<SRAI_PROJECT_NAME>"`.
+   - If missing, call `list_projects`; if still missing, call `create_project` with `name="<SRAI_PROJECT_NAME>"`.
+4. Upload generated markdown content with tool 11: `upload_document`.
+   - Use this for raw markdown/text generated in the chat.
+   - Use a clear document name such as `feature-code-profile-<feature>.md` or `codebase-code-profile-<repo>.md`.
+5. Upload files/diagrams with tool 10: `upload_document` when needed.
+   - Provide base64 file content and file name.
+   - Set `document_type` to `Component Diagram` for architecture diagrams.
+   - Set `document_type` to `Uploaded Knowledgebase doc` for other document uploads.
+6. Confirm the result.
+   - Report project name, upload tool used, document name, and that processing is asynchronous.
+   - If upload fails, return exact error details and next retry step.

package/{templates/shared → src/generators/rules}/vibereview-sync/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: vibereview-sync
-description: Write and synchronize a structured VibeReview markdown artifact under .vibreview/scans/ for the current security-relevant session. Use only after guardrail selection, PWNISMS threat modelling, and guardrail-enforced implementation are complete.
+description: Write and synchronize a structured VibeReview markdown artifact under vibereview/ for the current security-relevant session. Use after threat modelling or guardrail-enforced implementation.
 ---
 
 # VibeReview Markdown Sync
@@ -9,20 +9,18 @@ Configured SRAI project name: `<SRAI_PROJECT_NAME>`
 
 Use this skill whenever threat modelling output exists or security guardrail compliance must be synchronized to SRAI.
 
-This skill exists to make the markdown deterministic, grounded, and parseable without depending on a separate subagent. The same agent that performed the work should author the markdown and call `sync_ai_ide_markdown` directly with raw markdown content.
-
-For coding tasks, do not use this skill until the required sequence is complete: guardrail selection, PWNISMS threat modelling, implementation, then markdown sync.
+This skill exists to make the markdown deterministic, grounded, and parseable without depending on a separate subagent. The same agent that performed the work should author the markdown and call `sync_ai_ide_markdown` directly.
 
 ## Core Rules
 
-1. Write the artifact under `.vibreview/scans/`.
+1. Write the artifact under `vibereview/`.
 2. Author the markdown from the current task context only.
-3. Do not read other `.md` files in `.vibreview/scans/` to infer structure, copy content, or merge state.
+3. Do not read other `.md` files in `vibereview/` to infer structure, copy content, or merge state.
 4. If the current session file path is already known, update that one file directly.
 5. If the current session file does not exist yet, create a new file using a stable name such as:
 
 ```text
-.vibreview/scans/<chat_session_id>-<slugified-title-or-event-name>.md
+vibereview/<chat_session_id>-<slugified-title-or-event-name>.md
 ```
 
 6. Validate the markdown before calling `sync_ai_ide_markdown`.
@@ -30,7 +28,7 @@ For coding tasks, do not use this skill until the required sequence is complete:
 
 ## Why You Must Not Read Sibling Files
 
-Other markdown files in `.vibreview/scans/` may belong to different sessions, different workflows, or partially complete work. Reading them introduces drift and causes downstream extraction failures.
+Other markdown files in `vibereview/` may belong to different sessions, different workflows, or partially complete work. Reading them introduces drift and causes downstream extraction failures.
 
 Treat each VibeReview artifact as self-contained. The current artifact must be fully authorable from:
 
@@ -352,8 +350,8 @@ Allowed values:
 
 Before calling `sync_ai_ide_markdown`, verify all of the following:
 
-- The file is under `.vibreview/scans/`.
-- You did not read sibling markdown files in `.vibreview/scans/`.
+- The file is under `vibereview/`.
+- You did not read sibling markdown files in `vibereview/`.
 - `chat_session_id` exists in frontmatter.
 - `summary` exists in frontmatter.
 - `event_name` or `title` exists in frontmatter.
@@ -374,8 +372,7 @@ Before calling `sync_ai_ide_markdown`, verify all of the following:
 
 After validation:
 
-1. Save the markdown artifact under `.vibreview/scans/`.
-2. Call `sync_ai_ide_markdown` directly with the raw markdown string in the `markdown` argument.
-3. Do not pass JSON, a JSON string, a summary object, extracted event data, or metadata-only content as `markdown`.
-4. If sync succeeds, report success briefly.
-5. If sync fails, report failure clearly and leave the markdown artifact intact for retry.
+1. Save the markdown artifact under `vibereview/`.
+2. Call `sync_ai_ide_markdown` directly with that file's contents or path, depending on the tool interface exposed by the host.
+3. If sync succeeds, report success briefly.
+4. If sync fails, report failure clearly and leave the markdown artifact intact for retry.

package/src/generators/rules/vscode.js

@@ -0,0 +1,101 @@
+import { existsSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import {
+    GUARDRAILS_SELECTION_SKILL_REL_DIR,
+    THREAT_MODELLING_SKILL_REL_DIR,
+    VIBEREVIEW_SYNC_SKILL_REL_DIR,
+} from '../../utils/constants.js';
+import { upsertSentinelBlock, writeText } from '../../utils/fs-helpers.js';
+import { getRuleContent, getThreatModellingSkillContent, getVibeReviewSyncSkillContent } from './content.js';
+
+function writeGeneratedText(filePath, content) {
+    const action = existsSync(filePath) ? 'updated' : 'created';
+    writeText(filePath, content);
+    return { filePath, action };
+}
+
+function removeGeneratedText(filePath) {
+    if (existsSync(filePath)) {
+        unlinkSync(filePath);
+        return { filePath, action: 'deleted' };
+    }
+    return null;
+}
+
+function getCopilotSessionHookContent() {
+    const additionalContext = [
+        '## MANDATORY SECURITY GATE (Session Policy)',
+        '',
+        'For any request with security impact (auth, authorization, crypto, input handling, secrets, network, data storage, dependencies, new APIs/endpoints, infrastructure, or code handling untrusted data), follow this order:',
+        '',
+        '1. Fetch Vibe Guardrails first using .github/skills/guardrails-selection/SKILL.md. Resolve the project, call get_guardrails, shortlist relevant guardrails, then call get_guardrail_by_id for the shortlist.',
+        '2. Run PWNISMS threat modelling using .github/skills/threat-modelling/SKILL.md. Explicitly walk Product, Workload, Network, IAM, Secrets, Monitoring, and Supply Chain.',
+        '3. Implement secure code using both the hydrated guardrails and PWNISMS findings.',
+        '4. Read .github/skills/vibereview-sync/SKILL.md. Write a structured .md artifact under vibereview/, do not read sibling markdown files there just to infer format, validate it, and call sync_ai_ide_markdown directly after threat modelling or guardrail enforcement. Reuse the exact guardrail shortlist; do not re-query guardrails during the final sync.',
+        '',
+        'Do not use project-profile exploration tools during normal coding tasks. No blocking and no deferral: guardrails first, PWNISMS second, implementation third, VibeReview sync last.',
+    ].join('\n');
+
+    const commandPayload = JSON.stringify({
+        hookSpecificOutput: {
+            hookEventName: 'SessionStart',
+            additionalContext,
+        },
+    });
+
+    return JSON.stringify(
+        {
+            hooks: {
+                SessionStart: [
+                    {
+                        type: 'command',
+                        command: `printf '%s\\n' '${commandPayload.replaceAll("'", "'\\''")}'`,
+                        timeout: 5,
+                    },
+                ],
+            },
+        },
+        null,
+        2,
+    ) + '\n';
+}
+
+/**
+ * Generate VS Code Copilot instructions — appends to .github/copilot-instructions.md
+ */
+export function generate(cwd, options = {}) {
+    const optionsWithSkillDirs = {
+        ...options,
+        guardrailsSelectionSkillDir: GUARDRAILS_SELECTION_SKILL_REL_DIR.vscode,
+        threatModellingSkillDir: THREAT_MODELLING_SKILL_REL_DIR.vscode,
+        vibereviewSyncSkillDir: VIBEREVIEW_SYNC_SKILL_REL_DIR.vscode,
+    };
+    const filePath = join(cwd, '.github', 'copilot-instructions.md');
+    const content = getRuleContent(optionsWithSkillDirs);
+    const action = upsertSentinelBlock(filePath, content);
+
+    const threatSkillPath = join(cwd, THREAT_MODELLING_SKILL_REL_DIR.vscode, 'SKILL.md');
+    const threatSkill = writeGeneratedText(
+        threatSkillPath,
+        getThreatModellingSkillContent(optionsWithSkillDirs),
+    );
+
+    const vibereviewSyncSkillPath = join(cwd, VIBEREVIEW_SYNC_SKILL_REL_DIR.vscode, 'SKILL.md');
+    const vibereviewSyncSkill = writeGeneratedText(
+        vibereviewSyncSkillPath,
+        getVibeReviewSyncSkillContent(optionsWithSkillDirs),
+    );
+
+    const deletedLegacyAgent = removeGeneratedText(join(cwd, '.github', 'agents', 'ctm_sync.agent.md'));
+
+    const hooksPath = join(cwd, '.github', 'hooks', 'srai-session-policy.json');
+    const hooks = writeGeneratedText(hooksPath, getCopilotSessionHookContent());
+
+    return [
+        { filePath, action, kind: 'rule' },
+        { ...threatSkill, kind: 'skill' },
+        { ...vibereviewSyncSkill, kind: 'skill' },
+        { ...hooks, kind: 'hooks' },
+        ...(deletedLegacyAgent ? [{ ...deletedLegacyAgent, kind: 'cleanup' }] : []),
+    ];
+}