harnery 0.34.1 → 0.35.0

package/dist/lib/browser/standalone-html.js

@@ -0,0 +1,284 @@
+// Self-contained HTML snapshots for `harn browse` trio mode.
+//
+// `page.content()` serializes the DOM but not the resources it points at, and
+// framework pages reference those with root-absolute paths (`/_next/static/…`).
+// Written to a file and reopened from anywhere else — the files origin, another
+// host, `file://` — every one of those paths resolves against the wrong root and
+// 404s, so the snapshot renders as unstyled black-on-white text with broken
+// images. That is what an operator sees when they preview an artifact's `.html`.
+//
+// This rewrite makes the saved document stand on its own:
+//   - stylesheets are fetched and inlined as <style>
+//   - fonts, images, and icons are inlined as data: URIs under a byte budget
+//   - anything left over (too large, cross-origin, unreachable) is rewritten to
+//     an absolute URL on the captured origin rather than left root-relative
+//   - <script> and preload/prefetch hints are dropped: none of them can work in
+//     a snapshot, and a dead script tag only invites a hydration attempt
+//
+// The live page is untouched — everything happens on a clone of the document.
+/** Byte budget for one inlined sub-resource. Larger ones stay as absolute URLs. */
+export const DEFAULT_MAX_RESOURCE_BYTES = 512 * 1024;
+/** Byte budget for all inlined sub-resources in one snapshot. */
+export const DEFAULT_MAX_TOTAL_RESOURCE_BYTES = 8 * 1024 * 1024;
+export function buildStandaloneHtmlScript() {
+    return async ({ maxResourceBytes, maxTotalResourceBytes }) => {
+        const SKIP = /^(?:data:|blob:|javascript:|mailto:|tel:|sms:|about:|#)/i;
+        const base = document.baseURI;
+        let inlinedBytes = 0;
+        let resourcesInlined = 0;
+        let resourcesLinked = 0;
+        let stylesheetsInlined = 0;
+        let stylesheetsLinked = 0;
+        const absolute = (url, from) => {
+            try {
+                return new URL(url, from).href;
+            }
+            catch {
+                return null;
+            }
+        };
+        const dataUriCache = new Map();
+        /** Fetch a resource as a data: URI, or null when it is unreachable or over budget. */
+        const toDataUri = async (url) => {
+            const cached = dataUriCache.get(url);
+            if (cached !== undefined)
+                return cached;
+            let result = null;
+            try {
+                const res = await fetch(url, { credentials: "include" });
+                if (res.ok) {
+                    const buf = await res.arrayBuffer();
+                    const fits = buf.byteLength <= maxResourceBytes &&
+                        inlinedBytes + buf.byteLength <= maxTotalResourceBytes;
+                    if (fits) {
+                        const bytes = new Uint8Array(buf);
+                        let binary = "";
+                        const chunk = 0x8000;
+                        for (let i = 0; i < bytes.length; i += chunk) {
+                            binary += String.fromCharCode(...bytes.subarray(i, i + chunk));
+                        }
+                        const type = (res.headers.get("content-type") ?? "").split(";")[0]?.trim();
+                        result = `data:${type || "application/octet-stream"};base64,${btoa(binary)}`;
+                        inlinedBytes += buf.byteLength;
+                    }
+                }
+            }
+            catch {
+                result = null;
+            }
+            dataUriCache.set(url, result);
+            return result;
+        };
+        /** Resolve one reference: data: URI when it fits, absolute URL otherwise. */
+        const resolveRef = async (raw, from, inline) => {
+            const trimmed = raw.trim();
+            if (!trimmed || SKIP.test(trimmed))
+                return null;
+            const url = absolute(trimmed, from);
+            if (!url)
+                return null;
+            if (!inline)
+                return url;
+            const dataUri = await toDataUri(url);
+            if (dataUri) {
+                resourcesInlined += 1;
+                return dataUri;
+            }
+            resourcesLinked += 1;
+            return url;
+        };
+        /** Rewrite url() and @import references inside a stylesheet against its own URL. */
+        const rewriteCss = async (css, from) => {
+            const urlRef = /url\(\s*(['"]?)([^'")]*)\1\s*\)/g;
+            const importRef = /@import\s+(['"])([^'"]+)\1/g;
+            const replacements = new Map();
+            const collect = async (pattern, inline) => {
+                pattern.lastIndex = 0;
+                const seen = [];
+                for (let m = pattern.exec(css); m; m = pattern.exec(css)) {
+                    const raw = m[2];
+                    if (raw !== undefined && !replacements.has(raw))
+                        seen.push(raw);
+                }
+                for (const raw of seen) {
+                    const resolved = await resolveRef(raw, from, inline);
+                    if (resolved)
+                        replacements.set(raw, resolved);
+                }
+            };
+            await collect(urlRef, true);
+            await collect(importRef, false);
+            return css
+                .replace(urlRef, (full, _q, raw) => {
+                const next = replacements.get(raw);
+                return next ? `url("${next}")` : full;
+            })
+                .replace(importRef, (full, _q, raw) => {
+                const next = replacements.get(raw);
+                return next ? `@import "${next}"` : full;
+            });
+        };
+        const doc = document.cloneNode(true);
+        // Nothing executable survives a snapshot; leaving these in only produces
+        // console noise and a doomed hydration pass on reopen.
+        for (const node of Array.from(doc.querySelectorAll("script, base")))
+            node.remove();
+        const deadHints = 'link[rel~="preload"],link[rel~="modulepreload"],link[rel~="prefetch"]';
+        for (const node of Array.from(doc.querySelectorAll(deadHints)))
+            node.remove();
+        // Stylesheets: fetch → inline. Falls back to the CSSOM (which covers rules a
+        // same-origin sheet already parsed) and finally to an absolute <link>.
+        for (const link of Array.from(doc.querySelectorAll('link[rel~="stylesheet"]'))) {
+            const href = link.getAttribute("href");
+            const url = href ? absolute(href, base) : null;
+            if (!url) {
+                link.remove();
+                continue;
+            }
+            let css = null;
+            try {
+                const res = await fetch(url, { credentials: "include" });
+                if (res.ok)
+                    css = await res.text();
+            }
+            catch {
+                css = null;
+            }
+            if (css === null) {
+                for (const sheet of Array.from(document.styleSheets)) {
+                    if (sheet.href !== url)
+                        continue;
+                    try {
+                        css = Array.from(sheet.cssRules)
+                            .map((rule) => rule.cssText)
+                            .join("\n");
+                    }
+                    catch {
+                        css = null;
+                    }
+                    break;
+                }
+            }
+            if (css === null) {
+                link.setAttribute("href", url);
+                stylesheetsLinked += 1;
+                continue;
+            }
+            const style = doc.createElement("style");
+            style.setAttribute("data-harnery-inlined-from", url);
+            const media = link.getAttribute("media");
+            if (media)
+                style.setAttribute("media", media);
+            style.textContent = await rewriteCss(css, url);
+            link.replaceWith(style);
+            stylesheetsInlined += 1;
+        }
+        // Inline <style> blocks carry their own relative refs (framework @font-face
+        // rules in particular), so they need the same treatment.
+        for (const style of Array.from(doc.querySelectorAll("style"))) {
+            if (style.hasAttribute("data-harnery-inlined-from"))
+                continue;
+            const css = style.textContent;
+            if (css)
+                style.textContent = await rewriteCss(css, base);
+        }
+        // Stylesheets adopted via CSSOM never appear in the DOM and would be lost.
+        const adopted = document
+            .adoptedStyleSheets;
+        if (adopted?.length) {
+            const parts = [];
+            for (const sheet of adopted) {
+                try {
+                    parts.push(Array.from(sheet.cssRules)
+                        .map((rule) => rule.cssText)
+                        .join("\n"));
+                }
+                catch {
+                    // Constructed sheet with unreadable rules; nothing to recover.
+                }
+            }
+            if (parts.length) {
+                const style = doc.createElement("style");
+                style.setAttribute("data-harnery-adopted", "");
+                style.textContent = await rewriteCss(parts.join("\n"), base);
+                doc.head?.appendChild(style);
+            }
+        }
+        // Element references. Media and icons are worth inlining; navigation targets
+        // only need to stop pointing at the wrong root.
+        const inlineAttrs = [
+            ["img", "src"],
+            ["source", "src"],
+            ["video", "src"],
+            ["video", "poster"],
+            ["audio", "src"],
+            ["track", "src"],
+            ["input", "src"],
+            ["object", "data"],
+            ['link[rel~="icon"]', "href"],
+            ['link[rel~="apple-touch-icon"]', "href"],
+            ["image", "href"],
+            ["use", "href"],
+        ];
+        const absoluteAttrs = [
+            ["a", "href"],
+            ["area", "href"],
+            ["form", "action"],
+            ["iframe", "src"],
+            ["embed", "src"],
+            ["link", "href"],
+        ];
+        const applyAttrs = async (specs, inline) => {
+            for (const [selector, attr] of specs) {
+                for (const el of Array.from(doc.querySelectorAll(selector))) {
+                    const raw = el.getAttribute(attr);
+                    if (!raw)
+                        continue;
+                    const next = await resolveRef(raw, base, inline);
+                    if (next)
+                        el.setAttribute(attr, next);
+                }
+            }
+        };
+        await applyAttrs(inlineAttrs, true);
+        await applyAttrs(absoluteAttrs, false);
+        // srcset is a comma-separated list of `url descriptor` pairs.
+        for (const el of Array.from(doc.querySelectorAll("img[srcset], source[srcset]"))) {
+            const raw = el.getAttribute("srcset");
+            if (!raw)
+                continue;
+            const rewritten = [];
+            for (const candidate of raw.split(",")) {
+                const parts = candidate.trim().split(/\s+/);
+                const url = parts.shift();
+                if (!url)
+                    continue;
+                const next = (await resolveRef(url, base, true)) ?? url;
+                rewritten.push([next, ...parts].join(" "));
+            }
+            if (rewritten.length)
+                el.setAttribute("srcset", rewritten.join(", "));
+        }
+        // Inline style attributes can carry background-image url().
+        for (const el of Array.from(doc.querySelectorAll("[style]"))) {
+            const raw = el.getAttribute("style");
+            if (!raw?.includes("url("))
+                continue;
+            el.setAttribute("style", await rewriteCss(raw, base));
+        }
+        const provenance = doc.createElement("meta");
+        provenance.setAttribute("name", "harnery:snapshot-source");
+        provenance.setAttribute("content", location.href);
+        doc.head?.prepend(provenance);
+        const doctype = document.doctype ? `<!DOCTYPE ${document.doctype.name}>` : "<!DOCTYPE html>";
+        return {
+            html: `${doctype}\n${doc.documentElement.outerHTML}\n`,
+            source: location.href,
+            stylesheetsInlined,
+            stylesheetsLinked,
+            resourcesInlined,
+            resourcesLinked,
+            inlinedBytes,
+        };
+    };
+}

package/dist/lib/instructions/apply.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"apply.d.ts","sourceRoot":"","sources":["../../../src/lib/instructions/apply.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAsDH,sFAAsF;AACtF,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAYlE;AAkBD,UAAU,SAAS;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,WAAW,CA+GnF;AAED,UAAU,UAAU;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,WAAW,CAkFrF;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC;IACpC,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACzC,WAAW,CAkDb"}
+{"version":3,"file":"apply.d.ts","sourceRoot":"","sources":["../../../src/lib/instructions/apply.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAsDH,sFAAsF;AACtF,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAYlE;AAmBD,UAAU,SAAS;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,WAAW,CA+GnF;AAED,UAAU,UAAU;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,WAAW,CAkFrF;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC;IACpC,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACzC,WAAW,CAkDb"}

package/dist/lib/instructions/apply.js

@@ -70,6 +70,7 @@ function blockSkills(projectRoot, adapter) {
         decide: supported && !exclude.has("harn-decide"),
         council: supported && !exclude.has("harn-council"),
         end: supported && !exclude.has("harn-end"),
+        team: supported && !exclude.has("harn-team"),
     };
 }
 /**

package/dist/lib/instructions/templates.d.ts

@@ -29,6 +29,8 @@ export interface BlockSkills {
     council: boolean;
     /** the `harn-end` skill file is present */
     end: boolean;
+    /** the `harn-team` skill file is present */
+    team: boolean;
 }
 /**
  * The always-on orientation spliced into `AGENTS.md`. Target ≤ 80 rendered

package/dist/lib/instructions/templates.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../../../src/lib/instructions/templates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,+DAA+D;AAC/D,eAAO,MAAM,mBAAmB,iBAAiB,CAAC;AAClD,sEAAsE;AACtE,eAAO,MAAM,aAAa,WAAW,CAAC;AACtC;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,kBAAkB,CAAC;AAEpD,2EAA2E;AAC3E,MAAM,WAAW,WAAW;IAC1B,8CAA8C;IAC9C,MAAM,EAAE,OAAO,CAAC;IAChB,+CAA+C;IAC/C,OAAO,EAAE,OAAO,CAAC;IACjB,2CAA2C;IAC3C,GAAG,EAAE,OAAO,CAAC;CACd;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,MAAM,EACf,MAAM,GAAE,WAAwD,GAC/D,MAAM,CA+FR;AAID,mFAAmF;AACnF,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC;CACrC;AAsND,eAAO,MAAM,MAAM,EAAE,aAAa,EAqCjC,CAAC"}
+{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../../../src/lib/instructions/templates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,+DAA+D;AAC/D,eAAO,MAAM,mBAAmB,iBAAiB,CAAC;AAClD,sEAAsE;AACtE,eAAO,MAAM,aAAa,WAAW,CAAC;AACtC;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,kBAAkB,CAAC;AAEpD,2EAA2E;AAC3E,MAAM,WAAW,WAAW;IAC1B,8CAA8C;IAC9C,MAAM,EAAE,OAAO,CAAC;IAChB,+CAA+C;IAC/C,OAAO,EAAE,OAAO,CAAC;IACjB,2CAA2C;IAC3C,GAAG,EAAE,OAAO,CAAC;IACb,4CAA4C;IAC5C,IAAI,EAAE,OAAO,CAAC;CACf;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,MAAM,EACf,MAAM,GAAE,WAAoE,GAC3E,MAAM,CAqGR;AAID,mFAAmF;AACnF,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC;CACrC;AAmVD,eAAO,MAAM,MAAM,EAAE,aAAa,EAiDjC,CAAC"}

package/dist/lib/instructions/templates.js

@@ -35,12 +35,13 @@ export const HOST_ADDENDUM_REGION = "host-addendum";
  * excludes one via `skills.exclude` gets a CLI pointer instead of a dangling
  * reference to a skill it doesn't have.
  */
-export function renderInstructionsBlock(binName, skills = { decide: true, council: true, end: true }) {
+export function renderInstructionsBlock(binName, skills = { decide: true, council: true, end: true, team: true }) {
     const b = binName;
     const named = [
         skills.decide && "`harn-decide`",
         skills.council && "`harn-council`",
         skills.end && "`harn-end`",
+        skills.team && "`harn-team`",
     ].filter(Boolean);
     const deeper = named.length > 0
         ? `Procedures for the deeper flows live in the ${named.join(" and ")} skill${named.length > 1 ? "s" : ""}.`
@@ -54,6 +55,9 @@ export function renderInstructionsBlock(binName, skills = { decide: true, counci
     const endPointer = skills.end
         ? "When the whole session is genuinely finished, use the `harn-end` skill as the final workflow."
         : `When the whole session is genuinely finished, run \`${b} agents status --end-turn --end-session\` as the final tool action.`;
+    const teamPointer = skills.team
+        ? "The `harn-team` skill owns the tier choice, the governor artifacts, and the drive loop."
+        : `See \`${b} governor --help\` for the tier choice and the drive loop.`;
     // Render the journal categories from the canonical enum so this prose can
     // never drift from what `journal add` actually accepts (the "note, plan…" list
     // silently lagged the tool by two categories before this).
@@ -95,6 +99,7 @@ first when one pass will do, the second when the objective must outlive the
 attempt, and the third when a human would otherwise have to babysit the loop. A
 run that needs authorization parks durably instead of failing, so check
 \`${b} approval list\` when one appears to be waiting rather than stuck.
+${teamPointer}
 
 **Durable role handoff.** When you are replacing a prior session in the same
 named role, run \`${b} agents identity assume <name>\` before declaring your task.
@@ -103,9 +108,10 @@ live process still holds the name; never hand-edit Harnery's history, heartbeat,
 or derived identity cache.
 
 **Declare intent on shell commands.** Every command you run is captured to the
-coordination ledger. Lead a shell command with a \`# intent: <why>\` comment (or set
-the tool's description) so the recorded event carries a reason instead of
-\`(no intent)\`.
+coordination ledger (\`.harnery/ledgers/v3/\`). Lead a shell command with a
+\`# intent: <why>\` comment (or set the tool's description) so the recorded event
+carries a reason instead of \`(no intent)\`; the [tool-intent
+guide](https://harnery.com/guides/tool-intent/) owns the details.
 
 **Journal.** \`${b} journal add <category> "<text>"\` (category = ${journalCats})
 leaves breadcrumbs that survive context compaction;
@@ -336,6 +342,130 @@ explicitly identifies it. Use the web control or \`${b} agents end --instance-id
 <id>\` for that operator action; it records immediately for an idle session or
 durably queues the end for its current turn.`;
 }
+function teamBody(b) {
+    return `Harnery gives you three ways to put more than one agent on a job. They differ
+by how long the objective outlives a single execution, and picking the wrong one
+is the usual reason a team spins. This skill owns that choice, the files a
+governed team needs, and the drive loop.
+
+## Step 0: do not build a second team
+
+Run this before anything else, every time:
+
+\`\`\`bash
+${b} governor list
+\`\`\`
+
+If a goal already covers the objective, **you are done building** — drive the
+existing one (Step 3). A second team pointed at the same tree fights the first:
+both hold the same files and their frozen missions contradict each other. It is
+the most expensive mistake available here, and it looks like progress while you
+make it. Listings are tolerant: an unreadable record prints a warning row with
+its id, which is evidence the goal *exists* — inspect it before creating a
+replacement. Treat stale or suffixed experiment goals as shared runtime state;
+archiving them is an operator call, not yours.
+
+## Step 1: pick the tier
+
+Match the tier to how long the objective must survive, not to how big it feels.
+
+| Surface | Use when | Dies when |
+|---|---|---|
+| \`${b} run <script>\` | One bounded pass: deterministic JS stages fan out to headless subagents. | The pass ends. Nothing remembers it. |
+| \`${b} work create <title> <workflow>\` | The objective must outlive the attempt: retries, failures, review rounds. | You accept or cancel it. |
+| \`${b} governor create\` | A graph of interdependent work with distinct roles, where a human would otherwise babysit the loop. | You accept the root or it exhausts its bounds. |
+
+When unsure, start with \`${b} run\`: it is the only tier you can throw away for
+free, and iterating a script there before freezing it is how you avoid
+invalidating a durable work item later. And check the sizing first: a single
+agent often matches a team on a task that does not truly decompose — reliability
+is multiplicative across steps, and the metric that decides is cost per
+completed task, not agent count.
+
+## Step 2: build the governor team
+
+Four artifacts, kept in a managed workspace
+(\`${b} artifacts create <slug> --purpose "<why>"\`), then frozen:
+
+**team.json** maps specialist id to profile: \`instructions\` (the role's whole
+charter) plus optional \`adapter\`, \`effort\`, \`maxAttempts\`. Two role rules
+carry most of the value: **split producing evidence from judging it** (a
+verifier that runs gates, a separate reviewer that accepts or refuses — no agent
+grades its own homework), and **add a standing scope-auditor** that reports at
+each milestone whether the finish line moved, since no one else is positioned to
+notice a rising bar. Write each role's hard boundaries explicitly, in the
+negative: name every act that is somebody else's. Write every brief as a
+four-part contract — objective, output (the named artifact that proves it),
+tools, boundaries — and pass references, not pasted content. \`timeoutMs\` and
+\`maxTurns\` are workflow-script options, never specialist-profile keys; the
+create command rejects unsupported keys with the offending key and the allowed
+set.
+
+**mission.json** carries \`objective\`, \`acceptance\` (criteria), and
+\`max_milestones\`. Write acceptance so **refusing is a representable outcome**
+("X exists, or the blocker is stated with its citation") — a criterion an agent
+cannot satisfy by correctly refusing gets reissued forever. Every criterion
+names the artifact that satisfies it (a path, a passing command, a review
+record); a criterion satisfiable by prose will eventually be satisfied exactly
+that way.
+
+**replanning.json** freezes the planner policy: \`planner_specialist\`,
+\`auto_apply\`, \`max_replans\`, \`max_work_items_per_plan\`,
+\`max_total_work_items\`, a \`templates\` catalog, and \`review\` with
+\`reviewer_specialists\` and \`max_revision_rounds\`. Keep \`auto_apply: false\`
+and proof auto-acceptance off for anything that can touch public state.
+
+**Workflow templates** are the plain-JS scripts the planner may choose from;
+route product decisions to a decision-brief template, never an implement one.
+Authoring traps (frozen script hashes, the five-minute \`timeoutMs\` default,
+schema caps, child sandboxes) live in the
+[workflow-authoring guide](https://harnery.com/guides/workflow-authoring/).
+
+\`\`\`bash
+${b} governor create --id <goal-id> --title "<title>" \\
+  --team <ws>/team.json --mission <ws>/mission.json \\
+  --replanning <ws>/replanning.json --max-parallel-work 2 --json
+\`\`\`
+
+## Step 3: drive it
+
+\`${b} governor show <goal-id> --json\` — the \`projection\` object is the whole
+dashboard: read \`state\`, \`reason\`, and \`next_action\`, then do exactly that
+action. Useful fields: \`ready_work\` / \`retryable_work\` / \`attention_work\`,
+\`decision_blocked_work\` (parked on a docket entry, not broken),
+\`replans_used\` / \`replans_remaining\`, and the milestone counters.
+
+\`\`\`bash
+${b} governor tick <goal-id>   # at most one scheduling cycle
+${b} governor run <goal-id>    # cycles until success, attention, or budget
+${b} approval list             # a run needing authorization parks, not fails
+\`\`\`
+
+Rules that prevent stranded work:
+
+- **Never drive a governed item with \`${b} work retry\` or \`${b} work run\`.**
+  Only the governor supplies the frozen specialist map; a bare retry starts a
+  run with no team, dies at the first specialist stage, and still burns the
+  attempt. \`${b} work retry\` is for standalone work only.
+- **A blocked item cannot be accepted.** When its objective was met out of band,
+  the door back is \`${b} work reopen\` plus a fresh governor cycle, not accept.
+- **Read the spin signals before retrying.** Zero milestones with climbing
+  \`replans_used\` and repeated reviewer rejections means the mission prose or
+  acceptance criteria are wrong, not the agents. Replans are capped; diagnose
+  first.
+- **A frozen mission cannot be edited** — deliberately. Pass corrections as
+  retry context on individual items, or create a new goal and cancel the old
+  one. Do not keep re-planning against prose you know is stale.
+- **"ended without terminal evidence"** means the child died before writing its
+  proof, not that the work failed. Check whether the outcome landed before
+  redoing it.
+
+## Reporting back
+
+Tell the operator which tier you chose and why, the goal id, the roles, and the
+single next action. If you declined to build a team because one already existed,
+say that first; it is the most useful sentence in the reply.`;
+}
 export const SKILLS = [
     {
         id: "harn-decide",
@@ -367,4 +497,14 @@ export const SKILLS = [
             body: endBody(binName),
         }),
     },
+    {
+        id: "harn-team",
+        relPath: "harn-team/SKILL.md",
+        render: (binName) => buildOwnedSkill({
+            name: "harn-team",
+            description: "Stand up and drive a multi-agent team on an objective: pick between a bounded run, durable work, and a governed role team; build the governor artifacts; drive off projection.next_action. Use when asked to put a team of agents on a job, orchestrate agents, or check on a goal already running. Refuses to build a second team when one already covers the objective.",
+            binName,
+            body: teamBody(binName),
+        }),
+    },
 ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "harnery",
-  "version": "0.34.1",
+  "version": "0.35.0",
   "description": "Multi-agent coordination for AI coding agents - Claude Code, Cursor, and Codex.",
   "license": "MIT",
   "author": "Ryan Kelly",
@@ -102,6 +102,11 @@
       "types": "./dist/core/events/v3/index.d.ts",
       "import": "./dist/core/events/v3/index.js"
     },
+    "./core/semantic": {
+      "bun": "./src/core/semantic/index.ts",
+      "types": "./dist/core/semantic/index.d.ts",
+      "import": "./dist/core/semantic/index.js"
+    },
     "./core/governor/plans": {
       "bun": "./src/core/governor/plan-read.ts",
       "types": "./dist/core/governor/plan-read.d.ts",