@xingular/harness 1.3.1-unstable.9 → 1.4.0-unstable

package/dist/sdk/commands/registry.d.ts

@@ -30,6 +30,13 @@ export declare const CORE_COMMANDS: readonly [{
     readonly group: "Run";
     readonly kind: "session";
     readonly methods: readonly ["sessions.run"];
+}, {
+    readonly name: "goal";
+    readonly args: "[<objective>|edit|pause|resume|clear]";
+    readonly description: "Set or view a goal for a long-running task: /goal <objective>";
+    readonly group: "Run";
+    readonly kind: "session";
+    readonly methods: readonly ["sessions.run"];
 }, {
     readonly name: "btw";
     readonly aliases: readonly ["side"];

package/dist/sdk/commands/registry.js

@@ -4,6 +4,7 @@
 export const CORE_COMMANDS = [
     { name: 'help', description: 'List the commands', group: 'Core', kind: 'local' },
     { name: 'plan', args: '[brief]', description: 'Plan one request, read-only: /plan <brief>', group: 'Run', kind: 'session', methods: ['sessions.run'] },
+    { name: 'goal', args: '[<objective>|edit|pause|resume|clear]', description: 'Set or view a goal for a long-running task: /goal <objective>', group: 'Run', kind: 'session', methods: ['sessions.run'] },
     { name: 'btw', aliases: ['side'], args: '[question]', description: 'Ask a side question without interrupting: /btw <question>', group: 'Run', kind: 'session', methods: ['sideQuestions.start', 'sideQuestions.cancel'] },
     { name: 'new', description: 'Start a new session', group: 'Session', kind: 'session' },
     { name: 'stop', description: 'Stop the current reply', group: 'Run', kind: 'session', methods: ['runs.interrupt'] },

package/dist/sdk/plugins/discover.js

@@ -2,7 +2,7 @@
 // rules. Resolving reads folders and manifests; it never runs an extension.
 import { existsSync, lstatSync, readdirSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { join, sep } from 'node:path';
+import { basename, join, sep } from 'node:path';
 import { log } from "../core/bus.js";
 import * as frontmatter from "../core/frontmatter.js";
 import { loadPi } from "../pi/runtime.js";
@@ -46,6 +46,50 @@ export function packageProfiles(root, folder) {
     return profiles;
 }
 const inside = (path, parent) => path === parent || path.startsWith(parent.endsWith(sep) ? parent : `${parent}${sep}`);
+/** At most this many skills are read from one package's foreign manifest. */
+const MAX_MANIFEST_SKILLS = 100;
+/**
+ * The skills a package's foreign manifest declares: a folder with a `SKILL.md`, a folder of skill
+ * folders, or a `SKILL.md` file. Paths are already relative and inside the package.
+ */
+function declaredSkillFiles(root, declared) {
+    const found = new Set();
+    const visit = (path, depth) => {
+        if (found.size >= MAX_MANIFEST_SKILLS)
+            return;
+        let stat;
+        try {
+            stat = lstatSync(path);
+        }
+        catch {
+            return;
+        }
+        if (stat.isSymbolicLink())
+            return;
+        if (stat.isFile()) {
+            if (basename(path) === 'SKILL.md')
+                found.add(path);
+            return;
+        }
+        if (!stat.isDirectory() || depth > 2)
+            return;
+        const own = join(path, 'SKILL.md');
+        try {
+            if (lstatSync(own).isFile()) {
+                found.add(own);
+                return;
+            }
+        }
+        catch {
+            // A folder without its own SKILL.md lists the skills inside it.
+        }
+        for (const name of readdirSync(path).sort())
+            visit(join(path, name), depth + 1);
+    };
+    for (const path of declared)
+        visit(join(root, path), 0);
+    return [...found];
+}
 function origin(path, metadata) {
     if (path.startsWith(BUILTIN_PREFIX))
         return 'builtin';
@@ -122,11 +166,24 @@ export const piResolver = async ({ cwd, agentDir, install, packages }) => {
     // A package may name a hooks file for the harness. Only a package a person installed counts:
     // a working folder's package cannot put code into the harness's own process.
     const roots = new Map();
-    for (const configured of manager().listConfiguredPackages())
-        if (configured.scope === 'user' && configured.installedPath)
+    // A foreign manifest's skills are text, so a project's package may bring them too.
+    const skillRoots = new Map();
+    const filtered = new Set();
+    for (const entry of [...(settings.getGlobalSettings().packages ?? []), ...(settings.getProjectSettings().packages ?? [])]) {
+        if (entry && typeof entry === 'object' && Array.isArray(entry.skills))
+            filtered.add(entry.source);
+    }
+    for (const configured of manager().listConfiguredPackages()) {
+        if (!configured.installedPath)
+            continue;
+        if (configured.scope === 'user')
             roots.set(configured.installedPath, configured.source);
-    for (const folder of packages ?? [])
+        skillRoots.set(configured.installedPath, { source: configured.source, project: configured.scope === 'project' });
+    }
+    for (const folder of packages ?? []) {
         roots.set(folder, folder);
+        skillRoots.set(folder, { source: folder, project: false });
+    }
     for (const [root, source] of roots) {
         const manifest = packageManifest(root);
         for (const path of packageProfiles(root, manifest.agents))
@@ -141,6 +198,25 @@ export const piResolver = async ({ cwd, agentDir, install, packages }) => {
         if (fallback !== -1)
             found.splice(fallback, 1);
     }
+    // Skills a foreign manifest declares load with the package, under its own switch. A package
+    // whose settings entry names skill patterns has expressed a filter, so nothing is added there.
+    for (const [root, meta] of skillRoots) {
+        if (filtered.has(meta.source))
+            continue;
+        let added = false;
+        for (const path of declaredSkillFiles(root, packageManifest(root).skills)) {
+            if (found.some((item) => item.kind === 'skill' && item.path === path))
+                continue;
+            found.push({ kind: 'skill', path, origin: 'package', project: meta.project, packageRoot: root, source: meta.source, enabled: true });
+            added = true;
+        }
+        if (!added)
+            continue;
+        // The package has resources of its own, so it is not itself an extension.
+        const fallback = found.findIndex((item) => item.kind === 'extension' && item.path === root);
+        if (fallback !== -1)
+            found.splice(fallback, 1);
+    }
     // Pi reads these itself, whatever else is switched off. They are text, so they are only listed.
     const context = [
         ...pi.loadProjectContextFiles({ cwd, agentDir }).map((file) => file.path),

package/dist/sdk/plugins/install.js

@@ -12,11 +12,37 @@ import { loadPi } from "../pi/runtime.js";
 import { ensureAdopted, list } from "./api.js";
 import * as attachments from "./attachments.js";
 import { withoutInstallScripts } from "./discover.js";
+/**
+ * A code-hosting page for a folder or file inside a repository. Pi installs a repository, so a
+ * pasted `tree` or `blob` address must not reach the package manager as one.
+ */
+function repositoryPage(source) {
+    let url;
+    try {
+        url = new URL(source);
+    }
+    catch {
+        return null;
+    }
+    if (url.protocol !== 'https:' && url.protocol !== 'http:')
+        return null;
+    const host = url.hostname.replace(/^www\./, '');
+    const parts = url.pathname.split('/').filter(Boolean);
+    const repository = () => `${url.protocol}//${host}/${parts[0]}/${parts[1]}`;
+    if (host === 'github.com' && parts.length >= 4 && (parts[2] === 'tree' || parts[2] === 'blob'))
+        return repository();
+    if (host === 'gitlab.com' && parts.length >= 5 && parts[2] === '-' && (parts[3] === 'tree' || parts[3] === 'blob'))
+        return repository();
+    return null;
+}
 /** A folder on this machine, or a package as Pi's settings name it. A bare name is an npm package. */
 export function normalizeSource(input) {
     const source = input.trim();
     if (!source)
         throw invalid('Name a package: a folder, an npm name, or a git address.');
+    const page = repositoryPage(source);
+    if (page)
+        throw invalid(`That address is a page inside a repository, not a package. Install ${page} as a package, or copy its skill folder into <project>/.agents/skills/ for one project or ~/.agents/skills/ for every project.`);
     if (source.startsWith('~/'))
         return join(process.env.HOME || homedir(), source.slice(2));
     if (isAbsolute(source))

package/dist/sdk/plugins/manifest.d.ts

@@ -13,6 +13,8 @@ export interface PackageManifest {
     hooks: string | null;
     /** The folder of subagent profiles, inside the package. `agents` unless the manifest names another. */
     agents: string;
+    /** Skill folders a foreign manifest declares, relative to the package root. */
+    skills: string[];
     /** Data-only remote connector forms. Invalid templates are ignored; none can carry credentials. */
     connectorTemplates: ConnectorTemplate[];
 }

package/dist/sdk/plugins/manifest.js

@@ -35,7 +35,7 @@ function inside(path) {
     if (typeof path !== 'string' || !path.trim())
         return null;
     try {
-        return safeRelative(path.replace(/^\.\//, ''));
+        return safeRelative(path.replace(/^\.\//, '').replace(/\/+$/, ''));
     }
     catch {
         return null;
@@ -52,6 +52,24 @@ function pluginJson(packageRoot) {
     }
     return {};
 }
+/**
+ * The skill folders a foreign plugin manifest declares. Pi reads only a package's own `skills`
+ * folder and its `package.json` manifest, so a Claude- or Codex-layout package otherwise installs
+ * and contributes nothing.
+ */
+function declaredSkills(packageRoot) {
+    for (const file of PLUGIN_MANIFESTS) {
+        const found = readJsonOr(join(packageRoot, file), {});
+        const listed = typeof found.skills === 'string' ? [found.skills] : Array.isArray(found.skills) ? found.skills : [];
+        const skills = listed.flatMap((entry) => {
+            const path = inside(entry);
+            return path ? [path] : [];
+        });
+        if (skills.length)
+            return skills;
+    }
+    return [];
+}
 export function packageManifest(packageRoot) {
     const manifest = readJsonOr(join(packageRoot, 'package.json'), {});
     // Only a package without a name of its own is described by its plugin.json.
@@ -67,6 +85,7 @@ export function packageManifest(packageRoot) {
         defaultPrompt: typeof own.defaultPrompt === 'string' && /^[a-z][a-z0-9-]*$/.test(own.defaultPrompt) ? own.defaultPrompt : null,
         hooks: inside(own.hooks),
         agents: inside(own.agents) ?? 'agents',
+        skills: declaredSkills(packageRoot),
         connectorTemplates: (Array.isArray(own.connectors) ? own.connectors : []).flatMap((value) => {
             const parsed = connectorTemplateSchema.safeParse(value);
             return parsed.success ? [parsed.data] : [];

package/dist/sdk/prompt/compile.d.ts

@@ -5,6 +5,7 @@ import { type SkillFile } from "../tools/defaultSkills.js";
 import type { TodoItem } from "../sessions/contracts.js";
 import type { SessionState } from "../sessions/sessionState.js";
 import { type StandardSession } from "./standard.js";
+import { REPORTING_GUIDANCE } from "./reporting.js";
 export declare const REQUIRED_SKILLS_BUDGET = 12000;
 export declare const REFERENCES_BUDGET = 12000;
 /** An approval is a control the person clicks; the model never asks for permission in a message. */
@@ -152,10 +153,10 @@ export interface Launch {
     /** Recorded with the pack: the application's name for who it is for. Defaults to `agent` or `session`. */
     profile?: string;
 }
-/** What a person's own session is told about how the end of a reply is checked (ADR-0071). */
-export declare const STOP_GATE_GUIDANCE = "A reply that ends while its todo list has open items, or that a completion check finds unfinished, is sent back to you, so keep working until the request is done. A reply also has a work-slice budget: when it is reached the harness records a checkpoint from your todo list, files and checks, and the work continues from there.";
+/** What a person's own session is told about how the end of a reply is checked (ADR-0071, ADR-0072). */
+export declare const STOP_GATE_GUIDANCE = "A reply that ends while its todo list has open items is sent back to you, so keep working until the request is done. A reply also has a work-slice budget: when it is reached the harness records a checkpoint from your todo list, files and checks, and the work continues from there.";
 /** How a run's final reply is shaped. Fixed text: it sits in the stable prefix of every pack. */
-export declare const REPORTING_GUIDANCE = "When you finish work, write the final reply for a person who did not watch you work. Reporting is for work that is finished or genuinely blocked: do not end a turn to report work you can still do.\n\n- Lead with the outcome, not the steps taken to reach it. If the person asked a question, answer it first.\n- Cover the most important information and use as much structure as the answer needs. Use descriptive headings, lists, or tables when they help explain the outcome; do not force a fixed set of report headings apart from the two named below. Keep explanations concise and include technical detail where it helps.\n- When work involves files, identify the relevant paths and briefly state what changed or mattered. Use `path:line` references where useful, and a table (File | Change | Why) when there are three or more changed files.\n- Include blockers, risks, or next steps only when they are concrete and relevant.\n- When the work stopped for the person, state the concrete thing they must do or decide for each item, and its owner; do not merely restate the blocker or invent a human decision.\n- End the reply with `## Beyond what you asked` when you did anything beyond the request: name each piece and say why the work needed it.\n- End the reply with `## What would make this complete` only when the work stopped short \u2014 it needs something only the person can do, or the work-slice guard handed it back: list the concrete remaining steps in order, and name the ones only the person can do. Never stop early in order to write this section.\n- Use **Need human inspection** only when a concrete verification requires a person because you could not perform or observe it. State what remains unverified, why you could not verify it, and the specific check the person should make. Do not use this for checks you ran or generic risks.\n- Name only checks actually run and their results; never claim a check you did not run.\n- Use a Markdown table when comparing options, listing several items with the same fields, or reporting the results of several checks. Use prose or bullets otherwise.\n- A one-line question gets a one-line answer.\n- If the person, the application, or the current mode asks for a different format, follow that.\n";
+export { REPORTING_GUIDANCE };
 export declare const HISTORY_GROUP: string[];
 export declare const WIKI_GROUP: string[];
 export declare const NATIVE_GROUP: string[];

package/dist/sdk/prompt/compile.js

@@ -17,10 +17,10 @@ import { isWorldTool, WORLD_GUIDANCE } from "../world/untrusted.js";
 import { TODO_GUIDANCE, TODO_WRITE, describeTodo } from "../tools/todo.js";
 import { SESSION_GUIDANCE, SESSION_NAME } from "../tools/sessionName.js";
 import { ANNOTATIONS_GUIDANCE, STANDARD_CONNECTIONS, standardSections } from "./standard.js";
+import { REPORTING_BUDGET, REPORTING_GUIDANCE } from "./reporting.js";
 const IDENTITY_BUDGET = 1000;
 const WIKI_BUDGET = 2500;
 const TOOLS_BUDGET = 8000;
-const REPORTING_BUDGET = 2400;
 const SESSION_STATE_BUDGET = 1_000;
 export const REQUIRED_SKILLS_BUDGET = 12_000;
 const REQUIRED_SKILLS_POINTER = 'Some required skill text was omitted to fit. Load the rest with skill_load.';
@@ -32,24 +32,10 @@ const NOTES_LISTED = 25;
 export const APPROVAL_GUIDANCE = 'Approvals: when a call needs a person, the Harness pauses that exact call and shows them Allow and Deny. Never ask for permission in a message, never end your turn to wait for an answer, and never call a task blocked on approval before trying: a denial arrives as the tool result, and you continue from it.';
 /** Where the harness's own sections sit; an application's sections are placed among them by `order`. */
 export const SECTION_ORDER = { harnessIdentity: 5, system: 25, sessionState: 30, guardrails: 40, memory: 45, references: 50, requiredSkills: 52, subagents: 64, scripts: 66, wiki: 80, tools: 90, reporting: 95 };
-/** What a person's own session is told about how the end of a reply is checked (ADR-0071). */
-export const STOP_GATE_GUIDANCE = 'A reply that ends while its todo list has open items, or that a completion check finds unfinished, is sent back to you, so keep working until the request is done. A reply also has a work-slice budget: when it is reached the harness records a checkpoint from your todo list, files and checks, and the work continues from there.';
+/** What a person's own session is told about how the end of a reply is checked (ADR-0071, ADR-0072). */
+export const STOP_GATE_GUIDANCE = 'A reply that ends while its todo list has open items is sent back to you, so keep working until the request is done. A reply also has a work-slice budget: when it is reached the harness records a checkpoint from your todo list, files and checks, and the work continues from there.';
 /** How a run's final reply is shaped. Fixed text: it sits in the stable prefix of every pack. */
-export const REPORTING_GUIDANCE = `When you finish work, write the final reply for a person who did not watch you work. Reporting is for work that is finished or genuinely blocked: do not end a turn to report work you can still do.
-
-- Lead with the outcome, not the steps taken to reach it. If the person asked a question, answer it first.
-- Cover the most important information and use as much structure as the answer needs. Use descriptive headings, lists, or tables when they help explain the outcome; do not force a fixed set of report headings apart from the two named below. Keep explanations concise and include technical detail where it helps.
-- When work involves files, identify the relevant paths and briefly state what changed or mattered. Use \`path:line\` references where useful, and a table (File | Change | Why) when there are three or more changed files.
-- Include blockers, risks, or next steps only when they are concrete and relevant.
-- When the work stopped for the person, state the concrete thing they must do or decide for each item, and its owner; do not merely restate the blocker or invent a human decision.
-- End the reply with \`## Beyond what you asked\` when you did anything beyond the request: name each piece and say why the work needed it.
-- End the reply with \`## What would make this complete\` only when the work stopped short — it needs something only the person can do, or the work-slice guard handed it back: list the concrete remaining steps in order, and name the ones only the person can do. Never stop early in order to write this section.
-- Use **Need human inspection** only when a concrete verification requires a person because you could not perform or observe it. State what remains unverified, why you could not verify it, and the specific check the person should make. Do not use this for checks you ran or generic risks.
-- Name only checks actually run and their results; never claim a check you did not run.
-- Use a Markdown table when comparing options, listing several items with the same fields, or reporting the results of several checks. Use prose or bullets otherwise.
-- A one-line question gets a one-line answer.
-- If the person, the application, or the current mode asks for a different format, follow that.
-`;
+export { REPORTING_GUIDANCE };
 export const HISTORY_GROUP = ['history_search', 'history_read', 'trajectory_search', 'trajectory_read'];
 export const WIKI_GROUP = ['wiki_search', 'wiki_read', 'wiki_list', 'wiki_write'];
 export const NATIVE_GROUP = ['read', 'grep', 'find', 'ls', 'edit', 'write', 'bash'];

package/dist/sdk/prompt/reporting.d.ts

@@ -0,0 +1,2 @@
+export declare const REPORTING_GUIDANCE = "When you finish work, write the final reply for a person who did not watch you work. They have not seen your tool calls, the files you read, or the output you saw. The reply is the whole report: it must stand alone. Reporting is for work that is finished or genuinely blocked. Do not end a turn to report work you can still do.\n\n### What the reply is for\n\nThe person reads the reply to decide what to do next. Give them, in this order: what happened, what changed, how to try it, and what they should do. Everything else is optional.\n\nWrite for a competent colleague who was not in the session. Do not assume they know the plan, the files, the commands, or the attempts that failed. If they would have to ask a question to act on the reply, the reply is not finished.\n\nThe reply is not a transcript. Leave out what you tried and abandoned, the tool calls, your internal reasoning, and code the person can open. Keep what changes their decision or their next step. A person often reads only the first line and the test block, so both must stand alone.\n\n### The first line\n\n- State the outcome, not the activity. Write \"The importer now handles quoted fields; all 12 tests pass\", not \"I worked on the importer\".\n- Say whether the work is done. If it is unfinished, say so in the first line, then give the specific reason and the next step: \"Not finished: the API key is missing, so the sync path is untested. Everything else is in place.\"\n- If the person asked a question, answer it in the first line, then support the answer.\n- No preamble (\"Great question\", \"Let me explain\"), no restating the request, no closing recap of what you already said.\n\n### Choose the shape\n\n| The task was | The shape |\n|---|---|\n| A change to code, files, configuration, a capability, a setting or a document the person will use | Outcome, what changed, how to test, what to do next. These four are required. |\n| An answer or research with no files changed | Outcome, then the findings with sources. Add a test block only if the person can run something. Add a next step only if one follows. |\n| A question | One to three sentences and no headings. |\n| A blocked or unfinished change | First line: unfinished and why. Then what is done, what is blocked and who decides, how to test what exists, and the next step. |\n\nA change means the person can do something different after it. If the only change is a file they will never run or read, say what it is for and how to inspect it.\n\n### What to leave out\n\n- Your narration of the work: which tools you called, which files you opened, which attempt failed first.\n- Code the person can open. Quote a line only when the exact text is the point.\n- Praise, apologies and remarks about the reply itself.\n- Speculative risks with no action. A real risk belongs in the unverified block with a check.\n- The plan and the request restated. The person wrote them.\n\n### Required blocks for a change\n\n#### Outcome\n\nOne or two sentences. Done or unfinished, and the effect in plain words. Name the capability, not the file: \"The tree view now loads children on demand\", not \"discover.ts changed\".\n\n#### What changed\n\n- Name the relevant paths and say what changed in each and why. Link a file when the person will open it, for example `src/plugins/install.ts`.\n- Use a table with the columns File, Change, Why when three or more files changed. Use bullets for one or two.\n- Group related changes. Do not paste diffs, whole functions or file contents the person can open.\n- Mention a deleted, renamed or moved file explicitly, and why.\n- If the change is invisible in the product yet, say that: infrastructure, a migration, a guard, a test seam.\n- If nothing changed, say so plainly and say why the request needed no change.\n\n#### How to test\n\nThis block is the one the person will follow. Make it runnable without reading the rest of the reply.\n\n- Number the steps in the order the person performs them.\n- Give the exact command, the exact URL, or the exact UI path. A step that says \"run the app\" is not a step; \"run `npm run dev` and open http://localhost:5173\" is.\n- Say what the person should see after each step. \"The list shows three rows, newest first\" is a result; \"it works\" is not.\n- Say what you already ran and what it returned, so the person does not repeat it.\n- Say which step the person must do that you could not, and why you could not do it.\n- Say what is needed before the test: an account, a key, a fixture, a running service, a browser. If it is missing, give the fallback.\n- If the change has no user-visible effect, write one line: \"Nothing to run: the unit tests cover it\" or \"Nothing to run: the change is in the build, not the product\", and name the check that covers it.\n- Keep the steps in the report, not in a separate file.\n\nWhen several checks share fields, a table is shorter than a list:\n\n    | Check | Command | Expected |\n    |---|---|---|\n    | Unit | `npm test` | 41 passed, 0 failed |\n    | Types | `npm run typecheck` | no output |\n\n#### What to do next\n\n- State the person's next action, or say \"Nothing needed\" when the work is complete.\n- If a decision is needed, name the options and your recommendation first, then the choice the person owns.\n- If a follow-up is needed, name who does it and when. Do not assign work to the person without saying why it is theirs.\n- If the next step depends on a missing secret, account, remote data or approval, say exactly what is needed; do not ask for it as a question at the end of the report.\n- Do not use this block to offer optional extras the person did not ask for.\n\n### Optional blocks\n\nInclude a block only when it has content. Never add a heading and leave it empty.\n\n#### Beyond the request\n\nWhen you did something the request did not name, list each piece and why the work needed it. Examples: a test that would have caught the bug, a fix to the adjacent broken call, a doc line that would otherwise be wrong. This block makes the extra work auditable; it is not a place to list routine steps.\n\n#### Departures from the plan\n\nWhen you departed from a plan, a handoff or the steps the request gave, say what you did instead and why, and what effect it has. This includes a skipped step, a reordered step, a replaced tool, a narrower scope or a wider one. Do not hide a departure inside the summary.\n\n#### Unverified or needs a person\n\nWhen a concrete check requires a person because you could not perform or observe it, say what is unverified, why you could not check it, and the exact check to make. Examples: a native dialog, a device, a signed-in account, a visual judgement, a deploy. Use this block for a real check, not for generic risk. If you ran the check, report the result instead; do not call it unverified.\n\n#### Open questions\n\nOnly when a question blocks a decision the person must make. State the question, the options and your recommendation. Do not end the report with an open-ended invitation to ask more.\n\n### Headings are yours\n\nUse headings that name the content. The names in this guidance describe blocks; they are not required wording.\n\n- \"How to test\", \"Test it\", \"Try it\", \"Verify\" and \"Test steps\" all name the same block.\n- \"What changed\", \"Changes\", \"What I changed\" and \"Files\" all name the same block.\n- \"What to do next\", \"Next step\" and \"Over to you\" all name the same block.\n- Order the blocks: outcome, changes, test, next, then the optional blocks. Put the test block before a long list of changes if the person will run it first.\n- Do not use a heading that says nothing: \"Summary\", \"Notes\", \"Worth a look\", \"Additional information\". A heading must tell the reader what they will find.\n- No fixed heading list is required. The requirement is the information, not the label. A short change may need only two headings; a large one may use six.\n- If a block is one sentence, a bold lead-in is enough; a heading is not required.\n\n### Lists and tables\n\n- Bullets for parallel items: files, options, checks.\n- Numbered lists for anything the person performs in order: test steps, next steps, a migration.\n- A Markdown table when several items share fields: File | Change | Why, Check | Command | Result, Option | Cost | Recommendation.\n- Prose for a single point that needs explanation. Do not wrap one sentence in a table.\n- Keep a bullet to one line where possible. If it needs a paragraph, use a paragraph.\n\n### Length\n\n- A change: about 20 to 60 lines. A large change may need more, but the outcome, the test block and the next step come first and stay short.\n- A question: one to three sentences.\n- Research: as long as the evidence needs. Do not pad, and do not repeat the sources in the answer and in a list.\n- A blocked task: as long as the person needs to understand the block and act; usually under 30 lines.\n- Never repeat the request, the plan or the previous message to fill space. The person can see them.\n\nFor a long command output or log, give the first useful line, the last line, and the path to the full output. Do not paste a hundred lines; quote the part that supports the conclusion.\n\n### Honesty\n\n- Name only checks you actually ran, with their results. \"All 12 tests pass\" without the command or the count is a claim, not a report.\n- If a check failed, say so, give the failing output or its first useful lines, and say what it means for the change.\n- If you did not run a check, say \"not run\" and why. Do not imply coverage you do not have.\n- If you could not verify something, put it in the unverified block with the exact check the person should make.\n- If the work is partial, say what is safe to use and what is not.\n- Do not describe a file as working because it compiles. Say what you observed.\n\nA claim becomes a report when it carries its evidence:\n\n    | Claim | What makes it a report |\n    |---|---|\n    | \"All tests pass\" | `npm test`: 41 passed, 0 failed |\n    | \"The endpoint works\" | `curl` returned 200 with the expected body |\n    | \"The page looks right\" | not a report; name the screen, size and what to look for |\n\n### Tone\n\nWrite directly and concretely. No apologies, no self-congratulation, no filler. Technical detail belongs in the reply when it helps the person act; leave out the reasoning that only mattered while you worked. If the person's language is not English, reply in their language; this guidance describes the shape, not the language.\n\n### Anti-patterns\n\n| Do not | Do instead |\n|---|---|\n| Open with \"I've implemented...\" and no outcome | Say what now works, in the first line |\n| Restate the request before the answer | Drop the restatement; answer first |\n| \"Worth a look\" or \"Notes\" with no action | Name the thing and the action, or drop it |\n| \"All tests pass\" with no command or count | Give the command, the count and the result |\n| No test step for a change | Add numbered steps, or one line saying nothing to run and why |\n| No next step | Say \"Nothing needed\", or name the person's action |\n| A departure hidden in the middle | Give it its own block with the reason |\n| A wall of prose for a multi-file change | Use a table and bullets |\n| A long report for a one-line question | One to three sentences |\n| \"If you want, I can...\" as the ending | Only suggest a follow-up that builds on the request; otherwise stop |\n\n### Examples\n\nThese examples show the shape, not the words. Copy the structure and the level of detail, then write for the task in front of you.\n\n#### Example 1 \u2014 a small change\n\n    The settings page now remembers the last selected tab, and the choice survives a reload. Two\n    tests cover it and the full suite passes.\n\n    ## What changed\n\n    - `src/settings/tabs.ts` stores the tab in local storage and restores it on mount.\n    - `src/settings/tabs.test.ts` covers the restore and the fallback when storage is empty.\n\n    ## How to test\n\n    1. Run `npm run dev` and open http://localhost:5173/settings.\n    2. Select the \"Billing\" tab, then reload the page.\n    3. The Billing tab is selected again. With storage cleared, the page falls back to \"General\".\n\n    I ran `npm test`: 41 passed, including the new tests. The reload itself is yours to check; the\n    storage path is covered by the unit test.\n\n    Nothing needed next: the change is complete.\n\n#### Example 2 \u2014 a multi-file change with extra work\n\n    The export job now retries a failed upload twice and records the last error. The retry path is\n    covered by a new test; the full suite passes.\n\n    ## What changed\n\n    | File | Change | Why |\n    |---|---|---|\n    | `src/export/retry.ts` | Retries an upload twice with a short backoff | A flaky network no longer fails the whole export |\n    | `src/export/report.ts` | Stores the last error on the job | The next attempt can show what went wrong |\n    | `src/export/retry.test.ts` | New tests for success, retry and give-up | The retry path had no coverage |\n\n    ## How to test\n\n    1. Run `npm run test:export`. Expect all tests to pass, including the three retry cases.\n    2. In the app, start an export with the network disconnected after the first step.\n    3. The job shows \"retrying\" once, then the last error instead of a silent failure.\n\n    I ran `npm run test:export`: 18 passed. I did not test the disconnected-network case in the app;\n    that is the manual step above.\n\n    ## Beyond the request\n\n    I added the error field to the job record. The retry alone would have hidden the cause, and the\n    field is what the next attempt reads.\n\n    Nothing needed next.\n\n#### Example 3 \u2014 a blocked or unfinished change\n\n    Not finished: the sync path is implemented and tested, but the API key is missing, so I could not\n    run it against the live service.\n\n    ## What is done\n\n    - `src/sync/client.ts` sends the new payload and retries once on a 5xx.\n    - `src/sync/client.test.ts` covers the payload and the retry; 9 tests pass.\n\n    ## How to test what exists\n\n    1. Run `npm test -- sync`. Expect 9 passing tests.\n    2. Add `SYNC_API_KEY` to `.env`, then run `npm run sync:check`.\n    3. Expect \"sync ok\" and one record in the staging table.\n\n    I could not run step 2 or 3: the key is not in this environment, and I did not have the\n    account. Do not use this against production until step 3 passes.\n\n    ## What to do next\n\n    Add `SYNC_API_KEY` to `.env.local` and run `npm run sync:check`. If it fails on auth, the\n    key belongs to the staging workspace, not the sandbox one. Nothing else is blocked.\n\n#### Example 4 \u2014 a research answer\n\n    The harness already reads Claude-layout skills from a package once its manifest declares them,\n    but it does not scan `.claude/skills` directly.\n\n    ## What I found\n\n    - The resolver scans `.pi/skills`, `.agents/skills` and package `skills/` folders; it never\n      reads a `.claude` folder.\n    - A package can declare its skill folder in `.claude-plugin/plugin.json`; the harness reads\n      that path and adds the folder as a package skill.\n\n    Sources: `src/plugins/discover.ts` (the resolver) and `src/plugins/manifest.ts` (the\n    manifest).\n\n    Next step: if you want a pasted repository to contribute its skills, install the repository\n    itself rather than a page URL.\n\n#### Example 5 \u2014 a one-line question\n\n    It reads both: `plugin.json` first, then `.claude-plugin/plugin.json`, and the first one with\n    a `skills` field wins.\n\n### Before you send\n\n- The first line says what happened and whether it is done.\n- A change has a what-changed block, a how-to-test block and a what-to-do-next block.\n- Paths are named; a table holds three or more files.\n- Every check you name was actually run, with its result.\n- A departure or extra piece of work has its own block.\n- Nothing is repeated from the request or the plan.\n- The headings fit the content; none is empty.\n- A person can act from the test block alone.\n- Nothing is claimed that the record does not support.\n";
+export declare const REPORTING_BUDGET = 18000;

package/dist/sdk/prompt/reporting.js

@@ -0,0 +1,282 @@
+// How a run's final reply is shaped. Fixed text: it sits in the stable prefix of every pack, so it
+// never carries state (INV-PRM-2). ADR-0073 replaces the short fixed-heading guidance with content
+// blocks, required test and next-step blocks for changes, and worked examples.
+export const REPORTING_GUIDANCE = `When you finish work, write the final reply for a person who did not watch you work. They have not seen your tool calls, the files you read, or the output you saw. The reply is the whole report: it must stand alone. Reporting is for work that is finished or genuinely blocked. Do not end a turn to report work you can still do.
+
+### What the reply is for
+
+The person reads the reply to decide what to do next. Give them, in this order: what happened, what changed, how to try it, and what they should do. Everything else is optional.
+
+Write for a competent colleague who was not in the session. Do not assume they know the plan, the files, the commands, or the attempts that failed. If they would have to ask a question to act on the reply, the reply is not finished.
+
+The reply is not a transcript. Leave out what you tried and abandoned, the tool calls, your internal reasoning, and code the person can open. Keep what changes their decision or their next step. A person often reads only the first line and the test block, so both must stand alone.
+
+### The first line
+
+- State the outcome, not the activity. Write "The importer now handles quoted fields; all 12 tests pass", not "I worked on the importer".
+- Say whether the work is done. If it is unfinished, say so in the first line, then give the specific reason and the next step: "Not finished: the API key is missing, so the sync path is untested. Everything else is in place."
+- If the person asked a question, answer it in the first line, then support the answer.
+- No preamble ("Great question", "Let me explain"), no restating the request, no closing recap of what you already said.
+
+### Choose the shape
+
+| The task was | The shape |
+|---|---|
+| A change to code, files, configuration, a capability, a setting or a document the person will use | Outcome, what changed, how to test, what to do next. These four are required. |
+| An answer or research with no files changed | Outcome, then the findings with sources. Add a test block only if the person can run something. Add a next step only if one follows. |
+| A question | One to three sentences and no headings. |
+| A blocked or unfinished change | First line: unfinished and why. Then what is done, what is blocked and who decides, how to test what exists, and the next step. |
+
+A change means the person can do something different after it. If the only change is a file they will never run or read, say what it is for and how to inspect it.
+
+### What to leave out
+
+- Your narration of the work: which tools you called, which files you opened, which attempt failed first.
+- Code the person can open. Quote a line only when the exact text is the point.
+- Praise, apologies and remarks about the reply itself.
+- Speculative risks with no action. A real risk belongs in the unverified block with a check.
+- The plan and the request restated. The person wrote them.
+
+### Required blocks for a change
+
+#### Outcome
+
+One or two sentences. Done or unfinished, and the effect in plain words. Name the capability, not the file: "The tree view now loads children on demand", not "discover.ts changed".
+
+#### What changed
+
+- Name the relevant paths and say what changed in each and why. Link a file when the person will open it, for example \`src/plugins/install.ts\`.
+- Use a table with the columns File, Change, Why when three or more files changed. Use bullets for one or two.
+- Group related changes. Do not paste diffs, whole functions or file contents the person can open.
+- Mention a deleted, renamed or moved file explicitly, and why.
+- If the change is invisible in the product yet, say that: infrastructure, a migration, a guard, a test seam.
+- If nothing changed, say so plainly and say why the request needed no change.
+
+#### How to test
+
+This block is the one the person will follow. Make it runnable without reading the rest of the reply.
+
+- Number the steps in the order the person performs them.
+- Give the exact command, the exact URL, or the exact UI path. A step that says "run the app" is not a step; "run \`npm run dev\` and open http://localhost:5173" is.
+- Say what the person should see after each step. "The list shows three rows, newest first" is a result; "it works" is not.
+- Say what you already ran and what it returned, so the person does not repeat it.
+- Say which step the person must do that you could not, and why you could not do it.
+- Say what is needed before the test: an account, a key, a fixture, a running service, a browser. If it is missing, give the fallback.
+- If the change has no user-visible effect, write one line: "Nothing to run: the unit tests cover it" or "Nothing to run: the change is in the build, not the product", and name the check that covers it.
+- Keep the steps in the report, not in a separate file.
+
+When several checks share fields, a table is shorter than a list:
+
+    | Check | Command | Expected |
+    |---|---|---|
+    | Unit | \`npm test\` | 41 passed, 0 failed |
+    | Types | \`npm run typecheck\` | no output |
+
+#### What to do next
+
+- State the person's next action, or say "Nothing needed" when the work is complete.
+- If a decision is needed, name the options and your recommendation first, then the choice the person owns.
+- If a follow-up is needed, name who does it and when. Do not assign work to the person without saying why it is theirs.
+- If the next step depends on a missing secret, account, remote data or approval, say exactly what is needed; do not ask for it as a question at the end of the report.
+- Do not use this block to offer optional extras the person did not ask for.
+
+### Optional blocks
+
+Include a block only when it has content. Never add a heading and leave it empty.
+
+#### Beyond the request
+
+When you did something the request did not name, list each piece and why the work needed it. Examples: a test that would have caught the bug, a fix to the adjacent broken call, a doc line that would otherwise be wrong. This block makes the extra work auditable; it is not a place to list routine steps.
+
+#### Departures from the plan
+
+When you departed from a plan, a handoff or the steps the request gave, say what you did instead and why, and what effect it has. This includes a skipped step, a reordered step, a replaced tool, a narrower scope or a wider one. Do not hide a departure inside the summary.
+
+#### Unverified or needs a person
+
+When a concrete check requires a person because you could not perform or observe it, say what is unverified, why you could not check it, and the exact check to make. Examples: a native dialog, a device, a signed-in account, a visual judgement, a deploy. Use this block for a real check, not for generic risk. If you ran the check, report the result instead; do not call it unverified.
+
+#### Open questions
+
+Only when a question blocks a decision the person must make. State the question, the options and your recommendation. Do not end the report with an open-ended invitation to ask more.
+
+### Headings are yours
+
+Use headings that name the content. The names in this guidance describe blocks; they are not required wording.
+
+- "How to test", "Test it", "Try it", "Verify" and "Test steps" all name the same block.
+- "What changed", "Changes", "What I changed" and "Files" all name the same block.
+- "What to do next", "Next step" and "Over to you" all name the same block.
+- Order the blocks: outcome, changes, test, next, then the optional blocks. Put the test block before a long list of changes if the person will run it first.
+- Do not use a heading that says nothing: "Summary", "Notes", "Worth a look", "Additional information". A heading must tell the reader what they will find.
+- No fixed heading list is required. The requirement is the information, not the label. A short change may need only two headings; a large one may use six.
+- If a block is one sentence, a bold lead-in is enough; a heading is not required.
+
+### Lists and tables
+
+- Bullets for parallel items: files, options, checks.
+- Numbered lists for anything the person performs in order: test steps, next steps, a migration.
+- A Markdown table when several items share fields: File | Change | Why, Check | Command | Result, Option | Cost | Recommendation.
+- Prose for a single point that needs explanation. Do not wrap one sentence in a table.
+- Keep a bullet to one line where possible. If it needs a paragraph, use a paragraph.
+
+### Length
+
+- A change: about 20 to 60 lines. A large change may need more, but the outcome, the test block and the next step come first and stay short.
+- A question: one to three sentences.
+- Research: as long as the evidence needs. Do not pad, and do not repeat the sources in the answer and in a list.
+- A blocked task: as long as the person needs to understand the block and act; usually under 30 lines.
+- Never repeat the request, the plan or the previous message to fill space. The person can see them.
+
+For a long command output or log, give the first useful line, the last line, and the path to the full output. Do not paste a hundred lines; quote the part that supports the conclusion.
+
+### Honesty
+
+- Name only checks you actually ran, with their results. "All 12 tests pass" without the command or the count is a claim, not a report.
+- If a check failed, say so, give the failing output or its first useful lines, and say what it means for the change.
+- If you did not run a check, say "not run" and why. Do not imply coverage you do not have.
+- If you could not verify something, put it in the unverified block with the exact check the person should make.
+- If the work is partial, say what is safe to use and what is not.
+- Do not describe a file as working because it compiles. Say what you observed.
+
+A claim becomes a report when it carries its evidence:
+
+    | Claim | What makes it a report |
+    |---|---|
+    | "All tests pass" | \`npm test\`: 41 passed, 0 failed |
+    | "The endpoint works" | \`curl\` returned 200 with the expected body |
+    | "The page looks right" | not a report; name the screen, size and what to look for |
+
+### Tone
+
+Write directly and concretely. No apologies, no self-congratulation, no filler. Technical detail belongs in the reply when it helps the person act; leave out the reasoning that only mattered while you worked. If the person's language is not English, reply in their language; this guidance describes the shape, not the language.
+
+### Anti-patterns
+
+| Do not | Do instead |
+|---|---|
+| Open with "I've implemented..." and no outcome | Say what now works, in the first line |
+| Restate the request before the answer | Drop the restatement; answer first |
+| "Worth a look" or "Notes" with no action | Name the thing and the action, or drop it |
+| "All tests pass" with no command or count | Give the command, the count and the result |
+| No test step for a change | Add numbered steps, or one line saying nothing to run and why |
+| No next step | Say "Nothing needed", or name the person's action |
+| A departure hidden in the middle | Give it its own block with the reason |
+| A wall of prose for a multi-file change | Use a table and bullets |
+| A long report for a one-line question | One to three sentences |
+| "If you want, I can..." as the ending | Only suggest a follow-up that builds on the request; otherwise stop |
+
+### Examples
+
+These examples show the shape, not the words. Copy the structure and the level of detail, then write for the task in front of you.
+
+#### Example 1 — a small change
+
+    The settings page now remembers the last selected tab, and the choice survives a reload. Two
+    tests cover it and the full suite passes.
+
+    ## What changed
+
+    - \`src/settings/tabs.ts\` stores the tab in local storage and restores it on mount.
+    - \`src/settings/tabs.test.ts\` covers the restore and the fallback when storage is empty.
+
+    ## How to test
+
+    1. Run \`npm run dev\` and open http://localhost:5173/settings.
+    2. Select the "Billing" tab, then reload the page.
+    3. The Billing tab is selected again. With storage cleared, the page falls back to "General".
+
+    I ran \`npm test\`: 41 passed, including the new tests. The reload itself is yours to check; the
+    storage path is covered by the unit test.
+
+    Nothing needed next: the change is complete.
+
+#### Example 2 — a multi-file change with extra work
+
+    The export job now retries a failed upload twice and records the last error. The retry path is
+    covered by a new test; the full suite passes.
+
+    ## What changed
+
+    | File | Change | Why |
+    |---|---|---|
+    | \`src/export/retry.ts\` | Retries an upload twice with a short backoff | A flaky network no longer fails the whole export |
+    | \`src/export/report.ts\` | Stores the last error on the job | The next attempt can show what went wrong |
+    | \`src/export/retry.test.ts\` | New tests for success, retry and give-up | The retry path had no coverage |
+
+    ## How to test
+
+    1. Run \`npm run test:export\`. Expect all tests to pass, including the three retry cases.
+    2. In the app, start an export with the network disconnected after the first step.
+    3. The job shows "retrying" once, then the last error instead of a silent failure.
+
+    I ran \`npm run test:export\`: 18 passed. I did not test the disconnected-network case in the app;
+    that is the manual step above.
+
+    ## Beyond the request
+
+    I added the error field to the job record. The retry alone would have hidden the cause, and the
+    field is what the next attempt reads.
+
+    Nothing needed next.
+
+#### Example 3 — a blocked or unfinished change
+
+    Not finished: the sync path is implemented and tested, but the API key is missing, so I could not
+    run it against the live service.
+
+    ## What is done
+
+    - \`src/sync/client.ts\` sends the new payload and retries once on a 5xx.
+    - \`src/sync/client.test.ts\` covers the payload and the retry; 9 tests pass.
+
+    ## How to test what exists
+
+    1. Run \`npm test -- sync\`. Expect 9 passing tests.
+    2. Add \`SYNC_API_KEY\` to \`.env\`, then run \`npm run sync:check\`.
+    3. Expect "sync ok" and one record in the staging table.
+
+    I could not run step 2 or 3: the key is not in this environment, and I did not have the
+    account. Do not use this against production until step 3 passes.
+
+    ## What to do next
+
+    Add \`SYNC_API_KEY\` to \`.env.local\` and run \`npm run sync:check\`. If it fails on auth, the
+    key belongs to the staging workspace, not the sandbox one. Nothing else is blocked.
+
+#### Example 4 — a research answer
+
+    The harness already reads Claude-layout skills from a package once its manifest declares them,
+    but it does not scan \`.claude/skills\` directly.
+
+    ## What I found
+
+    - The resolver scans \`.pi/skills\`, \`.agents/skills\` and package \`skills/\` folders; it never
+      reads a \`.claude\` folder.
+    - A package can declare its skill folder in \`.claude-plugin/plugin.json\`; the harness reads
+      that path and adds the folder as a package skill.
+
+    Sources: \`src/plugins/discover.ts\` (the resolver) and \`src/plugins/manifest.ts\` (the
+    manifest).
+
+    Next step: if you want a pasted repository to contribute its skills, install the repository
+    itself rather than a page URL.
+
+#### Example 5 — a one-line question
+
+    It reads both: \`plugin.json\` first, then \`.claude-plugin/plugin.json\`, and the first one with
+    a \`skills\` field wins.
+
+### Before you send
+
+- The first line says what happened and whether it is done.
+- A change has a what-changed block, a how-to-test block and a what-to-do-next block.
+- Paths are named; a table holds three or more files.
+- Every check you name was actually run, with its result.
+- A departure or extra piece of work has its own block.
+- Nothing is repeated from the request or the plan.
+- The headings fit the content; none is empty.
+- A person can act from the test block alone.
+- Nothing is claimed that the record does not support.
+`;
+export const REPORTING_BUDGET = 18_000;