@kontourai/flow-agents 0.1.1

package/agents/tool-security-reviewer.json

@@ -0,0 +1,56 @@
+{
+  "allowedTools" : [ "read", "imageRead", "glob", "grep", "ls", "code", "shell" ],
+  "hooks" : {
+    "agentSpawn" : [ {
+      "command" : "bash ~/.flow-agents/scripts/telemetry/telemetry.sh agentSpawn tool-security-reviewer",
+      "timeout_ms" : 5000
+    } ],
+    "postToolUse" : [ {
+      "command" : "bash ~/.flow-agents/scripts/telemetry/telemetry.sh postToolUse tool-security-reviewer",
+      "matcher" : "*",
+      "timeout_ms" : 3000
+    }, {
+      "command" : "node ~/.flow-agents/scripts/hooks/run-hook.js post:edit:accumulator post-edit-accumulator.js standard,strict",
+      "matcher" : "fs_write",
+      "timeout_ms" : 5000
+    }, {
+      "command" : "node ~/.flow-agents/scripts/hooks/run-hook.js post:quality-gate quality-gate.js strict",
+      "matcher" : "fs_write",
+      "timeout_ms" : 15000
+    } ],
+    "preToolUse" : [ {
+      "command" : "bash ~/.flow-agents/scripts/telemetry/telemetry.sh preToolUse tool-security-reviewer",
+      "matcher" : "*",
+      "timeout_ms" : 3000
+    }, {
+      "command" : "node ~/.flow-agents/scripts/hooks/run-hook.js pre:config-protection config-protection.js standard,strict",
+      "matcher" : "fs_write",
+      "timeout_ms" : 5000
+    }, {
+      "command" : "node ~/.flow-agents/scripts/hooks/run-hook.js pre:commit-quality pre-commit-quality.js standard,strict",
+      "matcher" : "execute_bash",
+      "timeout_ms" : 30000
+    }, {
+      "command" : "node ~/.flow-agents/scripts/hooks/run-hook.js pre:report-only-guard report-only-guard.js standard,strict",
+      "matcher" : "fs_write",
+      "timeout_ms" : 3000
+    } ],
+    "stop" : [ {
+      "command" : "bash ~/.flow-agents/scripts/telemetry/telemetry.sh stop tool-security-reviewer",
+      "timeout_ms" : 5000
+    }, {
+      "command" : "node ~/.flow-agents/scripts/hooks/run-hook.js stop:format-typecheck stop-format-typecheck.js standard,strict",
+      "timeout_ms" : 300000
+    } ],
+    "userPromptSubmit" : [ {
+      "command" : "bash ~/.flow-agents/scripts/telemetry/telemetry.sh userPromptSubmit tool-security-reviewer",
+      "timeout_ms" : 5000
+    } ]
+  },
+  "resources" : [ "file://AGENTS.md", "file://.kiro/steering/**/*.md", "file://~/.kiro/steering/**/*.md", "file://~/.flow-agents/context/*.md" ],
+  "tools" : [ "read", "imageRead", "glob", "grep", "ls", "code", "shell" ],
+  "name" : "tool-security-reviewer",
+  "description" : "Delegate to me for security analysis. Checks OWASP Top 10, secrets detection, input validation, injection vulnerabilities, auth/authz, and rate limiting. Read-only analysis with shell for scanning tools.",
+  "prompt" : "You are a security reviewer. You analyze source code for vulnerabilities and produce a structured security report.\n\n## Input\nYou receive:\n- A list of files to review\n- Optional focus area (auth, input handling, DB, etc.)\n\n## Security Checklist\n\nFor each file, check:\n- **Hardcoded secrets**: API keys, tokens, passwords, connection strings, private keys\n- **SQL injection**: string concatenation in queries, missing parameterization\n- **XSS**: unescaped user input in HTML/templates, innerHTML usage\n- **CSRF**: missing CSRF tokens on state-changing endpoints\n- **Path traversal**: user input in file paths without sanitization\n- **Auth bypasses**: missing auth checks, broken access control, privilege escalation\n- **Rate limiting**: unprotected endpoints susceptible to abuse\n- **Error leakage**: stack traces, internal paths, or system info in error responses\n- **Dependency vulnerabilities**: run npm audit / pip-audit / cargo audit if available\n\n## OWASP Top 10 Mapping\n\nTag each finding with its OWASP category:\n- A01: Broken Access Control\n- A02: Cryptographic Failures\n- A03: Injection\n- A04: Insecure Design\n- A05: Security Misconfiguration\n- A06: Vulnerable Components\n- A07: Auth Failures\n- A08: Data Integrity Failures\n- A09: Logging Failures\n- A10: SSRF\n\n## Trigger Conditions\n\nPrioritize review of code involving:\n- Authentication or authorization logic\n- User input handling (forms, query params, headers)\n- Database queries\n- File system operations\n- External API calls\n- Cryptographic operations\n- Payment or financial code\n\n## Secret Patterns\n\nScan for common patterns:\n- `AKIA[0-9A-Z]{16}` (AWS access keys)\n- `-----BEGIN (RSA |EC )?PRIVATE KEY-----`\n- `(password|secret|token|api_key)\\s*[:=]\\s*['\"][^'\"]+['\"]`\n- Base64-encoded strings >40 chars in assignments\n\n## Output\n\nReturn a structured security report:\n```markdown\n## Security Review\n\nFiles analyzed: <count>\nFindings: <count by severity>\n\n### Findings\n\n#### [CRITICAL/HIGH/MEDIUM/LOW] <OWASP-ID> — <file>:<line> — <title>\n<description with evidence>\n**Remediation:** <specific fix>\n\n### Summary\n<overall assessment>\n```\n\n## Rules\n- No false positives without evidence. Show the vulnerable code.\n- Run dependency audit tools if available (npm audit, pip-audit, cargo audit).\n- If no security issues found, say so clearly — don't invent findings.\n- This is read-only analysis. Do not modify any files.",
+  "model" : "claude-sonnet-4.6-1m"
+}

