guardlink 1.3.0 → 1.4.1

package/dist/cli/index.js

@@ -18,6 +18,8 @@
  *   guardlink mcp                     Start MCP server (stdio) for Claude Code, Cursor, etc.
  *   guardlink tui [dir]               Interactive TUI with slash commands + AI chat
  *   guardlink gal                     Display GAL annotation language quick reference
+ *   guardlink link-project <repos...>  Link repos into a shared workspace
+ *   guardlink merge <files...>         Merge repo reports into unified dashboard
  *
  * @exposes #cli to #path-traversal [high] cwe:CWE-22 -- "User-supplied dir argument resolved via path.resolve"
  * @mitigates #cli against #path-traversal using #path-validation -- "resolve() canonicalizes paths; cwd-relative by design"
@@ -46,6 +48,7 @@ import { generateDashboardHTML } from '../dashboard/index.js';
 import { AGENTS, agentFromOpts, launchAgent, launchAgentInline, buildAnnotatePrompt } from '../agents/index.js';
 import { resolveConfig, saveProjectConfig, saveGlobalConfig, loadProjectConfig, loadGlobalConfig, maskKey, describeConfigSource } from '../agents/config.js';
 import { getReviewableExposures, applyReviewAction, formatExposureForReview, summarizeReview } from '../review/index.js';
