@securityreviewai/securityreview-kit 0.1.40 → 0.1.42

package/README.md

@@ -28,7 +28,7 @@ npx @securityreviewai/securityreview-kit init --switch-project
 | Target | Flag | MCP Config | Workspace Rule |
 |---|---|---|---|
 | Cursor | `cursor` | `.cursor/mcp.json` | `.cursor/rules/srai-security-review.mdc`, `.cursor/rules/ctm_sync_rule.mdc`, `.cursor/commands/ctm_sync.md`, `.cursor/agents/ctm_sync.md`, `.cursor/commands/create-ide-workflow.md`, `.cursor/commands/srai-profile.md`, `.cursor/skills/threat-modelling/SKILL.md` |
-| Claude Code | `claude` | `.claude/settings.json` | `CLAUDE.md`, `.claude/skills/threat-modelling/SKILL.md`, `.claude/skills/guardrails-profiler/SKILL.md`, `.claude/skills/guardrails-selection/SKILL.md`, `.claude/agents/ctm_sync.md`, `.claude/commands/guardrails-init-profile.md` |
+| Claude Code | `claude` | `.mcp.json` | `.claude/CLAUDE.md`, `.claude/settings.json`, `.claude/skills/threat-modelling/SKILL.md`, `.claude/skills/guardrails-profiler/SKILL.md`, `.claude/skills/guardrails-selection/SKILL.md`, `.claude/agents/ctm_sync.md`, `.claude/commands/guardrails-init-profile.md` |
 | VS Code Copilot | `vscode` | `.vscode/mcp.json` | `.github/copilot-instructions.md`, `.github/skills/threat-modelling/SKILL.md`, `.github/skills/guardrails-profiler/SKILL.md`, `.github/skills/guardrails-selection/SKILL.md`, `.github/agents/ctm_sync.agent.md`, `.github/hooks/srai-session-policy.json` |
 | Windsurf | `windsurf` | `.windsurf/mcp_config.json` | `.windsurf/rules/srai-security-review.md` |
 | Codex | `codex` | `.codex/config.toml` | `.codex/AGENTS.md`, `.codex/skills/threat-modelling/SKILL.md`, `.codex/skills/guardrails-profiler/SKILL.md`, `.codex/skills/guardrails-selection/SKILL.md`, `.codex/agents/ctm_sync.toml`, `.codex/hooks.json`, `.codex/commands/guardrails-init-profile.md` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@securityreviewai/securityreview-kit",
-  "version": "0.1.40",
+  "version": "0.1.42",
   "description": "Bootstrap security-review-mcp for AI IDEs and CLI tools",
   "author": "Debarshi Das <debarshi.das@we45.com>",
   "license": "UNLICENSED",

package/src/commands/init.js