package/agents/tool-verifier.json

@@ -0,0 +1,61 @@
+{
+  "allowedTools" : [ "read", "imageRead", "glob", "grep", "ls", "code", "shell", "write" ],
+  "hooks" : {
+    "agentSpawn" : [ {
+      "command" : "bash ~/.flow-agents/scripts/telemetry/telemetry.sh agentSpawn tool-verifier",
+      "timeout_ms" : 5000
+    } ],
+    "postToolUse" : [ {
+      "command" : "bash ~/.flow-agents/scripts/telemetry/telemetry.sh postToolUse tool-verifier",
+      "matcher" : "*",
+      "timeout_ms" : 3000
+    }, {
+      "command" : "node ~/.flow-agents/scripts/hooks/run-hook.js post:edit:accumulator post-edit-accumulator.js standard,strict",
+      "matcher" : "fs_write",
+      "timeout_ms" : 5000
+    }, {
+      "command" : "node ~/.flow-agents/scripts/hooks/run-hook.js post:quality-gate quality-gate.js strict",
+      "matcher" : "fs_write",
+      "timeout_ms" : 15000
+    } ],
+    "preToolUse" : [ {
+      "command" : "bash ~/.flow-agents/scripts/telemetry/telemetry.sh preToolUse tool-verifier",
+      "matcher" : "*",
+      "timeout_ms" : 3000
+    }, {
+      "command" : "node ~/.flow-agents/scripts/hooks/run-hook.js pre:config-protection config-protection.js standard,strict",
+      "matcher" : "fs_write",
+      "timeout_ms" : 5000
+    }, {
+      "command" : "node ~/.flow-agents/scripts/hooks/run-hook.js pre:commit-quality pre-commit-quality.js standard,strict",
+      "matcher" : "execute_bash",
+      "timeout_ms" : 30000
+    }, {
+      "command" : "node ~/.flow-agents/scripts/hooks/run-hook.js pre:report-only-guard report-only-guard.js standard,strict",
+      "matcher" : "fs_write",
+      "timeout_ms" : 3000
+    } ],
+    "stop" : [ {
+      "command" : "bash ~/.flow-agents/scripts/telemetry/telemetry.sh stop tool-verifier",
+      "timeout_ms" : 5000
+    }, {
+      "command" : "node ~/.flow-agents/scripts/hooks/run-hook.js stop:format-typecheck stop-format-typecheck.js standard,strict",
+      "timeout_ms" : 300000
+    } ],
+    "userPromptSubmit" : [ {
+      "command" : "bash ~/.flow-agents/scripts/telemetry/telemetry.sh userPromptSubmit tool-verifier",
+      "timeout_ms" : 5000
+    } ]
+  },
+  "resources" : [ "file://AGENTS.md", "file://docs/context-map.md", "file://.kiro/steering/**/*.md", "file://~/.kiro/steering/**/*.md", "file://~/.flow-agents/context/*.md", "file://~/.flow-agents/context/contracts/*.md", "file://~/.flow-agents/schemas/*.json" ],
+  "tools" : [ "read", "imageRead", "glob", "grep", "ls", "code", "shell", "write" ],
+  "toolsSettings" : {
+    "write" : {
+      "allowedPaths" : [ ".flow-agents/**/*" ]
+    }
+  },
+  "name" : "tool-verifier",
+  "description" : "Delegate to me for implementation verification. Read-only + shell for source code; writes review/evidence artifacts under .flow-agents. Verifies acceptance criteria and produces PASS/FAIL/NOT_VERIFIED verdicts with evidence. No production file modifications.",
+  "prompt" : "You are a verification auditor. You review implementation against a plan and produce structured verdicts.\n\n## Shared Contracts\nFollow `context/contracts/artifact-contract.md` and `context/contracts/verification-contract.md`. Those contracts are the source of truth for report-only behavior, verification phases, verdicts, review artifact format, structured evidence sidecars, evidence requirements, Goal Fit checks, and NOT_VERIFIED handling.\n\n## Input\nYou receive acceptance criteria, modified files, verification commands, and usually a todo_file path for the orchestrator's session artifact. If no todo_file is provided, run standalone verification against the current working directory and return the full report directly.\n\n## Process\n1. Read `docs/context-map.md` when it exists, then detect the project type and relevant build, type, lint, test, security, and diff-review checks.\n2. Run the checks that are available and relevant.\n3. Map every acceptance criterion to PASS, FAIL, or NOT_VERIFIED with evidence.\n4. Check Goal Fit when a Definition Of Done or user-facing outcome is available.\n5. Write a review artifact beside the session artifact when a todo_file is provided.\n6. When a todo_file is provided, create or update `evidence.json`, `acceptance.json`, and `state.json` beside the workflow artifact using the schemas under `schemas/`.\n7. Return the full report and sidecar paths to the orchestrator.\n\n## Rules\n- Report only. Do not modify source files, apply format fixes, lint autofixes, or patches.\n- Evidence is mandatory for PASS.\n- NOT_VERIFIED means evidence could not be collected; include the reason.\n- `evidence.json` must include normalized checks, a lowercase verdict, and any not_verified_gaps.\n- `acceptance.json` must map every criterion to pass, fail, not_verified, or accepted_gap.\n- If a command fails, capture the actual error output.\n- A technically green build is not enough for PASS when the user-facing Definition Of Done is unmet.",
+  "model" : "claude-sonnet-4.6-1m"
+}

