@xingular/harness 1.4.0-unstable → 1.5.0-unstable

package/docs/releases/1.5.0-unstable.md

@@ -0,0 +1,23 @@
+# Xingular Harness 1.5.0-unstable
+
+Unstable preview of the current Harness work. Install with `npm install @xingular/harness@unstable`.
+
+- **No todo gate.** The stop gate, its three reminders and the `unfinished` status that open todo
+  items produced are removed. A reply the model ends settles `completed`; the goal loop and the
+  work-slice guard keep their stop codes and checkpoints. `XINGULAR_STOP_GATE` is retired.
+- **Codex's final-answer guidance.** The reporting section adopts Codex's `gpt-6.1-sol` wording:
+  self-contained final, outcome first, what changed and why, how it was tested, risks and limits,
+  evidence summarized, tables for comparisons, length by complexity, prose before lists. It falls
+  from 9.2k to 3.7k characters.
+- **Personality and model identity.** A person's own session reads Codex's personality paragraph,
+  and the identity names the model the session runs when the host knows it. The unclear-scope rule
+  uses Codex's wording with `ask_user` for the follow-up.
+- **Work rules and credentials.** The tool guidance gains Codex's `rg`-first search, shell quoting,
+  command-separator, variable-name and test-restraint rules, plus the skill and plugin principles.
+  A login that blocks the work is answered with the exact command.
+
+Test suites were not run for this candidate, at the request to bypass tests.
+
+Prepared from commit a9c25b3. Not published in the session that prepared it: npm
+authentication was unavailable (the registry answered 401). Follow `docs/releases/README.md` before
+publishing.

package/docs/study/STUDY-0004-turn-end-controls.md

@@ -9,6 +9,13 @@ related:
 ---
 # How other harnesses control the end of a turn
 
+> **Update (2026-11-01, [ADR-0075](../decisions/ADR-0075-no-todo-gate.md)):** the todo gate is
+> removed. A peer check found that omp ships the same three-reminder gate on by default
+> (`todo.remindersMax` 3), while Claude Code only reminds the model to use TodoWrite
+> (`ccVersion` 2.1.139), Codex's `update_plan` is opt-in (0.152) and Kimi CLI has no nudge. A reply
+> the model ends now settles `completed`; the goal loop and the work-slice guard keep their stop
+> codes and checkpoints.
+
 > **Update (2026-11-01, [ADR-0072](../decisions/ADR-0072-codex-prompts-and-goal.md)):** OpenAI Codex is open source. It has no completion check on ordinary turns and keeps its model-called `update_goal` behind an opt-in `/goal`. The harness followed: ordinary replies rely on Codex's prompt wording and the todo gate, and the judge now checks a `/goal` completion claim only.
 
 > **Update (2026-10-31, [ADR-0071](../decisions/ADR-0071-completion-check.md)):** the model-judged evaluator rejected above was adopted after all, as an automatic completion check on the run's own model, because a live A/B showed a closed todo list hiding unfinished work and `finish(needs_decision)` used as an early exit; `finish` is removed.

package/docs/study/STUDY-0006-reporting-prompts.md

