Vibereview Sync

VibeReview Markdown Sync

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.

Core Rules

1. Write the artifact under vibereview/.
2. Author the markdown from the current task context only.
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:

vibereview/<chat_session_id>-<slugified-title-or-event-name>.md

6. Validate the markdown before calling sync_ai_ide_markdown.
7. If sync fails, leave the file on disk and report the failure clearly.

Why You Must Not Read Sibling Files

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:

• the current user request
• the current session context
• the threat model produced in this task
• the exact guardrail shortlist preserved in context
• the real code snippets touched in this task

Required Authoring Workflow

Step 1: Collect the required inputs

Before writing the markdown, confirm you have:

• a stable chat_session_id
• a concise summary
• either title or event_name
• the exact existing guardrails shortlisted earlier
• any ide_generated guardrails created during this task
• grounded threat entries
• grounded code snippets from actual files
• exact OWASP Top 10 2025 mappings when applicable

If any required field is missing, resolve it from current context before writing. Do not invent data.

Step 2: Write YAML frontmatter

The frontmatter should use this shape:

---
chat_session_id: "cursor-chat-7f3b2f44-8c4d-4d4a-9f1e-2b6a4c91b201"
workflow_name: "User Auth Hardening"
workflow_description: "Security improvements for auth flow handling in the current IDE session"
event_name: "Hardened AI IDE sync ingestion and workflow reuse"
summary: "This change moved AI IDE sync handling to the server so workflow resolution and event creation happen deterministically after markdown upload. We enforced stable session identity, validated required event fields, and added structured extraction for threats, guardrails, secure code snippets, and OWASP mappings. The endpoint now accepts markdown, returns immediately, and continues processing in the background."
external_id: "ai-ide-sync-2026-04-21-001"
---

Frontmatter rules

• chat_session_id is required.
• summary is required.
• At least one of event_name or title is required.
• workflow_name is optional.
• workflow_description is optional.
• external_id is optional.
• If workflow_name is omitted, the server may derive it from the title.
• Do not rely on developer_name or developer_email in markdown. The server ignores them when authenticated API identity exists.

Required Markdown Structure

Use this top-level shape:

# AI IDE Sync Event

## Event Identity
...

## Summary
...

# Threats Mitigated
...

# Best Practices Achieved
...

# Secure Code Snippets
...

# Guardrails Applied
...

# OWASP Top 10 2025 Mappings
...

The exact heading levels may vary slightly, but the section names should stay stable and obvious.

Event Identity Section

Preferred structure:

## Event Identity

- chat_session_id: `cursor-chat-7f3b2f44-8c4d-4d4a-9f1e-2b6a4c91b201`
- workflow_name: `User Auth Hardening`
- event_name: `Hardened AI IDE sync ingestion and workflow reuse`
- external_id: `ai-ide-sync-2026-04-21-001`

Summary Section

Repeat the summary in prose under ## Summary.

Threats Mitigated Section

Each threat entry must include:

• threat_name
• pwnisms_category
• severity
• mitigation_applied

When code exists, include a ### Code Snippet subsection with:

• file_path
• language
• explanation
• a fenced code block containing real code

Preferred example:

# Threats Mitigated

## Threat 1

- threat_name: Missing session identity can attach events to the wrong workflow
- pwnisms_category: IAM
- severity: High
- mitigation_applied: The server now requires a stable `chat_session_id` and uses it to resolve or create the workflow before persisting the event.

### Code Snippet

- file_path: `app/api/external_ai_ide.py`
- language: `python`
- explanation: This prevents ambiguous workflow association and ensures repeated syncs from the same IDE chat session map to the same workflow.

```python
chat_session_id = str(
    frontmatter.get("chat_session_id")
    or extracted.chat_session_id
    or ""
).strip()

if not chat_session_id:
    raise ValueError("chat_session_id could not be resolved from markdown content")
```

Threat authoring rules

• Keep each threat clearly separated.
• Do not collapse multiple threats into one malformed block.
• Always close fenced code blocks.
• Never let prose spill into the next threat entry.
• PWNISMS categories must be one of:
  • Product
  • Workload
  • Network
  • IAM
  • Secrets
  • Monitoring
  • Supply Chain