package/agents/tool-worker.json

@@ -0,0 +1,58 @@
+{
+  "allowedTools" : [ "@builtin" ],
+  "hooks" : {
+    "agentSpawn" : [ {
+      "command" : "bash ~/.flow-agents/scripts/telemetry/telemetry.sh agentSpawn tool-worker",
+      "timeout_ms" : 5000
+    } ],
+    "postToolUse" : [ {
+      "command" : "bash ~/.flow-agents/scripts/telemetry/telemetry.sh postToolUse tool-worker",
+      "matcher" : "*",
+      "timeout_ms" : 3000
+    }, {
+      "command" : "node ~/.flow-agents/scripts/hooks/run-hook.js post:edit:accumulator post-edit-accumulator.js standard,strict",
+      "matcher" : "fs_write",
+      "timeout_ms" : 5000
+    }, {
+      "command" : "node ~/.flow-agents/scripts/hooks/run-hook.js post:quality-gate quality-gate.js strict",
+      "matcher" : "fs_write",
+      "timeout_ms" : 15000
+    } ],
+    "preToolUse" : [ {
+      "command" : "bash ~/.flow-agents/scripts/telemetry/telemetry.sh preToolUse tool-worker",
+      "matcher" : "*",
+      "timeout_ms" : 3000
+    }, {
+      "command" : "node ~/.flow-agents/scripts/hooks/run-hook.js pre:config-protection config-protection.js standard,strict",
+      "matcher" : "fs_write",
+      "timeout_ms" : 5000
+    }, {
+      "command" : "node ~/.flow-agents/scripts/hooks/run-hook.js pre:commit-quality pre-commit-quality.js standard,strict",
+      "matcher" : "execute_bash",
+      "timeout_ms" : 30000
+    } ],
+    "stop" : [ {
+      "command" : "bash ~/.flow-agents/scripts/telemetry/telemetry.sh stop tool-worker",
+      "timeout_ms" : 5000
+    }, {
+      "command" : "node ~/.flow-agents/scripts/hooks/run-hook.js stop:format-typecheck stop-format-typecheck.js standard,strict",
+      "timeout_ms" : 300000
+    } ],
+    "userPromptSubmit" : [ {
+      "command" : "bash ~/.flow-agents/scripts/telemetry/telemetry.sh userPromptSubmit tool-worker",
+      "timeout_ms" : 5000
+    } ]
+  },
+  "resources" : [ "file://AGENTS.md", "file://docs/context-map.md", "file://.kiro/steering/**/*.md", "file://~/.kiro/steering/**/*.md", "file://~/.flow-agents/context/common/subagents.md", "file://~/.flow-agents/context/contracts/*.md" ],
+  "tools" : [ "@builtin" ],
+  "toolsSettings" : {
+    "shell" : {
+      "allowedPaths" : [ ],
+      "autoAllowReadonly" : true
+    }
+  },
+  "name" : "tool-worker",
+  "description" : "Delegate to me for writing and developing source code for a project. Works best when a detailed plan can be provided. NO access to web tools. Can be used in parallel for any coding tasks that require trusted access to the write and shell tools. WARNING: May spawn a `git worktree`",
+  "prompt" : "You are an autonomous coding worker. You execute well-defined tasks without human interaction. If instructions are insufficient, stop and report the blocker clearly.\n\n## Shared Contracts\nFollow `context/contracts/artifact-contract.md` and `context/contracts/execution-contract.md`. Those contracts are the source of truth for task artifacts, modified file tracking, conflict checks, parallel wave behavior, validation expectations, and completion rules.\n\n## Input\nYou receive a task from an approved plan, including files, changes, acceptance criteria, Definition Of Done items, context, and usually the plan artifact path.\n\n## Workflow\n1. Read `docs/context-map.md` when it exists, then check existing workflow artifacts for overlapping work and modified file conflicts.\n2. Validate that the task has clear scope, expected behavior, files, and acceptance criteria.\n3. Implement using existing project patterns and the smallest change that satisfies the plan.\n4. Update task/session artifacts with modified files and progress.\n5. Run relevant validation for changed areas.\n6. Report what changed, which files changed, what validation ran, and any blockers or deferred gaps.\n\n## Rules\n- Do not revert unrelated user or agent changes.\n- Do not invent speculative features or silent fallbacks.\n- If another in-progress task blocks this work, report it instead of forcing through.\n- If validation fails because of your changes, fix and re-run validation before reporting complete.\n- If validation cannot be run, report it as NOT_VERIFIED with the reason.",
+  "model" : "claude-sonnet-4.6-1m"
+}

