@bli-cockpit/cli 0.1.19 → 0.1.20

package/README.md

@@ -46,19 +46,21 @@ On machines where Codex or Claude agents will do ticketed work, interactive
 `cockpit onboard` checks `~/.codex/AGENTS.md` and `~/.claude/CLAUDE.md` after
 harvest proof. If equivalent Cockpit ticket-binding guidance already exists, it
 leaves the files alone. If guidance is missing or clearly stale, it asks whether
-to install or replace it.
+to install or replace it. The managed guidance is scoped to the workspace path
+used for onboarding, so agents should ignore it in private chats or unrelated
+repos.
 
 ```bash
 # Repair/manual path, or headless/json onboarding where Cockpit cannot prompt.
-cockpit agent-rules install
+cockpit agent-rules install --workspace "$PWD"
 ```
 
 The direct command updates `~/.codex/AGENTS.md` and `~/.claude/CLAUDE.md` with
 the Cockpit rule to bind known Linear tickets before edits, or ask once when
-the ticket ID is missing. That binding starts attributing the session's work to
-the specific ticket in Cockpit. It checks for managed or equivalent guidance
-first, so current files are left unchanged and stale Cockpit ticket-binding
-sections are replaced.
+the ticket ID is missing inside that workspace. That binding starts attributing
+the session's work to the specific ticket in Cockpit. It checks for managed or
+equivalent guidance first, so current files are left unchanged and stale Cockpit
+ticket-binding sections are replaced.
 
 Parent mode scans child git repos/worktrees (3 folder levels deep, up to 50
 repos by default — tune with `--max-depth` / `--max-repos`; a warning prints
@@ -113,6 +115,30 @@ cockpit sync \
 No ticket is required for setup, chatting, planning, or general ambient capture.
 Only pass `--ticket` when the work really belongs to a visible ticket.
 
+When the work is important but ticketless, label it explicitly before syncing so
+later analysis does not have to guess the topic:
+
+```bash
+cockpit start \
+  --workspace "$PWD" \
+  --topic "lead ingestion rewrite planning" \
+  --intent planning \
+  --phase discovery \
+  --intent-confidence 0.9
+
+cockpit sync \
+  --workspace "$PWD" \
+  --json
+```
+
+Supported `--intent` values are `implementation`, `bug_fix`,
+`root_cause_analysis`, `planning`, `discovery`, `review`, `testing`,
+`documentation`, `release`, `learning`, `coordination`, `maintenance`,
+`analysis`, `unknown`, and `other`. Supported `--phase` values are `planning`,
+`discovery`, `implementation`, `debugging`, `review`, `testing`,
+`documentation`, `release`, `handoff`, `analysis`, `unknown`, and `other`.
+Use `--topic-summary` only for short redacted summaries, not transcript text.
+
 ## What gets saved
 
 Local files:
@@ -180,3 +206,5 @@ This public package intentionally excludes Cockpit admin bootstrap commands,
 service-role credential handling, source maps, tests, and internal runbooks.
 Clean `npm pack` and `npm publish` run the public CLI build before packaging so
 `dist/cli.js` is present in emergency releases.
+When collector changes depend on new telemetry-core exports, publish
+`@bli-cockpit/telemetry-core` first, then publish `@bli-cockpit/cli`.

package/dist/adapters/raw-evidence.js

@@ -1,16 +1,15 @@
-import { SECRET_FILE_SEGMENT_PATTERN, SourceScanResultSchema, containsSecretLikeContent, } from "@bli-cockpit/telemetry-core";
-import { execFile } from "node:child_process";
+import { EvidenceCompletenessPayloadSchema, SECRET_FILE_SEGMENT_PATTERN, SourceScanResultSchema, containsSecretLikeContent, } from "@bli-cockpit/telemetry-core";
+import { spawn } from "node:child_process";
 import crypto from "node:crypto";
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
-import { promisify } from "node:util";
 import { makeSourceAdapterIdentity, } from "./common.js";
 import { collectAgentImageEvidenceFromJsonlFile, } from "./agent-image-evidence.js";
-const execFileAsync = promisify(execFile);
 const DEFAULT_SINCE_MINUTES = 24 * 60;
 const DEFAULT_SESSION_LIMIT = 50;
 const MAX_GIT_DIFF_BYTES = 2 * 1024 * 1024;
+const GIT_DIFF_TIMEOUT_MS = 3_000;
 export const RAW_EVIDENCE_BUCKET = "ambient-raw-evidence";
 export const RAW_EVIDENCE_RETENTION_MODE = "remote_durable";
 // Per-sync upload budgets enforced at COLLECTION time (D7b). With sidecars a
@@ -28,18 +27,65 @@ export async function collectRawEvidencePack(context, options) {
     const filesDir = path.join(evidenceDir, "files");
     const entries = [];
     const skipped = [];
+    const truncated = [];
     const reused = [];
+    const sinceMinutes = options.sinceMinutes ?? DEFAULT_SINCE_MINUTES;
+    const sessionLimit = options.sessionLimit ?? DEFAULT_SESSION_LIMIT;
+    const byteBudget = options.byteBudget ?? RAW_EVIDENCE_DEFAULT_BYTE_BUDGET;
+    const objectBudget = options.objectBudget ?? RAW_EVIDENCE_DEFAULT_OBJECT_BUDGET;
     const collection = {
         context,
         filesDir,
         packId,
         entries,
         skipped,
+        truncated,
         reused,
+        scanned: new Map(),
+        caps: [
+            {
+                source: "raw_evidence",
+                cap_type: "byte_budget",
+                limit: byteBudget,
+                observed: options.budget?.remainingBytes ?? byteBudget,
+                applied: false,
+            },
+            {
+                source: "raw_evidence",
+                cap_type: "object_budget",
+                limit: objectBudget,
+                observed: options.budget?.remainingObjects ?? objectBudget,
+                applied: false,
+            },
+            {
+                source: "git_diff",
+                cap_type: "max_bytes_per_diff",
+                limit: MAX_GIT_DIFF_BYTES,
+                applied: false,
+            },
+            {
+                source: "git_diff",
+                cap_type: "timeout_ms",
+                limit: GIT_DIFF_TIMEOUT_MS,
+                applied: false,
+            },
+            {
+                source: "claude_jsonl",
+                cap_type: "max_file_bytes",
+                limit: CLAUDE_MAX_COLLECT_FILE_BYTES,
+                applied: false,
+            },
+            {
+                source: "claude_jsonl_sidecar",
+                cap_type: "max_file_bytes",
+                limit: CLAUDE_MAX_COLLECT_FILE_BYTES,
+                applied: false,
+            },
+        ],
         skipContentHashes: options.skipContentHashes ?? new Set(),
         budget: options.budget ?? {
-            remainingBytes: options.byteBudget ?? RAW_EVIDENCE_DEFAULT_BYTE_BUDGET,
-            remainingObjects: options.objectBudget ?? RAW_EVIDENCE_DEFAULT_OBJECT_BUDGET,
+            remainingBytes: byteBudget,
+            remainingObjects: objectBudget,
         },
         index: { value: 0 },
     };
@@ -50,8 +96,8 @@ export async function collectRawEvidencePack(context, options) {
             await collectCodexJsonlFiles(collection, {
                 codexSessionFiles: options.codexSessionFiles,
                 sessionsDir: options.sessionsDir,
-                sinceMinutes: options.sinceMinutes ?? DEFAULT_SINCE_MINUTES,
-                limit: options.sessionLimit ?? DEFAULT_SESSION_LIMIT,
+                sinceMinutes,
+                limit: sessionLimit,
             });
         }
         if (options.includeClaudeJsonl !== false && options.claudeSessionFiles) {
@@ -61,6 +107,11 @@ export async function collectRawEvidencePack(context, options) {
         const deferredByteBudgetCount = skipped.filter((entry) => entry.reason === "deferred_byte_budget").length;
         const deferredObjectBudgetCount = skipped.filter((entry) => entry.reason === "deferred_object_budget").length;
         if (entries.length === 0) {
+            const evidenceCompleteness = makeEvidenceCompleteness(collection, {
+                startedAt,
+                finishedAt: context.now.toISOString(),
+                sinceMinutes,
+            });
             const facts = {
                 pack_id: packId,
                 manifest_path: path.join(evidenceDir, "manifest.json"),
@@ -73,6 +124,7 @@ export async function collectRawEvidencePack(context, options) {
                 deferred_byte_budget_count: deferredByteBudgetCount,
                 deferred_object_budget_count: deferredObjectBudgetCount,
                 content_kinds: [],
+                evidence_completeness: evidenceCompleteness,
                 pointers: [],
                 upload_files: [],
                 reused,
@@ -109,6 +161,11 @@ export async function collectRawEvidencePack(context, options) {
             bytes: manifestBytes,
         });
         entries.push(manifestEntry);
+        const evidenceCompleteness = makeEvidenceCompleteness(collection, {
+            startedAt,
+            finishedAt: context.now.toISOString(),
+            sinceMinutes,
+        });
         const facts = {
             pack_id: packId,
             manifest_path: manifestPath,
@@ -121,6 +178,7 @@ export async function collectRawEvidencePack(context, options) {
             deferred_byte_budget_count: deferredByteBudgetCount,
             deferred_object_budget_count: deferredObjectBudgetCount,
             content_kinds: [...new Set(entries.map((entry) => entry.kind))],
+            evidence_completeness: evidenceCompleteness,
             pointers: entries.map(pointerFromEntry),
             upload_files: entries.map((entry) => ({
                 pointer: pointerFromEntry(entry),
@@ -185,20 +243,33 @@ function makeRawEvidenceScan(options) {
             `bytes:${options.facts.byte_size}`,
             `skipped:${options.facts.skipped_count}`,
             `reused:${options.facts.reused_count}`,
+            `completeness:${options.facts.evidence_completeness.status}`,
+            `truncated:${options.facts.evidence_completeness.totals.truncated_count}`,
+            `deferred:${options.facts.evidence_completeness.totals.deferred_count}`,
             ...options.facts.content_kinds.map((kind) => `kind:${kind}`),
         ],
     });
 }
 async function collectCodexJsonlFiles(collection, options) {
-    const candidates = options.codexSessionFiles
+    const resolvedCandidates = options.codexSessionFiles
         ? options.codexSessionFiles.map((file) => ({
             filePath: file.local_path,
             codexSessionId: file.codex_session_id,
         }))
         : (await walkJsonlFiles(options.sessionsDir ?? path.join(os.homedir(), ".codex", "sessions"), collection.context.now.getTime() - options.sinceMinutes * 60 * 1000))
-            .slice(0, options.limit)
             .map((filePath) => ({ filePath, codexSessionId: null }));
+    collection.caps.push({
+        source: "codex_jsonl",
+        cap_type: "session_limit",
+        limit: options.limit,
+        observed: resolvedCandidates.length,
+        applied: !options.codexSessionFiles && resolvedCandidates.length > options.limit,
+    });
+    const candidates = options.codexSessionFiles
+        ? resolvedCandidates
+        : resolvedCandidates.slice(0, options.limit);
     for (const candidate of candidates) {
+        recordScanned(collection, "codex_jsonl");
         const codexSessionId = candidate.codexSessionId ?? shortHash(candidate.filePath);
         const transcriptAccepted = await collectOneEvidenceFile(collection, {
             filePath: candidate.filePath,
@@ -220,6 +291,7 @@ async function collectCodexJsonlFiles(collection, options) {
     }
 }
 async function collectClaudeJsonlFiles(collection, sessions) {
+    recordScanned(collection, "claude_jsonl", sessions.reduce((count, session) => count + 1 + session.sidecar_files.length, 0));
     for (const session of sessions) {
         const sessionId = session.claude_session_id;
         if (session.main_file_oversized) {
@@ -300,6 +372,7 @@ async function collectAgentImagesFromTranscript(collection, options) {
         sessionId: options.sessionId,
         sidecarId: options.sidecarId,
     });
+    recordScanned(collection, options.kind, result.images.length + result.skipped.length);
     for (const skipped of result.skipped) {
         collection.skipped.push({
             kind: options.kind,
@@ -336,6 +409,7 @@ async function collectOneAgentImageFile(collection, options) {
     }
     const deferReason = admitToBudget(collection.budget, raw.byteLength);
     if (deferReason) {
+        markBudgetCapApplied(collection, deferReason);
         collection.skipped.push({
             kind: options.kind,
             label: options.image.label,
@@ -392,6 +466,7 @@ async function collectOneEvidenceFile(collection, options) {
         return false;
     }
     if (options.maxFileBytes && raw.byteLength > options.maxFileBytes) {
+        markCapApplied(collection, options.kind, "max_file_bytes");
         collection.skipped.push({
             kind: options.kind,
             label: fileName,
@@ -419,6 +494,7 @@ async function collectOneEvidenceFile(collection, options) {
     }
     const deferReason = admitToBudget(collection.budget, raw.byteLength);
     if (deferReason) {
+        markBudgetCapApplied(collection, deferReason);
         collection.skipped.push({
             kind: options.kind,
             label: fileName,
@@ -465,10 +541,23 @@ async function collectGitDiffFiles(collection, repoRoot) {
         { label: "staged", args: ["diff", "--cached", "--no-ext-diff", "--"] },
     ];
     for (const target of diffTargets) {
+        recordScanned(collection, "git_diff");
         const diff = await runGitDiff(target.args, repoRoot);
-        if (!diff.trim())
+        if (diff.truncated) {
+            markCapApplied(collection, "git_diff", diff.truncationCapType);
+            collection.truncated.push({
+                kind: "git_diff",
+                reason: diff.truncationReason,
+                ...(diff.truncationCapType === "max_bytes_per_diff"
+                    ? { max_bytes: MAX_GIT_DIFF_BYTES }
+                    : {}),
+                observed_bytes: diff.observedBytes,
+                included_bytes: Buffer.byteLength(diff.stdout, "utf8"),
+            });
+        }
+        if (!diff.stdout.trim())
             continue;
-        if (containsSecretLikeContent(diff)) {
+        if (containsSecretLikeContent(diff.stdout)) {
             collection.skipped.push({
                 kind: "git_diff",
                 label: target.label,
@@ -476,7 +565,7 @@ async function collectGitDiffFiles(collection, repoRoot) {
             });
             continue;
         }
-        const raw = Buffer.from(diff.slice(0, MAX_GIT_DIFF_BYTES), "utf8");
+        const raw = Buffer.from(diff.stdout, "utf8");
         const contentHash = sha256(raw);
         if (collection.skipContentHashes.has(contentHash)) {
             collection.reused.push({
@@ -489,6 +578,7 @@ async function collectGitDiffFiles(collection, repoRoot) {
         }
         const deferReason = admitToBudget(collection.budget, raw.byteLength);
         if (deferReason) {
+            markBudgetCapApplied(collection, deferReason);
             collection.skipped.push({
                 kind: "git_diff",
                 label: target.label,
@@ -507,7 +597,9 @@ async function collectGitDiffFiles(collection, repoRoot) {
             localPath: destination,
             relativePath,
             mediaType: "text/x-diff",
-            redactedSummary: `Raw git ${target.label} diff preserved locally with env/secret paths excluded.`,
+            redactedSummary: diff.truncated
+                ? `Raw git ${target.label} diff truncated to the capture cap and preserved locally with env/secret paths excluded.`
+                : `Raw git ${target.label} diff preserved locally with env/secret paths excluded.`,
             bytes: raw,
             contentAddress: `git-diff/${target.label}-${contentHash.slice(0, 16)}.diff`,
         }));
@@ -526,12 +618,179 @@ async function runGitDiff(args, repoRoot) {
         ":(exclude)**/*.pem",
         ":(exclude)**/*.key",
     ];
-    const { stdout } = await execFileAsync("git", [...args, ...pathspec], {
-        cwd: repoRoot,
-        timeout: 3_000,
-        maxBuffer: MAX_GIT_DIFF_BYTES + 1024,
+    return new Promise((resolve, reject) => {
+        const child = spawn("git", [...args, ...pathspec], {
+            cwd: repoRoot,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        const stdoutChunks = [];
+        const stderrChunks = [];
+        let observedBytes = 0;
+        let includedBytes = 0;
+        let truncated = false;
+        let timedOut = false;
+        const timeout = setTimeout(() => {
+            timedOut = true;
+            truncated = true;
+            child.kill("SIGTERM");
+        }, GIT_DIFF_TIMEOUT_MS);
+        child.stdout.on("data", (chunk) => {
+            observedBytes += chunk.byteLength;
+            if (includedBytes < MAX_GIT_DIFF_BYTES) {
+                const remaining = MAX_GIT_DIFF_BYTES - includedBytes;
+                const next = chunk.subarray(0, remaining);
+                stdoutChunks.push(next);
+                includedBytes += next.byteLength;
+            }
+            if (observedBytes > MAX_GIT_DIFF_BYTES) {
+                truncated = true;
+                child.kill("SIGTERM");
+            }
+        });
+        child.stderr.on("data", (chunk) => {
+            if (stderrChunks.reduce((sum, item) => sum + item.byteLength, 0) < 4096) {
+                stderrChunks.push(chunk.subarray(0, 4096));
+            }
+        });
+        child.on("error", (error) => {
+            clearTimeout(timeout);
+            reject(error);
+        });
+        child.on("close", (code, signal) => {
+            clearTimeout(timeout);
+            if (code === 0 || truncated || signal === "SIGTERM") {
+                resolve({
+                    stdout: Buffer.concat(stdoutChunks).toString("utf8"),
+                    truncated,
+                    observedBytes,
+                    truncationReason: timedOut
+                        ? "git_diff_timeout"
+                        : "max_git_diff_bytes",
+                    truncationCapType: timedOut ? "timeout_ms" : "max_bytes_per_diff",
+                });
+                return;
+            }
+            const stderr = Buffer.concat(stderrChunks).toString("utf8").trim();
+            reject(new Error(stderr || `git diff failed with code ${code ?? signal}`));
+        });
+    });
+}
+function recordScanned(collection, source, count = 1) {
+    collection.scanned.set(source, (collection.scanned.get(source) ?? 0) + count);
+}
+function markBudgetCapApplied(collection, reason) {
+    markCapApplied(collection, "raw_evidence", reason === "deferred_object_budget" ? "object_budget" : "byte_budget");
+}
+function markCapApplied(collection, source, capType) {
+    const cap = collection.caps.find((candidate) => candidate.source === source && candidate.cap_type === capType);
+    if (cap)
+        cap.applied = true;
+}
+function makeEvidenceCompleteness(collection, options) {
+    const sources = new Set(collection.scanned.keys());
+    for (const entry of collection.entries)
+        sources.add(entry.kind);
+    for (const entry of collection.skipped)
+        sources.add(entry.kind);
+    for (const entry of collection.reused)
+        sources.add(entry.kind);
+    for (const entry of collection.truncated)
+        sources.add(entry.kind);
+    const sourceCounts = [...sources].sort().map((source) => {
+        const skipped = collection.skipped.filter((entry) => entry.kind === source);
+        return {
+            source,
+            scanned_count: collection.scanned.get(source) ?? 0,
+            included_count: collection.entries.filter((entry) => entry.kind === source).length,
+            skipped_count: skipped.length,
+            truncated_count: collection.truncated.filter((entry) => entry.kind === source).length,
+            deferred_count: skipped.filter((entry) => entry.reason.startsWith("deferred_")).length,
+            reused_count: collection.reused.filter((entry) => entry.kind === source).length,
+        };
+    });
+    const totals = sourceCounts.reduce((sum, count) => ({
+        scanned_count: sum.scanned_count + count.scanned_count,
+        included_count: sum.included_count + count.included_count,
+        skipped_count: sum.skipped_count + count.skipped_count,
+        truncated_count: sum.truncated_count + count.truncated_count,
+        deferred_count: sum.deferred_count + count.deferred_count,
+        reused_count: sum.reused_count + count.reused_count,
+    }), {
+        scanned_count: 0,
+        included_count: 0,
+        skipped_count: 0,
+        truncated_count: 0,
+        deferred_count: 0,
+        reused_count: 0,
+    });
+    const skipReasonCounts = new Map();
+    for (const skipped of collection.skipped) {
+        const key = `${skipped.kind}:${skipped.reason}`;
+        const existing = skipReasonCounts.get(key);
+        if (existing) {
+            existing.count += 1;
+        }
+        else {
+            skipReasonCounts.set(key, {
+                source: skipped.kind,
+                reason: skipped.reason,
+                count: 1,
+            });
+        }
+    }
+    const truncationCounts = new Map();
+    for (const truncated of collection.truncated) {
+        const key = `${truncated.kind}:${truncated.reason}`;
+        const existing = truncationCounts.get(key);
+        if (existing) {
+            existing.count += 1;
+            existing.observed_bytes = Math.max(existing.observed_bytes ?? 0, truncated.observed_bytes ?? 0);
+            existing.included_bytes = Math.max(existing.included_bytes ?? 0, truncated.included_bytes ?? 0);
+        }
+        else {
+            truncationCounts.set(key, {
+                source: truncated.kind,
+                reason: truncated.reason,
+                count: 1,
+                ...(truncated.max_bytes !== undefined
+                    ? { max_bytes: truncated.max_bytes }
+                    : {}),
+                ...(truncated.observed_bytes !== undefined
+                    ? { observed_bytes: truncated.observed_bytes }
+                    : {}),
+                ...(truncated.included_bytes !== undefined
+                    ? { included_bytes: truncated.included_bytes }
+                    : {}),
+            });
+        }
+    }
+    const hasGaps = totals.skipped_count > 0 ||
+        totals.truncated_count > 0 ||
+        totals.deferred_count > 0 ||
+        collection.caps.some((cap) => cap.applied);
+    const status = totals.included_count + totals.reused_count === 0 && !hasGaps
+        ? "empty"
+        : hasGaps
+            ? "partial"
+            : "complete";
+    return EvidenceCompletenessPayloadSchema.parse({
+        schema_version: "evidence-completeness.v1",
+        status,
+        generated_at: options.finishedAt,
+        scan_window: {
+            started_at: options.startedAt,
+            finished_at: options.finishedAt,
+            since_minutes: options.sinceMinutes,
+        },
+        source_counts: sourceCounts,
+        totals,
+        caps: collection.caps,
+        skip_reasons: [...skipReasonCounts.values()].sort((a, b) => `${a.source}:${a.reason}`.localeCompare(`${b.source}:${b.reason}`)),
+        truncation_markers: [...truncationCounts.values()].sort((a, b) => `${a.source}:${a.reason}`.localeCompare(`${b.source}:${b.reason}`)),
+        notes: hasGaps
+            ? ["Evidence is incomplete; downstream analysis should lower confidence."]
+            : [],
     });
-    return stdout;
 }
 async function walkJsonlFiles(dir, cutoffMs) {
     const out = [];

package/dist/agent-rules.js

@@ -15,7 +15,7 @@ export async function installAgentRules(options = {}) {
 }
 async function installAgentRulesForHost(host, options = {}) {
     const rulesFile = agentRulesFile(host, options.homeDir);
-    const block = cockpitAgentRulesBlock();
+    const block = cockpitAgentRulesBlock({ scopePath: options.scopePath });
     let existing = "";
     let existed = true;
     try {
@@ -24,7 +24,7 @@ async function installAgentRulesForHost(host, options = {}) {
     catch {
         existed = false;
     }
-    const prepared = prepareManagedBlockInstall(existing, block);
+    const prepared = prepareManagedBlockInstall(existing, block, options.scopePath);
     if (!prepared.next) {
         return agentRulesResult(host, rulesFile, "unchanged", block, prepared.state);
     }
@@ -78,7 +78,7 @@ export async function inspectAgentRules(options = {}) {
 }
 async function inspectAgentRulesForHost(host, options = {}) {
     const rulesFile = agentRulesFile(host, options.homeDir);
-    const block = cockpitAgentRulesBlock();
+    const block = cockpitAgentRulesBlock({ scopePath: options.scopePath });
     let existing = "";
     try {
         existing = await readFile(rulesFile, "utf8");
@@ -89,23 +89,28 @@ async function inspectAgentRulesForHost(host, options = {}) {
             installed: false,
         };
     }
-    const state = inspectAgentRulesContents(existing);
+    const state = inspectAgentRulesContents(existing, block, options.scopePath);
     const installed = state === "managed" || state === "equivalent";
     return {
         ...agentRulesResult(host, rulesFile, installed ? "unchanged" : "missing", block, state),
         installed,
     };
 }
-export function cockpitAgentRulesBlock() {
+export function cockpitAgentRulesBlock(options = {}) {
+    const scopePath = options.scopePath ? path.resolve(options.scopePath) : null;
+    const scopeLine = scopePath
+        ? `- This guidance only applies when the current working directory is inside the Cockpit-onboarded workspace/repo: \`${scopePath}\`. Outside that folder, do not run Cockpit ticket binding or sync commands for private chats or unrelated repos.`
+        : "- This guidance only applies when the current working directory is inside the workspace/repo that ran `cockpit onboard` or `cockpit agent-rules install`. Outside that folder, do not run Cockpit ticket binding or sync commands for private chats or unrelated repos.";
     return [
         MANAGED_BLOCK_START,
         "## Cockpit Ticket Binding",
         "",
-        "- For implementation, debugging, review, PR, or ship work tied to a clear Linear ticket, run `cockpit start --ticket <ticket-id> --repo \"$PWD\"` before the first code edit or mutating tool call. This starts attributing the session's work to that specific ticket in Cockpit.",
+        scopeLine,
+        "- For implementation, debugging, review, PR, or ship work tied to a clear Linear ticket, run `cockpit start --ticket <ticket-id> --workspace \"$PWD\"` before the first code edit or mutating tool call. This starts attributing the session's work to that specific ticket in Cockpit.",
         "- Use `--ticket`; do not invent `--ticketId` or other flag shapes.",
         "- If the user mentions ticketed work but no ticket ID is visible, ask once for the Linear ticket ID before editing. Agents cannot reliably infer it from context.",
         "- If there is truly no ticket, state that the work remains in general ambient capture and do not invent a ticket.",
-        "- After the first meaningful checkpoint, run `cockpit sync --repo \"$PWD\" --json` so Cockpit has fresh ticket/session binding metadata.",
+        "- After the first meaningful checkpoint, run `cockpit sync --workspace \"$PWD\" --json` so Cockpit has fresh ticket/session binding metadata.",
         MANAGED_BLOCK_END,
     ].join("\n");
 }
@@ -126,16 +131,19 @@ export function removeManagedBlock(contents) {
         return contents;
     return contents.replace(managedBlockPattern(), "").replace(/\n{3,}/gu, "\n\n").trimEnd() + "\n";
 }
-function prepareManagedBlockInstall(contents, block) {
+function prepareManagedBlockInstall(contents, block, scopePath) {
     if (!contents.trim())
         return { next: `${block}\n`, state: "missing" };
     if (hasManagedBlock(contents)) {
-        return { next: upsertManagedBlock(contents, block), state: "managed" };
+        return {
+            next: upsertManagedBlock(contents, block),
+            state: extractManagedBlock(contents) === block ? "managed" : "stale",
+        };
     }
-    if (hasEquivalentUnmanagedTicketBinding(contents)) {
+    if (hasEquivalentUnmanagedTicketBinding(contents, scopePath)) {
         return { next: null, state: "equivalent" };
     }
-    const staleBlock = findStaleUnmanagedTicketBindingBlock(contents);
+    const staleBlock = findStaleUnmanagedTicketBindingBlock(contents, scopePath);
     if (staleBlock) {
         return {
             next: replaceLineSpan(contents, staleBlock.startLine, staleBlock.endLine, block),
@@ -144,12 +152,13 @@ function prepareManagedBlockInstall(contents, block) {
     }
     return { next: `${contents.replace(/\s+$/u, "")}\n\n${block}\n`, state: "missing" };
 }
-function inspectAgentRulesContents(contents) {
-    if (hasManagedBlock(contents))
-        return "managed";
-    if (hasEquivalentUnmanagedTicketBinding(contents))
+function inspectAgentRulesContents(contents, block, scopePath) {
+    if (hasManagedBlock(contents)) {
+        return extractManagedBlock(contents) === block ? "managed" : "stale";
+    }
+    if (hasEquivalentUnmanagedTicketBinding(contents, scopePath))
         return "equivalent";
-    if (findStaleUnmanagedTicketBindingBlock(contents))
+    if (findStaleUnmanagedTicketBindingBlock(contents, scopePath))
         return "stale";
     return "missing";
 }
@@ -188,10 +197,17 @@ function aggregateAgentRulesResult(targets) {
 function managedBlockPattern() {
     return new RegExp(`${escapeRegExp(MANAGED_BLOCK_START)}[\\s\\S]*?${escapeRegExp(MANAGED_BLOCK_END)}`, "u");
 }
-function hasEquivalentUnmanagedTicketBinding(contents) {
+function extractManagedBlock(contents) {
+    return contents.match(managedBlockPattern())?.[0] ?? null;
+}
+function hasEquivalentUnmanagedTicketBinding(contents, scopePath) {
     const text = normalizeRuleText(contents);
     if (!hasTicketBindingCues(text))
         return false;
+    if (!hasRepoScopeGuard(text))
+        return false;
+    if (scopePath && !hasScopePath(text, scopePath))
+        return false;
     const signals = [
         /cockpit\s+start\s+--ticket\b/u,
         /before\s+(?:the\s+)?first\s+code\s+edit|before\s+ticketed\s+implementation/u,
@@ -203,7 +219,15 @@ function hasEquivalentUnmanagedTicketBinding(contents) {
     const score = signals.filter((signal) => signal.test(text)).length;
     return score >= 5;
 }
-function findStaleUnmanagedTicketBindingBlock(contents) {
+function hasScopePath(text, scopePath) {
+    return text.includes(normalizeRuleText(path.resolve(scopePath)));
+}
+function hasRepoScopeGuard(text) {
+    return (/only\s+applies\s+when\s+the\s+current\s+working\s+directory\s+is\s+inside/u.test(text) ||
+        /outside\s+that\s+(?:folder|workspace|repo).*(?:do\s+not|dont)\s+run\s+cockpit/u.test(text) ||
+        /private\s+chats\s+or\s+unrelated\s+repos/u.test(text));
+}
+function findStaleUnmanagedTicketBindingBlock(contents, scopePath) {
     const lines = contents.split("\n");
     for (let index = 0; index < lines.length; index += 1) {
         if (!/^#{1,6}\s+.*(?:cockpit\s+)?ticket\s+binding\b/iu.test(lines[index] ?? "")) {
@@ -218,7 +242,8 @@ function findStaleUnmanagedTicketBindingBlock(contents) {
         }
         const candidate = lines.slice(index, endLine).join("\n");
         const normalized = normalizeRuleText(candidate);
-        if (hasTicketBindingCues(normalized) && !hasEquivalentUnmanagedTicketBinding(candidate)) {
+        if (hasTicketBindingCues(normalized) &&
+            !hasEquivalentUnmanagedTicketBinding(candidate, scopePath)) {
             return { startLine: index, endLine };
         }
     }

package/dist/commands/local-args.js

@@ -5,6 +5,7 @@
 // Behavior-preserving extraction: functions moved verbatim, no logic change.
 import { DEFAULT_DASHBOARD_URL } from "../local-state.js";
 import { DEFAULT_AUTOSTART_INTERVAL_SECONDS } from "../autostart.js";
+import { IntentSourceSchema, WorkIntentSchema, WorkPhaseSchema, } from "@bli-cockpit/telemetry-core";
 const WORK_ROOT_FLAGS = ["--repo", "--workspace"];
 export function parseLocalArgs(argv) {
     const command = argv[0];
@@ -165,6 +166,12 @@ function parseStartArgs(args) {
             "--workspace",
             "--branch",
             "--ticket",
+            "--topic",
+            "--topic-summary",
+            "--intent",
+            "--phase",
+            "--intent-source",
+            "--intent-confidence",
             "--operator-id",
             "--session-id",
             "--json",
@@ -177,6 +184,12 @@ function parseStartArgs(args) {
             "--workspace",
             "--branch",
             "--ticket",
+            "--topic",
+            "--topic-summary",
+            "--intent",
+            "--phase",
+            "--intent-source",
+            "--intent-confidence",
             "--operator-id",
             "--session-id",
             "--max-depth",
@@ -184,12 +197,28 @@ function parseStartArgs(args) {
         ],
     });
     assertNoPositionals(values.positionals, "start");
+    const topicLabel = optionalNonEmpty(values.flags.get("--topic"));
+    const topicSummaryRedacted = optionalNonEmpty(values.flags.get("--topic-summary"));
+    const workIntent = optionalSchemaValue(WorkIntentSchema, values.flags.get("--intent"), "--intent");
+    const workPhase = optionalSchemaValue(WorkPhaseSchema, values.flags.get("--phase"), "--phase");
+    const intentConfidence = optionalConfidence(values.flags.get("--intent-confidence"), "--intent-confidence");
+    const explicitIntentMetadata = Boolean(topicLabel ||
+        topicSummaryRedacted ||
+        workIntent ||
+        workPhase ||
+        intentConfidence !== undefined);
     return {
         kind: "start",
         homeDir: optionalNonEmpty(values.flags.get("--home")),
         repoRoot: optionalNonEmpty(workRootFlagValue(values)),
         branch: optionalNonEmpty(values.flags.get("--branch")),
         activeTicketId: optionalNonEmpty(values.flags.get("--ticket")),
+        topicLabel,
+        topicSummaryRedacted,
+        workIntent,
+        workPhase,
+        intentSource: optionalSchemaValue(IntentSourceSchema, values.flags.get("--intent-source"), "--intent-source") ?? (explicitIntentMetadata ? "explicit_user" : undefined),
+        intentConfidence,
         operatorId: optionalNonEmpty(values.flags.get("--operator-id")),
         sessionId: optionalNonEmpty(values.flags.get("--session-id")),
         json: values.booleans.has("--json"),
@@ -345,8 +374,8 @@ function parseAutostartArgs(args) {
 }
 function parseAgentRulesArgs(args) {
     const values = parseNamedArgs(args, {
-        allowedFlags: ["--home", "--host", "--json"],
-        valueFlags: ["--home", "--host"],
+        allowedFlags: ["--home", "--host", "--repo", "--workspace", "--json"],
+        valueFlags: ["--home", "--host", "--repo", "--workspace"],
     });
     if (values.positionals.length > 1) {
         throw new Error("agent-rules accepts at most one action (install|uninstall|status).");
@@ -360,6 +389,7 @@ function parseAgentRulesArgs(args) {
         action,
         host: parseAgentRulesHost(values.flags.get("--host")),
         homeDir: optionalNonEmpty(values.flags.get("--home")),
+        repoRoot: optionalNonEmpty(workRootFlagValue(values)),
         json: values.booleans.has("--json"),
     };
 }
@@ -443,6 +473,25 @@ function optionalPositiveInteger(value, flag) {
     }
     return parsed;
 }
+function optionalConfidence(value, flag) {
+    if (value === undefined)
+        return undefined;
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed) || parsed < 0 || parsed > 1) {
+        throw new Error(`${flag} must be a number between 0 and 1.`);
+    }
+    return parsed;
+}
+function optionalSchemaValue(schema, value, flag) {
+    const trimmed = optionalNonEmpty(value);
+    if (!trimmed)
+        return undefined;
+    const parsed = schema.safeParse(trimmed);
+    if (!parsed.success || parsed.data === undefined) {
+        throw new Error(`${flag} has an unsupported value.`);
+    }
+    return parsed.data;
+}
 export function normalizeUrl(value) {
     const trimmed = value.trim().replace(/\/+$/, "");
     if (!trimmed)

package/dist/commands/local.js

@@ -80,13 +80,13 @@ export function localCommandHelp(command) {
         "  cockpit login [--email <owner@email>] [--device-name <name>] [--dashboard-url <url>] [--json]",
         "  cockpit pair [--email <owner@email>] [--device-name <name>] [--dashboard-url <url>] [--json]",
         "  cockpit logout",
-        "  cockpit start [--ticket <id>] [--workspace <path>] [--branch <name>] [--max-depth <n>] [--max-repos <n>] [--json]",
+        "  cockpit start [--ticket <id>] [--topic <label>] [--intent <intent>] [--phase <phase>] [--workspace <path>] [--branch <name>] [--max-depth <n>] [--max-repos <n>] [--json]",
         "  cockpit sync [--workspace <path>] [--dashboard-url <url>] [--max-depth <n>] [--max-repos <n>] [--json]",
         "  cockpit status [--workspace <path>] [--max-depth <n>] [--max-repos <n>] [--json]",
         "  cockpit sessions [--source codex|claude] [--workspace <path>] [--max-depth <n>] [--max-repos <n>] [--json]",
         "  cockpit serve [--port <port>] [--workspace <path>]",
         "  cockpit autostart [install|uninstall|status] [--workspace <path>] [--dashboard-url <url>] [--interval-seconds <n>] [--json]",
-        "  cockpit agent-rules [install|uninstall|status] [--host codex|claude|all] [--json]",
+        "  cockpit agent-rules [install|uninstall|status] [--host codex|claude|all] [--workspace <path>] [--json]",
         "",
         `Default dashboard: ${DEFAULT_DASHBOARD_URL}. Omit --dashboard-url for normal production use; pass it only for staging/custom dashboards or to force a different pairing.`,
     ].join("\n");
@@ -138,11 +138,14 @@ function localSubcommandHelp(command) {
         [
             "start",
             [
-                "Usage: cockpit start [--ticket <id>] [--workspace <path>] [--branch <name>] [--json]",
+                "Usage: cockpit start [--ticket <id>] [--topic <label>] [--topic-summary <summary>] [--intent <intent>] [--phase <phase>] [--intent-confidence <0..1>] [--workspace <path>] [--branch <name>] [--json]",
                 "",
                 "Starts local ambient capture. Parent folders start each child git worktree.",
                 "Add --ticket only when the work already has a visible ticket.",
-                "`--repo <path>` remains supported and is still the canonical agent-rule spelling.",
+                "Use --topic/--intent/--phase for planning, discovery, and learning work that has no ticket yet.",
+                "Supported intents: implementation, bug_fix, root_cause_analysis, planning, discovery, review, testing, documentation, release, learning, coordination, maintenance, analysis, unknown, other.",
+                "Supported phases: planning, discovery, implementation, debugging, review, testing, documentation, release, handoff, analysis, unknown, other.",
+                "`--repo <path>` remains supported as a backward-compatible alias; use --workspace in agent guidance.",
             ],
         ],
         [
@@ -209,13 +212,12 @@ function localSubcommandHelp(command) {
         [
             "agent-rules",
             [
-                "Usage: cockpit agent-rules [install|uninstall|status] [--host codex|claude|all] [--json]",
+                "Usage: cockpit agent-rules [install|uninstall|status] [--host codex|claude|all] [--workspace <path>] [--json]",
                 "",
                 "Installs a managed Cockpit Ticket Binding block into ~/.codex/AGENTS.md",
                 "and ~/.claude/CLAUDE.md by default. Pass --host to manage only one.",
-                "This gives Codex and Claude agents a user-scope rule to run",
-                "`cockpit start --ticket <id>` before ticketed implementation work, or ask",
-                "once when the ticket ID is missing.",
+                "The block is scoped to --workspace, or the current directory when omitted,",
+                "so Codex and Claude only run Cockpit ticket binding inside that onboarded folder.",
                 "Action defaults to `install`.",
             ],
         ],
@@ -314,19 +316,23 @@ async function maybeOfferAutostart(command, io) {
 async function maybeOfferAgentRules(command, io) {
     if (command.json || !isInteractiveStdin(io))
         return;
-    const current = await inspectAgentRules({ homeDir: command.homeDir });
+    const scopePath = path.resolve(command.repoRoot ?? process.cwd());
+    const current = await inspectAgentRules({
+        homeDir: command.homeDir,
+        scopePath,
+    });
     if (current.installed) {
         writeLine(io.stdout, onboardAgentRulesAlreadyInstalledLine(current));
         return;
     }
-    const answer = (await readLine(io, "Add Cockpit ticket-binding rules to AGENTS.md and CLAUDE.md? [Y/n] "))
+    const answer = (await readLine(io, `Add Cockpit ticket-binding rules scoped to ${scopePath} to AGENTS.md and CLAUDE.md? [Y/n] `))
         .trim()
         .toLowerCase();
     if (answer === "n" || answer === "no") {
-        writeLine(io.stdout, "Skipped agent rules. Run `cockpit agent-rules install` anytime.");
+        writeLine(io.stdout, "Skipped agent rules. Run `cockpit agent-rules install --workspace \"$PWD\"` anytime.");
         return;
     }
-    const result = await installAgentRules({ homeDir: command.homeDir });
+    const result = await installAgentRules({ homeDir: command.homeDir, scopePath });
     writeLine(io.stdout, `Agent rules: ${onboardAgentRulesInstallLine(result)}`);
     for (const target of result.targets) {
         writeLine(io.stdout, `${agentRuleHostLabel(target.host)}: ${target.rules_file}`);
@@ -776,7 +782,7 @@ function nextStepForOnboardBlocker(blocker) {
         case "install":
             return "Rerun `cockpit onboard` from the repo root; it will reinstall local config.";
         case "work_context":
-            return "Run `cockpit start --ticket <id> --repo \"$PWD\"`, then retry `cockpit sync`.";
+            return "Run `cockpit start --ticket <id> --workspace \"$PWD\"`, then retry `cockpit sync`.";
         default:
             return "Run `cockpit status --json` and report the blocker label plus last failure reason.";
     }
@@ -800,6 +806,12 @@ async function runStart(command, io) {
             repoRoot: worktree.repo_root,
             branch: command.branch,
             activeTicketId: command.activeTicketId,
+            topicLabel: command.topicLabel,
+            topicSummaryRedacted: command.topicSummaryRedacted,
+            workIntent: command.workIntent,
+            workPhase: command.workPhase,
+            intentSource: command.intentSource,
+            intentConfidence: command.intentConfidence,
             operatorId: command.operatorId,
             sessionId: command.sessionId,
         })));
@@ -822,6 +834,9 @@ async function runStart(command, io) {
     writeLine(io.stdout, `Repo: ${context.repo}`);
     writeLine(io.stdout, `Branch: ${context.branch}`);
     writeLine(io.stdout, `Ticket: ${displayTicketId(context.active_ticket_id)}`);
+    if (context.topic_label || context.work_intent || context.work_phase) {
+        writeLine(io.stdout, `Topic: ${context.topic_label ?? "unlabeled"} · ${context.work_intent ?? "unknown"} · ${context.work_phase ?? "unknown"}`);
+    }
     writeLine(io.stdout, `Context: ${context.work_context_id}`);
     return 0;
 }
@@ -1081,11 +1096,12 @@ async function runAutostart(command, io) {
 }
 async function runAgentRules(command, io) {
     const hosts = agentRuleHosts(command.host);
+    const scopePath = path.resolve(command.repoRoot ?? process.cwd());
     const result = command.action === "install"
-        ? await installAgentRules({ homeDir: command.homeDir, hosts })
+        ? await installAgentRules({ homeDir: command.homeDir, hosts, scopePath })
         : command.action === "uninstall"
             ? await uninstallAgentRules({ homeDir: command.homeDir, hosts })
-            : await inspectAgentRules({ homeDir: command.homeDir, hosts });
+            : await inspectAgentRules({ homeDir: command.homeDir, hosts, scopePath });
     if (command.json) {
         writeLine(io.stdout, JSON.stringify(result, null, 2));
         return 0;

package/dist/commands/public-root.js

@@ -25,9 +25,9 @@ function cockpitHelp() {
     "Install/update: `npm install -g @bli-cockpit/cli@latest`.",
     "Intern path: run `cockpit onboard` from the repo root; add `--ticket <id>` only when work already has a ticket.",
     "Already onboarded: run `cockpit sync --workspace \"$PWD\" --json`.",
-    "Agent setup: interactive `cockpit onboard` offers AGENTS.md/CLAUDE.md rules; use `cockpit agent-rules install` for repair/headless setup.",
+    "Agent setup: interactive `cockpit onboard` offers AGENTS.md/CLAUDE.md rules; use `cockpit agent-rules install --workspace \"$PWD\"` for repair/headless setup.",
     "Dashboard URL is optional for normal production use; pass `--dashboard-url` only for staging/custom dashboards or forced re-pairing.",
-    "Manual collector path: `install`, `login`, `start [--ticket <id>]`, `sync`, `status`, `agent-rules`.",
+    "Manual collector path: `install`, `login`, `start [--ticket <id>] [--topic <label>] [--intent <intent>] [--phase <phase>]`, `sync`, `status`, `agent-rules`.",
   ].join("\n");
 }
 

package/dist/local-state.js

@@ -170,6 +170,12 @@ export async function startLocalWorkContext(options = {}) {
         updated_at: now.toISOString(),
         active_ticket_id: options.activeTicketId ?? undefined,
         ticket_binding_candidates: ticketBindingCandidates,
+        topic_label: options.topicLabel,
+        topic_summary_redacted: options.topicSummaryRedacted,
+        work_intent: options.workIntent,
+        work_phase: options.workPhase,
+        intent_source: options.intentSource,
+        intent_confidence: options.intentConfidence,
         pull_request_url: existingContext?.pull_request_url,
         provenance: {
             capture_source: "collector_runtime",
@@ -285,7 +291,7 @@ export async function readLocalWorkContextForRepo(paths, repoRoot) {
         path.resolve(active.repo) === identity.repo_root) {
         return active;
     }
-    throw new Error(`Active work context missing for ${identity.worktree_label}. Run \`cockpit start --repo "${identity.repo_root}"\`.`);
+    throw new Error(`Active work context missing for ${identity.worktree_label}. Run \`cockpit start --workspace "${identity.repo_root}"\`.`);
 }
 async function readLocalWorkContextByFingerprint(paths, worktreeFingerprint) {
     return LocalWorkContextSchema.parse(await readJsonFile(workContextFile(paths, worktreeFingerprint)));

package/dist/upload.js

@@ -575,6 +575,7 @@ function makeSourceScanCompletedEvent(options) {
         throw new Error("Upload work context is missing provenance.");
     }
     const rawEvidencePointers = options.rawEvidenceFacts?.pointers ?? [];
+    const evidenceCompleteness = options.rawEvidenceFacts?.evidence_completeness;
     const hasRawEvidence = rawEvidencePointers.length > 0;
     const eventPrivacyClassification = hasRawEvidence
         ? "redacted_summary"
@@ -617,6 +618,12 @@ function makeSourceScanCompletedEvent(options) {
             raw_evidence_byte_size: options.rawEvidenceFacts?.byte_size ?? 0,
             raw_evidence_skipped_count: options.rawEvidenceFacts?.skipped_count ?? 0,
             raw_evidence_reused_count: options.rawEvidenceFacts?.reused_count ?? 0,
+            evidence_scanned_count: evidenceCompleteness?.totals.scanned_count ?? 0,
+            evidence_included_count: evidenceCompleteness?.totals.included_count ?? 0,
+            evidence_skipped_count: evidenceCompleteness?.totals.skipped_count ?? 0,
+            evidence_truncated_count: evidenceCompleteness?.totals.truncated_count ?? 0,
+            evidence_deferred_count: evidenceCompleteness?.totals.deferred_count ?? 0,
+            evidence_reused_count: evidenceCompleteness?.totals.reused_count ?? 0,
         },
         attributes: {
             repo_label: options.context.repo,
@@ -634,7 +641,31 @@ function makeSourceScanCompletedEvent(options) {
                 ? "remote_durable_raw_evidence"
                 : "metadata_only",
             raw_payload_included: false,
+            evidence_completeness_schema_version: evidenceCompleteness?.schema_version ?? "evidence-completeness.v1",
+            evidence_completeness_status: evidenceCompleteness?.status ?? "unknown",
+            evidence_incomplete: evidenceCompleteness
+                ? evidenceCompleteness.status !== "complete"
+                : true,
+            ...(options.context.topic_label
+                ? { topic_label: options.context.topic_label }
+                : {}),
+            ...(options.context.topic_summary_redacted
+                ? { topic_summary_redacted: options.context.topic_summary_redacted }
+                : {}),
+            ...(options.context.work_intent
+                ? { work_intent: options.context.work_intent }
+                : {}),
+            ...(options.context.work_phase
+                ? { work_phase: options.context.work_phase }
+                : {}),
+            ...(options.context.intent_source
+                ? { intent_source: options.context.intent_source }
+                : {}),
+            ...(options.context.intent_confidence !== undefined
+                ? { intent_confidence: options.context.intent_confidence }
+                : {}),
         },
+        evidence_completeness: evidenceCompleteness,
         ticket_binding: options.ticketBinding ?? undefined,
         risk_flags: options.riskFlags,
         raw_evidence_pointers: rawEvidencePointers,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bli-cockpit/cli",
-  "version": "0.1.19",
+  "version": "0.1.20",
   "private": false,
   "type": "module",
   "bin": {
@@ -26,6 +26,6 @@
     "test": "node dist/cli.js --help && node ../../scripts/assert-public-package-pack.mjs --workspace=@bli-cockpit/cli"
   },
   "dependencies": {
-    "@bli-cockpit/telemetry-core": "0.1.5"
+    "@bli-cockpit/telemetry-core": "0.1.6"
   }
 }