• Severity should be one of:
  • Critical
  • High
  • Medium
  • Low

Best Practices Achieved Section

Use structured practice entries, not plain bullet-only lists.

# Best Practices Achieved

## Practice 1
- practice_name: Stable workflow correlation
- description: Used a stable chat session identifier to ensure repeated syncs map to the same workflow.
- category: identity

## Practice 2
- practice_name: Server-side workflow orchestration
- description: Kept workflow and event creation on the server instead of relying on IDE-side orchestration.
- category: design

## Practice 3
- practice_name: Required field validation
- description: Validated required event identity fields before persisting security review data.
- category: validation

Best practice rules

• Each entry should be introduced with a stable heading such as ## Practice 1, ## Practice 2, and so on.
• Each entry must include:
  • practice_name
  • description
  • category
• Keep the values concise and grounded in the actual work completed.
• Do not turn this section into freeform paragraphs.
• Do not reduce this section to plain bullet statements without field names.

Secure Code Snippets Section

Each snippet entry should include:

• file_path
• language
• explanation
• a fenced code block with real code

Preferred example:

# Secure Code Snippets

## Snippet 1

- file_path: `app/api/external_ai_ide.py`
- language: `python`
- explanation: This is security-relevant because it isolates background processing from the request lifecycle and ensures the authenticated developer identity is propagated server-side.

```python
async def _process_ai_ide_markdown_ingestion(
    *,
    project_id: int,
    ingestion_id: str,
    filename: str,
    markdown_text: str,
    developer_name: str,
    developer_email: str,
) -> None:
    logger.info(
        "Starting AI IDE markdown ingestion %s for project %s",
        ingestion_id,
        project_id,
    )
```

Secure snippet rules

• Snippets must be real code, not invented examples.
• Prefer snippets already cited in threat mitigations when they are strongly relevant.
• Use fenced code blocks.
• Keep snippets focused and bounded.

Guardrails Applied Section

Each guardrail entry must include:

• title
• rule_type
• category
• instruction
• source
• satisfied
• notes

Preferred example:

# Guardrails Applied

## Guardrail 1

- title: Require stable AI IDE session identity
- rule_type: must
- category: Identity
- instruction: Every AI IDE sync markdown must include a stable chat_session_id so workflow association is deterministic.
- source: existing
- satisfied: true
- notes: Enforced during markdown ingestion before workflow lookup or workflow creation.

Guardrail rules

• rule_type must be must or must_not.
• source must be existing or ide_generated.
• satisfied must be true or false.
• Do not drop shortlisted existing guardrails even when unsatisfied.
• If a guardrail was not fully satisfied, keep it and explain why in notes.

OWASP Top 10 2025 Mappings Section

Use exact IDs and names. Preferred structures:

# OWASP Top 10 2025 Mappings

- A07: Authentication Failures
- A06: Insecure Design
- A10: Mishandling of Exceptional Conditions

or

# OWASP Top 10 2025 Mappings

- category_id: A07
  category_name: Authentication Failures
- category_id: A06
  category_name: Insecure Design

Allowed values:

• A01 Broken Access Control
• A02 Security Misconfiguration
• A03 Software Supply Chain Failures
• A04 Cryptographic Failures
• A05 Injection
• A06 Insecure Design
• A07 Authentication Failures
• A08 Software or Data Integrity Failures
• A09 Security Logging and Alerting Failures
• A10 Mishandling of Exceptional Conditions

Validation Checklist Before Sync

Before calling sync_ai_ide_markdown, verify all of the following:

• 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.
• The Event Identity section exists.
• The Summary section exists.
• The Threats Mitigated section exists.
• The Best Practices Achieved section exists.
• The Secure Code Snippets section exists.
• The Guardrails Applied section exists.
• The OWASP Top 10 2025 Mappings section exists.
• Every threat entry is structurally complete.
• Every code fence is closed.
• Every snippet is grounded in real code.
• Every guardrail entry is structurally complete.
• OWASP IDs and names are exact.

Final Step

After validation:

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.