delimit-cli 4.3.4 → 4.5.0

package/CHANGELOG.md

@@ -1,5 +1,101 @@
 # Changelog
 
+
+## [4.5.0] - 2026-04-27
+
+### Added — Ledger hygiene toolkit (LED-1145, 7 PRs)
+
+The full hygiene loop is now a single MCP surface — call `delimit_ledger_health` to see what's wrong, then run the suggested tool to fix it.
+
+- **`delimit_ledger_health`** — one-shot traffic-light status (P0 inflation / stale / duplicates / garbage venture) with ranked next-action list
+- **`delimit_ledger_groom`** — read-only proposal: stale-open + duplicate-titles + garbage-venture detection. Each proposal includes a copy-pasteable `delimit_ledger_bulk` invocation
+- **`delimit_ledger_bulk(item_ids, action, dry_run=True)`** — batch operations (`archive`, `set_status`, `set_priority`, `add_tag`, `mark_done`, `cancel`). `dry_run=True` is the safety default. **No hard delete** — archive is an append-only soft transition
+- **`delimit_ledger_auto_close_external`** — find LEDs linked to a GitHub issue/PR and auto-close when the upstream resolves (mark_done for merged PRs / closed-as-completed; archive for not_planned closures)
+- **`delimit_ledger_auto_cancel_stale`** — auto-archive items dormant past `DELIMIT_STALE_TTL_DAYS` (default 60). Composes `bulk_action(archive)`. dry_run default
+- **Extended `delimit_ledger_list`** — new filters: `status_in`, `priority_in`, `tags_contains_all`, `text`, `linked_external_id`, `created_before/after`, `updated_before/after`, `sort`, `order`, `fields` projection (`"slim"` / explicit list / unknown=error), cursor pagination
+- **P0 soft-quota** on `delimit_ledger_add` — soft warning when count > `DELIMIT_P0_SOFT_QUOTA` (default 50). Item still added; surfaces a nudge to groom
+
+### Added — Memory-system convergence (LED-1165)
+
+`delimit_memory` is now the canonical durable memory; Claude Code auto-memory becomes a one-way client projection.
+
+- **`hot_load: bool` parameter** on `delimit_memory_store` — opt-in, default False. Marks an entry for projection
+- **`delimit_memory_index(target_path, dry_run, limit)`** — projects hot_load=True entries into a managed section of MEMORY.md (`<!-- delimit:start -->` / `<!-- delimit:end -->` markers). User content outside markers is preserved verbatim. **One-way only** — never reads MEMORY.md back into delimit_memory
+
+### Fixed — Secret-scanner false positives in `tools_infra`
+
+The `_CREDENTIAL_FALSE_POSITIVES` regex now suppresses three additional benign patterns so legitimate credential-loading code (env-var lookup, dict-getter, control-flow guards) doesn't trip the audit:
+- `\w+\.get(` (any object-method getter, was tokens-only)
+- `if not <var>:` (Python control-flow with credential variable)
+- `:\n` matched-text (block-opener colon, not key-value separator)
+
+### Fixed — OpenAPI diff engine defensive coverage
+
+Real-world specs can ship malformed shapes. The diff engine now defends against the entire dict-iteration crash class without losing any actual finding:
+
+- **`required: bool` in object schemas** (legal in parameter objects but seen leaking into nested schemas) — was raising `TypeError: 'bool' object is not iterable`. Treats as no-required-fields and continues
+- **`properties: [...]` instead of dict** (Kong-class) — `.keys()` no longer crashes; treats as empty properties and continues
+- **`paths: []`, `responses: []`, `content: []` (request and response)** — all coerce to `{}` at function entry. Diffs against the well-formed side still produce correct findings
+
+### Tests
+- 108 ledger-manager tests (15 originals + 93 new across 7 features + E2E hygiene-loop integration)
+- 24 memory-bridge tests (new test file)
+- 60 diff-engine tests (49 + 11 new defensive)
+- All backward-compatible — existing test suites pass without modification
+
+### Backward compatibility
+- All MCP tool parameter additions are optional with safe defaults
+- Existing storage format is unchanged (`hot_load` and `archived` are additive on the entry/status side)
+- No CLI command renamed or removed
+- Default `delimit_ledger_list` response shape preserved (full record by default; `fields="slim"` opts into the 90% payload reduction)
+
+## [4.4.0] - 2026-04-25
+
+### Added — Pre-external-PR duplicate guard
+
+- **New MCP tool `delimit_external_pr_check(repo, author)`** — pre-flight gate that runs `gh pr list` against a target repo and returns a fail-closed verdict if any matching open PR (or recently-merged PR within 30 days) already exists. Prevents autonomous workflows from drafting duplicate external-repo PRs off stale outreach signals.
+- **`delimit_gov_evaluate(action="external_pr", context={target_repo, author})`** composes the duplicate check + policy evaluation in one call. Verdict `blocked_duplicate` is a hard stop.
+- **CLAUDE.md auto-trigger rule added**: BEFORE drafting any external-repo PR, the duplicate gate must pass.
+- 12 new unit tests covering: open PR, recently-merged PR, old merged PR, closed PR, gh CLI not installed, gh auth failure, missing target_repo. End-to-end test against real `goharbor/harbor` PR #23089 confirms duplicate detection works.
+
+### Documentation
+- readme: replace stale demo links + delete old GIF (#67) (e6059dd3)
+- LED-1089 SECURITY.md — install-time + runtime threat model (#65) (4e03319c)
+- readme: canon-aligned hero + real attestation demo (#63) (9172924a)
+
+### CI/CD
+- retry verify-published-version with bounded backoff (fixes v4.3.4 race) (#62) (f5a768d5)
+
+### Other
+- LED-1084 week 2 hygiene: build features.json during `delimit setup` (#66) (8145456f)
+- sync: gateway LED-1010 design tool fixes (Tailwind awareness, status taxonomy, link-href FP) (#64) (d756e1bb)
+
+### Completed Ledger Items
+- **LED-1094**: [P1] Consensus reached: Review the full transcript. As orchestrator, provide your own analysis and final
+- **LED-1095**: [P1] Consensus reached: Review the full transcript. As orchestrator, provide your own analysis and final
+- **LED-1096**: [P1] Consensus reached: Review the full transcript. As orchestrator, provide your own analysis and final
+- **LED-1097**: [P1] Consensus reached: Review the full transcript. As orchestrator, provide your own analysis and final
+- **LED-1098**: [P1] Consensus reached: Review the full transcript. As orchestrator, provide your own analysis and final
+- **LED-1100**: [P1] Consensus reached: Review the full transcript. As orchestrator, provide your own analysis and final
+- **LED-1102**: [P1] Consensus reached: Review the full transcript. As orchestrator, provide your own analysis and final
+- **LED-1103**: [P1] Consensus reached: Review the full transcript. As orchestrator, provide your own analysis and final
+- **LED-1104**: [P1] Consensus reached: Review the full transcript. As orchestrator, provide your own analysis and final
+- **LED-1105**: [P1] Consensus reached: Review the full transcript. As orchestrator, provide your own analysis and final
+- **LED-1106**: [P1] Build responsive-overflow gate (narrow MVP) — dogfood on delimit.ai
+- **LED-1107**: [P1] Fix 3 responsive overflow bugs caught by LED-1106 gate on first dogfood run
+- **LED-1108**: [P1] Cross-venture task
+- **LED-1109**: [P1] Cross-venture task
+- **LED-1110**: [P1] Cross-venture task
+- **LED-1111**: [P1] Consensus reached: Review the full transcript. As orchestrator, provide your own analysis and final
+- **LED-1113**: [P1] Cross-venture task
+- **LED-1114**: [P1] Consensus reached: Review the full transcript. As orchestrator, provide your own analysis and final
+
+### Stats
+- **Commits**: 6
+- **Files changed**: 6
+- **Insertions**: 708(+) / 130(-)
+- **Since**: v4.3.4
+
 ## [4.2.0] - 2026-04-21
 
 ### Added (gateway sync — LED-987 through LED-1008)

package/README.md

@@ -1,36 +1,43 @@
 # `</>` Delimit
 
-Stop re-explaining your codebase every session. Memory, tasks, and governance that persist across Claude Code, Codex, Cursor, and Gemini CLI.
+**The merge gate for AI-written code — with signed, replayable attestation.**
 
-
----
-
-## Think and Build
-
-The universal command for the Delimit Swarm. When you say **"Think and Build"**, your AI agents (Claude, Codex, Gemini, Cursor) automatically deploy a background autonomous build loop that monitors your ledger, deliberates on strategy, and implements code while you focus on the architecture.
-
-- **"Think"**: Trigger multi-model deliberation and strategic dispatch.
-- **"Build"**: Activate the background daemon to execute tasks and verify gates.
-- **"Vault"**: Manage local secrets and API keys (AES-256 encrypted).
-
-Works across any configuration — from a single model on a budget to an enterprise swarm of 4+ models.
+Wrap any AI coding assistant (Claude Code, Codex, Cursor, Gemini CLI) with a governance chain that runs your gates, records what changed, and signs a replayable receipt for every merge.
 
 [![npm](https://img.shields.io/npm/v/delimit-cli)](https://www.npmjs.com/package/delimit-cli)
-[![Tests](https://img.shields.io/badge/tests-134%20passing-brightgreen)](https://github.com/delimit-ai/delimit-mcp-server)
+[![Tests](https://img.shields.io/badge/tests-165%20passing-brightgreen)](https://github.com/delimit-ai/delimit-mcp-server)
 [![GitHub Action](https://img.shields.io/badge/GitHub%20Action-v1.6.0-blue)](https://github.com/marketplace/actions/delimit-api-governance)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 [![Glama](https://glama.ai/mcp/servers/delimit-ai/delimit/badge)](https://glama.ai/mcp/servers/delimit-ai/delimit)
 
-<p align="center">
-  <img src="docs/demo.gif" alt="Delimit v4.20 — doctor, simulate, status, memory" width="700">
-</p>
+```console
+$ delimit wrap -- claude "fix the flaky test in tests/api.spec.ts"
+
+✓ repo_diagnose
+✓ security_audit       0 critical · 0 secrets
+✓ test_smoke           165/165
+✓ changed_files        1
+✓ attestation signed   att_a05050eb8e13277e
+                       delimit.attestation.v1 · HMAC-SHA256
+                       replay → https://delimit.ai/att/att_a05050eb8e13277e
+```
+
+Every wrapped run emits a `delimit.attestation.v1` bundle: repo head before/after, changed files, gate results, HMAC-SHA256 signature, and a replay URL. Advisory by default; flip to enforcing when you're ready.
 
 <p align="center">
-  <a href="https://youtu.be/8e_6P7rkFxo">Watch the demo</a> · <a href="https://youtu.be/4O1wY4vWmiY">Multi-model deliberation</a> · <a href="https://delimit.ai">Website</a>
+  <a href="https://github.com/delimit-ai/delimit-action/releases/tag/v1.10.0">See a signed release</a> · <a href="https://delimit.ai/docs/workflow">Workflow guide</a> · <a href="https://delimit.ai">Website</a>
 </p>
 
 ---
 
+## Think and Build
+
+Beyond the merge gate, Delimit orchestrates multi-model deliberation and autonomous builds. `delimit think` dispatches a strategic question to Claude, Codex, Gemini, and Grok; `delimit build` activates a background daemon that executes ledger tasks through the gate chain. `delimit vault` manages local secrets (AES-256).
+
+Works across any configuration, from a single model on a budget to a full panel.
+
+---
+
 ## Try it in 2 minutes
 
 ```bash

package/adapters/codex-security.js

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+/**
+ * Delimit Security Skill for Codex CLI
+ *
+ * Validates that Codex-generated code doesn't introduce security anti-patterns.
+ * Runs as a security validation skill.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const SECURITY_PATTERNS = [
+    { pattern: /eval\s*\(/g, severity: 'high', message: 'eval() usage detected — potential code injection' },  // nosec B-eval_usage: regex-pattern DEFINITION string for security scanner
+    { pattern: /exec\s*\(/g, severity: 'medium', message: 'exec() usage — verify input sanitization' },  // nosec B-exec_usage: regex-pattern DEFINITION string for security scanner
+    { pattern: /shell\s*=\s*True/g, severity: 'high', message: 'subprocess with shell=True — command injection risk' },
+    { pattern: /dangerouslySetInnerHTML/g, severity: 'medium', message: 'dangerouslySetInnerHTML — XSS risk' },  // nosec B-dangerous_innerHTML: regex-pattern DEFINITION string
+    { pattern: /password\s*=\s*["'][^"']+["']/gi, severity: 'high', message: 'Hardcoded password detected' },
+    { pattern: /api[_-]?key\s*=\s*["'][A-Za-z0-9]{10,}["']/gi, severity: 'high', message: 'Hardcoded API key detected' },
+];
+
+function checkSecurity(context) {
+    const code = context.code || context.content || '';
+    if (!code) return { status: 'clean', findings: [] };
+
+    const findings = [];
+    for (const { pattern, severity, message } of SECURITY_PATTERNS) {
+        const matches = code.match(pattern);
+        if (matches) {
+            findings.push({ severity, message, count: matches.length });
+        }
+    }
+
+    // Audit
+    try {
+        const auditDir = path.join(process.env.HOME || '', '.delimit', 'audit');
+        fs.mkdirSync(auditDir, { recursive: true });
+        const record = {
+            timestamp: new Date().toISOString(),
+            source: 'codex-security',
+            findings_count: findings.length,
+            high_count: findings.filter(f => f.severity === 'high').length,
+        };
+        const auditFile = path.join(auditDir, `${new Date().toISOString().split('T')[0]}.jsonl`);
+        fs.appendFileSync(auditFile, JSON.stringify(record) + '\n');
+    } catch {}
+
+    const hasHigh = findings.some(f => f.severity === 'high');
+    return {
+        status: hasHigh ? 'flagged' : findings.length > 0 ? 'warnings' : 'clean',
+        findings,
+    };
+}
+
+const context = process.argv[2] ? JSON.parse(process.argv[2]) : {};
+const result = checkSecurity(context);
+
+if (result.status === 'flagged') {
+    for (const f of result.findings) {
+        console.error(`[Delimit Security] ${f.severity.toUpperCase()}: ${f.message}`);
+    }
+    process.exit(1);
+}
+
+process.exit(0);

package/adapters/codex-skill.js

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+/**
+ * Delimit Governance Skill for Codex CLI
+ *
+ * Runs as a validation skill triggered on pre-code-generation and pre-suggestion.
+ * Checks governance state and policy compliance before Codex executes actions.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const DELIMIT_HOME = path.join(process.env.HOME || '', '.delimit');
+const MODE_FILE = path.join(DELIMIT_HOME, 'enforcement_mode');
+
+function getMode() {
+    try {
+        return fs.readFileSync(MODE_FILE, 'utf-8').trim();
+    } catch {
+        return 'guarded'; // Default
+    }
+}
+
+function checkGovernance(context) {
+    const mode = getMode();
+    const warnings = [];
+
+    // Check if governance is initialized
+    const policiesFile = path.join(process.cwd(), '.delimit', 'policies.yml');
+    if (!fs.existsSync(policiesFile)) {
+        warnings.push('No .delimit/policies.yml — run: delimit init');
+    }
+
+    // Check for sensitive file access
+    const sensitivePatterns = ['.env', 'credentials', '.ssh', 'secrets'];
+    const target = context.target || context.file || '';
+    for (const pattern of sensitivePatterns) {
+        if (target.includes(pattern)) {
+            if (mode === 'enforce') {
+                return { status: 'blocked', reason: `Access to sensitive path: ${target}` };
+            }
+            warnings.push(`Accessing sensitive path: ${target}`);
+        }
+    }
+
+    // Audit log
+    try {
+        const auditDir = path.join(DELIMIT_HOME, 'audit');
+        fs.mkdirSync(auditDir, { recursive: true });
+        const record = {
+            timestamp: new Date().toISOString(),
+            source: 'codex-skill',
+            mode,
+            context: typeof context === 'object' ? JSON.stringify(context).slice(0, 200) : String(context).slice(0, 200),
+            warnings,
+        };
+        const auditFile = path.join(auditDir, `${new Date().toISOString().split('T')[0]}.jsonl`);
+        fs.appendFileSync(auditFile, JSON.stringify(record) + '\n');
+    } catch {}
+
+    return { status: 'allowed', mode, warnings };
+}
+
+// Entry point — read context from stdin or args
+const context = process.argv[2] ? JSON.parse(process.argv[2]) : {};
+const result = checkGovernance(context);
+
+if (result.status === 'blocked') {
+    console.error(`[Delimit] BLOCKED: ${result.reason}`);
+    process.exit(1);
+}
+
+if (result.warnings.length > 0) {
+    for (const w of result.warnings) {
+        console.error(`[Delimit] Warning: ${w}`);
+    }
+}
+
+process.exit(0);

package/adapters/cursor-rules.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+/**
+ * Delimit Governance Rules for Cursor
+ *
+ * Cursor doesn't have a hook system like Claude Code or Codex,
+ * so governance enforcement happens server-side via MCP tool calls.
+ * This adapter manages the .cursorrules and .cursor/rules/ files
+ * that guide Cursor's behavior.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// LED-213: Import canonical template for cross-model parity
+const { getDelimitSection } = require('../lib/delimit-template');
+
+const HOME = process.env.HOME || '';
+const CURSOR_DIR = path.join(HOME, '.cursor');
+const CURSOR_RULES_DIR = path.join(CURSOR_DIR, 'rules');
+const CURSORRULES_FILE = path.join(HOME, '.cursorrules');
+
+/**
+ * Install Delimit governance rules into Cursor.
+ * Creates both .cursorrules (legacy) and .cursor/rules/delimit.md (new).
+ */
+function installRules(version) {
+    const rules = getDelimitRules(version);
+
+    // Install to .cursor/rules/delimit.md (new location, Cursor 0.45+)
+    if (fs.existsSync(CURSOR_DIR)) {
+        fs.mkdirSync(CURSOR_RULES_DIR, { recursive: true });
+        const rulesFile = path.join(CURSOR_RULES_DIR, 'delimit.md');
+        fs.writeFileSync(rulesFile, rules);
+    }
+
+    return { installed: true, paths: [CURSORRULES_FILE, path.join(CURSOR_RULES_DIR, 'delimit.md')] };
+}
+
+/**
+ * Remove Delimit rules from Cursor.
+ */
+function uninstallRules() {
+    const removed = [];
+
+    // Remove from .cursor/rules/
+    const rulesFile = path.join(CURSOR_RULES_DIR, 'delimit.md');
+    if (fs.existsSync(rulesFile)) {
+        fs.unlinkSync(rulesFile);
+        removed.push(rulesFile);
+    }
+
+    return { removed };
+}
+
+function getDelimitRules(version) {
+    // LED-213: Use canonical Consensus 123 template for Cursor parity
+    return getDelimitSection();
+}
+
+module.exports = { installRules, uninstallRules, getDelimitRules };
+
+// CLI entry point
+if (require.main === module) {
+    const action = process.argv[2] || 'install';
+    const version = process.argv[3] || '3.11.9';
+    if (action === 'install') {
+        const result = installRules(version);
+        console.log(`Installed Delimit rules to Cursor: ${result.paths.join(', ')}`);
+    } else if (action === 'uninstall') {
+        const result = uninstallRules();
+        console.log(`Removed: ${result.removed.join(', ') || 'nothing to remove'}`);
+    }
+}

package/bin/delimit-setup.js

@@ -273,6 +273,29 @@ async function main() {
         }
     }
 
+    // LED-1084 week 2: build the content-grounding feature whitelist.
+    // Populates ~/.delimit/content/grounding/features.json with every
+    // @mcp.tool() entry + every CLI subcommand we ship. Drafters then
+    // have a concrete list of "things delimit actually does" to check
+    // generated text against. Fail-soft — install continues even if
+    // the build fails for any reason.
+    try {
+        const groundingModule = path.join(DELIMIT_HOME, 'server', 'ai', 'content_grounding', 'features.py');
+        if (fs.existsSync(groundingModule)) {
+            execSync(`"${python}" -m ai.content_grounding.features build`, {
+                stdio: 'pipe',
+                cwd: path.join(DELIMIT_HOME, 'server'),
+                env: { ...process.env, PYTHONPATH: path.join(DELIMIT_HOME, 'server') },
+                timeout: 10000,
+            });
+            await logp(`  ${green('✓')} Grounding whitelist built (~/.delimit/content/grounding/features.json)`);
+        }
+    } catch {
+        // Silent fail — the whitelist is optional; drafters fall back to empty
+        // which makes the gate strict but doesn't break anything. Customers
+        // can rebuild manually later: `python -m ai.content_grounding.features build`.
+    }
+
     // Step 3: Configure Claude Code MCP
     step(3, 'Configuring Claude Code MCP...');
 

package/gateway/ai/backends/governance_bridge.py

@@ -158,9 +158,49 @@ def _not_init_response(tool_name: str, **extra) -> Dict[str, Any]:
 
 
 def evaluate_trigger(action: str, context: Optional[Dict] = None, repo: str = ".") -> Dict[str, Any]:
-    """Evaluate if governance is required for an action."""
+    """Evaluate if governance is required for an action.
+
+    Special action "external_pr" runs the duplicate-PR pre-flight check
+    (gov.external_pr_check) before any other governance evaluation.
+    Context for external_pr should include {"target_repo": "owner/name",
+    "author": "github-username"} (author optional but recommended).
+    Verdict "duplicate" is propagated to callers as a hard stop.
+    """
     if not _is_initialized(repo):
         return _not_init_response("gov.evaluate", action=action, repo=repo)
+
+    # Pre-flight: external PR submission must check for duplicates first
+    if action == "external_pr":
+        target_repo = (context or {}).get("target_repo")
+        if not target_repo:
+            return {
+                "tool": "gov.evaluate",
+                "status": "evaluated",
+                "action": action,
+                "verdict": "missing_input",
+                "error": "external_pr action requires context.target_repo",
+            }
+        author = (context or {}).get("author")
+        check = external_pr_check(repo=target_repo, author=author)
+        # If duplicate found, fail-closed: callers should not proceed
+        if check.get("verdict") == "duplicate":
+            return {
+                "tool": "gov.evaluate",
+                "status": "evaluated",
+                "action": action,
+                "verdict": "blocked_duplicate",
+                "external_pr_check": check,
+                "next_action": (
+                    "STOP. A matching PR already exists. Review existing PR(s); "
+                    "do not draft, deliberate, or submit a duplicate."
+                ),
+            }
+        # No duplicate: still surface the check so the caller can audit
+        # the chain. Falls through to normal policy evaluation below.
+        external_check_result = check
+    else:
+        external_check_result = None
+
     # Governance is initialized -- evaluate against loaded policy
     repo_path = Path(repo).resolve()
     policies_file = repo_path / ".delimit" / "policies.yml"
@@ -169,7 +209,7 @@ def evaluate_trigger(action: str, context: Optional[Dict] = None, repo: str = ".
         rules = data.get("rules", []) if isinstance(data, dict) else []
     except Exception:
         rules = []
-    return {
+    result = {
         "tool": "gov.evaluate",
         "status": "evaluated",
         "action": action,
@@ -178,6 +218,11 @@ def evaluate_trigger(action: str, context: Optional[Dict] = None, repo: str = ".
         "governance_required": len(rules) > 0,
         "active_rules": len(rules),
     }
+    if external_check_result is not None:
+        result["external_pr_check"] = external_check_result
+        result["verdict"] = "ready_for_deliberation"
+        result["next_action"] = "Run delimit_deliberate, then submit the PR."
+    return result
 
 
 def new_task(title: str, scope: str, risk_level: str = "medium", repo: str = ".") -> Dict[str, Any]:
@@ -241,3 +286,124 @@ def require_owner_approval(context: str, repo: str = ".") -> Dict[str, Any]:
         "approval_required": False,
         "context": context,
     }
+
+
+def external_pr_check(
+    repo: str,
+    author: Optional[str] = None,
+    state: str = "all",
+) -> Dict[str, Any]:
+    """Pre-PR duplicate guard. Lists existing PRs from `author` against `repo`.
+
+    Returned verdict is fail-closed: any matching PR (open OR recently merged
+    within 30 days OR pending review) returns verdict='duplicate' so callers
+    can stop drafting before deliberation/submission.
+
+    Args:
+        repo: External GitHub repo, e.g. "goharbor/harbor".
+        author: GitHub username to filter by. If None, lists all PRs.
+        state: "open" | "closed" | "merged" | "all". Default "all" (broad).
+
+    Returns dict with:
+        verdict: "no_duplicate" | "duplicate" | "gh_unavailable" | "error"
+        prs: List of matching PR records (number, state, reviewDecision, url, mergedAt)
+        guidance: Human-readable next-step hint.
+    """
+    if not repo or "/" not in repo:
+        return {
+            "tool": "gov.external_pr_check",
+            "verdict": "error",
+            "error": "repo must be in 'owner/name' format",
+        }
+
+    cmd = ["gh", "pr", "list", "--repo", repo, "--state", state, "--limit", "50",
+           "--json", "number,title,state,reviewDecision,createdAt,mergedAt,url,author"]
+    if author:
+        cmd.extend(["--author", author])
+
+    try:
+        proc = subprocess.run(cmd, capture_output=True, text=True, timeout=20)
+    except FileNotFoundError:
+        return {
+            "tool": "gov.external_pr_check",
+            "verdict": "gh_unavailable",
+            "error": "gh CLI not installed",
+            "guidance": "Install gh (https://cli.github.com) or run `gh pr list --repo "
+                        f"{repo}" + (f" --author {author}" if author else "") + "` manually before drafting.",
+        }
+    except subprocess.TimeoutExpired:
+        return {
+            "tool": "gov.external_pr_check",
+            "verdict": "error",
+            "error": "gh pr list timed out after 20s",
+        }
+
+    if proc.returncode != 0:
+        # Most common reason: not authenticated
+        stderr = (proc.stderr or "").strip()[:300]
+        return {
+            "tool": "gov.external_pr_check",
+            "verdict": "error",
+            "error": f"gh pr list failed: {stderr}",
+            "guidance": "Run `gh auth status` to verify authentication.",
+        }
+
+    try:
+        prs = json.loads(proc.stdout or "[]")
+    except json.JSONDecodeError as exc:
+        return {
+            "tool": "gov.external_pr_check",
+            "verdict": "error",
+            "error": f"could not parse gh output: {exc}",
+        }
+
+    # Fail-closed criteria: any open PR, or any PR merged in the last 30 days
+    import time as _time
+    from datetime import datetime, timezone, timedelta
+    cutoff = datetime.now(timezone.utc) - timedelta(days=30)
+
+    duplicates = []
+    for pr in prs:
+        is_open = pr.get("state") == "OPEN"
+        merged_at = pr.get("mergedAt")
+        recently_merged = False
+        if merged_at:
+            try:
+                # gh returns ISO8601 like "2026-04-10T11:15:13Z"
+                ts = datetime.fromisoformat(merged_at.replace("Z", "+00:00"))
+                recently_merged = ts >= cutoff
+            except Exception:
+                pass
+        if is_open or recently_merged:
+            duplicates.append({
+                "number": pr.get("number"),
+                "title": pr.get("title"),
+                "state": pr.get("state"),
+                "reviewDecision": pr.get("reviewDecision"),
+                "createdAt": pr.get("createdAt"),
+                "mergedAt": merged_at,
+                "url": pr.get("url"),
+                "author": (pr.get("author") or {}).get("login"),
+            })
+
+    if duplicates:
+        return {
+            "tool": "gov.external_pr_check",
+            "verdict": "duplicate",
+            "repo": repo,
+            "author": author,
+            "prs": duplicates,
+            "guidance": (
+                f"Found {len(duplicates)} existing PR(s) — DO NOT draft a duplicate. "
+                "Review the existing PR(s) and decide: monitor, comment, or update."
+            ),
+        }
+
+    return {
+        "tool": "gov.external_pr_check",
+        "verdict": "no_duplicate",
+        "repo": repo,
+        "author": author,
+        "checked_count": len(prs),
+        "guidance": "Safe to proceed with drafting. Run delimit_deliberate before submitting.",
+    }