+import { populateMetadata, mergeReports, formatMergeSummary, diffMergedReports, formatDiffSummary, linkProject, addToWorkspace, removeFromWorkspace } from '../workspace/index.js';
 import gradient from 'gradient-string';
 const program = new Command();
 const ASCII_LOGO = `
@@ -92,7 +95,7 @@ function detectProjectName(root, explicit) {
 program
     .name('guardlink')
     .description('GuardLink — Security annotations for code. Threat modeling that lives in your codebase.')
-    .version('1.1.0')
+    .version('1.4.1')
     .addHelpText('before', gradient(['#00ff41', '#00d4ff'])(ASCII_LOGO));
 // ─── init ────────────────────────────────────────────────────────────
 program
@@ -266,9 +269,10 @@ program
     .description('Generate a threat model report with Mermaid diagram')
     .argument('[dir]', 'Project directory to scan', '.')
     .option('-p, --project <n>', 'Project name', 'unknown')
-    .option('-o, --output <file>', 'Write report to file (default: threat-model.md)')
+    .option('-o, --output <file>', 'Write report to file')
+    .option('-f, --format <fmt>', 'Output format: md, json, or both (default: md)', 'md')
     .option('--diagram-only', 'Output only the Mermaid diagram, no report wrapper')
-    .option('--json', 'Also output threat-model.json alongside the report')
+    .option('--json', 'Also output threat-model.json alongside the report (legacy; prefer --format)')
     .action(async (dir, opts) => {
     const root = resolve(dir);
     const { model, diagnostics } = await parseProject({ root, project: opts.project });
@@ -278,9 +282,11 @@ program
         printDiagnostics(errors);
         console.error(`Fix errors above before generating report.\n`);
     }
+    // Enrich with provenance metadata (git SHA, branch, workspace, schema version)
+    const enrichedModel = populateMetadata(model, root);
     if (opts.diagramOnly) {
         // Just output Mermaid
-        const mermaid = generateMermaid(model);
+        const mermaid = generateMermaid(enrichedModel);
         if (opts.output) {
             const { writeFile } = await import('node:fs/promises');
             await writeFile(opts.output, mermaid + '\n');
@@ -289,19 +295,23 @@ program
         else {
             console.log(mermaid);
         }
+        return;
     }
-    else {
-        // Full report
-        const report = generateReport(model);
-        const outFile = opts.output || 'threat-model.md';
-        const { writeFile } = await import('node:fs/promises');
-        await writeFile(resolve(root, outFile), report + '\n');
-        console.error(`✓ Wrote threat model report to ${outFile}`);
-        if (opts.json) {
-            const jsonFile = outFile.replace(/\.md$/, '.json');
-            await writeFile(resolve(root, jsonFile), JSON.stringify(model, null, 2) + '\n');
-            console.error(`✓ Wrote threat model JSON to ${jsonFile}`);
-        }
+    const { writeFile } = await import('node:fs/promises');
+    const wantJson = opts.format === 'json' || opts.format === 'both' || opts.json;
+    const wantMd = opts.format === 'md' || opts.format === 'both' || opts.json;
+    if (wantMd) {
+        const report = generateReport(enrichedModel);
+        const mdFile = opts.output || (opts.format === 'md' ? 'threat-model.md' : 'threat-model.md');
+        await writeFile(resolve(root, mdFile), report + '\n');
+        console.error(`✓ Wrote threat model report to ${mdFile}`);
+    }
+    if (wantJson) {
+        const jsonFile = opts.output && opts.format === 'json'
+            ? opts.output
+            : (opts.output || 'threat-model').replace(/\.md$/, '') + '.json';
+        await writeFile(resolve(root, jsonFile), JSON.stringify(enrichedModel, null, 2) + '\n');
+        console.error(`✓ Wrote threat model JSON to ${jsonFile} (schema v${enrichedModel.metadata?.schema_version})`);
     }
 });
 // ─── diff ────────────────────────────────────────────────────────────
@@ -971,6 +981,224 @@ program
     console.error(`✓ Dashboard generated: ${outFile}`);
     console.error(`  Open in browser to view. Toggle ☀️/🌙 for light/dark mode.`);
 });
+// ─── link-project ────────────────────────────────────────────────────
+program
+    .command('link-project')
+    .description('Link repos into a shared workspace for cross-repo threat modeling')
+    .argument('[repos...]', 'Repo directories to link (fresh setup: 2+ paths)')
+    .option('-w, --workspace <n>', 'Workspace name (fresh link only)', 'workspace')
+    .option('-r, --registry <url>', 'GitHub/GitLab org base URL (e.g. github.com/unstructured)')
+    .option('--add <path>', 'Add a new repo to an existing workspace (provide path to new repo)')
+    .option('--remove <name>', 'Remove a repo from the workspace by name')
+    .option('--from <path>', 'Existing workspace repo to read config from (used with --add or --remove)')
+    .action(async (repos, opts) => {
+    let result;
+    if (opts.remove) {
+        // ── Remove mode: remove a repo from an existing workspace ──
+        if (!opts.from) {
+            console.error('⚠ --remove requires --from <existing-workspace-repo-path>');
+            console.error('  Example: guardlink link-project --remove payment-svc --from ./api-gateway');
+            process.exit(1);
+        }
+        console.error(`Removing "${opts.remove}" from workspace...`);
+        console.error(`  Reference repo: ${opts.from}`);
+        console.error('');
+        result = removeFromWorkspace({
+            repoName: opts.remove,
+            existingRepoPath: opts.from,
+        });
+        for (const name of result.updated) {
+            console.error(`  ↻ ${name} — workspace.yaml updated`);
+        }
+        for (const f of result.agentFilesUpdated) {
+            if (f.includes('(cleaned)'))
+                console.error(`  🧹 ${f}`);
+        }
+        for (const s of result.skipped) {
+            console.error(`  ✗ ${s.name} — ${s.reason}`);
+        }
+        console.error('');
+        if (result.updated.length > 0) {
+            console.error(`✓ Removed "${opts.remove}", updated ${result.updated.length} remaining repo(s)`);
+            console.error('');
+            console.error('Next steps:');
+            console.error('  1. Review and commit changes in each updated repo');
+        }
+        else if (result.skipped.length > 0) {
+            process.exit(1);
+        }
+    }
+    else if (opts.add) {
+        // ── Add mode: add a new repo to an existing workspace ──
+        if (!opts.from) {
+            console.error('⚠ --add requires --from <existing-workspace-repo-path>');
+            console.error('  Example: guardlink link-project --add ./new-service --from ./api-gateway');
+            process.exit(1);
+        }
+        console.error(`Adding repo to existing workspace...`);
+        console.error(`  New repo:      ${opts.add}`);
+        console.error(`  From workspace: ${opts.from}`);
+        console.error('');
+        result = addToWorkspace({
+            newRepoPath: opts.add,
+            existingRepoPath: opts.from,
+            registry: opts.registry,
+        });
+        // Report results
+        for (const name of result.initialized) {
+            console.error(`  ⚡ ${name} — auto-initialized (no prior guardlink setup)`);
+        }
+        for (const name of result.linked) {
+            console.error(`  ✓ ${name} — linked to workspace`);
+        }
+        for (const name of result.updated) {
+            console.error(`  ↻ ${name} — workspace.yaml updated`);
+        }
+        for (const s of result.skipped) {
+            console.error(`  ✗ ${s.name} — skipped: ${s.reason}`);
+        }
+        console.error('');
+        if (result.linked.length > 0 || result.updated.length > 0) {
+            const total = result.linked.length + result.updated.length;
+            console.error(`✓ ${result.linked.length} repo(s) added, ${result.updated.length} existing repo(s) updated`);
+            if (result.agentFilesUpdated.length > 0) {
+                console.error(`  ↻ Updated ${result.agentFilesUpdated.length} agent instruction file(s)`);
+            }
+            // Warn about repos not found on disk
+            // (they're in workspace.yaml but we couldn't locate their directory)
+            console.error('');
+            console.error('Next steps:');
+            console.error('  1. Review and commit changes in each updated repo');
+            console.error('  2. Add "guardlink report --format json" to the new repo\'s CI');
+            console.error('  3. Run "guardlink merge" with all repo reports');
+        }
+        else {
+            console.error('✗ No repos were added. Check the paths provided.');
+            process.exit(1);
+        }
+    }
+    else {
+        // ── Fresh link mode: link N repos together ──
+        if (repos.length < 2) {
+            console.error('⚠ Fresh linking requires at least 2 repo paths.');
+            console.error('  To add a repo to an existing workspace, use:');
+            console.error('  guardlink link-project --add <new-repo> --from <existing-repo>');
+            process.exit(1);
+        }
+        console.error(`Linking ${repos.length} repos into workspace "${opts.workspace}"...`);
+        console.error('');
+        result = linkProject({
+            workspace: opts.workspace,
+            repoPaths: repos,
+            registry: opts.registry,
+        });
+        for (const name of result.initialized) {
+            console.error(`  ⚡ ${name} — auto-initialized (no prior guardlink setup)`);
+        }
+        for (const name of result.linked) {
+            console.error(`  ✓ ${name} — workspace.yaml written, agent files updated`);
+        }
+        for (const s of result.skipped) {
+            console.error(`  ✗ ${s.name} — skipped: ${s.reason}`);
+        }
+        console.error('');
+        if (result.linked.length > 0) {
+            console.error(`✓ Linked ${result.linked.length} repo(s) into "${opts.workspace}"`);
+            if (result.agentFilesUpdated.length > 0) {
+                console.error(`  ↻ Updated ${result.agentFilesUpdated.length} agent instruction file(s)`);
+            }
+            console.error('');
+            console.error('Next steps:');
+            console.error('  1. Review and commit .guardlink/workspace.yaml in each repo');
+            console.error('  2. Add "guardlink report --format json -o guardlink-report.json" to each repo\'s CI');
+            console.error('  3. Use "guardlink merge" to combine reports into a unified dashboard');
+        }
+        else {
+            console.error('✗ No repos were linked. Check the paths provided.');
+            process.exit(1);
+        }
+    }
+});
+// ─── merge ───────────────────────────────────────────────────────────
+program
+    .command('merge')
+    .description('Merge multiple repo report JSONs into a unified workspace threat model')
+    .argument('<files...>', 'Report JSON file paths (glob supported)')
+    .option('-o, --output <file>', 'Output file for merged dashboard HTML (default: workspace-dashboard.html)')
+    .option('--json <file>', 'Also write merged report JSON to this file')
+    .option('--diff-against <file>', 'Compare against a previous merged JSON for weekly summary')
+    .option('-w, --workspace <name>', 'Workspace name (auto-detected from reports if not set)')
+    .option('--summary-only', 'Print only the text summary, skip dashboard generation')
+    .action(async (files, opts) => {
+    const { writeFile, readFile } = await import('node:fs/promises');
+    const { resolve: resolvePath } = await import('node:path');
+    // Resolve file paths (support globs via shell expansion — files already expanded by shell)
+    const resolvedFiles = files.map(f => resolvePath(f));
+    if (resolvedFiles.length === 0) {
+        console.error('✗ No report files provided.');
+        process.exit(1);
+    }
+    console.error(`Merging ${resolvedFiles.length} report(s)...`);
+    // Run merge
+    const merged = await mergeReports(resolvedFiles, {
+        workspace: opts.workspace,
+    });
+    const t = merged.totals;
+    // Print summary to stderr
+    console.error('');
+    console.error(`✓ ${merged.workspace} — ${t.repos_loaded}/${t.repos} repos loaded`);
+    console.error(`  ${t.annotations} annotations | ${t.assets} assets | ${t.threats} threats | ${t.controls} controls`);
+    console.error(`  ${t.mitigations} mitigations | ${t.exposures} exposures | ${t.unmitigated_exposures} unmitigated`);
+    console.error(`  ${t.flows} flows | ${t.external_refs_resolved} refs resolved | ${t.external_refs_unresolved} unresolved`);
+    // Print warnings
+    for (const w of merged.warnings) {
+        const icon = w.level === 'error' ? '✗' : w.level === 'warning' ? '⚠' : 'ℹ';
+        console.error(`  ${icon} ${w.message}`);
+    }
+    console.error('');
+    // Write merged JSON
+    if (opts.json) {
+        const jsonPath = resolvePath(opts.json);
+        await writeFile(jsonPath, JSON.stringify(merged, null, 2) + '\n');
+        console.error(`✓ Wrote merged JSON to ${opts.json}`);
+    }
+    // Diff against previous
+    if (opts.diffAgainst) {
+        try {
+            const prevRaw = await readFile(resolvePath(opts.diffAgainst), 'utf-8');
+            const previous = JSON.parse(prevRaw);
+            const diff = diffMergedReports(merged, previous);
+            const diffMd = formatDiffSummary(diff, merged.workspace);
+            // Write diff markdown
+            const diffFile = (opts.json || 'workspace-merge').replace(/\.json$/, '') + '-weekly-diff.md';
+            await writeFile(resolvePath(diffFile), diffMd + '\n');
+            console.error(`✓ Wrote weekly diff to ${diffFile}`);
+            // Also print a compact version to stderr
+            const riskIcon = diff.risk_delta === 'increased' ? '🔴'
+                : diff.risk_delta === 'decreased' ? '🟢' : '⚪';
+            console.error(`  ${riskIcon} Risk ${diff.risk_delta} since last merge`);
+            if (diff.new_unmitigated > 0)
+                console.error(`  🔴 +${diff.new_unmitigated} new unmitigated exposure(s)`);
+            if (diff.resolved_unmitigated > 0)
+                console.error(`  🟢 ${diff.resolved_unmitigated} exposure(s) now mitigated`);
+            if (diff.mitigations_removed > 0)
+                console.error(`  ⚠️  ${diff.mitigations_removed} mitigation(s) removed`);
+            console.error('');
+        }
+        catch (err) {
+            console.error(`⚠ Could not diff against ${opts.diffAgainst}: ${err instanceof Error ? err.message : err}`);
+        }
+    }
+    // Generate dashboard HTML (unless --summary-only)
+    if (!opts.summaryOnly) {
+        const html = generateDashboardHTML(merged.model);
+        const outFile = opts.output || 'workspace-dashboard.html';
+        await writeFile(resolvePath(outFile), html);
+        console.error(`✓ Wrote workspace dashboard to ${outFile}`);
+    }
+    // Print full markdown summary to stdout (pipeable)
+    console.log(formatMergeSummary(merged));
+});
 // ─── mcp ─────────────────────────────────────────────────────────────
 program
     .command('mcp')
@@ -1013,112 +1241,130 @@ program
         console.log(D('  Annotations live in source code comments. GuardLink parses'));
         console.log(D('  them to build a live threat model from your codebase.'));
         console.log('');
-        console.log(D('  Syntax:  @verb  subject  [preposition  object]  [: description]'));
+        console.log(D('  Syntax:  @verb  subject  [preposition  object]  [-- "description"]'));
         console.log('');
         // ── DEFINITIONS ──
         console.log(H('  ── Definitions ─────────────────────────────────────────────'));
         console.log('');
-        console.log(`  ${V('@asset')}  ${K('<path>')}  ${D('[: description]')}`);
+        console.log(`  ${V('@asset')}  ${K('<path>')}  ${D('[-- "description"]')}`);
         console.log(D('    Declare a named asset (component, service, data store).'));
         console.log(D('    Path uses dot notation for hierarchy.'));
-        console.log(EX('    // @asset  api.auth.token_store  : Stores JWT refresh tokens'));
+        console.log(EX('    // @asset  api.auth.token_store  -- "Stores JWT refresh tokens"'));
         console.log(EX('    // @asset  db.users'));
         console.log('');
-        console.log(`  ${V('@threat')}  ${K('<name>')}  ${D('[severity: critical|high|medium|low]  [: description]')}`);
-        console.log(D('    Declare a named threat. Severity aliases: P0=critical P1=high P2=medium P3=low.'));
-        console.log(EX('    // @threat  SQL Injection  severity:high  : Unsanitized input reaches DB'));
-        console.log(EX('    // @threat  Token Theft  severity:P0'));
+        console.log(`  ${V('@threat')}  ${K('<name>')}  ${D('(#id)')}  ${D('[critical|high|medium|low]')}  ${D('[ext-refs]')}  ${D('[-- "description"]')}`);
+        console.log(D('    Declare a named threat. Severity in brackets: [P0]=[critical] [P1]=[high] [P2]=[medium] [P3]=[low].'));
+        console.log(EX('    // @threat  SQL Injection  (#sql-inj)  [high]  cwe:CWE-89  -- "Unsanitized input reaches DB"'));
+        console.log(EX('    // @threat  Token Theft  [P0]'));
         console.log('');
-        console.log(`  ${V('@control')}  ${K('<name>')}  ${D('[: description]')}`);
+        console.log(`  ${V('@control')}  ${K('<name>')}  ${D('(#id)')}  ${D('[-- "description"]')}`);
         console.log(D('    Declare a security control (mitigation mechanism).'));
-        console.log(EX('    // @control  Input Validation  : Sanitize all user-supplied strings'));
+        console.log(EX('    // @control  Input Validation  (#input-val)  -- "Sanitize all user-supplied strings"'));
         console.log(EX('    // @control  Rate Limiting'));
         console.log('');
         // ── RELATIONSHIPS ──
         console.log(H('  ── Relationships ───────────────────────────────────────────'));
         console.log('');
-        console.log(`  ${V('@exposes')}  ${K('<asset>')}  ${D('to')}  ${K('<threat>')}  ${D('[severity: ...]  [: description]')}`);
+        console.log(`  ${V('@exposes')}  ${K('<asset>')}  ${D('to')}  ${K('<threat>')}  ${D('[severity]')}  ${D('[ext-refs]')}  ${D('[-- "description"]')}`);
         console.log(D('    Mark an asset as exposed to a threat at this code location.'));
         console.log(D('    This is the primary annotation — every exposure creates a finding.'));
-        console.log(EX('    // @exposes  api.auth  to  SQL Injection  severity:high'));
-        console.log(EX('    // @exposes  db.users  to  Token Theft  severity:critical  : No token rotation'));
+        console.log(EX('    // @exposes  api.auth  to  SQL Injection  [high]  cwe:CWE-89'));
+        console.log(EX('    // @exposes  db.users  to  Token Theft  [critical]  -- "No token rotation"'));
         console.log('');
-        console.log(`  ${V('@mitigates')}  ${K('<asset>')}  ${D('against')}  ${K('<threat>')}  ${D('[with')}  ${K('<control>')}${D(']  [: description]')}`);
+        console.log(`  ${V('@mitigates')}  ${K('<asset>')}  ${D('against')}  ${K('<threat>')}  ${D('[using')}  ${K('<control>')}${D(']')}  ${D('[-- "description"]')}`);
         console.log(D('    Mark that a control mitigates a threat on an asset.'));
         console.log(D('    Closes the exposure — removes it from open findings.'));
-        console.log(EX('    // @mitigates  api.auth  against  SQL Injection  with  Input Validation'));
-        console.log(EX('    // @mitigates  db.users  against  Token Theft  : Rotation implemented in v2'));
+        console.log(D('    "using" is the primary keyword; "with" also accepted.'));
+        console.log(EX('    // @mitigates  api.auth  against  SQL Injection  using  Input Validation'));
+        console.log(EX('    // @mitigates  db.users  against  Token Theft  -- "Rotation implemented in v2"'));
         console.log('');
-        console.log(`  ${V('@accepts')}  ${K('<threat>')}  ${D('on')}  ${K('<asset>')}  ${D('[: reason]')}`);
+        console.log(`  ${V('@accepts')}  ${K('<threat>')}  ${D('on')}  ${K('<asset>')}  ${D('[-- "reason"]')}`);
         console.log(D('    Explicitly accept a risk. Removes it from open findings.'));
         console.log(D('    Use when the risk is known and intentionally not mitigated.'));
-        console.log(EX('    // @accepts  Timing Attack  on  api.auth  : Acceptable for current threat model'));
+        console.log(EX('    // @accepts  Timing Attack  on  api.auth  -- "Acceptable for current threat model"'));
         console.log('');
-        console.log(`  ${V('@transfers')}  ${K('<threat>')}  ${D('from')}  ${K('<source>')}  ${D('to')}  ${K('<target>')}  ${D('[: description]')}`);
+        console.log(`  ${V('@transfers')}  ${K('<threat>')}  ${D('from')}  ${K('<source>')}  ${D('to')}  ${K('<target>')}  ${D('[-- "description"]')}`);
         console.log(D('    Transfer responsibility for a threat to another asset/team.'));
-        console.log(EX('    // @transfers  DDoS  from  api.gateway  to  cdn.cloudflare  : Handled by CDN layer'));
+        console.log(EX('    // @transfers  DDoS  from  api.gateway  to  cdn.cloudflare  -- "Handled by CDN layer"'));
         console.log('');
         // ── DATA FLOWS ──
         console.log(H('  ── Data Flows & Boundaries ─────────────────────────────────'));
         console.log('');
-        console.log(`  ${V('@flows')}  ${K('<source>')}  ${D('to')}  ${K('<target>')}  ${D('[via')}  ${K('<mechanism>')}${D(']  [: description]')}`);
+        console.log(`  ${V('@flows')}  ${K('<source>')}  ${D('->')}  ${K('<target>')}  ${D('[via')}  ${K('<mechanism>')}${D(']')}  ${D('[-- "description"]')}`);
         console.log(D('    Document data movement between components.'));
         console.log(D('    Appears in the Data Flow Diagram.'));
-        console.log(EX('    // @flows  api.auth  to  db.users  via  TLS 1.3'));
-        console.log(EX('    // @flows  mobile.app  to  api.gateway  via  HTTPS  : User credentials'));
+        console.log(EX('    // @flows  api.auth  ->  db.users  via  TLS 1.3'));
+        console.log(EX('    // @flows  mobile.app  ->  api.gateway  via  HTTPS  -- "User credentials"'));
         console.log('');
-        console.log(`  ${V('@boundary')}  ${K('<asset_a>')}  ${D('and')}  ${K('<asset_b>')}  ${D('[: description]')}`);
+        console.log(`  ${V('@boundary')}  ${K('<asset_a>')}  ${D('and')}  ${K('<asset_b>')}  ${D('(#id)')}  ${D('[-- "description"]')}`);
         console.log(D('    Declare a trust boundary between two assets.'));
         console.log(D('    Groups assets in the Data Flow Diagram.'));
-        console.log(EX('    // @boundary  internet  and  api.gateway  : Public-facing edge'));
-        console.log(EX('    // @boundary  api.gateway  and  db.users  : Internal network boundary'));
+        console.log(D('    Alternate: @boundary between A and B  or  @boundary A | B'));
+        console.log(EX('    // @boundary  internet  and  api.gateway  (#edge)  -- "Public-facing edge"'));
+        console.log(EX('    // @boundary  api.gateway | db.users  -- "Internal network boundary"'));
         console.log('');
         // ── LIFECYCLE ──
         console.log(H('  ── Lifecycle & Governance ──────────────────────────────────'));
         console.log('');
-        console.log(`  ${V('@handles')}  ${K('<classification>')}  ${D('on')}  ${K('<asset>')}  ${D('[: description]')}`);
+        console.log(`  ${V('@handles')}  ${K('<classification>')}  ${D('on')}  ${K('<asset>')}  ${D('[-- "description"]')}`);
         console.log(D('    Declare data classification handled by an asset.'));
         console.log(D('    Classifications: pii  phi  financial  secrets  internal  public'));
-        console.log(EX('    // @handles  pii  on  db.users  : Stores name, email, phone'));
+        console.log(EX('    // @handles  pii  on  db.users  -- "Stores name, email, phone"'));
         console.log(EX('    // @handles  secrets  on  api.auth.token_store'));
         console.log('');
-        console.log(`  ${V('@owns')}  ${K('<owner>')}  ${K('<asset>')}  ${D('[: description]')}`);
+        console.log(`  ${V('@owns')}  ${K('<owner>')}  ${D('for')}  ${K('<asset>')}  ${D('[-- "description"]')}`);
         console.log(D('    Assign ownership of an asset to a team or person.'));
-        console.log(EX('    // @owns  platform-team  api.auth'));
+        console.log(EX('    // @owns  platform-team  for  api.auth'));
         console.log('');
-        console.log(`  ${V('@validates')}  ${K('<control>')}  ${D('on')}  ${K('<asset>')}  ${D('[: description]')}`);
+        console.log(`  ${V('@validates')}  ${K('<control>')}  ${D('for')}  ${K('<asset>')}  ${D('[-- "description"]')}`);
         console.log(D('    Assert that a control has been validated/tested on an asset.'));
-        console.log(EX('    // @validates  Input Validation  on  api.auth  : Pen-tested 2024-Q3'));
+        console.log(EX('    // @validates  Input Validation  for  api.auth  -- "Pen-tested 2024-Q3"'));
         console.log('');
-        console.log(`  ${V('@audit')}  ${K('<asset>')}  ${D('[: description]')}`);
+        console.log(`  ${V('@audit')}  ${K('<asset>')}  ${D('[-- "description"]')}`);
         console.log(D('    Mark that this code path is an audit trail point.'));
-        console.log(EX('    // @audit  db.users  : All writes logged to audit_log table'));
+        console.log(EX('    // @audit  db.users  -- "All writes logged to audit_log table"'));
         console.log('');
-        console.log(`  ${V('@assumes')}  ${K('<asset>')}  ${D('[: description]')}`);
+        console.log(`  ${V('@assumes')}  ${K('<asset>')}  ${D('[-- "description"]')}`);
         console.log(D('    Document a security assumption about an asset.'));
-        console.log(EX('    // @assumes  api.gateway  : Upstream WAF filters malformed requests'));
+        console.log(EX('    // @assumes  api.gateway  -- "Upstream WAF filters malformed requests"'));
         console.log('');
-        console.log(`  ${V('@comment')}  ${D('[: description]')}`);
+        console.log(`  ${V('@comment')}  ${D('[-- "description"]')}`);
         console.log(D('    Free-form developer security note (no structural effect).'));
-        console.log(EX('    // @comment  : TODO — add rate limiting before v2 launch'));
+        console.log(EX('    // @comment  -- "TODO — add rate limiting before v2 launch"'));
         console.log('');
         // ── SHIELD BLOCKS ──
         console.log(H('  ── Shield Blocks ───────────────────────────────────────────'));
         console.log('');
+        console.log(`  ${V('@shield')}  ${D('[-- "reason"]')}`);
+        console.log(D('    Single-line marker for a security-sensitive code point.'));
+        console.log(EX('    // @shield  -- "Crypto key derivation — do not refactor without review"'));
+        console.log('');
         console.log(`  ${V('@shield:begin')}  ${D('/')}  ${V('@shield:end')}`);
         console.log(D('    Wrap a code block to mark it as security-sensitive.'));
         console.log(D('    GuardLink will flag unannotated symbols inside the block.'));
-        console.log(EX('    // @shield:begin'));
+        console.log(EX('    // @shield:begin  -- "Auth verification block"'));
         console.log(EX('    function verifyToken(token: string) { ... }'));
         console.log(EX('    // @shield:end'));
         console.log('');
+        // ── EXTERNAL REFERENCES ──
+        console.log(H('  ── External References ─────────────────────────────────────'));
+        console.log('');
+        console.log(D('  Append space-separated refs after severity on @threat and @exposes:'));
+        console.log(EX('    cwe:CWE-89  owasp:A03:2021  capec:CAPEC-66  attack:T1190'));
+        console.log('');
+        console.log(D('  Example:'));
+        console.log(EX('    // @exposes  api.auth  to  SQL Injection  [high]  cwe:CWE-89  owasp:A03:2021'));
+        console.log('');
         // ── TIPS ──
         console.log(H('  ── Tips ────────────────────────────────────────────────────'));
         console.log('');
+        console.log(D('  • Descriptions use -- "quoted text" format (not : colon)'));
+        console.log(D('  • Severity uses brackets: [critical] [high] [medium] [low] or [P0]-[P3]'));
         console.log(D('  • Annotations work in any comment style: // /* # -- <!-- -->'));
         console.log(D('  • Place annotations on the line ABOVE the code they describe'));
         console.log(D('  • Asset names are case-insensitive and normalized (spaces→underscores)'));
         console.log(D('  • Threat/control names can reference IDs with #id syntax'));
+        console.log(D('  • @flows uses -> arrow syntax (not "to")'));
         console.log(D('  • Run guardlink parse after adding annotations to update the threat model'));
         console.log(D('  • Run guardlink validate to check for syntax errors and dangling references'));
         console.log(D('  • Run guardlink annotate to have an AI agent add annotations automatically'));