@@ -657,7 +657,7 @@ export async function initCommand(options) {
                 claudeProfilerAuth = await resolveClaudeProfilerAuth(options, interactive, cwd);
                 console.log(
                     chalk.dim(
-                        `  Claude Code: profiling uses \`.claude/settings.json\`, the configured MCP server, and \`${claudeProfilerAuth.model}\` for this run.`,
+                        `  Claude Code: profiling uses \`.mcp.json\`, \`.claude/settings.json\`, bypassed tool prompts for this profiling pass, and \`${claudeProfilerAuth.model}\` for this run.`,
                     ),
                 );
                 console.log(chalk.dim(`  Auth mode: ${claudeProfilerAuth.summary}.`));
@@ -819,7 +819,7 @@ export async function initCommand(options) {
                     );
                     console.log(
                         chalk.dim(
-                            '    • MCP missing: re-run init with Claude Code selected and MCP installation enabled so `.claude/settings.json` is written.',
+                            '    • MCP missing: re-run init with Claude Code selected and MCP installation enabled so `.mcp.json` is written and `.claude/settings.json` enables `security-review-mcp`.',
                         ),
                     );
                 } else if (agentTarget === 'codex') {

package/src/generators/mcp/claude.js

@@ -10,7 +10,7 @@ function getClaudeSessionStartHooks() {
         '1. Fetch Vibe Guardrails first using .claude/skills/guardrails-selection/SKILL.md.',
         '2. Run PWNISMS threat modelling using .claude/skills/threat-modelling/SKILL.md.',
         '3. Implement secure code using the hydrated guardrails and threat findings.',
-        '4. Invoke the ctm_sync agent using .claude/agents/ctm_sync.md after implementation or threat-model updates.',
+        '4. Invoke the ctm_sync agent using .claude/agents/ctm_sync.md after implementation or threat-model updates. The agent should write a structured .md sync artifact and upload it with sync_ai_ide_markdown.',
         '',
         'Do not use project-profile exploration tools during normal coding tasks. No blocking and no deferral: guardrails first, PWNISMS second, implementation third, ctm_sync last.',
     ].join('\n');
@@ -29,17 +29,17 @@ function getClaudeSessionStartHooks() {
 }
 
 /**
- * Generate Claude Code MCP config at .claude/settings.json
+ * Generate Claude Code project MCP config at .mcp.json and project settings at .claude/settings.json
  */
 export function generate(cwd, envVars) {
-    const filePath = join(cwd, '.claude', 'settings.json');
-    const existing = readJson(filePath) || {};
+    const mcpPath = join(cwd, '.mcp.json');
+    const mcpConfig = readJson(mcpPath) || {};
 
-    if (!existing.mcpServers) {
-        existing.mcpServers = {};
+    if (!mcpConfig.mcpServers) {
+        mcpConfig.mcpServers = {};
     }
 
-    existing.mcpServers[MCP_SERVER_NAME] = {
+    mcpConfig.mcpServers[MCP_SERVER_NAME] = {
         command: 'npx',
         args: ['-y', `${MCP_SERVER_PACKAGE}@latest`],
         env: {
@@ -48,6 +48,17 @@ export function generate(cwd, envVars) {
         },
     };
 
+    writeJson(mcpPath, mcpConfig);
+
+    const settingsPath = join(cwd, '.claude', 'settings.json');
+    const existing = readJson(settingsPath) || {};
+    const enabledServers = Array.isArray(existing.enabledMcpjsonServers)
+        ? existing.enabledMcpjsonServers.filter((name) => typeof name === 'string' && name.trim())
+        : [];
+    if (!enabledServers.includes(MCP_SERVER_NAME)) {
+        existing.enabledMcpjsonServers = [...enabledServers, MCP_SERVER_NAME];
+    }
+
     const existingSessionStart = Array.isArray(existing.SessionStart) ? existing.SessionStart : [];
     const marker = 'MANDATORY SECURITY GATE (Claude Code Session Policy)';
     const ours = getClaudeSessionStartHooks();
@@ -57,6 +68,6 @@ export function generate(cwd, envVars) {
     );
     existing.SessionStart = hasOurs ? existingSessionStart : [...existingSessionStart, ...ours];
 
-    writeJson(filePath, existing);
-    return filePath;
+    writeJson(settingsPath, existing);
+    return mcpPath;
 }

package/src/generators/mcp/claude.test.js

@@ -5,7 +5,7 @@ import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import { generate } from './claude.js';
 
-test('Claude MCP generator writes mcp server and session hooks', () => {
+test('Claude MCP generator writes .mcp.json, enables the project MCP server, and adds session hooks', () => {
     const cwd = mkdtempSync(join(tmpdir(), 'securityreview-kit-claude-mcp-'));
 
     generate(cwd, {
@@ -13,10 +13,12 @@ test('Claude MCP generator writes mcp server and session hooks', () => {
         apiToken: 'secret-token',
     });
 
-    const config = JSON.parse(readFileSync(join(cwd, '.claude', 'settings.json'), 'utf8'));
-    assert.equal(config.mcpServers['security-review-mcp'].command, 'npx');
-    assert.equal(Array.isArray(config.SessionStart), true);
-    assert.match(config.SessionStart[0].hooks[0].prompt, /MANDATORY SECURITY GATE/);
+    const mcpConfig = JSON.parse(readFileSync(join(cwd, '.mcp.json'), 'utf8'));
+    const settings = JSON.parse(readFileSync(join(cwd, '.claude', 'settings.json'), 'utf8'));
+    assert.equal(mcpConfig.mcpServers['security-review-mcp'].command, 'npx');
+    assert.deepEqual(settings.enabledMcpjsonServers, ['security-review-mcp']);
+    assert.equal(Array.isArray(settings.SessionStart), true);
+    assert.match(settings.SessionStart[0].hooks[0].prompt, /MANDATORY SECURITY GATE/);
 });
 
 test('Claude MCP generator preserves existing SessionStart hooks', () => {
@@ -50,4 +52,5 @@ test('Claude MCP generator preserves existing SessionStart hooks', () => {
     assert.equal(config.SessionStart.length, 2);
     assert.match(config.SessionStart[0].hooks[0].prompt, /Existing hook/);
     assert.match(config.SessionStart[1].hooks[0].prompt, /MANDATORY SECURITY GATE/);
+    assert.deepEqual(config.enabledMcpjsonServers, ['security-review-mcp']);
 });

package/src/generators/rules/claude.js

@@ -1,12 +1,14 @@
-import { existsSync } from 'node:fs';
+import { existsSync, unlinkSync } from 'node:fs';
 import { join } from 'node:path';
 import {
     CTM_SYNC_AGENT_REL_PATH,
     GUARDRAILS_PROFILER_SKILL_REL_DIR,
     GUARDRAILS_SELECTION_SKILL_REL_DIR,
+    SENTINEL_END,
+    SENTINEL_START,
     THREAT_MODELLING_SKILL_REL_DIR,
 } from '../../utils/constants.js';
-import { upsertSentinelBlock, writeText } from '../../utils/fs-helpers.js';
+import { readText, upsertSentinelBlock, writeText } from '../../utils/fs-helpers.js';
 import {
     getCtmSyncWorkflowContent,
     getGuardrailsInitProfileContent,
@@ -40,7 +42,7 @@ function getClaudeCtmSyncAgentContent(options = {}) {
 }
 
 /**
- * Generate Claude Code workspace rule — appends to CLAUDE.md
+ * Generate Claude Code workspace rule — appends to .claude/CLAUDE.md
  */
 export function generate(cwd, options = {}) {
     const optionsWithSkillDirs = {
@@ -49,10 +51,25 @@ export function generate(cwd, options = {}) {
         threatModellingSkillDir: THREAT_MODELLING_SKILL_REL_DIR.claude,
         ctmSyncAgentPath: CTM_SYNC_AGENT_REL_PATH.claude,
     };
-    const filePath = join(cwd, 'CLAUDE.md');
+    const legacyRootPath = join(cwd, 'CLAUDE.md');
+    const filePath = join(cwd, '.claude', 'CLAUDE.md');
     const content = getRuleContent(optionsWithSkillDirs);
     const action = upsertSentinelBlock(filePath, content);
 
+    const legacyContent = readText(legacyRootPath);
+    if (legacyContent.includes(SENTINEL_START) && legacyContent.includes(SENTINEL_END)) {
+        const startIdx = legacyContent.indexOf(SENTINEL_START);
+        const endIdx = legacyContent.indexOf(SENTINEL_END);
+        const before = legacyContent.substring(0, startIdx);
+        const after = legacyContent.substring(endIdx + SENTINEL_END.length);
+        const migrated = `${before}${after}`.trim();
+        if (migrated) {
+            writeText(legacyRootPath, migrated + '\n');
+        } else if (existsSync(legacyRootPath)) {
+            unlinkSync(legacyRootPath);
+        }
+    }
+
     const threatSkillPath = join(cwd, THREAT_MODELLING_SKILL_REL_DIR.claude, 'SKILL.md');
     const threatSkill = writeGeneratedText(
         threatSkillPath,

package/src/generators/rules/claude.test.js

@@ -1,17 +1,17 @@
-import { existsSync, mkdtempSync, readFileSync } from 'node:fs';
+import { existsSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import { generate } from './claude.js';
 
-test('Claude generator writes CLAUDE.md, threat skill, ctm_sync agent, and profiling command', () => {
+test('Claude generator writes .claude/CLAUDE.md, threat skill, ctm_sync agent, and profiling command', () => {
     const cwd = mkdtempSync(join(tmpdir(), 'securityreview-kit-claude-'));
 
     const results = generate(cwd, { projectName: 'SmokeProject' });
 
     const expectedPaths = [
-        'CLAUDE.md',
+        '.claude/CLAUDE.md',
         '.claude/skills/threat-modelling/SKILL.md',
         '.claude/agents/ctm_sync.md',
         '.claude/commands/guardrails-init-profile.md',
@@ -23,7 +23,7 @@ test('Claude generator writes CLAUDE.md, threat skill, ctm_sync agent, and profi
 
     assert.deepEqual(results.map((entry) => entry.kind), ['rule', 'skill', 'agent', 'command']);
 
-    const instructions = readFileSync(join(cwd, 'CLAUDE.md'), 'utf8');
+    const instructions = readFileSync(join(cwd, '.claude/CLAUDE.md'), 'utf8');
     assert.match(instructions, /\.claude\/skills\/guardrails-selection\/SKILL\.md/);
     assert.match(instructions, /\.claude\/skills\/threat-modelling\/SKILL\.md/);
     assert.match(instructions, /\.claude\/agents\/ctm_sync\.md/);
@@ -36,4 +36,26 @@ test('Claude generator writes CLAUDE.md, threat skill, ctm_sync agent, and profi
     assert.match(agent, /^---\nname: ctm_sync/m);
     assert.match(agent, /model: inherit/);
     assert.match(agent, /Configured SRAI project name: `SmokeProject`/);
+    assert.match(agent, /sync_ai_ide_markdown/);
+    assert.match(agent, /structured markdown artifact/i);
+    assert.match(agent, /chat_session_id/);
+    assert.match(agent, /Guardrails Applied/);
+    assert.match(agent, /vibereview\//);
+    assert.doesNotMatch(agent, /Call `create_ai_ide_event` with/i);
+});
+
+test('Claude generator migrates the kit-managed root CLAUDE.md block into .claude/CLAUDE.md', () => {
+    const cwd = mkdtempSync(join(tmpdir(), 'securityreview-kit-claude-migrate-'));
+    const legacyPath = join(cwd, 'CLAUDE.md');
+
+    writeFileSync(
+        legacyPath,
+        '<!-- securityreview-kit:start -->\nold managed block\n<!-- securityreview-kit:end -->\n',
+        'utf8',
+    );
+
+    generate(cwd, { projectName: 'SmokeProject' });
+
+    assert.equal(existsSync(join(cwd, '.claude/CLAUDE.md')), true);
+    assert.equal(existsSync(legacyPath), false);
 });

package/src/generators/rules/codex.js

@@ -29,7 +29,7 @@ function getCodexSessionHookContent() {
         '1. Fetch Vibe Guardrails first using .codex/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 .codex/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. Invoke the ctm_sync subagent using .codex/agents/ctm_sync.toml after threat modelling or guardrail enforcement. Reuse the exact guardrail shortlist; do not re-query guardrails during CTM sync.',
+        '4. Invoke the ctm_sync subagent using .codex/agents/ctm_sync.toml after threat modelling or guardrail enforcement. Reuse the exact guardrail shortlist; do not re-query guardrails during CTM sync. The subagent should write a structured .md sync artifact and upload it with sync_ai_ide_markdown.',
         '',
         'Do not use project-profile exploration tools during normal coding tasks. No blocking and no deferral: guardrails first, PWNISMS second, implementation third, ctm_sync last.',
     ].join('\n');

package/src/generators/rules/codex.test.js

@@ -42,6 +42,12 @@ test('Codex generator writes AGENTS, skills, subagent, hooks, and profiling comm
     assert.match(agent, /name = "ctm_sync"/);
     assert.match(agent, /developer_instructions = '''/);
     assert.match(agent, /Configured SRAI project name: `SmokeProject`/);
+    assert.match(agent, /sync_ai_ide_markdown/);
+    assert.match(agent, /structured markdown artifact/i);
+    assert.match(agent, /chat_session_id/);
+    assert.match(agent, /Best Practices Achieved/);
+    assert.match(agent, /vibereview\//);
+    assert.doesNotMatch(agent, /Call `create_ai_ide_event` with/i);
 
     const hooks = JSON.parse(readFileSync(join(cwd, '.codex/hooks.json'), 'utf8'));
     assert.equal(hooks.hooks.SessionStart[0].hooks[0].type, 'command');

package/src/generators/rules/content.md

@@ -28,8 +28,8 @@ For any task that touches auth, authorization, input handling, secrets, network,
 
 4. **Run CTM sync last.**
    - After threat modelling is created or updated, or after guardrails are enforced during implementation, invoke the `ctm_sync` agent/workflow.
-   - Use `{{CTM_SYNC_AGENT_PATH}}` for the detailed payload contract.
-   - Pass the current threat model summary, the stable `chat_session_id`, the exact existing guardrails shortlisted earlier, and any `ide_generated` guardrails.
+   - Use `{{CTM_SYNC_AGENT_PATH}}` for the markdown contract and sync workflow.
+   - Pass the current threat model summary, the stable `chat_session_id`, the exact existing guardrails shortlisted earlier, and any `ide_generated` guardrails so `ctm_sync` can write a structured `.md` artifact for server-side extraction.
    - Do not re-query guardrails during CTM sync; reuse the shortlist selected before implementation.
 
 ## When To Skip
@@ -50,5 +50,5 @@ The normal coding workflow is guardrails selection, PWNISMS threat modelling, se
 |---|---|
 | Project resolution | `find_project_by_name`, `list_projects`, `create_project`, `get_project` |
 | Guardrails | `get_guardrails`, `get_guardrail_by_id` |
-| CTM sync | `create_ai_ide_workflow`, `create_ai_ide_event`, `get_current_user` or equivalent user identity tool |
+| CTM sync | `sync_ai_ide_markdown` |
 | Profiler only | `update_vibe_profile`, `write_default_pack` are used by init-time profiling, not normal coding tasks |

package/src/generators/rules/ctm_sync.md

@@ -1,6 +1,6 @@
 ---
 name: ctm_sync
-description: Command/workflow triggered whenever a threat model is generated or updated, or guardrails are proposed/modified. Builds and uploads CTM sync details and guardrail updates through security-review-mcp.
+description: Command/workflow triggered whenever a threat model is generated or updated, or guardrails are proposed/modified. Writes a grounded AI IDE sync markdown file and uploads it through security-review-mcp.
 ---
 
 # CTM Sync Workflow
@@ -9,114 +9,167 @@ Configured SRAI project name: `<SRAI_PROJECT_NAME>`
 
 When invoked:
 
-0. Verify `create_ai_ide_event` and `create_ai_ide_workflow` exist in `security-review-mcp`. If a `list_*` tool for AI IDE workflows exists, prefer it for workflow discovery.
-1. Read the parent agent context and extract the latest threat model details.
-2. **Chat session identity (required)** — The event payload MUST include a stable `chat_session_id` for the current IDE chat session:
-   - Use a session identifier supplied by the host environment when one exists (e.g. conversation or session id from the IDE/agent runtime).
-   - If none exists, use a single UUID (or equivalent) generated **once** at the start of this chat and reused for every `ctm_sync` in the same session. The parent agent must pass this value into `ctm_sync` (or derive it consistently from context) so all events in one chat share one id and events from other chats do not.
-3. **Resolve or create the AI IDE workflow** (one workflow per distinct `chat_session_id`):
-   - Resolve the SRAI project: `find_project_by_name` with `name="<SRAI_PROJECT_NAME>"`. If missing, `list_projects` (respecting org constraints), then `create_project` if needed. Obtain `project_id` as required by MCP tools.
-   - List or search AI IDE workflows for that project (use the MCP tool provided, e.g. listing workflows filtered by project). Find a workflow whose **description** (or other documented metadata field) contains the exact marker: `chat_session_id:<the same string as in the payload>`.
-   - **If a matching workflow exists:** use its `workflow_id` for the event.
-   - **If none exists:** call `create_ai_ide_workflow` with:
-     - `project_id`
-     - `name`: a short, meaningful heading derived from the **high-level feature or topic** being worked on in this session (e.g. `"User Auth Hardening"`, `"Payment Gateway Integration"`, `"API Rate Limiting"`, `"File Upload Security"`). Use 2–5 words, title-case. Do **not** use sequential labels like `session1/session2`. If no clear feature context is available, use a brief description of the dominant threat area instead.
-     - `description`: must include `chat_session_id:<chat_session_id>` so future syncs can attach to this workflow. Add a brief human-readable note if helpful. Do not add the word ctm anywhere.
-   - Store the returned `workflow_id` for the upload step.
-4. **Resolve developer identity from the API** — Call `get_current_user` (or the equivalent user-identity tool exposed by `security-review-mcp`) to retrieve the authenticated user's name and email. Use the values returned by the API as-is for `developer_name` and `developer_email` in the payload.
-   - **Never use placeholder values** such as `"IDE Agent"`, `"agent@local"`, `"unknown"`, `"AI"`, or any other invented string for these fields.
-   - **Never accept identity values passed in from the parent agent prompt** — always re-resolve from the API directly in this step; the API is the only authoritative source.
-   - If the API call fails or returns empty values, leave `developer_name` and `developer_email` as empty strings `""`. Do not substitute a fallback placeholder.
-5. **Identify guardrails for the payload** — Do **not** call `get_guardrails` or `get_guardrail_by_id` here. Guardrails were already shortlisted earlier (per the Vibe Guardrails rule and the guardrails-selection skill) and applied during code generation. From the parent agent context, identify:
-   - Which **existing** guardrails were shortlisted earlier from `get_guardrails` and then hydrated via `get_guardrail_by_id`.
-   - Which of those shortlisted existing guardrails were applied to the code in this session.
-   - Which guardrails the IDE agent **created on the fly** (`ide_generated`) based on gaps found during threat modeling or code review.
-   Include all of these in the `guardrails_applied` payload field. The shortlisted existing guardrails selected earlier are mandatory input to `ctm_sync`; do not re-fetch or re-call guardrail tools here.
-6. **Build the event payload** — Construct a JSON object for `create_ai_ide_event` conforming to the **Event Payload Schema** below.
-7. **Upload the payload** using `security-review-mcp`:
-   - Call `create_ai_ide_event` with the JSON payload.
-   - **Stop here.** Do not push a separate project/code profile as part of this workflow; profile and default guardrail pack uploads are handled by the init-time guardrails profiler (or manual profile commands), not per CTM sync.
+0. Verify `sync_ai_ide_markdown` exists in `security-review-mcp`.
+1. Read the parent agent context and extract the latest threat model details, guardrail outcomes, and grounded code snippets from the actual work completed in this session.
+2. **Chat session identity (required)** — The markdown MUST include a stable `chat_session_id` for the current IDE chat session:
+   - Use a session identifier supplied by the host environment when one exists (for example, the IDE conversation or session id).
+   - If none exists, use a single UUID (or equivalent) generated **once** at the start of this chat and reused for every `ctm_sync` in the same session.
+   - Put `chat_session_id` in frontmatter whenever possible. The value must exist somewhere in the markdown even if frontmatter is unavailable.
+3. **Create a structured markdown artifact** — `ctm_sync` is now a thin sync shim. Do not build a JSON payload and do not perform workflow lookup or creation client-side. Instead, write a `.md` file under `vibereview/` so all sync artifacts stay in one predictable place. Create the directory if it does not already exist. The markdown file should give the server everything it needs to extract the structured event.
+4. **Populate the markdown with grounded content**:
+   - Include the exact shortlisted existing guardrails selected earlier plus any `ide_generated` guardrails created during the session.
+   - Use real code snippets from the files changed or inspected in this session. Never invent code or mitigation text.
+   - Keep threat names, severities, PWNISMS categories, guardrail satisfaction, and OWASP mappings aligned with the actual work performed.
+5. **Upload the markdown**:
+   - Call `sync_ai_ide_markdown` with the markdown artifact.
+   - The server is responsible for normalizing author identity, deriving a workflow name from the title when needed, and extracting structured output from the markdown.
+6. **Stop there** — Do not call `create_ai_ide_event`, `create_ai_ide_workflow`, or client-side user identity tools from `ctm_sync`.
 
 ---
 
-## Event Payload Schema
-
-The `create_ai_ide_event` payload MUST be a JSON object with the following structure. Use this exact schema — do not add, rename, or omit required keys.
-
-```json
-{
-  "workflow_id": "<string — resolved or newly created AI IDE workflow id>",
-  "chat_session_id": "<string — stable session identifier, same for all events in this chat>",
-  "title": "<string — concise title describing what was threat-modeled or implemented, 5-15 words>",
-  "summary": "<string — 2-5 sentence summary of the threat model findings, key risks identified, mitigations applied, and any guardrails enforced>",
-  "developer_name": "<string — from API/user context provided by MCP or host runtime>",
-  "developer_email": "<string — from API/user context provided by MCP or host runtime>",
-  "threats_mitigated": [
-    {
-      "threat_name": "<string — short threat title>",
-      "pwnisms_category": "<string — one of: Product, Workload, Network, IAM, Secrets, Monitoring, Supply Chain>",
-      "severity": "<string — Critical | High | Medium | Low>",
-      "mitigation_applied": "<string — what was done to address the threat>",
-      "code_snippet": {
-        "file_path": "<string — relative path to the actual source file where mitigation is implemented>",
-        "language": "<string — programming language>",
-        "snippet": "<string — the exact source code lines implementing the mitigation, max 30 lines, must be grounded in the actual codebase not invented>",
-        "explanation": "<string — how this specific code addresses the threat>"
-      }
-    }
-  ],
-  "best_practises_achieved": [
-    "<string — each entry is a concise statement of a security best practice that was followed during implementation>"
-  ],
-  "secure_code_snippets": [
-    {
-      "file_path": "<string — relative path to the file>",
-      "language": "<string — programming language>",
-      "snippet": "<string — the security-relevant code snippet, max 50 lines>",
-      "explanation": "<string — why this snippet is security-relevant and what it protects against>"
-    }
-  ],
-  "guardrails_applied": [
-    {
-      "title": "<string — guardrail title>",
-      "rule_type": "<string — must | must_not>",
-      "category": "<string | null — grouping label>",
-      "instruction": "<string — the actionable coding directive>",
-      "source": "<string — 'existing' if selected earlier from project guardrails, 'ide_generated' if newly created by the IDE agent>",
-      "satisfied": "<boolean — true if the guardrail was fully satisfied, false if partially or not satisfied>",
-      "notes": "<string — optional: how it was applied, why it could not be fully satisfied, or rationale for a new guardrail>"
-    }
-  ],
-  "owasp_top_10_2025_mappings": [
-    {
-      "category_id": "<string — OWASP Top 10 2025 category ID, e.g. A01>",
-      "category_name": "<string — OWASP Top 10 2025 category name, e.g. Broken Access Control>"
+## Markdown Contract
+
+The markdown file must be a `.md` document written under `vibereview/`, with frontmatter when available and clear, structured sections underneath. Keep the structure deterministic so the server can parse it reliably.
+
+Recommended path pattern:
+
+```text
+vibereview/<chat_session_id>-<slugified-title-or-event-name>.md
+```
+
+If a safe filename cannot be derived, use any stable `.md` filename inside `vibereview/`.
+
+### Frontmatter
+
+Use YAML frontmatter at the top of the file whenever possible:
+
+```yaml
+---
+chat_session_id: "<required stable session id>"
+workflow_name: "<optional short workflow name>"
+workflow_description: "<optional workflow description>"
+title: "<required event title if event_name is omitted>"
+event_name: "<required event name if title is omitted>"
+summary: "<required concise summary>"
+---
+```
+
+Rules:
+
+- `chat_session_id` must exist somewhere in the markdown, but frontmatter is preferred.
+- `workflow_name` is optional. If omitted, the server derives it from the title.
+- `workflow_description` is optional.
+- Either `event_name` or `title` must exist. Including both is allowed.
+- `summary` must exist.
+- `developer_name` and `developer_email` in the markdown are ignored. The server always uses the authenticated API user.
+
+### Body sections
+
+Use clear Markdown headings. The exact wording below is preferred because it keeps parsing simple and consistent.
+
+#### Best Practices Achieved
+
+Use plain bullet strings:
+
+```md
+## Best Practices Achieved
+
+- Enforced server-side authorization before updating workflow state.
+- Used parameterized queries for threat-model persistence.
+```
+
+Internally the server accepts both `best_practises_achieved` and `best_practices_achieved`, but authored markdown should prefer a normal `Best Practices Achieved` section with bullets.
+
+#### Threats Mitigated
+
+Each threat entry should include all of the following:
+
+- `threat_name`
+- `pwnisms_category`
+- `severity`
+- `mitigation_applied`
+- grounded code snippet info if available
+
+Preferred structure:
+
+```md
+## Threats Mitigated
+
+### Threat 1
+- threat_name: Missing authorization check on workflow sync endpoint
+- pwnisms_category: IAM
+- severity: High
+- mitigation_applied: Added server-side authorization before allowing markdown sync writes.
+- file_path: src/routes/sync.js
+- language: javascript
+- snippet: |
+    if (!user || !user.canSyncWorkflows) {
+      throw new ForbiddenError('Not allowed to sync workflow markdown');
     }
-  ]
-}
+- explanation: Prevents unauthorized users from creating or updating AI IDE sync events.
+```
+
+Notes:
+
+- Snippets must be real code from the repo or actual generated output, not invented text.
+- If no code snippet exists for a threat, omit the snippet block and explain the mitigation in prose.
+
+#### Secure Code Snippets
+
+Include security-relevant snippets that may or may not map 1:1 with a threat:
+
+```md
+## Secure Code Snippets
+
+### Snippet 1
+- file_path: src/server/markdown-sync.ts
+- language: typescript
+- snippet: |
+    const markdown = await fs.readFile(inputPath, 'utf8');
+    await securityReview.syncAiIdeMarkdown({ markdown });
+- explanation: Sends the structured markdown artifact directly to the server-side sync pipeline.
+```
+
+#### Guardrails Applied
+
+Each guardrail should include:
+
+- `title`
+- `rule_type` as `must` or `must_not`
+- `source` as `existing` or `ide_generated`
+- `satisfied` as `true` or `false`
+
+Preferred structure:
+
+```md
+## Guardrails Applied
+
+### Guardrail 1
+- title: Enforce authorization on workflow updates
+- rule_type: must
+- category: authorization
+- instruction: Require an authenticated, authorized user before mutating workflow records.
+- source: existing
+- satisfied: true
+- notes: Applied in the server-side markdown sync handler.
 ```
 
-### Field rules
+The exact shortlist from earlier in the session must be carried forward. Do not call `get_guardrails` or `get_guardrail_by_id` inside `ctm_sync`.
+
+#### OWASP Top 10 2025 Mappings
 
-| Field | Required | Notes |
-|---|---|---|
-| `workflow_id` | Yes | From step 3 |
-| `chat_session_id` | Yes | From step 2 |
-| `title` | Yes | 5-15 words, descriptive |
-| `summary` | Yes | 2-5 sentences |
-| `developer_name` | Yes | From API/user context (never read from git config) |
-| `developer_email` | Yes | From API/user context (never read from git config) |
-| `threats_mitigated` | Yes | Array, may be empty `[]` if no threats were identified. Each entry must include a `code_snippet` grounded in actual source code |
-| `best_practises_achieved` | Yes | Array of strings, may be empty `[]` |
-| `secure_code_snippets` | Yes | Array, may be empty `[]` |
-| `guardrails_applied` | Yes | Array of all guardrails enforced during this session — both existing ones shortlisted earlier from project guardrails and new ones the IDE agent created. Use `source` to distinguish origin. Empty `[]` if none |
-| `owasp_top_10_2025_mappings` | Yes | Array of OWASP Top 10 2025 category objects (`category_id` + `category_name`) relevant to the threats and mitigations in this event. May be empty `[]` if no mapping applies |
+Use exact IDs and names:
 
-### OWASP Top 10 2025 Reference
+```md
+## OWASP Top 10 2025 Mappings
 
-Use the following IDs and names exactly when populating `owasp_top_10_2025_mappings`:
+- A01: Broken Access Control
+- A04: Cryptographic Failures
+```
+
+Allowed values:
 
-| `category_id` | `category_name` |
+| ID | Name |
 |---|---|
 | `A01` | Broken Access Control |
 | `A02` | Security Misconfiguration |
@@ -129,27 +182,34 @@ Use the following IDs and names exactly when populating `owasp_top_10_2025_mappi
 | `A09` | Security Logging and Alerting Failures |
 | `A10` | Mishandling of Exceptional Conditions |
 
-### Constraints
+---
 
-- Every `threats_mitigated` entry must map to one of the 7 PWNISMS categories.
-- Every `threats_mitigated` entry must include a `code_snippet`. The snippet must be taken from the actual source code written or modified in this session — never fabricated. If no code was written for a threat (e.g. it was addressed architecturally), set `snippet` to an empty string and explain in `explanation`.
-- `secure_code_snippets` must not exceed 50 lines per snippet; `threats_mitigated[].code_snippet.snippet` must not exceed 30 lines; truncate with a comment if needed.
-- Do not call `get_guardrails` or `get_guardrail_by_id` during CTM sync. Guardrails are shortlisted once earlier in the session; identify which ones were applied from the parent agent context.
-- Guardrails shortlisted earlier by the IDE must be included in `guardrails_applied` even when some were only partially satisfied. Use `satisfied: false` plus `notes` instead of silently dropping them.
-- `guardrails_applied` entries with `source: "existing"` must reference guardrails by the exact `title` they had when fetched at session start.
-- `guardrails_applied` entries with `source: "ide_generated"` are new guardrails the IDE agent created based on gaps found during threat modeling or code review.
-- `developer_name` and `developer_email` must be resolved via `get_current_user` (or equivalent) in step 4 — the API is the only source. Never use placeholder strings (`"IDE Agent"`, `"agent@local"`, `"unknown"`, `"AI"`, etc.) and never accept values for these fields from the parent agent prompt. If the API returns nothing, send empty strings.
-- `owasp_top_10_2025_mappings` entries must use the exact `category_id` and `category_name` values from the OWASP Top 10 2025 Reference table above. Do not invent or abbreviate category names.make sure the ones being sent in the payload are revelant to that event.
-- Never invent values for any field; use empty strings or empty arrays when data is unavailable.
-- Never omit `chat_session_id` from the payload.
+## Constraints
+
+- The artifact written by `ctm_sync` must be a `.md` file under `vibereview/`.
+- `chat_session_id` must never be omitted.
+- `summary` must never be omitted.
+- `event_name` or `title` must exist.
+- `workflow_name` and `workflow_description` are optional.
+- `developer_name` and `developer_email` should not influence sync behavior; the server ignores them.
+- Every threat entry must include `threat_name`, `pwnisms_category`, `severity`, and `mitigation_applied`.
+- PWNISMS categories must match the supported set: `Product`, `Workload`, `Network`, `IAM`, `Secrets`, `Monitoring`, `Supply Chain`.
+- `severity` should be one of `Critical`, `High`, `Medium`, or `Low`.
+- Guardrails must include `title`, `rule_type`, `source`, and `satisfied`.
+- `rule_type` must be `must` or `must_not`.
+- `source` must be `existing` or `ide_generated`.
+- `satisfied` must be `true` or `false`.
+- OWASP mappings must use the exact IDs and names listed above.
+- Snippets must be grounded in real code. Never fabricate examples just to fill the markdown.
+- Do not call client-side workflow creation, event creation, or developer identity tools from `ctm_sync`.
 
 ---
 
 ## Output Contract
 
-- Never skip upload when a threat model exists.
-- Never invent missing values; use empty strings/arrays if data is unavailable.
-- Never omit `chat_session_id` from the payload.
+- Never skip sync when a threat model or guardrail-compliance update exists.
+- Never invent missing values; omit optional fields or use concise prose when exact structured data is unavailable.
 - Return a compact confirmation after upload including:
-  - Whether an existing workflow was reused or a new named workflow was created
-  - Count of guardrails applied (existing vs IDE-generated)
+  - the markdown file path used for sync, which should point inside `vibereview/`
+  - whether `workflow_name` was explicit or left for server-side derivation
+  - count of guardrails included (existing vs IDE-generated)

package/src/generators/rules/ctm_sync_rule.md

@@ -67,14 +67,15 @@ This includes both:
      - Where the latest threat content can be found (e.g., "from this conversation" or "from the last threat modeling step")
      - The `chat_session_id` value to use for this sync
      - Whether guardrails were applied (existing and/or IDE-generated)
-   - **Do NOT include developer name or email in the handoff prompt.** The `ctm_sync` agent resolves user identity directly from the API. Passing identity values from the parent agent — including any placeholders like `"IDE Agent"` or `"agent@local"` — will cause them to be used incorrectly. Leave identity resolution entirely to `ctm_sync`.
+     - That `ctm_sync` should write a structured `.md` artifact and upload it via `sync_ai_ide_markdown`
+   - **Do NOT include developer name or email in the handoff prompt.** Any identity fields in the markdown are ignored server-side; the authenticated API user is authoritative.
 
    **Example invocation (conceptual, not literal code):**
 
    Use Task tool with:
    - subagent_type: "ctm_sync"
    - description: "Sync latest threat model for <system/component>"
-   - prompt: Brief summary of what was threat-modeled, what artifacts were produced (threat scenarios, countermeasures, components, data dictionary, guardrails applied/proposed, etc.), and that the agent should upload/update CTM data accordingly.
+   - prompt: Brief summary of what was threat-modeled, what artifacts were produced (threat scenarios, countermeasures, components, data dictionary, guardrails applied/proposed, etc.), and that the agent should write the sync markdown and upload it accordingly.
    - readonly: false (it must be allowed to write/update CTM data)
 
 3. Let `ctm_sync` complete its work

package/src/generators/rules/guardrails-init-profile.md

@@ -33,9 +33,9 @@ You can still sign in manually with `agent login` (or `cursor-agent login`). To
 
 ## Claude Code CLI (scripted)
 
-From the repo root, non-interactive runs should execute with the project settings file and the Haiku model for this profiling pass:
+From the repo root, non-interactive runs should execute with the project settings file, the project `.mcp.json` server config, explicit MCP-only loading, bypassed tool prompts for the profiling pass, and the Haiku model:
 
-`claude -p "<your profiling instructions>" --settings .claude/settings.json --model haiku`
+`claude -p "<your profiling instructions>" --settings .claude/settings.json --mcp-config "$(cat .mcp.json)" --strict-mcp-config --permission-mode bypassPermissions --model haiku`
 
 During `securityreview-kit init`, choose **Yes** when asked to run Claude Code login, or pass **`--profiler-claude-login`** with **`--profile-repo`** so `claude auth login` and profiling stay in one run.
 

package/src/generators/rules/guardrails_rule.md

@@ -81,7 +81,7 @@ Guardrails are living artifacts. The IDE agent can create, apply, and update the
 
 - **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 via CTM sync 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 — flow into the single `guardrails_applied` array in the CTM sync payload.
+- All guardrails — existing and IDE-generated — must be preserved in the CTM sync markdown under a single `Guardrails Applied` section that the server can normalize into `guardrails_applied`.
 
 ---
 

package/src/generators/rules/hooks.json

@@ -3,7 +3,7 @@
   "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. **ctm_sync (last)** - Push payload to SRAI only after implementation is done. Invoke ctm_sync agent (Task tool, subagent_type=ctm_sync) as the final step. Include the exact shortlisted guardrails from earlier plus any IDE-generated guardrails in the guardrails_applied payload field; do not query again during ctm_sync. See .cursor/agents/ctm_sync.md and .cursor/rules/ctm_sync_rule.mdc.\\n\\nNo blocking. No deferral. Guardrails enforce secure code; threat modeling guides the design; ctm_sync runs last to push to SRAI. Both ctm_sync and guardrail compliance are mandatory and should be part of your to-do.\"}'",
+        "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. **ctm_sync (last)** - Write a structured `.md` sync artifact and push it to SRAI only after implementation is done. Invoke ctm_sync agent (Task tool, subagent_type=ctm_sync) as the final step. Include the exact shortlisted guardrails from earlier plus any IDE-generated guardrails in the markdown; do not query again during ctm_sync. See .cursor/agents/ctm_sync.md and .cursor/rules/ctm_sync_rule.mdc.\\n\\nNo blocking. No deferral. Guardrails enforce secure code; threat modeling guides the design; ctm_sync runs last to sync the markdown artifact to SRAI. Both ctm_sync and guardrail compliance are mandatory and should be part of your to-do.\"}'",
         "timeout": 5
       }
     ]

package/src/generators/rules/skill.md

@@ -209,12 +209,13 @@ When discussing designs before code exists:
 
 ### What CTM sync uploads
 
-The `ctm_sync` agent builds and pushes an event payload containing:
+The `ctm_sync` agent writes a structured `.md` artifact 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**: security patterns followed during implementation
 - **Secure code snippets**: security-relevant code with explanations
 - **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 invoke
 
@@ -223,7 +224,7 @@ Use the host's `ctm_sync` agent/workflow with:
 - The `chat_session_id` for workflow routing
 - Whether this is a new threat model or an update
 
-See `{{CTM_SYNC_AGENT_PATH}}` for the full workflow and payload schema.
+See `{{CTM_SYNC_AGENT_PATH}}` for the full workflow and markdown schema.
 
 ---
 

package/src/generators/rules/vscode.js

@@ -23,7 +23,7 @@ function getCopilotSessionHookContent() {
         '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. Run the ctm_sync custom agent using .github/agents/ctm_sync.agent.md after threat modelling or guardrail enforcement. Reuse the exact guardrail shortlist; do not re-query guardrails during CTM sync.',
+        '4. Run the ctm_sync custom agent using .github/agents/ctm_sync.agent.md after threat modelling or guardrail enforcement. Reuse the exact guardrail shortlist; do not re-query guardrails during CTM sync. The agent should write a structured .md sync artifact and upload it with sync_ai_ide_markdown.',
         '',
         'Do not use project-profile exploration tools during normal coding tasks. No blocking and no deferral: guardrails first, PWNISMS second, implementation third, ctm_sync last.',
     ].join('\n');

package/src/generators/rules/vscode.test.js

@@ -36,6 +36,14 @@ test('VS Code Copilot generator writes instructions, skills, agent, and hooks',
     assert.match(threatSkill, /\.github\/agents\/ctm_sync\.agent\.md/);
     assert.doesNotMatch(threatSkill, /get_project_profile_description/);
 
+    const agent = readFileSync(join(cwd, '.github/agents/ctm_sync.agent.md'), 'utf8');
+    assert.match(agent, /Configured SRAI project name: `SmokeProject`/);
+    assert.match(agent, /sync_ai_ide_markdown/);
+    assert.match(agent, /structured markdown artifact/i);
+    assert.match(agent, /OWASP Top 10 2025 Mappings/);
+    assert.match(agent, /vibereview\//);
+    assert.doesNotMatch(agent, /Call `create_ai_ide_event` with/i);
+
     const hooks = JSON.parse(readFileSync(join(cwd, '.github/hooks/srai-session-policy.json'), 'utf8'));
     assert.equal(hooks.hooks.SessionStart[0].type, 'command');
 });

package/src/utils/constants.js

@@ -17,8 +17,8 @@ export const TARGETS = {
     },
     claude: {
         name: 'Claude Code',
-        mcpConfigPath: '.claude/settings.json',
-        rulePath: 'CLAUDE.md',
+        mcpConfigPath: '.mcp.json',
+        rulePath: '.claude/CLAUDE.md',
         ruleMode: 'append',
         detectDirs: ['.claude'],
     },

package/src/utils/profiler-agent.js

@@ -213,6 +213,21 @@ export function buildCodexConfigOverrides(cwd, overrides = {}) {
     ];
 }
 
+export function buildClaudeAdditionalMcpConfig(cwd) {
+    const projectMcp = readJson(join(cwd, '.mcp.json'));
+    const sourceServer = projectMcp?.mcpServers?.[MCP_SERVER_NAME];
+
+    if (!sourceServer || typeof sourceServer !== 'object') {
+        return null;
+    }
+
+    return JSON.stringify({
+        mcpServers: {
+            [MCP_SERVER_NAME]: sourceServer,
+        },
+    });
+}
+
 export function pickProfilerAgentTarget(targets) {
     for (const t of PREFERRED_ORDER) {
         if (targets.includes(t)) {
@@ -288,7 +303,26 @@ export function runProfilerAgent(
             return { ok: false, message: 'claude not on PATH' };
         }
         const settingsPath = join(cwd, '.claude', 'settings.json');
-        const args = ['-p', '--settings', settingsPath, '--model', modelOverride || 'haiku'];
+        const mcpConfig = buildClaudeAdditionalMcpConfig(cwd);
+        if (!mcpConfig) {
+            return {
+                ok: false,
+                message:
+                    'Claude profiling needs the SRAI MCP server in .mcp.json. Re-run init with MCP installation enabled.',
+            };
+        }
+        const args = [
+            '-p',
+            '--settings',
+            settingsPath,
+            '--mcp-config',
+            mcpConfig,
+            '--strict-mcp-config',
+            '--permission-mode',
+            'bypassPermissions',
+            '--model',
+            modelOverride || 'haiku',
+        ];
         if (streamProgress) {
             args.push('--output-format', 'stream-json', '--include-partial-messages', '--include-hook-events', '--verbose');
         }