@securityreviewai/vibereview-cli 0.1.4 → 0.1.5

package/README.md

@@ -110,18 +110,19 @@ VibeReview creates:
 ├── config.json
 ├── profile.json
 ├── guardrails.yml
+├── guardrails.md
 ├── state.json
 ├── gates/
 └── reports/
 ```
 
-The full catalog and generator skill remain inside the installed npm package. They are not copied into the target workspace. `guardrails.yml` contains only matched baseline, generated code-specific, and user-maintained custom rules.
+The full catalog and generator skill remain inside the installed npm package. They are not copied into the target workspace. `guardrails.yml` is the canonical machine-readable source containing matched baseline, generated code-specific, and user-maintained custom rules. `guardrails.md` is an automatically regenerated, table-formatted view for humans; do not edit it directly.
 
 ## Code-specific generation
 
 VibeReview selects at most 30 security-relevant source files, capped at 80 KB in total and 24 KB per file. It excludes common dependency/build directories, provider configuration directories, `.env` files, credential-like paths, private keys, lockfiles, binary files, and symbolic links. The selected contents are sent through the configured provider CLI under that provider's own account and data-handling terms.
 
-The provider runs in a temporary empty directory rather than the repository. Cursor uses plan mode and sandboxing; Codex uses an ephemeral read-only execution; Claude Code runs in plan mode with tools disabled and no persisted session; Copilot runs non-interactively with only its read tool exposed to the empty directory. The model receives the bounded evidence inline and cannot edit the repository through this job.
+The provider runs in a temporary empty directory rather than the repository. Cursor uses read-only ask mode and sandboxing; Codex uses an ephemeral read-only execution; Claude Code runs in plan mode with tools disabled and no persisted session; Copilot runs non-interactively with only its read tool exposed to the empty directory. The model receives the bounded evidence inline and cannot edit the repository through this job.
 
 Generated output must pass the bundled JSON schema. Every rule needs an exact evidence path from the supplied bundle, generic or baseline-duplicate rules are removed, and invalid output gets one repair attempt. A successful regeneration atomically replaces only `code_specific`; baseline and custom rules remain intact.
 
@@ -157,7 +158,7 @@ Reports live at:
 
 The IDE agent writes the report directly; the CLI does not generate a JSON scan. The session ID is the complete file identity, so feature title changes cannot create another report accidentally. A new IDE chat creates one Markdown file. Every security-relevant follow-up reads and rewrites that same file. The agent may add, revise, reorder, or remove content so the report describes the latest cumulative state rather than preserving a chronological log.
 
-Reports retain the established VibeReview fields in readable sections: summary, scope and assumptions, threats mitigated, best practices achieved, OSV.dev dependency security, secure code changes, guardrails applied, OWASP mappings, verification, and residual risks. YAML frontmatter carries session identity, provider, status, and timestamps.
+Reports retain the established VibeReview fields in table-formatted sections: scope and assumptions, threats mitigated, best practices achieved, OSV.dev dependency security, secure code changes, guardrails applied, OWASP mappings, verification, and residual risks. YAML frontmatter carries session identity, provider, status, and timestamps.
 
 ## Deterministic detection
 

package/dist/src/commands/generate.js

@@ -57,5 +57,6 @@ export async function generateCommand(options) {
     if (options.verbose)
         ui.detail(`  Evidence bundle: ${result.evidence.total_bytes.toLocaleString()} bytes; ${result.evidence.omitted_file_count} candidate files omitted`);
     ui.detail(`Guardrails: ${path.relative(root, outputPath)}`);
+    ui.detail(`Readable: ${path.relative(root, path.join(root, ".vibereview", "guardrails.md"))}`);
 }
 //# sourceMappingURL=generate.js.map

package/dist/src/commands/init.js

@@ -118,6 +118,7 @@ export async function initCommand(options) {
     ui.info("\nWorkspace configured.");
     ui.detail(`Profile:    ${path.relative(root, path.join(root, ".vibereview", "profile.json"))}`);
     ui.detail(`Guardrails: ${path.relative(root, path.join(root, ".vibereview", "guardrails.yml"))}`);
+    ui.detail(`Readable:   ${path.relative(root, path.join(root, ".vibereview", "guardrails.md"))}`);
     ui.step(`Installed local security workflow for ${PROVIDER_NAMES[provider]}`);
     ui.detail(`Reports:    ${path.relative(root, path.join(root, ".vibereview", "reports"))}/*.md`);
     ui.info("\nVibeReview is ready. Restart the IDE agent if it is already running.\n");

package/dist/src/core/guardrail-markdown.js

@@ -0,0 +1,58 @@
+export function renderGuardrailsMarkdown(file) {
+    const sections = [
+        "<!-- Generated by VibeReview. Do not edit this file; edit guardrails.yml or use the CLI. -->",
+        `# VibeReview Guardrails — ${escapeInline(file.project || "Workspace")}`,
+        "",
+        "> Human-readable view generated from `.vibereview/guardrails.yml`. The YAML file remains the canonical source used by the CLI and IDE agents.",
+        "",
+        "## Overview",
+        "",
+        "| Source | Count |",
+        "|---|---:|",
+        `| Baseline packs | ${file.baseline.length} |`,
+        `| Code-specific | ${file.code_specific.length} |`,
+        `| Custom | ${file.custom.length} |`,
+        `| **Total** | **${file.baseline.length + file.code_specific.length + file.custom.length}** |`,
+        "",
+        `Generated: ${escapeInline(file.generated_at || "unknown")}`,
+        "",
+        renderSection("Baseline Guardrails", file.baseline),
+        renderSection("Code-Specific Guardrails", file.code_specific),
+        renderSection("Custom Guardrails", file.custom),
+    ];
+    return `${sections.join("\n").trimEnd()}\n`;
+}
+function renderSection(title, rules) {
+    const lines = [`## ${title}`, ""];
+    if (!rules.length)
+        return `${lines.join("\n")}None.`;
+    lines.push("| Guardrail | Requirement |", "|---|---|");
+    for (const rule of rules) {
+        const identity = [
+            `**${escapeCell(rule.title)}**`,
+            `\`${escapeCode(rule.id)}\``,
+            `${escapeCell(rule.category)} · \`${escapeCode(rule.type)}\``,
+            rule.pack ? `Pack: \`${escapeCode(rule.pack)}\`` : "",
+            rule.confidence ? `Confidence: ${escapeCell(rule.confidence)}` : "",
+        ].filter(Boolean).join("<br>");
+        const detail = [
+            escapeCell(rule.instruction),
+            rule.rationale ? `**Why:** ${escapeCell(rule.rationale)}` : "",
+            rule.evidence?.length ? `**Evidence:** ${rule.evidence.map((item) => `\`${escapeCode(item.path)}\` — ${escapeCell(item.reason)}`).join("<br>")}` : "",
+            rule.cwe_ids?.length ? `**CWE:** ${rule.cwe_ids.map((item) => `CWE-${escapeCell(item)}`).join(", ")}` : "",
+            rule.owasp_top10?.length ? `**OWASP:** ${rule.owasp_top10.map(escapeCell).join(", ")}` : "",
+        ].filter(Boolean).join("<br><br>");
+        lines.push(`| ${identity} | ${detail} |`);
+    }
+    return lines.join("\n");
+}
+function escapeInline(value) {
+    return value.replace(/[\r\n]+/g, " ").trim();
+}
+function escapeCell(value) {
+    return escapeInline(value).replace(/\|/g, "\\|");
+}
+function escapeCode(value) {
+    return escapeCell(value).replace(/`/g, "\\`");
+}
+//# sourceMappingURL=guardrail-markdown.js.map

package/dist/src/core/workspace.js

@@ -6,6 +6,7 @@ import { SCHEMA_VERSION } from "../types.js";
 import { sha256, stableJson } from "./hash.js";
 import { writeFileAtomic } from "./fs.js";
 import { currentCommit } from "./repository.js";
+import { renderGuardrailsMarkdown } from "./guardrail-markdown.js";
 export async function initializeWorkspace(input) {
     const workspaceDir = path.join(input.root, ".vibereview");
     const configPath = path.join(workspaceDir, "config.json");
@@ -43,6 +44,7 @@ export async function initializeWorkspace(input) {
         ["config.json", json(config)],
         ["profile.json", json(input.profile)],
         ["guardrails.yml", stringify(guardrailFile, { lineWidth: 100 })],
+        ["guardrails.md", renderGuardrailsMarkdown(guardrailFile)],
         ["state.json", json(state)],
     ];
     const workspaceExists = await exists(workspaceDir);
@@ -100,6 +102,7 @@ export async function updateCodeSpecificGuardrails(root, guardrailFile, codeSpec
         code_specific: codeSpecific,
     };
     await writeFileAtomic(filePath, stringify(updated, { lineWidth: 100 }));
+    await writeFileAtomic(path.join(root, ".vibereview", "guardrails.md"), renderGuardrailsMarkdown(updated));
     return filePath;
 }
 async function readGuardrails(filePath) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@securityreviewai/vibereview-cli",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Local-first security guardrails for AI coding agents.",
   "type": "module",
   "bin": {

package/skills/vibereview-report/SKILL.md

@@ -31,6 +31,8 @@ Feature names belong in `title` and `workflow_name`, not in the filename. Before
 
 The final report is a current-state document, not an event log.
 
+Use the compact table layouts in the report contract for structured records. Tables must improve scanning in an IDE Markdown preview: keep cells short, escape pipe characters, use `<br>` for intentional in-cell breaks, and move substantial explanation below the table when needed. Do not force narrative context into an unreadably wide row.
+
 If more than one report is already associated with the current session ID, do not create another. Continue with the canonical `<chat-session-id>.md` path and disclose the pre-existing duplicates; do not delete user files without explicit authority.
 
 ## Accuracy rules

package/skills/vibereview-report/references/report-contract.md

@@ -23,71 +23,73 @@ updated_at: "<ISO-8601 timestamp>"
 
 ## Scope and Assumptions
 
-- **Scope:** ...
-- **Assets:** ...
-- **Entry points:** ...
-- **Trust boundaries:** ...
-- **Assumptions:** ...
+| Area | Current state |
+|---|---|
+| Scope | ... |
+| Assets | ... |
+| Entry points | ... |
+| Trust boundaries | ... |
+| Assumptions | ... |
 
 ## Threats Mitigated
 
-### T-01 — <Threat title>
-
-- **PWNISMS category:** Product | Workload | Network | IAM | Secrets | Monitoring | Supply Chain
-- **Scenario:** <actor/action/impact>
-- **Likelihood:** low | medium | high
-- **Impact:** low | medium | high | critical
-- **Status:** mitigated | partial | open | not_applicable
-- **Mitigation:** <implemented control>
-- **Guardrails:** <IDs or None>
-- **Evidence:** <repository paths/tests/configuration>
+| ID and category | Scenario and risk | Current control | Status and evidence |
+|---|---|---|---|
+| **T-01 — <title>**<br>Product \| Workload \| Network \| IAM \| Secrets \| Monitoring \| Supply Chain | <actor/action/impact><br>Likelihood: low \| medium \| high<br>Impact: low \| medium \| high \| critical | <implemented mitigation><br>Guardrails: <IDs or None> | `mitigated` \| `partial` \| `open` \| `not_applicable`<br><paths/tests/configuration> |
 
 ## Best Practices Achieved
 
-- **<Practice>:** <what was implemented and where>
+| Practice | Implementation and evidence |
+|---|---|
+| <Practice> | <what was implemented and where> |
 
 ## Dependency Security (OSV.dev)
 
-### `<ecosystem>:<package>@<evaluated version>`
-
-- **Change:** added | upgraded | downgraded | replaced
-- **Result:** clear | remediated | residual_risk | unverified
-- **Advisories:** <OSV IDs and severity, or None found>
-- **Decision:** <accepted version, replacement, removal, or unresolved reason>
-- **Verification:** <initial scan and required re-scan outcome>
+| Dependency and change | Result | Advisories | Decision and verification |
+|---|---|---|---|
+| `<ecosystem>:<package>@<version>`<br>added \| upgraded \| downgraded \| replaced | `clear` \| `remediated` \| `residual_risk` \| `unverified` | <OSV IDs and severity, or None found> | <accepted version, replacement, removal, or unresolved reason><br><initial scan and required re-scan outcome> |
 
 Use `Not applicable — no dependency changes` when the feature did not change dependencies. Never use `clear` for a failed query, unknown severity, missing exact version, or an unscanned remediation version.
 
 ## Secure Code Changes
 
-### `<repository-relative path>`
-
-<Short explanation of the security-relevant change. Include a small fenced excerpt only when it materially helps the reader.>
+| Path | Security-relevant change |
+|---|---|
+| `<repository-relative path>` | <what changed and which control it implements> |
 
 ## Guardrails Applied
 
-### `<guardrail id>` — <title>
-
-- **Source:** pack | code_generated | custom
-- **Type:** must | must_not
-- **Category:** ...
-- **Satisfied:** yes | no
-- **Application:** <how the implementation complied, or why it did not>
-- **Evidence:** <paths/tests>
+| Guardrail | Application | Satisfied | Evidence |
+|---|---|:---:|---|
+| **<title>**<br>`<guardrail id>`<br>pack \| code_generated \| custom · must \| must_not · <category> | <how the implementation complied, or why it did not> | yes \| no | <paths/tests> |
 
 ## OWASP Mappings
 
-- **<OWASP identifier and title>:** <mapped threats and controls>
+| OWASP identifier | Mapped threats and controls |
+|---|---|
+| <identifier and title> | <threat IDs and implemented controls> |
 
 ## Verification
 
-- `<command or check>` — passed | failed | not run — <important result>
+| Check | Result | Important evidence |
+|---|:---:|---|
+| `<command or check>` | passed \| failed \| not run | <important result> |
 
 ## Residual Risks
 
-- <Remaining exposure, operational dependency, deferred decision, or `None identified within the reviewed scope`.>
+| Risk | Exposure and next action |
+|---|---|
+| <short risk title> | <remaining exposure, operational dependency, or deferred decision> |
 ```
 
+## Table formatting rules
+
+- Keep one logical record per row. Use `<br>` for short line breaks inside a cell; never place a literal newline inside a table row.
+- Escape literal pipe characters as `\|` so they do not create accidental columns.
+- Keep cells concise. Put a short code excerpt below the relevant table only when it materially improves verification.
+- Remove a table or row when it is no longer relevant. For a considered area with no findings, use one explicit row such as `None within the reviewed scope` rather than an empty table.
+- Prefer repository-relative links or backticked paths. Do not place large code blocks, raw tool output, or a chronological change log in a cell.
+
 ## Field semantics
 
 - `workflow_name` remains stable in follow-ups even if `title` changes as scope becomes clearer.