package/build/src/cli/console-learning-projection.js

@@ -0,0 +1,123 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { flagBool, flagString, parseArgs } from "../lib/args.js";
+import { buildWorkflowLearningProjection, readWorkflowLearningSources } from "../lib/workflow-learning-projection.js";
+const SAFE_SEGMENT = /^[A-Za-z0-9._-]+$/;
+function printHelp() {
+    console.log("Usage: flow-agents console-learning-projection [options]");
+    console.log("");
+    console.log("Build an inert Console learning projection from local workflow learning sidecars.");
+    console.log("");
+    console.log("Options:");
+    console.log("  --artifact-root <path>  Workflow artifact root to scan (default: .flow-agents)");
+    console.log("  --kontour-root <path>   Local Kontour root to write under (default: .kontour)");
+    console.log("  --scope <id>            Projection scope id (default: current directory name)");
+    console.log("  --scope-kind <kind>     Projection scope kind (default: repo)");
+    console.log("  --producer <id>         Projection producer id (default: flow-agents-learning)");
+    console.log("  --generated-at <ISO>    Override generated timestamp for deterministic output");
+    console.log("  --dry-run               Do not write a projection file");
+    console.log("  --json                  Print stable JSON summary");
+    console.log("  --help                  Show this help");
+}
+function defaultScopeId() {
+    return path.basename(process.cwd()) || "local";
+}
+function requireSafeSegment(value, label) {
+    if (!SAFE_SEGMENT.test(value)) {
+        throw new Error(`${label} must contain only letters, numbers, dot, underscore, or hyphen: ${value}`);
+    }
+    return value;
+}
+function ensureNoSymlinkPath(target) {
+    const resolved = path.resolve(target);
+    const root = path.parse(resolved).root;
+    const parts = path.relative(root, resolved).split(path.sep).filter(Boolean);
+    let cursor = root;
+    for (const part of parts) {
+        cursor = path.join(cursor, part);
+        if (fs.existsSync(cursor) && fs.lstatSync(cursor).isSymbolicLink()) {
+            throw new Error(`refusing to write through symlink path: ${cursor}`);
+        }
+    }
+}
+function ensureDirectory(target) {
+    ensureNoSymlinkPath(target);
+    fs.mkdirSync(target, { recursive: true });
+    ensureNoSymlinkPath(target);
+    const stat = fs.statSync(target);
+    if (!stat.isDirectory())
+        throw new Error(`destination directory is not a directory: ${target}`);
+}
+function containedPath(root, destination) {
+    const relative = path.relative(root, destination);
+    if (relative === "" || relative.startsWith("..") || path.isAbsolute(relative)) {
+        throw new Error(`destination escapes kontour root: ${destination}`);
+    }
+}
+function destinationPath(kontourRoot, producer, scopeKind, scopeId) {
+    const root = path.resolve(kontourRoot);
+    const destination = path.resolve(root, "projections", producer, `${scopeKind}-${scopeId}.json`);
+    containedPath(root, destination);
+    return destination;
+}
+function writeProjection(file, root, projection) {
+    containedPath(root, file);
+    ensureDirectory(path.dirname(file));
+    if (fs.existsSync(file) && fs.lstatSync(file).isSymbolicLink()) {
+        throw new Error(`refusing to write symlinked projection file: ${file}`);
+    }
+    fs.writeFileSync(file, `${JSON.stringify(projection, null, 2)}\n`, "utf8");
+}
+function printText(summary) {
+    console.log(`Scanned learning files: ${summary.scanned_learning_file_count}`);
+    console.log(`Emitted learnings: ${summary.emitted_learning_count}`);
+    if (summary.dry_run)
+        console.log("Dry run: no projection written");
+    else
+        console.log(`Projection: ${summary.destination}`);
+}
+export function main(argv = process.argv.slice(2)) {
+    const { flags } = parseArgs(argv);
+    if (flagBool(flags, "help") || flagBool(flags, "h")) {
+        printHelp();
+        return 0;
+    }
+    try {
+        const artifactRoot = path.resolve(flagString(flags, "artifact-root", ".flow-agents") ?? ".flow-agents");
+        const kontourRoot = path.resolve(flagString(flags, "kontour-root", ".kontour") ?? ".kontour");
+        const producer = requireSafeSegment(flagString(flags, "producer", "flow-agents-learning") ?? "flow-agents-learning", "--producer");
+        const scope = {
+            kind: requireSafeSegment(flagString(flags, "scope-kind", "repo") ?? "repo", "--scope-kind"),
+            id: requireSafeSegment(flagString(flags, "scope", defaultScopeId()) ?? defaultScopeId(), "--scope"),
+        };
+        const dryRun = flagBool(flags, "dry-run");
+        const sources = readWorkflowLearningSources(artifactRoot);
+        const projection = buildWorkflowLearningProjection(sources, {
+            scope,
+            producer: { id: producer, product: "flow-agents" },
+            generatedAt: flagString(flags, "generated-at"),
+        });
+        const destination = dryRun ? null : destinationPath(kontourRoot, producer, scope.kind, scope.id);
+        if (destination)
+            writeProjection(destination, kontourRoot, projection);
+        const summary = {
+            scanned_learning_file_count: sources.length,
+            emitted_learning_count: projection.learnings.length,
+            destination,
+            producer,
+            scope,
+            dry_run: dryRun,
+        };
+        if (flagBool(flags, "json"))
+            console.log(JSON.stringify(summary, null, 2));
+        else
+            printText(summary);
+        return 0;
+    }
+    catch (error) {
+        console.error(`console-learning-projection: ${error instanceof Error ? error.message : String(error)}`);
+        return 1;
+    }
+}
+if (import.meta.url === `file://${process.argv[1]}`)
+    process.exit(main());