@@ -32,9 +32,9 @@ for every session and every application.
 | Claude Code | Official docs, [Output styles](https://code.claude.com/docs/en/output-styles), checked 2026-11-01 | Default and Concise styles: the first sentence states what happened; no preamble, narration or closing recap; a simple question is answered in one to three sentences; error reports, failing test output, security warnings and destructive-action confirmations stay complete. Output styles are session-level, not a fixed report template. |
 | Claude Code | Extracted prompt, [Away summary generation](https://raw.githubusercontent.com/Piebald-AI/claude-code-system-prompts/main/system-prompts/agent-prompt-away-summary-generation.md) (third-party extraction, `ccVersion` 2.1.173) | Recap in under 40 words, one or two plain sentences, no markdown: the overall goal, the current task, then the one next action; skip root-cause narrative and secondary to-dos. |
 | Claude Code | Extracted prompt, [Subagent reporting notes](https://raw.githubusercontent.com/Piebald-AI/claude-code-system-prompts/main/system-prompts/agent-prompt-subagent-reporting-notes-lean-rewrite.md) (third-party extraction, `ccVersion` 2.1.301) | The final message is the report; absolute paths; code snippets only when the exact text is load-bearing; do not recap code that was read. |
-| Codex | Repository listing, [openai/codex `codex-rs/core`](https://github.com/openai/codex/tree/main/codex-rs/core) (checked 2026-11-01) | Per-model prompt files of 6.6k–24k characters (`gpt5codexprompt.md` 6,647; `gpt-5.2-codexprompt.md` 7,589; `gpt51prompt.md` 24,204; `gpt52prompt.md` 21,652). The exact final-answer wording could not be fetched: the raw files returned 404, so it is **unverified**. |
+| Codex | Repository listing, [openai/codex `codex-rs/core`](https://github.com/openai/codex/tree/main/codex-rs/core) (checked 2026-11-01) | Per-model prompt files of 6.6k–24k characters (`gpt5codexprompt.md` 6,647; `gpt-5.2-codexprompt.md` 7,589; `gpt51prompt.md` 24,204; `gpt52prompt.md` 21,652). Its final-answer wording is measured below from `models.json`. |
 | Kimi CLI | [external/kimi-cli/src/kimi_cli/agents/default/system.md](../../external/kimi-cli/src/kimi_cli/agents/default/system.md) | No final-report format. The prompt says to inform the user that the task completed or failed, or to ask for more information; the shape is left to the model. |
-| This harness | [src/prompt/reporting.ts](../../src/prompt/reporting.ts), [04-prompt.md](../architecture/04-prompt.md) | ADR-0073: ~15.8k characters, content blocks, required test and next-step blocks for changes, five examples. |
+| This harness | [src/prompt/reporting.ts](../../src/prompt/reporting.ts), [04-prompt.md](../architecture/04-prompt.md) | ADR-0076: ~3.7k characters. Codex's final-answer and technical-communication text: self-contained, outcome first, change/why/tested/risks, evidence summarized, tables, length by complexity, two examples. |
 
 ### What the peer evidence supports
 
@@ -49,10 +49,46 @@ for every session and every application.
 - **No single template.** Kimi has no shape; Claude Code changes shape by output style; Codex's
   per-model files differ. A fixed heading list is this harness's own invention, not a peer norm.
 
+## Codex's prompt measured
+
+Checked 2026-11-01 against `openai/codex` at `126a0ee` (2026-10-26). The prompts now live in
+`codex-rs/models-manager/models.json` as `model_messages.instructions_template`; the `gpt-6.1-sol`
+template is 21,769 characters, 4,212 tokens (o200k). `## Final answer` with its
+`### Formatting rules` and `### Visualizations` subsections is 453 tokens, and
+`## Intermediate commentary` adds 216: Codex spends 669 tokens (16%) on the text of its replies.
+Its tone rules sit outside that block, in `## Writing style` (442) and
+`## Technical communication` (190).
+
+| Prompt | Characters | Tokens (o200k) | Share of its own prompt |
+|---|---:|---:|---:|
+| Codex `## Final answer` (with formatting and visualizations) | 2,318 | 453 | 10.8% |
+| Codex final answer plus intermediate commentary | 3,413 | 669 | 15.9% |
+| This harness's `reporting` section, ADR-0073 (superseded) | 15,808 | 3,736 | ~54% of a ~6.9k-token prefix |
+| This harness's `reporting` section, ADR-0074 (superseded) | 8,921 | 2,108 | ~40% of a ~5.3k-token prefix |
+| This harness's `reporting` section, ADR-0076 | 3,697 | 792 | ~20% of a ~4.0k-token prefix |
+| The three worked examples inside it | 1,777 | 425 | 20.2% of the section |
+
+ADR-0073's four required blocks did not survive use. Replies listed the agent's own commands —
+`npm run typecheck — passed`, `npm test — 212 test files passed` — under a heading meant for the
+person's testing, ended with "Nothing needed next", and reused "What changed / How to check / Next
+step" on unrelated work. ADR-0074 replaced the blocks with content questions, made the by-hand
+section optional and human-only, banned the filler ending, and cut the text to 8,921 characters
+(2,108 tokens). The Codex numbers above are the baseline that made a large section defensible; the
+failure was in what the blocks asked for, not in their size.
+
+ADR-0076 then adopted Codex's wording for the report. The section is 3,697 characters, 792 tokens:
+1.7 times Codex's final-answer block and 19% of Codex's 4,212-token prompt. It is no longer the
+largest fixed section; the ranking and the remaining budget are recorded in
+[04-prompt.md](../architecture/04-prompt.md). The section keeps one advantage over Codex's: a login
+that blocks the work is answered with the exact command, in `autonomy` and in the blocked-publish
+example.
+
+The 6.6k–24k character sizes in the peer table above describe the per-model `*prompt.md` files that
+earlier listings named; the prompt source has since moved into `models.json`, so those sizes are not
+the text measured here.
+
 ## What could not be verified
 
-- Codex's exact final-answer rules: the raw prompt files in `openai/codex` returned 404 through the
-  fetch path; only the file names and sizes are verified.
 - Claude Code's prompt is a third-party extraction from the compiled package, not an Anthropic
   publication. The official output-styles page was used for the Default and Concise behavior; the
   extracted prompts are cited as a secondary source and versioned by `ccVersion`.
@@ -62,19 +98,21 @@ for every session and every application.
 ## Design implications
 
 1. Keep the section foundation-owned and stable; no variant or application should have to repeat it.
-2. Define required **content blocks**, not fixed headings; the old three headings become examples.
-3. Make "how to test" and "what to do next" required for a change, with a one-line fallback when
-   nothing is user-visible or nothing remains.
-4. Spend the prompt budget on rules, anti-patterns and five worked examples; measure the cache cost
-   with real requests ([INV-PRM-8](../architecture/04-prompt.md)).
+2. Define content questions, not fixed blocks or headings; the four block names are gone.
+3. Treat the agent's runs as one line of evidence, not steps for the person; a by-hand check covers
+   only what a person alone can do, and is absent when nothing needs one.
+4. Spend the prompt budget on rules, an anti-pattern table and three worked examples; measure the
+   cache cost with real requests ([INV-PRM-8](../architecture/04-prompt.md)).
 5. Keep the reply short: a question stays one to three sentences, and the change report leads with
-   the outcome and the test block.
+   the outcome and the person's check.
 
 ## Sources
 
 - [Claude Code: Output styles](https://code.claude.com/docs/en/output-styles), fetched 2026-11-01.
 - [Piebald-AI/claude-code-system-prompts](https://github.com/Piebald-AI/claude-code-system-prompts),
   `README.md` and the two extracted prompt files linked above, fetched 2026-11-01.
+- [openai/codex `codex-rs/models-manager/models.json`](https://github.com/openai/codex/blob/126a0ee92ed2c5e73cd8a8f7e37563e8527552d7/codex-rs/models-manager/models.json),
+  `model_messages.instructions_template` of `gpt-6.1-sol`, fetched 2026-11-01.
 - [openai/codex `codex-rs/core`](https://github.com/openai/codex/tree/main/codex-rs/core), directory
   listing fetched 2026-11-01.
 - [external/kimi-cli/src/kimi_cli/agents/default/system.md](../../external/kimi-cli/src/kimi_cli/agents/default/system.md),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xingular/harness",
-  "version": "1.4.0-unstable",
+  "version": "1.5.0-unstable",
   "type": "module",
   "description": "Xingular Harness — a Pi agent harness built on recursive harnessing (Harness²): versioned eight-component variants, refinement from evidence, multi-account sessions, a compiled prompt, project notes, tools, and MCP",
   "repository": {

package/dist/sdk/sessions/stopGate.d.ts

@@ -1,78 +0,0 @@
-import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
-import { type CheckModel } from "./completionCheck.js";
-import { type Checkpoint, type TodoItem } from "./contracts.js";
-import type { GoalState } from "./goal.js";
-export declare const STOP_GATE_EXTENSION = "stop-gate";
-export declare const STOP_GATE_CUSTOM_TYPE = "xingular-stop-gate";
-/** Nudges per reply before the reply is handed back to the person. */
-export declare const MAX_STOP_GATE_NUDGES = 3;
-/** What the gate knows about the live reply. */
-export interface StopGateState {
-    /** The reply's todo list as the model last wrote it (or as a continued run inherited it). */
-    todo: TodoItem[];
-    /** The person's request this reply answers. */
-    request: string;
-    /** Nudges sent in this reply. */
-    nudges: number;
-    /** Work tool calls since the last nudge. */
-    callsSinceNudge: number;
-    /** Work tool calls in this reply. */
-    callsInReply: number;
-}
-export declare function createStopGateState(initialTodo?: readonly TodoItem[]): StopGateState;
-/** A new reply starts from the inherited todo list, with no nudges. */
-export declare function resetStopGateState(state: StopGateState, initialTodo?: readonly TodoItem[], request?: string): void;
-/** The todo items a reply has not finished. */
-export declare function openItems(todo: readonly TodoItem[]): TodoItem[];
-/** How a settled reply ended when its work is not done; `null` when it is. */
-export type StopOutcome = {
-    code: 'needs_person';
-    reason: string;
-    open: TodoItem[];
-} | {
-    code: 'unfinished';
-    reason: string;
-    open: TodoItem[];
-};
-/**
- * `goal` is the session's /goal, when it has one: a goal that ended `blocked` needs the person,
- * and one that ended on a limit, a pause or a stall leaves work (ADR-0072).
- */
-export declare function stopOutcome(state: StopGateState, goal?: GoalState | null): StopOutcome | null;
-/** What a checkpoint learns from the reply's todo list and the goal. */
-export declare function handoffFields(state?: StopGateState | null, goal?: GoalState | null): Pick<Checkpoint, 'done' | 'next'> & {
-    blocked?: string;
-};
-/** Why a checkpoint written for a stop outcome was written. */
-export declare const stopCheckpointReason: (outcome: StopOutcome) => Checkpoint["reason"];
-/** The summary a stop outcome's checkpoint falls back to when the reply left no text. */
-export declare function stopSummary(outcome: StopOutcome): string;
-/** The text the model reads when the todo gate sends its reply back. */
-export declare function nudgeText(count: number, max: number, open: readonly TodoItem[]): string;
-/** What the gate reports for the run record: each nudge. */
-export type StopGateEvent = {
-    kind: 'todo';
-    count: number;
-    open: TodoItem[];
-};
-/** One line for the run record per stop-gate nudge. */
-export declare function stopGateNotice(event: StopGateEvent): string;
-export interface StopGateOptions {
-    state: StopGateState;
-    /** The todo list a continued run inherits; each new reply starts from it. */
-    initialTodo?: readonly TodoItem[];
-    /** The person's request when the prompt is not it (a continuation's "Continue from where you stopped."). */
-    request?: () => string | null;
-    /** Whether the gate applies to the current reply; a function follows the terminal's live plan switch. */
-    active?: () => boolean;
-    /** True when the work-slice guard ended this reply: the gate stays silent and the slice hands off. */
-    sliceEnded?: () => boolean;
-    /** True when the reply already failed (a provider error): nothing to continue. */
-    failed?: () => boolean;
-    max?: number;
-    /** Called for each nudge, for the run record. */
-    onEvent?: (event: StopGateEvent) => void;
-}
-export declare function stopGate(options: StopGateOptions): (pi: ExtensionAPI) => void;
-/** The model a goal-claim check asks: the session's own model, at low effort, through Pi's registry. */
-export declare function sessionCheckModel(ctx: unknown): CheckModel | null;

package/dist/sdk/sessions/stopGate.js

@@ -1,143 +0,0 @@
-import { TODO_WRITE } from "../tools/todo.js";
-import { validatedTodo } from "./compactionCheckpoint.js";
-import { answerText } from "./completionCheck.js";
-import { MAX_CHECKPOINT_DONE } from "./contracts.js";
-export const STOP_GATE_EXTENSION = 'stop-gate';
-export const STOP_GATE_CUSTOM_TYPE = 'xingular-stop-gate';
-/** Nudges per reply before the reply is handed back to the person. */
-export const MAX_STOP_GATE_NUDGES = 3;
-/** Calls that are bookkeeping, not work: they neither count as progress nor make a reply checkable. */
-const BOOKKEEPING_TOOLS = new Set([TODO_WRITE, 'session_name']);
-export function createStopGateState(initialTodo = []) {
-    return { todo: validatedTodo(initialTodo) ?? [], request: '', nudges: 0, callsSinceNudge: 0, callsInReply: 0 };
-}
-/** A new reply starts from the inherited todo list, with no nudges. */
-export function resetStopGateState(state, initialTodo = [], request = '') {
-    state.todo = validatedTodo(initialTodo) ?? [];
-    state.request = request;
-    state.nudges = 0;
-    state.callsSinceNudge = 0;
-    state.callsInReply = 0;
-}
-/** The todo items a reply has not finished. */
-export function openItems(todo) {
-    return todo.filter((item) => item.status !== 'completed');
-}
-/**
- * `goal` is the session's /goal, when it has one: a goal that ended `blocked` needs the person,
- * and one that ended on a limit, a pause or a stall leaves work (ADR-0072).
- */
-export function stopOutcome(state, goal) {
-    const open = openItems(state.todo);
-    if (goal?.status === 'blocked')
-        return { code: 'needs_person', reason: goal.lastReason || 'The goal is blocked.', open };
-    if (goal && (goal.status === 'budget_limited' || goal.status === 'usage_limited' || goal.status === 'paused')) {
-        return { code: 'unfinished', reason: goal.lastReason || `The goal is ${goal.status.replace('_', ' ')}.`, open };
-    }
-    if (open.length)
-        return { code: 'unfinished', reason: '', open };
-    return null;
-}
-/** What a checkpoint learns from the reply's todo list and the goal. */
-export function handoffFields(state, goal) {
-    const todo = state?.todo ?? [];
-    const next = openItems(todo)[0]?.text || '';
-    const blocked = goal?.status === 'blocked' ? (goal.lastReason || 'The goal is blocked.').slice(0, 500) : '';
-    return {
-        done: todo.filter((item) => item.status === 'completed').slice(0, MAX_CHECKPOINT_DONE).map((item) => ({ item: item.text.slice(0, 300), evidence: [] })),
-        next: next.slice(0, 500),
-        ...(blocked ? { blocked } : {})
-    };
-}
-/** Why a checkpoint written for a stop outcome was written. */
-export const stopCheckpointReason = (outcome) => outcome.code === 'needs_person' ? 'requested' : 'stuck';
-/** The summary a stop outcome's checkpoint falls back to when the reply left no text. */
-export function stopSummary(outcome) {
-    if (outcome.code === 'needs_person')
-        return `The reply stopped for the person: ${outcome.reason}`.slice(0, 1_200);
-    if (outcome.reason)
-        return `The reply ended with work left: ${outcome.reason}`.slice(0, 1_200);
-    return `The reply ended with ${outcome.open.length} open todo item${outcome.open.length === 1 ? '' : 's'}.`;
-}
-/** The text the model reads when the todo gate sends its reply back. */
-export function nudgeText(count, max, open) {
-    const list = open.slice(0, 12).map((item) => `- ${item.text}`).join('\n');
-    const more = open.length > 12 ? `\n- …and ${open.length - 12} more` : '';
-    return [
-        `Harness stop gate (${count}/${max}): your reply ended with ${open.length} open todo item${open.length === 1 ? '' : 's'}:`,
-        `${list}${more}`,
-        'Continue with the next open item now. Mark an item completed only after it is done and checked.',
-        'The list shows progress; it is not the limit of the work. If the request needs more than the list says, add it and do it.',
-        'Decisions inside the request are yours. Stop only for something only the person can do (a deploy, a secret, remote data, money, missing access), and then say exactly what it is.'
-    ].join('\n');
-}
-/** One line for the run record per stop-gate nudge. */
-export function stopGateNotice(event) {
-    return `Stop gate ${event.count}: the reply ended with ${event.open.length} open todo item${event.open.length === 1 ? '' : 's'}; continuing.`;
-}
-export function stopGate(options) {
-    const { state } = options;
-    const max = options.max ?? MAX_STOP_GATE_NUDGES;
-    return (pi) => {
-        // Pi emits agent_start again for every continuation, so a reply resets only on a person's message.
-        pi.on('before_agent_start', (event) => {
-            if (event.messageType !== undefined && event.messageType !== 'user')
-                return;
-            resetStopGateState(state, options.initialTodo, options.request?.() || (typeof event.prompt === 'string' ? event.prompt : ''));
-        });
-        pi.on('tool_call', (event) => {
-            if (BOOKKEEPING_TOOLS.has(event.toolName))
-                return;
-            state.callsSinceNudge += 1;
-            state.callsInReply += 1;
-        });
-        pi.on('tool_result', (event) => {
-            if (event.toolName !== TODO_WRITE || event.isError)
-                return;
-            const items = validatedTodo(event.input?.items);
-            if (items)
-                state.todo = items;
-        });
-        pi.on('agent_before_settle', (event, ctx) => {
-            if (event.outcome !== 'completed' || event.continue || ctx?.signal?.aborted)
-                return;
-            if (options.active && !options.active())
-                return;
-            if (options.sliceEnded?.() || options.failed?.())
-                return;
-            if (state.nudges >= max)
-                return;
-            // A nudge that produced no work will not be followed by one that does: hand it back.
-            if (state.nudges > 0 && state.callsSinceNudge === 0)
-                return;
-            const open = openItems(state.todo);
-            if (!open.length)
-                return;
-            state.nudges += 1;
-            state.callsSinceNudge = 0;
-            options.onEvent?.({ kind: 'todo', count: state.nudges, open });
-            return {
-                entries: [...event.entries, { type: 'custom_message', customType: STOP_GATE_CUSTOM_TYPE, content: nudgeText(state.nudges, max, open), display: true }],
-                continue: true
-            };
-        });
-    };
-}
-/** The model a goal-claim check asks: the session's own model, at low effort, through Pi's registry. */
-export function sessionCheckModel(ctx) {
-    const session = (ctx ?? {});
-    const model = session.model;
-    const registry = session.modelRegistry;
-    if (!model || !registry)
-        return null;
-    // Some providers (opencode-go) reject a request without a session id.
-    const sessionId = session.sessionManager?.getSessionId?.();
-    return async (system, user, signal) => {
-        const context = { systemPrompt: system, messages: [{ role: 'user', content: user, timestamp: Date.now() }] };
-        const message = await registry.streamSimple(model, context, { ...(model.reasoning ? { reasoning: 'low' } : {}), ...(sessionId ? { sessionId } : {}), maxTokens: 4_000, signal }).result();
-        const failed = message.stopReason;
-        if (failed === 'error' || failed === 'aborted')
-            throw new Error(message.errorMessage || `the check request ended: ${failed}`);
-        return { text: answerText(message), message };
-    };
-}