thumbgate 1.16.12 → 1.16.19

package/scripts/cli-schema.js

@@ -162,6 +162,283 @@ const CLI_COMMANDS = [
       { name: 'ai-only', type: 'boolean', description: 'Only report AI/browser bridge manifests' },
     ],
   }),
+  discoveryCommand({
+    name: 'code-graph-guardrails',
+    aliases: ['knowledge-graph-guardrails', 'graph-guardrails'],
+    description: 'Map code-graph risk signals to Knowledge Graph Safety pre-action gates',
+    flags: [
+      jsonFlag(),
+      { name: 'graph-tool', type: 'string', description: 'Graph tool name, such as understand-anything or code-graph-mcp' },
+      { name: 'graph-path', type: 'string', description: 'Path to generated graph output or cache directory' },
+      { name: 'central-files', type: 'string', description: 'Comma-separated high-centrality files' },
+      { name: 'layers', type: 'string', description: 'Comma-separated architecture layers touched, such as api,data,ui' },
+      { name: 'generated-artifacts', type: 'string', description: 'Comma-separated generated graph artifacts to protect' },
+      { name: 'changed-files', type: 'number', description: 'Estimated changed file count for blast-radius context' },
+    ],
+  }),
+  discoveryCommand({
+    name: 'proxy-pointer-rag-guardrails',
+    aliases: ['document-rag-guardrails', 'multimodal-rag-guardrails'],
+    description: 'Map document-tree and image-pointer RAG signals to Document RAG Safety gates',
+    flags: [
+      jsonFlag(),
+      { name: 'rag-tool', type: 'string', description: 'RAG pipeline name, such as proxy-pointer-rag or docling-rag' },
+      { name: 'tree-path', type: 'string', description: 'Path to generated document section tree JSON' },
+      { name: 'section-ids', type: 'string', description: 'Comma-separated section ids included in retrieved context' },
+      { name: 'image-pointers', type: 'string', description: 'Comma-separated image, chart, or figure pointers selected for the answer' },
+      { name: 'documents', type: 'string', description: 'Comma-separated source document ids represented in the answer' },
+      { name: 'candidate-images', type: 'number', description: 'Number of candidate images considered before final answer synthesis' },
+      { name: 'cross-doc-policy', type: 'string', description: 'Set to strict when images must never cross source documents' },
+      { name: 'vision-filter', type: 'boolean', description: 'Mark that a vision sanity check was used or required' },
+      { name: 'visual-claims', type: 'boolean', description: 'Mark that the answer makes claims about visual content' },
+    ],
+  }),
+  discoveryCommand({
+    name: 'gemini-embedding-plan',
+    aliases: ['embedding-plan'],
+    description: 'Plan Gemini Embedding 2 task prefixes, Matryoshka dimensions, and Batch API indexing',
+    flags: [
+      jsonFlag(),
+      { name: 'task', type: 'string', description: 'Retrieval task, such as code retrieval, search result, or classification' },
+      { name: 'corpus-items', type: 'number', description: 'Estimated number of lessons, docs, or proof artifacts to index' },
+      { name: 'dim', type: 'number', description: 'Requested output dimensionality; snaps to 3072, 1536, or 768' },
+      { name: 'no-batch', type: 'boolean', description: 'Skip Batch API recommendation for online-only indexing' },
+    ],
+  }),
+  discoveryCommand({
+    name: 'agent-design-governance',
+    aliases: ['agent-architecture', 'agent-governance-plan'],
+    description: 'Decide single-agent vs multi-agent architecture and required eval/tool safeguards',
+    mcpTool: 'plan_agent_design_governance',
+    flags: [
+      jsonFlag(),
+      { name: 'workflow', type: 'string', description: 'Workflow name or short description' },
+      { name: 'tools', type: 'string', description: 'Comma-separated tool names available to the agent' },
+      { name: 'tool-count', type: 'number', description: 'Total available tools when not listing names' },
+      { name: 'similar-tool-count', type: 'number', description: 'Number of similar/overlapping tools competing for selection' },
+      { name: 'conditional-branches', type: 'number', description: 'Rough count of if/then instruction branches' },
+      { name: 'high-risk-tools', type: 'string', description: 'Comma-separated tools that affect production, money, data, secrets, or outbound actions' },
+      { name: 'write-tools', type: 'string', description: 'Comma-separated write-capable tools' },
+      { name: 'baseline-evals', type: 'boolean', description: 'Whether baseline agent evals already exist' },
+      { name: 'docs', type: 'boolean', description: 'Instructions draw on existing workflow docs' },
+      { name: 'examples', type: 'boolean', description: 'Instructions include concrete examples' },
+      { name: 'edge-cases', type: 'boolean', description: 'Instructions include edge cases and failure paths' },
+      { name: 'tool-approvals', type: 'boolean', description: 'Risky tool calls require approval' },
+      { name: 'exit-condition', type: 'boolean', description: 'Instructions define when the run is complete' },
+    ],
+  }),
+  discoveryCommand({
+    name: 'proactive-agent-eval-guardrails',
+    aliases: ['pare-guardrails', 'proactive-agent-guardrails'],
+    description: 'Map PARE-style proactive-agent eval gaps to stateful pre-action gates',
+    mcpTool: 'plan_proactive_agent_eval_guardrails',
+    flags: [
+      jsonFlag(),
+      { name: 'workflow', type: 'string', description: 'Proactive assistant workflow name' },
+      { name: 'apps', type: 'string', description: 'Comma-separated apps involved in the workflow' },
+      { name: 'states', type: 'string', description: 'Comma-separated app states modeled for the eval' },
+      { name: 'state-count', type: 'number', description: 'Number of modeled states' },
+      { name: 'action-count', type: 'number', description: 'Number of state-dependent actions' },
+      { name: 'task-count', type: 'number', description: 'Number of benchmark tasks or scenarios' },
+      { name: 'state-machine', type: 'boolean', description: 'Whether apps are modeled as finite state machines' },
+      { name: 'active-user-simulation', type: 'boolean', description: 'Whether active user simulation exists' },
+      { name: 'goal-inference-evals', type: 'boolean', description: 'Whether goal inference is graded' },
+      { name: 'intervention-timing-evals', type: 'boolean', description: 'Whether intervention timing is graded' },
+      { name: 'multi-app-evals', type: 'boolean', description: 'Whether multi-app orchestration is graded' },
+      { name: 'flat-tool-api-only', type: 'boolean', description: 'Mark that the current eval only covers flat tool calls' },
+      { name: 'proactive-writes', type: 'boolean', description: 'Mark that the proactive agent can write or mutate state' },
+      { name: 'user-visible-actions', type: 'boolean', description: 'Mark that interventions can notify, schedule, send, or otherwise affect users' },
+    ],
+  }),
+  discoveryCommand({
+    name: 'reward-hacking-guardrails',
+    aliases: ['proxy-reward-guardrails', 'reward-guardrails'],
+    description: 'Detect reward-hacking patterns and require proof before proxy metrics or completion claims are trusted',
+    mcpTool: 'plan_reward_hacking_guardrails',
+    flags: [
+      jsonFlag(),
+      { name: 'workflow', type: 'string', description: 'Agent workflow or release lane being evaluated' },
+      { name: 'text', type: 'string', description: 'Candidate response, claim, summary, or verifier output to inspect' },
+      { name: 'evidence', type: 'string', description: 'Comma-separated evidence artifacts attached to the claim' },
+      { name: 'metrics', type: 'string', description: 'Comma-separated proxy metrics or reward scores used by the workflow' },
+      { name: 'holdout', type: 'boolean', description: 'Whether holdout, regression, or real-workflow evidence exists' },
+      { name: 'human-objective', type: 'boolean', description: 'Whether proxy metrics are mapped to a human/user objective' },
+      { name: 'verifier-trace', type: 'boolean', description: 'Whether verifier trace, run log, or proof artifact exists' },
+      { name: 'optimized-for-score', type: 'boolean', description: 'Mark that the workflow is optimizing an eval, benchmark, or reward score' },
+      { name: 'multimodal', type: 'boolean', description: 'Mark that claims depend on screenshots, PDFs, charts, images, or video' },
+    ],
+  }),
+  discoveryCommand({
+    name: 'oss-pr-opportunity-scout',
+    aliases: ['github-pr-scout', 'upstream-pr-scout'],
+    description: 'Find upstream GitHub repos ThumbGate uses and rank proof-backed issue/bug-bounty PR opportunities',
+    mcpTool: 'plan_oss_pr_opportunity_scout',
+    flags: [
+      jsonFlag(),
+      { name: 'package-path', type: 'string', description: 'Path to package.json used to discover dependencies' },
+      { name: 'dependencies', type: 'string', description: 'Comma-separated dependency names to scout instead of package.json' },
+      { name: 'max-repos', type: 'number', description: 'Maximum mapped upstream repositories to include' },
+      { name: 'include-bounties', type: 'boolean', description: 'Include bug-bounty and security search queries' },
+    ],
+  }),
+  discoveryCommand({
+    name: 'chatgpt-ads-readiness-pack',
+    aliases: ['chatgpt-ads-plan', 'ai-ads-plan'],
+    description: 'Prepare ThumbGate copy, intent clusters, proof gates, and measurement for ChatGPT Ads Manager tests',
+    mcpTool: 'plan_chatgpt_ads_readiness',
+    flags: [
+      jsonFlag(),
+      { name: 'offer', type: 'string', description: 'Offer to advertise, such as Pro or Workflow Hardening Sprint' },
+      { name: 'audience', type: 'string', description: 'Audience segment to target' },
+      { name: 'budget', type: 'number', description: 'Initial test budget' },
+      { name: 'keywords', type: 'string', description: 'Comma-separated high-intent conversational queries' },
+      { name: 'proof-links', type: 'string', description: 'Comma-separated proof URLs required by ad claims' },
+    ],
+  }),
+  discoveryCommand({
+    name: 'rag-precision-guardrails',
+    aliases: ['retrieval-precision-guardrails', 'agentic-rag-guardrails'],
+    description: 'Map RAG precision tuning and retrieval-regression signals to Document RAG Safety gates',
+    flags: [
+      jsonFlag(),
+      { name: 'rag-tool', type: 'string', description: 'RAG pipeline name, such as agentic-rag or redis-rag' },
+      { name: 'baseline-recall', type: 'number', description: 'Recall@k before embedding, threshold, or reranking changes' },
+      { name: 'new-recall', type: 'number', description: 'Recall@k after the proposed retrieval change' },
+      { name: 'baseline-precision', type: 'number', description: 'Precision@k before the proposed retrieval change' },
+      { name: 'new-precision', type: 'number', description: 'Precision@k after the proposed retrieval change' },
+      { name: 'top-k', type: 'number', description: 'Retrieval k used for the baseline and candidate metrics' },
+      { name: 'threshold-change', type: 'boolean', description: 'Mark that vector threshold or top-k routing changed' },
+      { name: 'embedding-finetune', type: 'boolean', description: 'Mark that embedding fine-tuning or replacement is proposed' },
+      { name: 'structural-near-misses', type: 'boolean', description: 'Mark that negation or role-reversal near misses matter' },
+      { name: 'verifier', type: 'boolean', description: 'Mark that a second-stage verifier or reranker is present' },
+      { name: 'latency-ms', type: 'number', description: 'Observed end-to-end retrieval latency after verifier or reranker' },
+      { name: 'latency-budget-ms', type: 'number', description: 'Workflow retrieval latency budget' },
+      { name: 'agentic', type: 'boolean', description: 'Mark that retrieval output can trigger downstream agent actions' },
+    ],
+  }),
+  discoveryCommand({
+    name: 'ai-engineering-stack-guardrails',
+    aliases: ['ai-stack-guardrails', 'internal-ai-stack-guardrails', 'llm-wiki-guardrails'],
+    description: 'Map AI gateway, MCP portal, AGENTS.md/LLM wiki, reviewer, and sandbox gaps to stack gates',
+    flags: [
+      jsonFlag(),
+      { name: 'stack', type: 'string', description: 'Stack name or rollout program' },
+      { name: 'gateway', type: 'boolean', description: 'Mark that a central model gateway or proxy exists' },
+      { name: 'direct-provider-keys', type: 'boolean', description: 'Mark that clients still hold provider API keys directly' },
+      { name: 'mcp-tool-count', type: 'number', description: 'Number of MCP tools exposed before progressive discovery' },
+      { name: 'code-mode', type: 'boolean', description: 'Mark that MCP tools are hidden behind code-mode search/execute or progressive discovery' },
+      { name: 'agents-md', type: 'boolean', description: 'Mark that short repo-local AGENTS.md context exists' },
+      { name: 'llm-wiki-pages', type: 'number', description: 'Number of source-backed LLM wiki pages in the stack' },
+      { name: 'context-freshness-days', type: 'number', description: 'Days since AGENTS.md or LLM wiki context was refreshed' },
+      { name: 'ai-reviewer', type: 'boolean', description: 'Mark that risk-tiered AI code review is active' },
+      { name: 'codex-rules', type: 'boolean', description: 'Mark that engineering standards are available as rules or skills' },
+      { name: 'background-agents', type: 'boolean', description: 'Mark that durable/background agents can run work' },
+      { name: 'sandbox', type: 'boolean', description: 'Mark that background agents run in isolated build/test sandboxes' },
+      { name: 'high-risk-workflows', type: 'string', description: 'Comma-separated workflows touching money, prod, secrets, data, or publishing' },
+    ],
+  }),
+  discoveryCommand({
+    name: 'long-running-agent-context-guardrails',
+    aliases: ['agent-context-guardrails', 'slack-context-guardrails'],
+    description: 'Map long-running agent context risks to director-journal and critic-review gates',
+    flags: [
+      jsonFlag(),
+      { name: 'workflow', type: 'string', description: 'Workflow or agent loop name' },
+      { name: 'request-count', type: 'number', description: 'Approximate number of requests in the long-running workflow' },
+      { name: 'output-mb', type: 'number', description: 'Approximate generated output volume in megabytes' },
+      { name: 'director-journal', type: 'boolean', description: 'Mark that structured working memory is present' },
+      { name: 'critic-review', type: 'boolean', description: 'Mark that expert findings receive critic review' },
+      { name: 'critic-timeline', type: 'boolean', description: 'Mark that a deduplicated credibility timeline is present' },
+      { name: 'credibility-scores', type: 'boolean', description: 'Mark that findings carry evidence credibility scores' },
+      { name: 'conflicts', type: 'boolean', description: 'Mark that the timeline contains unresolved conflicting findings' },
+      { name: 'raw-chat-only', type: 'boolean', description: 'Mark that the workflow only accumulates raw chat history' },
+    ],
+  }),
+  discoveryCommand({
+    name: 'reasoning-efficiency-guardrails',
+    aliases: ['sas-guardrails', 'reasoning-compression-guardrails'],
+    description: 'Map reasoning compression, verifier, and step-confidence signals to efficiency safety gates',
+    flags: [
+      jsonFlag(),
+      { name: 'workload', type: 'string', description: 'Reasoning workload name' },
+      { name: 'baseline-tokens', type: 'number', description: 'Average reasoning tokens before compression' },
+      { name: 'compressed-tokens', type: 'number', description: 'Average reasoning tokens after compression' },
+      { name: 'baseline-accuracy', type: 'number', description: 'Pass@1 or accuracy before compression' },
+      { name: 'compressed-accuracy', type: 'number', description: 'Pass@1 or accuracy after compression' },
+      { name: 'verifier', type: 'boolean', description: 'Mark that verifier outcomes are present' },
+      { name: 'low-confidence-steps', type: 'number', description: 'Low-confidence accepted reasoning steps to inspect' },
+      { name: 'high-confidence-failures', type: 'number', description: 'High-confidence failed rollouts to inspect' },
+      { name: 'truncation-failures', type: 'boolean', description: 'Mark that failures may be truncation-related' },
+    ],
+  }),
+  discoveryCommand({
+    name: 'deepseek-v4-runtime-guardrails',
+    aliases: ['sparse-attention-runtime-guardrails', 'deepseek-runtime-guardrails'],
+    description: 'Map DeepSeek-V4 sparse-attention serving and verified-RL rollout risks to runtime safety gates',
+    flags: [
+      jsonFlag(),
+      { name: 'workload', type: 'string', description: 'Runtime workload name' },
+      { name: 'model', type: 'string', description: 'Model candidate, such as deepseek-v4-flash or deepseek-v4-pro' },
+      { name: 'engine', type: 'string', description: 'Serving engine, such as sglang' },
+      { name: 'context-tokens', type: 'number', description: 'Observed or target long-context token count' },
+      { name: 'target-context-tokens', type: 'number', description: 'Maximum context target for the runtime rollout' },
+      { name: 'baseline-throughput', type: 'number', description: 'Baseline decode throughput before runtime change' },
+      { name: 'new-throughput', type: 'number', description: 'Decode throughput after runtime change' },
+      { name: 'hybrid-attention', type: 'boolean', description: 'Mark that hybrid sparse attention is active' },
+      { name: 'prefix-cache', type: 'boolean', description: 'Mark that prefix caching is active' },
+      { name: 'cache-coherence-eval', type: 'boolean', description: 'Mark that cache reuse and rollback coherence were evaluated' },
+      { name: 'speculative-decoding', type: 'boolean', description: 'Mark that MTP, EAGLE, or another speculation path is active' },
+      { name: 'accept-length', type: 'number', description: 'Measured speculative decoding accept length' },
+      { name: 'kv-offload', type: 'boolean', description: 'Mark that KV cache offload or capacity extension is active' },
+      { name: 'training', type: 'boolean', description: 'Mark that the rollout feeds RL, DPO, or fine-tuning' },
+      { name: 'rollout-replay', type: 'boolean', description: 'Mark that rollout routing replay is captured' },
+      { name: 'indexer-replay', type: 'boolean', description: 'Mark that sparse indexer choices are replayed for training' },
+      { name: 'train-inference-drift', type: 'number', description: 'Measured train versus inference log-prob or route drift' },
+      { name: 'precision-mode', type: 'string', description: 'Precision mode, such as fp4, fp8, mxfp, or mixed' },
+      { name: 'deterministic', type: 'boolean', description: 'Mark that deterministic settings and sensitive FP32 paths are enforced' },
+      { name: 'numerical-spikes', type: 'boolean', description: 'Mark that KL, reward, or eval spikes were observed' },
+    ],
+  }),
+  discoveryCommand({
+    name: 'upstream-contributions',
+    aliases: ['upstream-contribution-engine', 'upstream-prs'],
+    description: 'Rank issues in upstream repos ThumbGate depends on and generate governed PR contribution lanes',
+    flags: [
+      jsonFlag(),
+      { name: 'write', type: 'boolean', description: 'Write markdown and JSON operator artifacts under docs/marketing' },
+      { name: 'live', type: 'boolean', description: 'Use gh issue list for live issue discovery; default is offline query planning' },
+      { name: 'max-repos', type: 'number', description: 'Maximum direct dependency repos to scan or plan' },
+      { name: 'max-issues', type: 'number', description: 'Maximum issues to keep per repo' },
+    ],
+  }),
+  discoveryCommand({
+    name: 'background-governance',
+    aliases: ['background-agent-governance', 'agent-governance'],
+    description: 'Report background-agent runs and pre-check unattended PR dispatch risk',
+    flags: [
+      jsonFlag(),
+      { name: 'window-hours', type: 'number', description: 'Lookback window for the run report (default 24)' },
+      { name: 'feedback-dir', type: 'string', description: 'Explicit ThumbGate feedback directory' },
+      { name: 'check', type: 'boolean', description: 'Run a pre-dispatch governance check instead of the report' },
+      { name: 'agent-id', type: 'string', description: 'Agent identifier for --check' },
+      { name: 'run-type', type: 'string', description: 'Run type for --check, such as pr or ci-repair' },
+      { name: 'branch', type: 'string', description: 'Target branch for --check' },
+      { name: 'files-changed', type: 'number', description: 'Estimated files changed for --check' },
+    ],
+  }),
+  discoveryCommand({
+    name: 'model-candidates',
+    aliases: ['managed-models'],
+    description: 'Rank managed model candidates and emit benchmark plans for routed workloads',
+    flags: [
+      jsonFlag(),
+      { name: 'workload', type: 'string', description: 'Workload id, such as pretool-gating, long-trace-review, cheap-fast-path, or dashboard-analysis' },
+      { name: 'provider', type: 'string', description: 'Provider filter, such as openai, anthropic, or openai-compatible' },
+      { name: 'family', type: 'string', description: 'Model family filter' },
+      { name: 'gateway', type: 'string', description: 'Gateway filter for openai-compatible providers' },
+      { name: 'max', type: 'number', description: 'Maximum recommendations to return (default 3)' },
+    ],
+  }),
   {
     name: 'lesson-health',
     aliases: ['stale'],

package/scripts/code-graph-guardrails.js

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+'use strict';
+
+const path = require('node:path');
+const { listGateTemplates } = require('./gate-templates');
+
+const DEFAULT_GRAPH_TOOL = 'code-graph';
+const KNOWLEDGE_GRAPH_CATEGORY = 'Knowledge Graph Safety';
+
+function splitCsv(value) {
+  if (Array.isArray(value)) return value.map(String).map((item) => item.trim()).filter(Boolean);
+  if (value === undefined || value === null || value === true) return [];
+  return String(value)
+    .split(',')
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+function unique(values) {
+  return Array.from(new Set(values.filter(Boolean)));
+}
+
+function normalizeOptions(options = {}) {
+  const layers = unique([
+    ...splitCsv(options.layers),
+    ...splitCsv(options['layers-touched']),
+  ]);
+  const centralFiles = unique([
+    ...splitCsv(options['central-files']),
+    ...splitCsv(options.centrality === 'high' || options.centrality === 'critical' ? options.files : []),
+  ]);
+  const generatedArtifacts = unique([
+    ...splitCsv(options['generated-artifacts']),
+    ...splitCsv(options.artifacts),
+  ]);
+
+  return {
+    graphTool: String(options['graph-tool'] || options.tool || DEFAULT_GRAPH_TOOL).trim() || DEFAULT_GRAPH_TOOL,
+    graphPath: options['graph-path'] ? String(options['graph-path']).trim() : null,
+    centralFiles,
+    layersTouched: layers,
+    generatedArtifacts,
+    changedFiles: Number.isFinite(Number(options['changed-files'])) ? Number(options['changed-files']) : null,
+  };
+}
+
+function gateApplicability(template, options) {
+  if (template.id === 'require-diff-impact-before-central-edit') {
+    return options.centralFiles.length > 0;
+  }
+  if (template.id === 'checkpoint-cross-layer-refactor') {
+    return options.layersTouched.length >= 2;
+  }
+  if (template.id === 'protect-graph-generated-artifacts') {
+    return options.generatedArtifacts.length > 0 || Boolean(options.graphPath);
+  }
+  return false;
+}
+
+function buildSignalSummary(options) {
+  const signals = [];
+  if (options.centralFiles.length > 0) {
+    signals.push({
+      id: 'central_files',
+      label: 'High-centrality files',
+      values: options.centralFiles,
+      risk: 'central edits can break many downstream paths',
+    });
+  }
+  if (options.layersTouched.length >= 2) {
+    signals.push({
+      id: 'cross_layer_refactor',
+      label: 'Cross-layer refactor',
+      values: options.layersTouched,
+      risk: 'one run is crossing architectural layers',
+    });
+  }
+  if (options.generatedArtifacts.length > 0 || options.graphPath) {
+    signals.push({
+      id: 'generated_graph_artifacts',
+      label: 'Generated graph artifacts',
+      values: unique([...options.generatedArtifacts, options.graphPath ? path.normalize(options.graphPath) : null]),
+      risk: 'graph outputs should be regenerated from source, not hand-edited',
+    });
+  }
+  if (options.changedFiles !== null && options.changedFiles >= 20) {
+    signals.push({
+      id: 'large_blast_radius',
+      label: 'Large blast radius',
+      values: [`${options.changedFiles} changed files`],
+      risk: 'large graph-informed changes should be checkpointed before execution continues',
+    });
+  }
+  return signals;
+}
+
+function buildCodeGraphGuardrailsPlan(rawOptions, templatesPath) {
+  const options = normalizeOptions(rawOptions || {});
+  const templates = listGateTemplates(templatesPath)
+    .filter((template) => template.category === KNOWLEDGE_GRAPH_CATEGORY);
+  const signals = buildSignalSummary(options);
+  const recommendedTemplates = templates.map((template) => ({
+    ...template,
+    recommended: gateApplicability(template, options),
+  }));
+
+  const activeTemplates = recommendedTemplates.filter((template) => template.recommended);
+  const status = activeTemplates.length > 0 ? 'actionable' : 'ready';
+
+  return {
+    name: 'thumbgate-code-graph-guardrails',
+    status,
+    graphTool: options.graphTool,
+    graphPath: options.graphPath,
+    summary: {
+      signalCount: signals.length,
+      templateCount: templates.length,
+      recommendedTemplateCount: activeTemplates.length,
+      changedFiles: options.changedFiles,
+    },
+    signals,
+    templates: recommendedTemplates,
+    nextActions: buildNextActions(),
+    exampleCommand: 'npx thumbgate code-graph-guardrails --central-files=src/api/server.js --layers=api,data --generated-artifacts=.codegraph/index.json --json',
+  };
+}
+
+function buildNextActions() {
+  return [
+    'Generate or refresh the code graph before a risky agent edit session.',
+    'Tag central files, architecture layers, and generated graph outputs in your agent context.',
+    'Enable the recommended Knowledge Graph Safety templates as pre-action gates.',
+    'Capture thumbs-down corrections when a graph-informed action still misses impact review.',
+  ];
+}
+
+function formatCodeGraphGuardrailsPlan(report) {
+  const lines = [
+    '',
+    'ThumbGate Code Graph Guardrails',
+    '-'.repeat(36),
+    `Status     : ${report.status}`,
+    `Graph tool : ${report.graphTool}`,
+  ];
+  if (report.graphPath) lines.push(`Graph path : ${report.graphPath}`);
+  lines.push(`Signals    : ${report.summary.signalCount}`);
+  lines.push(`Templates  : ${report.summary.recommendedTemplateCount}/${report.summary.templateCount} recommended`);
+
+  if (report.signals.length > 0) {
+    lines.push('', 'Detected graph risk signals:');
+    for (const signal of report.signals) {
+      lines.push(`  - ${signal.label}: ${signal.values.join(', ')}`);
+      lines.push(`    Risk: ${signal.risk}`);
+    }
+  }
+
+  lines.push('', 'Recommended templates:');
+  for (const template of report.templates.filter((entry) => entry.recommended)) {
+    lines.push(`  - ${template.id} [${template.defaultAction}]`);
+    lines.push(`    ${template.roi}`);
+  }
+  if (report.summary.recommendedTemplateCount === 0) {
+    lines.push('  - No graph-specific signals were passed. Start by supplying --central-files, --layers, or --generated-artifacts.');
+  }
+
+  lines.push('', 'Next actions:');
+  for (const action of report.nextActions) lines.push(`  - ${action}`);
+  lines.push('', `Example: ${report.exampleCommand}`, '');
+  return `${lines.join('\n')}\n`;
+}
+
+module.exports = {
+  buildCodeGraphGuardrailsPlan,
+  formatCodeGraphGuardrailsPlan,
+  normalizeOptions,
+};