package/build/src/cli/docs-preview.js

@@ -0,0 +1,39 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+function esc(value) {
+    return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+function titleFor(file, text) {
+    return text.match(/^title:\s*(.+)$/m)?.[1].trim() ?? text.split(/\r?\n/).find((line) => line.startsWith("# "))?.slice(2).trim() ?? path.basename(file, ".md").replace(/-/g, " ");
+}
+function render(text) {
+    return text.replace(/^---\n.*?\n---\n/s, "").split(/\r?\n/).map((line) => {
+        if (line.startsWith("# "))
+            return `<h1>${esc(line.slice(2).trim())}</h1>`;
+        if (line.startsWith("## "))
+            return `<h2>${esc(line.slice(3).trim())}</h2>`;
+        if (line.startsWith("- "))
+            return `<li>${esc(line.slice(2).trim())}</li>`;
+        return line.trim() ? `<p>${esc(line.trim())}</p>` : "";
+    }).join("\n");
+}
+export function main() {
+    const root = path.resolve(path.dirname(process.argv[1]), "..");
+    const docs = path.join(root, "docs");
+    const out = path.join(root, "_site");
+    fs.rmSync(out, { recursive: true, force: true });
+    fs.mkdirSync(out, { recursive: true });
+    const assets = path.join(docs, "assets");
+    if (fs.existsSync(assets))
+        fs.cpSync(assets, path.join(out, "assets"), { recursive: true });
+    for (const file of fs.readdirSync(docs).filter((name) => name.endsWith(".md")).sort()) {
+        const source = path.join(docs, file);
+        const text = fs.readFileSync(source, "utf8");
+        const title = titleFor(file, text);
+        fs.writeFileSync(path.join(out, `${path.basename(file, ".md")}.html`), `<!doctype html><html><head><meta charset="utf-8"><title>${esc(title)}</title><link rel="stylesheet" href="assets/site.css"></head><body>${render(text)}<script src="assets/site.js" defer></script></body></html>`, "utf8");
+    }
+    console.log(`Built local docs preview: ${out}`);
+    return 0;
+}
+if (import.meta.url === `file://${process.argv[1]}`)
+    process.exit(main());

package/build/src/cli/effective-backlog-settings.js

@@ -0,0 +1,102 @@
+import * as child_process from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseArgs, flagString, flagBool } from "../lib/args.js";
+import { readJson } from "../lib/fs.js";
+const PROJECT_SETTINGS_RELATIVE_PATH = path.join("context", "settings", "backlog-provider-settings.json");
+function loadSettings(file) {
+    if (!fs.existsSync(file))
+        return null;
+    const data = readJson(file);
+    if (data.schema_version !== "1.0")
+        throw new Error(`${file}: unsupported schema_version ${String(data.schema_version)}`);
+    return data;
+}
+function repoFromText(text) {
+    const match = text.trim().match(/github\.com[:/]([^/]+)\/([^/.]+)(?:\.git)?$/);
+    return match ? { owner: match[1], name: match[2] } : null;
+}
+function currentRepo(repoPath) {
+    try {
+        const out = child_process.execFileSync("git", ["-C", repoPath, "remote", "get-url", "origin"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+        const repo = repoFromText(out);
+        if (repo)
+            return repo;
+    }
+    catch { }
+    const packagePath = path.join(repoPath, "package.json");
+    if (fs.existsSync(packagePath)) {
+        const data = readJson(packagePath);
+        const repository = data.repository;
+        const url = typeof repository === "object" && repository !== null ? repository.url : repository;
+        if (typeof url === "string")
+            return repoFromText(url);
+    }
+    return null;
+}
+function merge(base, override) {
+    if (!base && !override)
+        return null;
+    if (!base)
+        return structuredClone(override);
+    if (!override)
+        return structuredClone(base);
+    const out = structuredClone(base);
+    for (const [key, value] of Object.entries(override)) {
+        out[key] = typeof value === "object" && value !== null && typeof out[key] === "object" && out[key] !== null && !Array.isArray(value)
+            ? merge(out[key], value)
+            : structuredClone(value);
+    }
+    return out;
+}
+function findProject(settings, repo) {
+    const projects = settings?.projects;
+    if (!Array.isArray(projects))
+        return null;
+    return projects.find((project) => {
+        const projectRepo = (project.project?.repo ?? {});
+        return projectRepo.owner === repo.owner && projectRepo.name === repo.name;
+    }) ?? null;
+}
+function defaultProjectSettingsPath() {
+    let cursor = path.dirname(fileURLToPath(import.meta.url));
+    while (true) {
+        const candidate = path.join(cursor, PROJECT_SETTINGS_RELATIVE_PATH);
+        if (fs.existsSync(candidate))
+            return candidate;
+        const parent = path.dirname(cursor);
+        if (parent === cursor)
+            return path.resolve(PROJECT_SETTINGS_RELATIVE_PATH);
+        cursor = parent;
+    }
+}
+function effective(repoPath, projectSettings, globalSettings) {
+    const repo = currentRepo(repoPath);
+    const projectDoc = loadSettings(projectSettings);
+    const globalDoc = loadSettings(globalSettings);
+    if (!repo)
+        return [{ status: "ask_user", reason: "could_not_identify_current_repo", message: "Ask the user which backlog WorkItemProvider and BoardProvider to use for this workspace.", resolution: { project_settings_path: projectSettings, global_settings_path: globalSettings } }, 2];
+    const effectiveSettings = merge(merge(merge(globalDoc?.defaults, findProject(globalDoc, repo)), projectDoc?.defaults), findProject(projectDoc, repo));
+    if (!effectiveSettings)
+        return [{ status: "ask_user", reason: "no_backlog_provider_settings", message: "Ask the user which backlog WorkItemProvider and BoardProvider to use before selecting work.", current_repo: repo, resolution: { project_settings_path: projectSettings, global_settings_path: globalSettings, checked: ["project", "global"] } }, 2];
+    return [{ status: "configured", current_repo: repo, source: findProject(projectDoc, repo) || projectDoc?.defaults ? "project" : "global", precedence: ["project.projects match", "project.defaults", "global.projects match", "global.defaults"], settings: effectiveSettings }, 0];
+}
+export function main(argv = process.argv.slice(2)) {
+    const args = parseArgs(argv);
+    try {
+        const [result, code] = effective(path.resolve(flagString(args.flags, "repo-path", ".") ?? "."), path.resolve(flagString(args.flags, "project-settings", defaultProjectSettingsPath()) ?? ""), path.resolve(flagString(args.flags, "global-settings", path.join(os.homedir(), ".config", "flow-agents", "backlog-provider-settings.json")) ?? ""));
+        if (flagBool(args.flags, "json"))
+            console.log(JSON.stringify(result, null, 2));
+        else
+            console.log(`status: ${String(result.status)}`);
+        return code;
+    }
+    catch (error) {
+        console.error(`error: ${error.message}`);
+        return 1;
+    }
+}
+if (import.meta.url === `file://${process.argv[1]}`)
+    process.exit(main());

package/build/src/cli/export-bookmarks.js

@@ -0,0 +1,38 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+function esc(value) {
+    return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+export function main(argv = process.argv.slice(2)) {
+    if (argv.length < 1) {
+        console.log("Usage: export-bookmarks <bookmarks.md> [output.html]");
+        return 1;
+    }
+    const input = argv[0];
+    const output = argv[1] ?? path.join(os.homedir(), "Downloads", "bookmarks_organized.html");
+    if (!fs.existsSync(input)) {
+        console.log(`Error: ${input} not found`);
+        return 1;
+    }
+    const links = Array.from(fs.readFileSync(input, "utf8").matchAll(/^- \*\*[\d-]+\*\* \[(\w+)\]: (.+?) — (https?:\/\/\S+)(?: — (.+))?$/gm), (m) => ({ tag: m[1], title: m[2], url: m[3] }));
+    const timestamp = Math.floor(Date.now() / 1000);
+    const byTag = new Map();
+    for (const link of links)
+        byTag.set(link.tag, [...(byTag.get(link.tag) ?? []), link]);
+    const lines = ["<!DOCTYPE NETSCAPE-Bookmark-file-1>", '<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=UTF-8">', "<TITLE>Bookmarks</TITLE>", "<H1>Bookmarks</H1>", "<DL><p>"];
+    for (const tag of Array.from(byTag.keys()).sort()) {
+        lines.push(`    <DT><H3 ADD_DATE="${timestamp}" LAST_MODIFIED="${timestamp}">${esc(tag)}</H3>`, "    <DL><p>");
+        for (const link of (byTag.get(tag) ?? []).sort((a, b) => a.title.localeCompare(b.title)))
+            lines.push(`        <DT><A HREF="${esc(link.url)}" ADD_DATE="${timestamp}">${esc(link.title)}</A>`);
+        lines.push("    </DL><p>");
+    }
+    lines.push("</DL><p>");
+    fs.writeFileSync(output, lines.join("\n"), "utf8");
+    console.log("Bookmarks exported");
+    console.log(`Source: ${input} (${links.length} links)`);
+    console.log(`Output: ${output}`);
+    return 0;
+}
+if (import.meta.url === `file://${process.argv[1]}`)
+    process.exit(main());

package/build/src/cli/fixture-retirement-audit.js

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+import * as fs from "node:fs";
+import * as path from "node:path";
+const root = path.resolve(".");
+const fixtureRoot = "evals/fixtures";
+const ownerScanRoots = ["evals/static", "evals/integration", "scripts"];
+const textExtensions = new Set([".md", ".yaml", ".yml", ".json", ".sh", ".js", ".ts"]);
+const selfAuditRefs = new Set([
+    "evals/integration/test_fixture_retirement_audit.sh",
+]);
+function printHelp() {
+    console.log("Usage: flow-agents fixture-retirement-audit [--json]");
+    console.log("");
+    console.log("Read-only audit for canonical eval fixture retirement candidates.");
+    console.log("");
+    console.log("A fixture group is kept when docs/fixture-ownership.md lists existing");
+    console.log("owners and at least one live eval/script reference still points at it.");
+    console.log("The command never deletes, archives, or rewrites fixtures.");
+}
+function readText(file) {
+    return fs.readFileSync(path.join(root, file), "utf8");
+}
+function walkFiles(dir) {
+    const abs = path.join(root, dir);
+    if (!fs.existsSync(abs))
+        return [];
+    const out = [];
+    for (const entry of fs.readdirSync(abs, { withFileTypes: true })) {
+        const full = path.join(abs, entry.name);
+        if (entry.isDirectory())
+            out.push(...walkFiles(path.relative(root, full).split(path.sep).join("/")));
+        else if (entry.isFile())
+            out.push(path.relative(root, full).split(path.sep).join("/"));
+    }
+    return out;
+}
+function fixtureDirs() {
+    const abs = path.join(root, fixtureRoot);
+    return fs.readdirSync(abs, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => `${fixtureRoot}/${entry.name}`)
+        .sort();
+}
+function ownerInventory() {
+    const doc = readText("docs/fixture-ownership.md");
+    const rows = new Map();
+    for (const line of doc.split(/\r?\n/)) {
+        if (!line.startsWith("| `evals/fixtures/"))
+            continue;
+        const cells = line.split("|").map((cell) => cell.trim());
+        const fixture = cells[1]?.replace(/^`|`$/g, "");
+        const ownersCell = cells[3] ?? "";
+        if (!fixture)
+            continue;
+        const owners = [...ownersCell.matchAll(/`([^`]+)`/g)].map((match) => match[1]).sort();
+        rows.set(fixture, owners);
+    }
+    return rows;
+}
+function scanFiles() {
+    return ownerScanRoots
+        .flatMap((dir) => walkFiles(dir))
+        .filter((file) => textExtensions.has(path.extname(file)))
+        .sort();
+}
+function audit() {
+    const inventory = ownerInventory();
+    const files = scanFiles();
+    const fixtures = fixtureDirs().map((fixture) => {
+        const owners = inventory.get(fixture) ?? [];
+        const directRefs = files
+            .filter((file) => readText(file).includes(fixture))
+            .filter((file) => !file.startsWith(`${fixture}/`))
+            .filter((file) => !selfAuditRefs.has(file))
+            .sort();
+        const reasons = [];
+        if (!inventory.has(fixture))
+            reasons.push("missing from docs/fixture-ownership.md");
+        const missingOwners = owners.filter((owner) => !fs.existsSync(path.join(root, owner)));
+        if (missingOwners.length)
+            reasons.push(`owner path missing: ${missingOwners.join(", ")}`);
+        if (!owners.length)
+            reasons.push("no owners listed");
+        if (!directRefs.length)
+            reasons.push("no direct eval/script references");
+        const unlistedRefs = directRefs.filter((ref) => !owners.includes(ref));
+        if (unlistedRefs.length)
+            reasons.push(`direct references not listed as owners: ${unlistedRefs.join(", ")}`);
+        return {
+            fixture,
+            classification: reasons.length ? "retire_candidate" : "kept",
+            owners,
+            direct_refs: directRefs,
+            reasons: reasons.length ? reasons : ["owned fixture with live eval/script references"],
+        };
+    });
+    return {
+        fixture_root: path.join(root, fixtureRoot),
+        totals: {
+            scanned: fixtures.length,
+            kept: fixtures.filter((item) => item.classification === "kept").length,
+            retire_candidates: fixtures.filter((item) => item.classification === "retire_candidate").length,
+        },
+        fixtures,
+    };
+}
+function printText(result) {
+    console.log("Fixture retirement audit (dry run, read-only)");
+    console.log(`Fixture root: ${result.fixture_root}`);
+    console.log(`Scanned fixture groups: ${result.totals.scanned}`);
+    console.log(`Kept: ${result.totals.kept}`);
+    console.log(`Retire candidates: ${result.totals.retire_candidates}`);
+    for (const item of result.fixtures) {
+        console.log(`- ${item.classification}: ${item.fixture}`);
+        console.log(`  owners: ${item.owners.join(", ") || "none"}`);
+        console.log(`  direct_refs: ${item.direct_refs.join(", ") || "none"}`);
+        for (const reason of item.reasons)
+            console.log(`  reason: ${reason}`);
+    }
+}
+export function main(argv = process.argv.slice(2)) {
+    try {
+        if (argv.includes("--help") || argv.includes("-h")) {
+            printHelp();
+            return 0;
+        }
+        const result = audit();
+        if (argv.includes("--json"))
+            console.log(JSON.stringify(result, null, 2));
+        else
+            printText(result);
+        return 0;
+    }
+    catch (error) {
+        console.error(`fixture-retirement-audit: ${error instanceof Error ? error.message : String(error)}`);
+        return 1;
+    }
+}
+if (import.meta.url === `file://${process.argv[1]}`)
+    process.exit(main());