harnery 0.5.0 → 0.6.0

package/dist/lib/decision/index.js

@@ -0,0 +1,523 @@
+/**
+ * Decision docket: a persistent queue of decisions an agent would otherwise
+ * route to a human, plus the lifecycle that carries each one from filing to a
+ * reviewed, graduated resolution.
+ *
+ * State layout (mirrors councils):
+ *   - `.harnery/decisions/<id>.json`      — one manifest per decision
+ *   - `.harnery/decisions/<id>/`          — long-form bodies (brief, options,
+ *                                            evidence write-up) as markdown
+ *   - `.harnery/decisions/archive/`       — graduated / terminal decisions move here
+ *
+ * This module is the engine only. It stores `tier` (0/1/2) and `stakes` as
+ * opaque typed fields; what those *mean* — which decisions belong to which
+ * tier — is host policy, applied by the filing agent, never encoded here. That
+ * keeps the docket generic across host projects.
+ *
+ * Every function takes `coordRoot` explicitly (the council pattern) so the
+ * state machine is trivially testable against a tmpdir. The command layer
+ * resolves the root once via `monorepoRoot()` and threads it down.
+ *
+ * Concurrency: one file per decision (no shared index to contend on) + atomic
+ * temp→rename writes. `claim` is last-writer-wins — deliberating the same
+ * decision twice wastes tokens, not correctness.
+ */
+import { randomBytes } from "node:crypto";
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { dirname, join } from "node:path";
+export const DECISION_SCHEMA_VERSION = 1;
+/** Tier of human-involvement. Meaning is host policy; the engine only stores it. */
+export const DECISION_TIERS = [0, 1, 2];
+export const DECISION_STAKES = ["small", "medium", "high"];
+export const DECISION_STATUSES = [
+    "filed",
+    "triaged",
+    "deliberating",
+    "resolved",
+    "enacted",
+    "reviewed",
+    "archived",
+    "superseded",
+    "wontfix",
+];
+export const REVIEW_VERDICTS = [
+    "ratified",
+    "overridden",
+    "wrong-tier-high",
+    "wrong-tier-low",
+];
+export const TERMINAL_STATUSES = ["archived", "superseded", "wontfix"];
+/**
+ * Legal status transitions. `superseded` is reachable from any non-terminal
+ * state (a decision can be obsoleted at any point); `wontfix` closes an
+ * un-deliberated decision. `deliberating → triaged` allows the sweeper to
+ * re-triage a decision's tier on first touch (the self-triage safeguard).
+ */
+export const LEGAL_TRANSITIONS = {
+    filed: ["triaged", "deliberating", "resolved", "superseded", "wontfix"],
+    triaged: ["deliberating", "resolved", "superseded", "wontfix"],
+    deliberating: ["triaged", "resolved", "superseded", "wontfix"],
+    resolved: ["enacted", "reviewed", "superseded"],
+    enacted: ["reviewed", "superseded"],
+    reviewed: ["archived", "superseded"],
+    archived: [],
+    superseded: [],
+    wontfix: [],
+};
+// ─── Type guards ────────────────────────────────────────────────────────────
+export function isTier(n) {
+    return DECISION_TIERS.includes(n);
+}
+export function isStakes(s) {
+    return typeof s === "string" && DECISION_STAKES.includes(s);
+}
+export function isStatus(s) {
+    return typeof s === "string" && DECISION_STATUSES.includes(s);
+}
+export function isVerdict(v) {
+    return typeof v === "string" && REVIEW_VERDICTS.includes(v);
+}
+export function isTerminal(status) {
+    return TERMINAL_STATUSES.includes(status);
+}
+export function canTransition(from, to) {
+    return (LEGAL_TRANSITIONS[from] ?? []).includes(to);
+}
+// ─── Paths ──────────────────────────────────────────────────────────────────
+export function decisionsDir(coordRoot) {
+    return join(coordRoot, ".harnery", "decisions");
+}
+export function archiveDir(coordRoot) {
+    return join(decisionsDir(coordRoot), "archive");
+}
+export function manifestPath(coordRoot, id) {
+    return join(decisionsDir(coordRoot), `${id}.json`);
+}
+export function archivedManifestPath(coordRoot, id) {
+    return join(archiveDir(coordRoot), `${id}.json`);
+}
+export function decisionBodyDir(coordRoot, id) {
+    return join(decisionsDir(coordRoot), id);
+}
+// ─── Low-level IO ─────────────────────────────────────────────────────────────
+function nowIso() {
+    return new Date().toISOString();
+}
+function atomicWriteText(path, content) {
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp.${process.pid}`;
+    writeFileSync(tmp, content, "utf8");
+    renameSync(tmp, path);
+}
+/**
+ * Kebab-case slug from question text: first 5 words, lowercased,
+ * non-alphanumerics stripped. Local (not imported from council) so the module
+ * stays standalone.
+ */
+export function deriveSlug(question) {
+    const cleaned = question
+        .toLowerCase()
+        .replace(/[^a-z0-9\s-]+/g, " ")
+        .split(/\s+/)
+        .filter(Boolean)
+        .slice(0, 5)
+        .join("-")
+        .replace(/-+/g, "-")
+        .replace(/^-|-$/g, "");
+    return cleaned || "decision";
+}
+/**
+ * Build a decision_id: `<slug>-<YYYY-MM-DD>-<4hex>`. The hex suffix is
+ * crypto-random (not a hash of the question) so two decisions sharing a
+ * slug + date don't collide.
+ */
+export function buildDecisionId(question, now = new Date()) {
+    const slug = deriveSlug(question);
+    const date = now.toISOString().slice(0, 10);
+    const hash = randomBytes(2).toString("hex");
+    return `${slug}-${date}-${hash}`;
+}
+/**
+ * Read a manifest by id, checking the active dir then the archive. Returns null
+ * if absent or unparseable. Throws on an unsupported schema_version (fail loud
+ * on a real-but-incompatible manifest, the way councils do).
+ */
+export function readManifest(coordRoot, id) {
+    for (const p of [manifestPath(coordRoot, id), archivedManifestPath(coordRoot, id)]) {
+        if (!existsSync(p))
+            continue;
+        const parsed = JSON.parse(readFileSync(p, "utf8"));
+        if (parsed.schema_version !== DECISION_SCHEMA_VERSION) {
+            throw new Error(`decision ${id}: unsupported schema_version=${parsed.schema_version} (expected ${DECISION_SCHEMA_VERSION})`);
+        }
+        return parsed;
+    }
+    return null;
+}
+/** Locate whichever manifest path (active or archive) currently holds this id. */
+function resolveManifestPath(coordRoot, id) {
+    const active = manifestPath(coordRoot, id);
+    if (existsSync(active))
+        return active;
+    const archived = archivedManifestPath(coordRoot, id);
+    if (existsSync(archived))
+        return archived;
+    return null;
+}
+export function writeManifest(coordRoot, manifest) {
+    const p = resolveManifestPath(coordRoot, manifest.decision_id) ??
+        manifestPath(coordRoot, manifest.decision_id);
+    atomicWriteText(p, `${JSON.stringify(manifest, null, 2)}\n`);
+}
+export function fileDecision(coordRoot, input) {
+    if (!input.question?.trim())
+        return { ok: false, reason: "question is empty" };
+    if (!isTier(input.tier))
+        return { ok: false, reason: `invalid tier ${input.tier} (0 | 1 | 2)` };
+    if (!isStakes(input.stakes)) {
+        return {
+            ok: false,
+            reason: `invalid stakes "${input.stakes}" (${DECISION_STAKES.join(" | ")})`,
+        };
+    }
+    const now = input.now ?? new Date();
+    const id = buildDecisionId(input.question, now);
+    const ts = now.toISOString();
+    const manifest = {
+        schema_version: DECISION_SCHEMA_VERSION,
+        decision_id: id,
+        status: "filed",
+        tier: input.tier,
+        stakes: input.stakes,
+        question: input.question.trim(),
+        context: input.context?.trim() || undefined,
+        default_taken: input.defaultTaken?.trim() || null,
+        filed_by: input.filedBy,
+        filed_by_id: input.filedById,
+        filed_at: ts,
+        claimed_by: null,
+        council_id: null,
+        resolution: null,
+        review: null,
+        graduated_to: null,
+        superseded_by: null,
+        wontfix_reason: null,
+        updated_at: ts,
+    };
+    atomicWriteText(manifestPath(coordRoot, id), `${JSON.stringify(manifest, null, 2)}\n`);
+    if (input.brief?.trim()) {
+        atomicWriteText(join(decisionBodyDir(coordRoot, id), "brief.md"), `${input.brief.trim()}\n`);
+    }
+    return { ok: true, manifest };
+}
+// ─── Transitions ───────────────────────────────────────────────────────────────
+/**
+ * Apply a status change with legality + terminality checks, stamp updated_at,
+ * merge extra field patches, and persist. The single mutation chokepoint.
+ */
+function transition(coordRoot, id, to, patch = {}) {
+    const manifest = readManifest(coordRoot, id);
+    if (!manifest)
+        return { ok: false, reason: `no decision "${id}"` };
+    if (isTerminal(manifest.status) && manifest.status !== to) {
+        return { ok: false, reason: `decision is ${manifest.status} (terminal, read-only)` };
+    }
+    if (manifest.status !== to && !canTransition(manifest.status, to)) {
+        return {
+            ok: false,
+            reason: `illegal transition ${manifest.status} → ${to} (legal: ${(LEGAL_TRANSITIONS[manifest.status] ?? []).join(", ") || "none"})`,
+        };
+    }
+    const updated = {
+        ...manifest,
+        ...patch,
+        status: to,
+        updated_at: nowIso(),
+    };
+    writeManifest(coordRoot, updated);
+    return { ok: true, manifest: updated };
+}
+export function triageDecision(coordRoot, id, opts) {
+    if (opts.tier !== undefined && !isTier(opts.tier)) {
+        return { ok: false, reason: `invalid tier ${opts.tier} (0 | 1 | 2)` };
+    }
+    if (opts.stakes !== undefined && !isStakes(opts.stakes)) {
+        return {
+            ok: false,
+            reason: `invalid stakes "${opts.stakes}" (${DECISION_STAKES.join(" | ")})`,
+        };
+    }
+    const patch = {};
+    if (opts.tier !== undefined)
+        patch.tier = opts.tier;
+    if (opts.stakes !== undefined)
+        patch.stakes = opts.stakes;
+    return transition(coordRoot, id, "triaged", patch);
+}
+export function claimDecision(coordRoot, id, owner) {
+    if (!owner?.trim())
+        return { ok: false, reason: "claim owner is empty" };
+    return transition(coordRoot, id, "deliberating", { claimed_by: owner.trim() });
+}
+export function escalateToCouncil(coordRoot, id, councilId) {
+    if (!councilId?.trim())
+        return { ok: false, reason: "council id is empty" };
+    return transition(coordRoot, id, "deliberating", { council_id: councilId.trim() });
+}
+/**
+ * Resolve a decision. Evidence is required (≥1 citation): a resolution with no
+ * cited evidence is structurally incomplete and bounced here — the same guard
+ * the sweeper enforces.
+ */
+export function resolveDecision(coordRoot, id, resolution) {
+    if (!resolution.recommendation?.trim()) {
+        return { ok: false, reason: "resolution requires a recommendation" };
+    }
+    const evidence = (resolution.evidence ?? []).map((e) => e.trim()).filter(Boolean);
+    if (evidence.length === 0) {
+        return {
+            ok: false,
+            reason: "resolution requires ≥1 evidence citation (queries run, files read, costs computed) — an evidence-free resolution is bounced",
+        };
+    }
+    if (!resolution.resolved_by?.trim()) {
+        return { ok: false, reason: "resolution requires resolved_by" };
+    }
+    const full = {
+        recommendation: resolution.recommendation.trim(),
+        confidence: resolution.confidence?.trim() || undefined,
+        reversal_cost: resolution.reversal_cost?.trim() || undefined,
+        wrong_if: resolution.wrong_if?.trim() || undefined,
+        revisit_when: resolution.revisit_when?.trim() || undefined,
+        evidence,
+        resolved_by: resolution.resolved_by.trim(),
+        resolved_at: resolution.resolved_at ?? nowIso(),
+    };
+    return transition(coordRoot, id, "resolved", { resolution: full });
+}
+export function enactDecision(coordRoot, id) {
+    return transition(coordRoot, id, "enacted");
+}
+export function reviewDecision(coordRoot, id, opts) {
+    if (!isVerdict(opts.verdict)) {
+        return {
+            ok: false,
+            reason: `invalid verdict "${opts.verdict}" (${REVIEW_VERDICTS.join(" | ")})`,
+        };
+    }
+    const review = {
+        verdict: opts.verdict,
+        note: opts.note?.trim() || undefined,
+        reviewed_at: nowIso(),
+    };
+    return transition(coordRoot, id, "reviewed", { review });
+}
+export function supersedeDecision(coordRoot, id, bySupersedingId) {
+    return transition(coordRoot, id, "superseded", {
+        superseded_by: bySupersedingId?.trim() || null,
+    });
+}
+export function wontfixDecision(coordRoot, id, reason) {
+    return transition(coordRoot, id, "wontfix", { wontfix_reason: reason?.trim() || null });
+}
+/**
+ * Archive a decision (terminal). Records where its output graduated, then moves
+ * manifest + body dir into `archive/`. Idempotent-ish: safe to re-run.
+ */
+export function archiveDecision(coordRoot, id, graduatedTo) {
+    const result = transition(coordRoot, id, "archived", {
+        graduated_to: graduatedTo?.trim() || null,
+    });
+    if (!result.ok)
+        return result;
+    const activeManifest = manifestPath(coordRoot, id);
+    const archivedManifest = archivedManifestPath(coordRoot, id);
+    const activeBody = decisionBodyDir(coordRoot, id);
+    const archivedBody = join(archiveDir(coordRoot), id);
+    mkdirSync(archiveDir(coordRoot), { recursive: true });
+    if (existsSync(activeManifest)) {
+        try {
+            renameSync(activeManifest, archivedManifest);
+        }
+        catch {
+            cpSync(activeManifest, archivedManifest);
+            rmSync(activeManifest, { force: true });
+        }
+    }
+    if (existsSync(activeBody)) {
+        if (existsSync(archivedBody)) {
+            rmSync(activeBody, { recursive: true, force: true });
+        }
+        else {
+            try {
+                renameSync(activeBody, archivedBody);
+            }
+            catch {
+                cpSync(activeBody, archivedBody, { recursive: true });
+                rmSync(activeBody, { recursive: true, force: true });
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Reopen an archived decision back to `reviewed` — the inverse of `archive`,
+ * and the one sanctioned way out of the (otherwise terminal) archived state.
+ * Since `archived` has no legal outgoing transition, this deliberately bypasses
+ * the `transition` guard, the same way `archive` does its file moves outside it.
+ * Moves the manifest + body dir back from `archive/` into the active dir and
+ * clears `graduated_to` (a re-archive sets it fresh). Only `archived` decisions
+ * reopen; `superseded`/`wontfix` stay terminal.
+ *
+ * Ordering is write-active-then-remove-archived so an interrupted call leaves
+ * the decision reopened (active copy wins in `readManifest`) rather than lost.
+ */
+export function reopenDecision(coordRoot, id) {
+    const manifest = readManifest(coordRoot, id);
+    if (!manifest)
+        return { ok: false, reason: `no decision "${id}"` };
+    if (manifest.status !== "archived") {
+        return {
+            ok: false,
+            reason: `only archived decisions can be reopened (this is ${manifest.status})`,
+        };
+    }
+    const archivedBody = join(archiveDir(coordRoot), id);
+    const activeBody = decisionBodyDir(coordRoot, id);
+    if (existsSync(archivedBody)) {
+        if (existsSync(activeBody)) {
+            rmSync(archivedBody, { recursive: true, force: true });
+        }
+        else {
+            try {
+                renameSync(archivedBody, activeBody);
+            }
+            catch {
+                cpSync(archivedBody, activeBody, { recursive: true });
+                rmSync(archivedBody, { recursive: true, force: true });
+            }
+        }
+    }
+    const reopened = {
+        ...manifest,
+        status: "reviewed",
+        graduated_to: null,
+        updated_at: nowIso(),
+    };
+    atomicWriteText(manifestPath(coordRoot, id), `${JSON.stringify(reopened, null, 2)}\n`);
+    const archived = archivedManifestPath(coordRoot, id);
+    if (existsSync(archived))
+        rmSync(archived, { force: true });
+    return { ok: true, manifest: reopened };
+}
+function scanManifests(dir) {
+    if (!existsSync(dir))
+        return [];
+    const out = [];
+    for (const f of readdirSync(dir)) {
+        if (!f.endsWith(".json"))
+            continue;
+        const p = join(dir, f);
+        try {
+            if (!statSync(p).isFile())
+                continue;
+            const parsed = JSON.parse(readFileSync(p, "utf8"));
+            if (parsed.schema_version !== DECISION_SCHEMA_VERSION)
+                continue;
+            out.push(parsed);
+        }
+        catch {
+            // skip unparseable manifest; one bad file never kills the scan
+        }
+    }
+    return out;
+}
+export function listDecisions(coordRoot, filter = {}) {
+    let rows = scanManifests(decisionsDir(coordRoot));
+    if (filter.includeArchived)
+        rows = rows.concat(scanManifests(archiveDir(coordRoot)));
+    if (filter.status)
+        rows = rows.filter((d) => d.status === filter.status);
+    if (filter.tier !== undefined)
+        rows = rows.filter((d) => d.tier === filter.tier);
+    if (filter.stakes)
+        rows = rows.filter((d) => d.stakes === filter.stakes);
+    if (filter.openOnly)
+        rows = rows.filter((d) => !isTerminal(d.status));
+    rows.sort((a, b) => (b.filed_at ?? "").localeCompare(a.filed_at ?? ""));
+    return rows;
+}
+export function showDecision(coordRoot, id) {
+    const manifest = readManifest(coordRoot, id);
+    if (!manifest)
+        return null;
+    const archived = !existsSync(manifestPath(coordRoot, id));
+    const bodyDir = archived ? join(archiveDir(coordRoot), id) : decisionBodyDir(coordRoot, id);
+    const bodies = [];
+    if (existsSync(bodyDir)) {
+        for (const f of readdirSync(bodyDir)) {
+            if (!f.endsWith(".md"))
+                continue;
+            try {
+                bodies.push({ name: f, content: readFileSync(join(bodyDir, f), "utf8") });
+            }
+            catch {
+                // skip unreadable body
+            }
+        }
+    }
+    return { manifest, bodies, archived };
+}
+/**
+ * Case-insensitive substring search over manifests + bodies. Deliberately
+ * dumb: precedent recall depends on the host's decision skill running this before
+ * filing, not on ranking sophistication. Includes the archive (precedent
+ * lives there).
+ */
+export function searchDecisions(coordRoot, query) {
+    const q = query.trim().toLowerCase();
+    if (!q)
+        return [];
+    const all = listDecisions(coordRoot, { includeArchived: true });
+    const hits = [];
+    for (const manifest of all) {
+        const fields = [
+            { where: "question", text: manifest.question ?? "" },
+            { where: "context", text: manifest.context ?? "" },
+            {
+                where: "resolution",
+                text: manifest.resolution
+                    ? `${manifest.resolution.recommendation} ${manifest.resolution.evidence.join(" ")}`
+                    : "",
+            },
+        ];
+        const bodyDir = existsSync(manifestPath(coordRoot, manifest.decision_id))
+            ? decisionBodyDir(coordRoot, manifest.decision_id)
+            : join(archiveDir(coordRoot), manifest.decision_id);
+        if (existsSync(bodyDir)) {
+            for (const f of readdirSync(bodyDir)) {
+                if (!f.endsWith(".md"))
+                    continue;
+                try {
+                    fields.push({ where: "body", text: readFileSync(join(bodyDir, f), "utf8") });
+                }
+                catch {
+                    // skip
+                }
+            }
+        }
+        for (const field of fields) {
+            const idx = field.text.toLowerCase().indexOf(q);
+            if (idx >= 0) {
+                const start = Math.max(0, idx - 40);
+                const snippet = field.text
+                    .slice(start, idx + q.length + 40)
+                    .replace(/\s+/g, " ")
+                    .trim();
+                hits.push({ manifest, snippet: `${start > 0 ? "…" : ""}${snippet}…`, where: field.where });
+                break;
+            }
+        }
+    }
+    return hits;
+}

package/dist/lib/docs-lint.d.ts

@@ -2,6 +2,7 @@ export declare function initDocsContext(opts: {
     repoRoot: string;
     submodules: readonly string[];
     extraExcludedPrefixes?: readonly string[];
+    docsRootAllowlist?: readonly string[];
 }): void;
 /**
  * Documentation linter. Enforces the docs directory-layout + naming contract.

package/dist/lib/docs-lint.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"docs-lint.d.ts","sourceRoot":"","sources":["../../src/lib/docs-lint.ts"],"names":[],"mappings":"AAYA,wBAAgB,eAAe,CAAC,IAAI,EAAE;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B,qBAAqB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3C,GAAG,IAAI,CAIP;AAaD;;;;;;GAMG;AAEH,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,SAAS,CAAC;AAE3C,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,QAAQ,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,QAAQ;IACvB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAuVD,wBAAsB,OAAO,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAoBlE"}
+{"version":3,"file":"docs-lint.d.ts","sourceRoot":"","sources":["../../src/lib/docs-lint.ts"],"names":[],"mappings":"AAaA,wBAAgB,eAAe,CAAC,IAAI,EAAE;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B,qBAAqB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC,GAAG,IAAI,CAKP;AAaD;;;;;;GAMG;AAEH,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,SAAS,CAAC;AAE3C,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,QAAQ,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,QAAQ;IACvB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AA+XD,wBAAsB,OAAO,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAqBlE"}

package/dist/lib/docs-lint.js

@@ -8,10 +8,12 @@ import { sh } from "./exec.js";
 let REPO_ROOT = "";
 let SUBMODULES = [];
 let EXTRA_EXCLUDED_PREFIXES = [];
+let DOCS_ROOT_ALLOWLIST = [];
 export function initDocsContext(opts) {
     REPO_ROOT = opts.repoRoot;
     SUBMODULES = opts.submodules;
     EXTRA_EXCLUDED_PREFIXES = opts.extraExcludedPrefixes ?? [];
+    DOCS_ROOT_ALLOWLIST = opts.docsRootAllowlist ?? [];
 }
 function submodulePath(name) {
     return __resolveForDocs(REPO_ROOT, name);
@@ -196,6 +198,52 @@ function checkRootAllowlist(repoName, repoPath) {
     }
     return violations;
 }
+/**
+ * The host project's `docs/` root is an entry tier: only allowlisted files may
+ * sit loose there; topic docs belong in `docs/<topic>/` subdirs. Config-gated —
+ * a no-op unless the host supplies `docsRootAllowlist`. Parent-repo only:
+ * submodule `docs/` roots have their own entry tiers, not this one.
+ */
+function checkDocsRootAllowlist(repoName, repoPath) {
+    const violations = [];
+    if (DOCS_ROOT_ALLOWLIST.length === 0)
+        return violations; // opt-in
+    if (repoName !== "(root)")
+        return violations; // parent repo only
+    const allow = new Set(DOCS_ROOT_ALLOWLIST);
+    const docsDir = join(repoPath, "docs");
+    let entries;
+    try {
+        entries = readdirSync(docsDir);
+    }
+    catch {
+        return violations; // no docs/ dir — nothing to check
+    }
+    for (const entry of entries) {
+        // Subdirs are the intended home for topic docs; only loose files matter.
+        let isFile;
+        try {
+            isFile = statSync(join(docsDir, entry)).isFile();
+        }
+        catch {
+            continue;
+        }
+        if (!isFile)
+            continue;
+        if (!(entry.endsWith(".md") || entry.endsWith(".json")))
+            continue;
+        if (allow.has(entry))
+            continue;
+        violations.push({
+            severity: "error",
+            repo: repoName,
+            path: join("docs", entry),
+            rule: "docs-root-file",
+            message: `${entry} is not allowed loose at docs/ root — move it into a docs/<topic>/ subdir (or add it to context.docsRootAllowlist if it's a genuine entry-tier doc)`,
+        });
+    }
+    return violations;
+}
 /** No SCREAMING_SNAKE_CASE filenames anywhere */
 function checkNamingConvention(repoName, _repoPath, files) {
     const violations = [];
@@ -371,6 +419,7 @@ export async function runLint(opts) {
     for (const { name, path, isSubmodule } of repos) {
         violations.push(...checkEntryTier(name, path, isSubmodule));
         violations.push(...checkRootAllowlist(name, path));
+        violations.push(...checkDocsRootAllowlist(name, path));
         const files = await findMarkdownFiles(path);
         violations.push(...checkNamingConvention(name, path, files));
         violations.push(...checkDatedDirs(name, path, files));

package/dist/lib/tunnel/gate.js

@@ -97,5 +97,5 @@ const server = Bun.serve({
 // This worker runs detached via `bun run gate.ts`, outside the CLI command
 // framework, so no AsyncLocalStorage context is available. stdout/stderr is
 // captured into .cache/tunnel/gate.log by the spawning command.
-console.log(`bp-tunnel-gate :${server.port} -> ${UPSTREAM_HTTP} (Host: ${VHOST})`); // lint-ok-emission: detached worker, see file note above
+console.log(`harn-tunnel-gate :${server.port} -> ${UPSTREAM_HTTP} (Host: ${VHOST})`); // lint-ok-emission: detached worker, see file note above
 console.log(`allow: ${[...ALLOW].join(", ") || "(empty, denies all)"}`); // lint-ok-emission: detached worker, see file note above

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "harnery",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Multi-agent coordination + harness adapters + portable CLI utilities for Claude Code / Cursor / Codex.",
   "license": "MIT",
   "author": "Ryan Kelly",
@@ -128,6 +128,8 @@
     "prepublishOnly": "npm run clean && npm run build",
     "typecheck": "bun x tsc --noEmit",
     "lint": "bun x @biomejs/biome check src",
+    "check:portability": "bun run scripts/check-portability.ts",
+    "lint:fix": "bun x @biomejs/biome check --write src",
     "format": "bun x @biomejs/biome format --write src",
     "test": "bun test src tests",
     "test:web": "cd web && bun install && bun test",

package/src/commander.ts

@@ -27,6 +27,7 @@ import { registerCompletionCommand } from "./commands/completion.ts";
 import { registerConfigGetCommand } from "./commands/config-get.ts";
 import { registerContextCommand } from "./commands/context.ts";
 import { registerCookiesCommand } from "./commands/cookies.ts";
+import { registerDecisionCommand } from "./commands/decision.ts";
 import { registerDeinitCommand } from "./commands/deinit.ts";
 import { registerDocsCommand } from "./commands/docs.ts";
 import { registerDoctorCommand } from "./commands/doctor.ts";
@@ -129,6 +130,16 @@ export interface HarneryProgramContext {
    * exclusions (`.claude/`, `.harnery/`, `.codex/`, `.cursor/`).
    */
   extraDocsExcludedPrefixes?: readonly string[];
+  /**
+   * Filenames permitted at the host project's `docs/` root (parent repo only).
+   * When set, `harn docs lint` flags any other `.md`/`.json` file sitting
+   * loose at `docs/` root (rule `docs-root-file`) — topic docs belong in
+   * `docs/<topic>/` subdirs. Names are matched exactly (basename). When
+   * omitted or empty, the rule is a no-op, so standalone `harn` and consumers
+   * that don't opt in are unaffected. Submodule `docs/` roots are never
+   * checked (their entry tiers differ from the parent's).
+   */
+  docsRootAllowlist?: readonly string[];
   /**
    * Default Host header for `tunnel up` when `--vhost` is omitted: a literal
    * host, or a resolver evaluated at start time (e.g. read a dev stack's
@@ -225,6 +236,7 @@ export function createHarneryProgram(opts: HarneryContextOpts = {}): Command {
   registerCompletionCommand(program, emit, opts.context);
   registerContextCommand(program, emit, opts.context);
   registerScratchCommand(program, emit);
+  registerDecisionCommand(program, emit);
   registerTunnelCommand(program, emit, opts.context);
   registerDocsCommand(program, emit, opts.context);
   registerAgentsCommand(program, emit);