@iowarp/clio-coder 0.4.2 → 0.4.4

package/src/cli/context-map.ts

@@ -0,0 +1,114 @@
+import { execFileSync } from "node:child_process";
+import { mkdirSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { CLIO_ARTIFACT_DIR } from "../core/artifact-paths.js";
+import { readCodewiki } from "../domains/context/codewiki/artifact.js";
+import { buildArchitectureSeed, serializeArchitectureSeed } from "../domains/context/wiki/map-seed.js";
+
+const HELP = `Usage:
+  clio-coder context map [--out <path>] [--json]
+
+Write an archify architecture seed for the current repository from the codewiki
+index, without model calls. The seed is the starting spec for the archify skill:
+components are the largest directory areas, connections are collapsed import
+edges, and sources point at indexed files and lines.
+
+Options:
+  --out <path>    where to write the seed (default: ${CLIO_ARTIFACT_DIR}/maps/<repo>.architecture.json)
+  --json          print machine-readable details about the written seed
+`;
+
+/** Where the seed lands when the operator names no path: a human-transient map artifact. */
+function defaultMapSeedPath(cwd: string): string {
+	return path.join(cwd, CLIO_ARTIFACT_DIR, "maps", `${path.basename(cwd)}.architecture.json`);
+}
+
+function gitValue(cwd: string, args: string[]): string | null {
+	try {
+		const out = execFileSync("git", args, { cwd, timeout: 5000, stdio: ["ignore", "pipe", "ignore"] })
+			.toString("utf8")
+			.trim();
+		return out.length > 0 ? out : null;
+	} catch {
+		return null;
+	}
+}
+
+/** The origin remote as an https URL and HEAD as a full sha, when git can say. */
+function repositoryFacts(cwd: string): { url: string; revision: string } | undefined {
+	const remote = gitValue(cwd, ["remote", "get-url", "origin"]);
+	const revision = gitValue(cwd, ["rev-parse", "--verify", "HEAD"]);
+	if (!remote || !revision) return undefined;
+	let url = remote.endsWith(".git") ? remote.slice(0, -4) : remote;
+	const ssh = /^git@([^:]+):(.+)$/.exec(url);
+	if (ssh) url = `https://${ssh[1]}/${ssh[2]}`;
+	return { url, revision };
+}
+
+export async function runContextMapCommand(args: string[]): Promise<number> {
+	if (args.includes("--help") || args.includes("-h")) {
+		process.stdout.write(HELP);
+		return 0;
+	}
+	let out: string | null = null;
+	let json = false;
+	for (let index = 0; index < args.length; index += 1) {
+		const arg = args[index] as string;
+		if (arg === "--json") {
+			json = true;
+			continue;
+		}
+		if (arg === "--out") {
+			const value = args[index + 1];
+			if (!value || value.startsWith("--")) {
+				process.stderr.write("clio-coder context map: --out requires a path\n");
+				return 2;
+			}
+			out = value;
+			index += 1;
+			continue;
+		}
+		process.stderr.write(`clio-coder context map: unknown flag ${arg}\n`);
+		return 2;
+	}
+	const cwd = process.cwd();
+	const codewiki = readCodewiki(cwd);
+	if (!codewiki) {
+		process.stderr.write(
+			"clio-coder context map: no codewiki index in .clio-coder/codewiki.json; run `clio-coder context index` first\n",
+		);
+		return 1;
+	}
+	const seed = buildArchitectureSeed(codewiki, {
+		title: path.basename(cwd),
+		repository: repositoryFacts(cwd),
+	});
+	const target = out ? path.resolve(cwd, out) : defaultMapSeedPath(cwd);
+	mkdirSync(path.dirname(target), { recursive: true });
+	writeFileSync(target, serializeArchitectureSeed(seed), "utf8");
+	const payload = {
+		path: target,
+		components: seed.components.length,
+		connections: seed.connections.length,
+		repository: seed.meta.repository ?? null,
+	};
+	if (json) {
+		process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+		return 0;
+	}
+	process.stdout.write(
+		[
+			`clio-coder context map wrote ${target}`,
+			`  ${payload.components} components, ${payload.connections} connections${
+				payload.repository
+					? `, sources pinned at ${payload.repository.revision.slice(0, 12)}`
+					: "; no GitHub origin at a full revision, so no source citations"
+			}`,
+			payload.repository
+				? "  next: validate and deliver it with the archify skill, passing --repo-root ."
+				: "  next: validate and deliver it with the archify skill (without --repo-root)",
+			"",
+		].join("\n"),
+	);
+	return 0;
+}

package/src/cli/context.ts

@@ -10,6 +10,7 @@ const HELP = `Usage:
                     [--target <id>] [--model <id>] [--thinking off|low|medium|high]
   clio-coder context reset [--all] [--yes]
   clio-coder context index [--json]
+  clio-coder context map [--out <path>] [--json]
   clio-coder context replay --sessions <path>... [options]
   clio-coder context working-set --session <id|path>
 
@@ -20,6 +21,7 @@ Project context commands:
   clio-coder context wiki         generate or inspect the agent-authored Markdown wiki
   clio-coder context reset        clear accumulated project context artifacts
   clio-coder context index        build the codewiki index without model calls
+  clio-coder context map          write an archify architecture seed from the codewiki index
   clio-coder context replay       compare working-set policies over Clio ledgers
   clio-coder context working-set  inspect one session's working-set fold and path index
 `;
@@ -317,6 +319,8 @@ export async function runContextCommand(args: string[]): Promise<number> {
 			return (await import("./context-clear.js")).runContextClearCommand(rest);
 		case "index":
 			return (await import("./context-index.js")).runContextIndexCommand(rest);
+		case "map":
+			return (await import("./context-map.js")).runContextMapCommand(rest);
 		case "replay":
 			return (await import("./context-working-set.js")).runContextReplayCommand(rest);
 		case "working-set":

package/src/cli/doctor-state-size.ts

@@ -2,6 +2,7 @@ import { lstatSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { resolveClioDirs } from "../core/xdg.js";
 import type { DoctorFinding } from "../domains/lifecycle/doctor.js";
+import { formatBytes } from "./lifecycle-presenter.js";
 
 interface MeasuredEntry {
 	bytes: number;
@@ -68,15 +69,3 @@ function measureEntry(path: string): MeasuredEntry {
 	}
 	return { bytes, error: null };
 }
-
-function formatBytes(bytes: number): string {
-	if (bytes < 1024) return `${bytes} B`;
-	const units = ["KiB", "MiB", "GiB", "TiB"];
-	let value = bytes;
-	let unit = -1;
-	do {
-		value /= 1024;
-		unit += 1;
-	} while (value >= 1024 && unit < units.length - 1);
-	return `${value.toFixed(value >= 10 ? 1 : 2)} ${units[unit]}`;
-}

package/src/cli/doctor-validation-contract.ts

@@ -0,0 +1,28 @@
+import type { DoctorFinding } from "../domains/lifecycle/doctor.js";
+import { describeValidationContract, loadValidationContract } from "../domains/safety/validation-contract.js";
+
+/**
+ * One row for the workspace's scientific validation contract: absent, parsed
+ * (and so raising the rigor default to high), Markdown-only advisory, or
+ * invalid with the parse fault. Reads the workspace root only; creates nothing.
+ */
+export function validationContractFinding(workspaceRoot = process.cwd()): DoctorFinding {
+	const name = "validation contract";
+	const loaded = loadValidationContract(workspaceRoot);
+	if (!loaded.ok) {
+		return { ok: false, name, detail: `invalid: ${describeValidationContract(loaded)}; rigor default stays normal` };
+	}
+	if (loaded.contract === null) {
+		if ("advisory" in loaded) {
+			return { ok: true, name, level: "warn", detail: `markdown-only: ${describeValidationContract(loaded)}` };
+		}
+		return { ok: true, name, detail: "none at the workspace root; rigor default normal" };
+	}
+	const artifacts = loaded.contract.artifacts?.length ?? 0;
+	const validators = loaded.contract.validators?.length ?? 0;
+	return {
+		ok: true,
+		name,
+		detail: `valid: ${loaded.path} (version ${loaded.contract.version}, ${artifacts} artifact(s), ${validators} validator(s)); rigor default high`,
+	};
+}

package/src/cli/doctor.ts

@@ -12,6 +12,7 @@ import { namingFootprintFindings } from "./doctor-naming.js";
 import { panesFindings } from "./doctor-panes.js";
 import { stateStorageFinding } from "./doctor-state-size.js";
 import { toolchainFindings } from "./doctor-toolchain.js";
+import { validationContractFinding } from "./doctor-validation-contract.js";
 import { printError } from "./shared.js";
 
 const HELP = `clio-coder doctor [--fix] [--json]
@@ -72,6 +73,9 @@ export async function runDoctorCommand(args: ReadonlyArray<string> = []): Promis
 	// has already agreed not to build on an untouched home.
 	const paneChecks = untouched ? [] : await panesFindings();
 	const namingChecks = namingFootprintFindings({ fix, yaziEnabled: filesEnabled });
+	// The validation contract lives in the workspace, not the home, so it is
+	// checked on every run: a broken contract is why rigor stayed normal.
+	const contractChecks = [validationContractFinding()];
 	const all = [
 		...findings,
 		...storageChecks,
@@ -82,6 +86,7 @@ export async function runDoctorCommand(args: ReadonlyArray<string> = []): Promis
 		...toolChecks,
 		...paneChecks,
 		...namingChecks,
+		...contractChecks,
 	];
 	const ok = all.every((f) => f.ok);
 	if (json) {

package/src/cli/evidence-detail.ts

@@ -1,78 +1,4 @@
-/**
- * Fixed machine-readable projection of one evidence bundle's trust record.
- *
- * `evidence inspect <id>` prints an operator record that quotes the task text,
- * the bundle's file list, and per-finding prose. This is the same bundle read
- * down to the one thing a GUI can carry safely and usefully: which runs the
- * bundle covers, what verdict each run earned, and which axis produced it.
- *
- * Every value here comes from a closed vocabulary. The axis names, the axis
- * states, and the verdicts are all enumerations the harness owns, so there is
- * no free-form text on this surface at all, which is what lets it answer the
- * question the inventory raises without reopening the boundary the inventory
- * closed.
- *
- * Unlike the other fixed reads this one takes an identifier, because an
- * operator names the bundle. The GUI host may only pass back an id it served
- * inside its current bounded window; see `apps/workbench/artifact-allowlist.ts`.
- */
-
-import { clioDataDir } from "../core/xdg.js";
-import {
-	inspectEvidence,
-	TRUST_STATUS_AXES,
-	type TrustStatusAxis,
-	type TrustVerdict,
-	trustVerdict,
-} from "../domains/evidence/index.js";
-
-export const EVIDENCE_DETAIL_MAX_RUNS = 16;
-
-export interface EvidenceDetailRun {
-	readonly runId: string;
-	readonly verdict: TrustVerdict;
-	/** Every axis, always all six, so an absent axis is stated rather than missing. */
-	readonly axes: Readonly<Record<TrustStatusAxis, string>>;
-}
-
-export interface EvidenceDetailSnapshot {
-	readonly version: 1;
-	readonly generatedAt: string;
-	readonly evidenceId: string;
-	readonly sourceKind: "run" | "session" | "eval";
-	/** False when the bundle predates the canonical trust projection. */
-	readonly canonical: boolean;
-	readonly runs: readonly EvidenceDetailRun[];
-	readonly runsTruncated: boolean;
-}
-
-async function evidenceDetailSnapshot(
-	evidenceId: string,
-	now: () => number = Date.now,
-	dataDir: string = clioDataDir(),
-): Promise<EvidenceDetailSnapshot> {
-	const inspected = await inspectEvidence(dataDir, evidenceId);
-	const all = inspected.trustStatus.runs;
-	const window = all.slice(0, EVIDENCE_DETAIL_MAX_RUNS);
-	return {
-		version: 1,
-		generatedAt: new Date(now()).toISOString(),
-		evidenceId: inspected.overview.evidenceId,
-		sourceKind: inspected.overview.source.kind,
-		canonical: inspected.trustStatus.projection === "canonical",
-		runs: window.map(
-			(run): EvidenceDetailRun => ({
-				runId: run.runId,
-				verdict: trustVerdict(run.status),
-				axes: Object.fromEntries(TRUST_STATUS_AXES.map((axis) => [axis, run.status[axis].state])) as Record<
-					TrustStatusAxis,
-					string
-				>,
-			}),
-		),
-		runsTruncated: all.length > window.length,
-	};
-}
+import { evidenceDetailSnapshot } from "../domains/evidence/detail.js";
 
 /**
  * `clio-coder evidence inspect <id> --json`.

package/src/cli/evidence-inventory.ts

@@ -1,170 +1,4 @@
-/**
- * Fixed machine-readable projection of recent evidence artifacts.
- *
- * `evidence list` is an operator table and `evidence inspect <id>` needs an id,
- * so neither is a transport a GUI host can invoke blind. This command accepts
- * no identifier, path, or limit, selects a bounded newest-first window itself,
- * and emits provenance, tags, totals, and a trust verdict.
- *
- * An overview carries the working directories the runs executed in, the task
- * text the operator typed, and the file names inside the bundle. None of that
- * appears here. What does is the shape of the artifact and how far it can be
- * trusted, which is what an operator picks a bundle by.
- */
-
-import { clioDataDir } from "../core/xdg.js";
-import {
-	EVIDENCE_TAGS,
-	type EvidenceOverview,
-	type EvidenceTag,
-	listEvidenceOverviews,
-	loadEvidenceTrustStatus,
-	type TrustVerdict,
-	trustVerdict,
-} from "../domains/evidence/index.js";
-import { sanitizeCallTargetText } from "../domains/safety/call-target.js";
-import { truncateToWidth } from "../engine/tui-primitives.js";
-
-export const EVIDENCE_INVENTORY_MAX_ARTIFACTS = 12;
-export const EVIDENCE_INVENTORY_MAX_IDS = 8;
-
-const IDENTITY_WIDTH = 128;
-
-/**
- * Worst verdict first.
- *
- * An artifact covering several runs is only as trustworthy as its weakest run,
- * so the fold takes the worst rather than the newest or the most common. A
- * `compromised` run inside an otherwise clean bundle is the fact the operator
- * needs, and averaging it away would be the one summary worth not printing.
- */
-const VERDICT_SEVERITY: ReadonlyArray<TrustVerdict> = ["compromised", "unverified", "unknown", "grounded", "reviewed"];
-
-export interface EvidenceInventoryArtifact {
-	readonly evidenceId: string;
-	readonly sourceKind: "run" | "session" | "eval";
-	readonly generatedAt: string;
-	readonly startedAt: string | null;
-	readonly endedAt: string | null;
-	readonly runIds: readonly string[];
-	readonly runIdsTruncated: boolean;
-	readonly agentIds: readonly string[];
-	readonly statuses: readonly string[];
-	readonly tags: readonly EvidenceTag[];
-	readonly totals: Readonly<{
-		runs: number;
-		receipts: number;
-		toolCalls: number;
-		toolErrors: number;
-		blockedToolCalls: number;
-		protectedArtifacts: number;
-		tokens: number;
-		costUsd: number;
-		wallTimeMs: number;
-	}>;
-	/** Secret-shaped values the builder replaced across the bundle's exports. */
-	readonly redactionCount: number;
-	readonly trust: Readonly<{
-		verdict: TrustVerdict;
-		/** Runs whose canonical trust status the bundle actually recorded. */
-		runsCovered: number;
-		/** True when the bundle predates the canonical trust projection. */
-		historical: boolean;
-	}>;
-}
-
-export interface EvidenceInventorySnapshot {
-	readonly version: 1;
-	readonly generatedAt: string;
-	readonly artifacts: readonly EvidenceInventoryArtifact[];
-	readonly truncated: boolean;
-}
-
-function bounded(value: string, width: number): string {
-	const sanitized = sanitizeCallTargetText(value);
-	if (sanitized.length === 0) return "unavailable";
-	return sanitizeCallTargetText(truncateToWidth(sanitized, width, "…", false));
-}
-
-/** Distinct, sanitized, bounded, in first-seen order. */
-function identities(values: ReadonlyArray<string>): string[] {
-	const seen: string[] = [];
-	for (const value of values) {
-		const text = bounded(value, IDENTITY_WIDTH);
-		if (!seen.includes(text)) seen.push(text);
-		if (seen.length >= EVIDENCE_INVENTORY_MAX_IDS) break;
-	}
-	return seen;
-}
-
-function tally(value: number | undefined): number {
-	return typeof value === "number" && Number.isFinite(value) && value >= 0 ? Math.trunc(value) : 0;
-}
-
-function amount(value: number | undefined): number {
-	return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : 0;
-}
-
-/** Newest generation first. An unparseable stamp sorts oldest rather than throwing. */
-function byNewest(a: EvidenceOverview, b: EvidenceOverview): number {
-	return (Date.parse(b.generatedAt) || 0) - (Date.parse(a.generatedAt) || 0);
-}
-
-async function evidenceInventorySnapshot(
-	now: () => number = Date.now,
-	dataDir: string = clioDataDir(),
-): Promise<EvidenceInventorySnapshot> {
-	const all = (await listEvidenceOverviews(dataDir)).sort(byNewest);
-	const window = all.slice(0, EVIDENCE_INVENTORY_MAX_ARTIFACTS);
-	const artifacts: EvidenceInventoryArtifact[] = [];
-	for (const overview of window) {
-		// One unreadable trust file costs that artifact its verdict, never the
-		// whole inventory: the bundle itself is still the thing being listed.
-		let verdict: TrustVerdict = "unknown";
-		let runsCovered = 0;
-		let historical = true;
-		try {
-			const status = await loadEvidenceTrustStatus(dataDir, overview.evidenceId);
-			historical = status.projection !== "canonical";
-			runsCovered = status.runs.length;
-			const verdicts = status.runs.map((run) => trustVerdict(run.status));
-			verdict = VERDICT_SEVERITY.find((candidate) => verdicts.includes(candidate)) ?? "unknown";
-		} catch {
-			verdict = "unknown";
-		}
-		artifacts.push({
-			evidenceId: bounded(overview.evidenceId, IDENTITY_WIDTH),
-			sourceKind: overview.source.kind,
-			generatedAt: overview.generatedAt,
-			startedAt: overview.startedAt,
-			endedAt: overview.endedAt,
-			runIds: identities(overview.runIds),
-			runIdsTruncated: overview.runIds.length > EVIDENCE_INVENTORY_MAX_IDS,
-			agentIds: identities(overview.agentIds),
-			statuses: identities(overview.statuses),
-			tags: overview.tags.filter((tag) => EVIDENCE_TAGS.includes(tag)),
-			totals: {
-				runs: tally(overview.totals.runs),
-				receipts: tally(overview.totals.receipts),
-				toolCalls: tally(overview.totals.toolCalls),
-				toolErrors: tally(overview.totals.toolErrors),
-				blockedToolCalls: tally(overview.totals.blockedToolCalls),
-				protectedArtifacts: tally(overview.totals.protectedArtifacts),
-				tokens: tally(overview.totals.tokens),
-				costUsd: amount(overview.totals.costUsd),
-				wallTimeMs: tally(overview.totals.wallTimeMs),
-			},
-			redactionCount: tally(overview.redactionCount),
-			trust: { verdict, runsCovered, historical },
-		});
-	}
-	return {
-		version: 1,
-		generatedAt: new Date(now()).toISOString(),
-		artifacts,
-		truncated: all.length > window.length,
-	};
-}
+import { evidenceInventorySnapshot } from "../domains/evidence/inventory.js";
 
 /**
  * `clio-coder evidence inventory --json`, and nothing else.

package/src/cli/index.ts

@@ -56,6 +56,7 @@ Usage:
   clio-coder context wiki [--update] [--status] [--depth auto|simple|medium|detailed] [--target <id>] [--model <id>]
   clio-coder context reset [--all] [--yes]  clear accumulated project context artifacts
   clio-coder context index [--json]  build the codewiki index without model calls
+  clio-coder context map [--out <path>] [--json]  write an archify architecture seed from the codewiki index
   clio-coder context replay --sessions <path>...  compare working-set policies over Clio ledgers
   clio-coder context working-set --session <id|path>  inspect one session's working-set state
   clio-coder uninstall            remove all Clio Coder state; --remove-binary also unlinks the launcher
@@ -70,6 +71,7 @@ Usage:
   clio-coder extensions           install, list, enable, disable, or remove extension packages
   clio-coder skills               list, inspect, validate, or install skills
   clio-coder library              list, search, add, or sync agents, prompts, fleets, and skills from catalogs
+  clio-coder tasks                list, add, hand, finish, or drop project operator tasks
   clio-coder verifiers            discover, inspect, author, validate, edit, or dry-run project checks
   clio-coder tools list|status|install|remove <id>  pinned external programs Clio can drive
   clio-coder interop inspect --json  detected external coding agents and how far each one is wired
@@ -258,6 +260,7 @@ const COMMAND_HANDLERS = new Map<string, CommandHandler>([
 	["fleet", async (subArgs) => (await import("./fleet.js")).runFleetCommand(subArgs)],
 	["skills", async (subArgs) => (await import("./skills.js")).runSkillsCommand(subArgs)],
 	["library", async (subArgs) => (await import("./library.js")).runLibraryCommand(subArgs)],
+	["tasks", async (subArgs) => (await import("./tasks.js")).runTasksCommand(subArgs)],
 	["verifiers", async (subArgs) => (await import("./verifiers.js")).runVerifiersCommand(subArgs)],
 	["docs", async (subArgs) => (await import("./docs.js")).runDocsCommand(subArgs)],
 	["share", async (subArgs) => (await import("./share.js")).runShareCommand(subArgs)],