@navels/neal 0.1.0 → 0.3.0

package/dist/neal/prompts/specs.js

@@ -1,3 +1,4 @@
+import { createHash } from 'node:crypto';
 function field(key, source, required, description) {
     return { key, source, required, description };
 }
@@ -36,8 +37,7 @@ const PLAN_REVIEWER_CONTEXT = context('PlanReviewerPromptContext', [
     field('parentPlanDoc', 'prompt_argument', false, 'Path to the parent plan when reviewing a derived plan.'),
     field('derivedFromScopeNumber', 'orchestrator_state', false, 'Parent scope number when reviewing a derived plan.'),
     field('repositoryState', 'repository_state', true, 'Current repository context and directly referenced companion docs.'),
-    field('inlineContext', 'repository_state', false, "Neal-inlined plan document, parent plan, and review-history sections for reviewers without repository read access; only valid with the 'no-read' access mode."),
-    field('accessMode', 'orchestrator_state', false, "Three-way reviewer doctrine access mode derived from the reviewer provider's structured-advisor tool access: 'tool-access' (inspect and execute), 'read-only' (read tools only; no command execution, test runs, or scratch work), or 'no-read' (judge entirely from Neal-inlined context). When absent the builder derives 'no-read' from inline-context presence, else 'tool-access'."),
+    field('accessMode', 'orchestrator_state', false, "Two-way reviewer doctrine access mode derived from the reviewer provider's structured-advisor tool access: 'tool-access' (inspect and execute) or 'read-only' (read tools only; no command execution, test runs, or scratch work). Defaults to 'tool-access' when absent."),
 ]);
 const SCOPE_CODER_CONTEXT = context('ScopeCoderPromptContext', [
     field('planDoc', 'prompt_argument', true, 'Path to the active execute-mode plan.'),
@@ -65,8 +65,7 @@ const SCOPE_REVIEWER_CONTEXT = context('ScopeReviewerPromptContext', [
     field('recentHistorySummary', 'review_history', true, 'Accepted-scope history for the active parent objective.'),
     field('reviewMarkdownPath', 'run_artifact', true, 'Review artifact that carries prior findings and coder responses.'),
     field('scratchDir', 'run_artifact', true, 'Run-local reviewer scratch directory for temporary verification artifacts.'),
-    field('inlineContext', 'repository_state', false, "Neal-inlined full diff, plan document, and review-history sections for reviewers without repository read access; only valid with the 'no-read' access mode."),
-    field('accessMode', 'orchestrator_state', false, "Three-way reviewer doctrine access mode derived from the reviewer provider's structured-advisor tool access: 'tool-access' (inspect and execute), 'read-only' (read tools only; no command execution, test runs, or scratch work), or 'no-read' (judge entirely from Neal-inlined context). When absent the builder derives 'no-read' from inline-context presence, else 'tool-access'."),
+    field('accessMode', 'orchestrator_state', false, "Two-way reviewer doctrine access mode derived from the reviewer provider's structured-advisor tool access: 'tool-access' (inspect and execute) or 'read-only' (read tools only; no command execution, test runs, or scratch work). Defaults to 'tool-access' when absent."),
 ]);
 const COMPLETION_CODER_CONTEXT = context('CompletionCoderPromptContext', [
     field('planDoc', 'prompt_argument', true, 'Path to the execute-mode plan being evaluated for final completion.'),
@@ -79,14 +78,32 @@ const COMPLETION_REVIEWER_CONTEXT = context('CompletionReviewerPromptContext', [
     field('summary', 'review_history', true, 'Coder-authored whole-plan completion summary under review.'),
     field('scratchDir', 'run_artifact', true, 'Run-local final-completion reviewer scratch directory for temporary verification artifacts.'),
     field('repositoryState', 'repository_state', true, 'Current repository state used to judge whole-plan completion.'),
-    field('inlineContext', 'repository_state', false, "Neal-inlined aggregate diff (or evidence-gap statement) and plan-document sections for reviewers without repository read access; only valid with the 'no-read' access mode."),
-    field('accessMode', 'orchestrator_state', false, "Three-way reviewer doctrine access mode derived from the reviewer provider's structured-advisor tool access: 'tool-access' (inspect and execute), 'read-only' (read tools only; no command execution, test runs, or scratch work), or 'no-read' (judge entirely from Neal-inlined context). When absent the builder derives 'no-read' from inline-context presence, else 'tool-access'."),
+    field('accessMode', 'orchestrator_state', false, "Two-way reviewer doctrine access mode derived from the reviewer provider's structured-advisor tool access: 'tool-access' (inspect and execute) or 'read-only' (read tools only; no command execution, test runs, or scratch work). Defaults to 'tool-access' when absent."),
+]);
+const CONSULTANT_CONTEXT = context('ConsultantPromptContext', [
+    field('blockedReason', 'prompt_argument', true, 'Blocked reason reported by the stalled coder or reviewer turn.'),
+    field('inlineContext', 'repository_state', true, 'Neal-inlined adjudication context (plan content, open blocking findings, reviewer-round snapshots, or coder blocker plus changed files) the consultant judges entirely from.'),
 ]);
 export const PROMPT_SPECS = [
     {
         id: 'plan_author',
+        version: 3,
+        changelog: [
+            {
+                version: 1,
+                renderSha: '2e5600ef64885419b574cc0a04b684dc93f3efcc9ede65e4cacc8951a220d5cd',
+            },
+            {
+                version: 2,
+                renderSha: 'a9ebcafa81fa0f60812adcb7c7b68f999a6c45c1c7fa7b7a20911031d6b0fd9e',
+            },
+            {
+                version: 3,
+                renderSha: '51943007b2a334ee0c92d8314616fb882e9cea7b410b05c5aeda668c7c9e04dc',
+            },
+        ],
         role: 'coder',
-        purpose: 'Author or revise Neal-executable plans without leaking planning-task scaffolding into final artifacts.',
+        purpose: 'Author or revise concise, human-reviewable Neal-executable plans at moderate-to-high-level implementation detail.',
         requiredContext: PLAN_AUTHOR_CONTEXT,
         schemaTarget: {
             kind: 'structured_json',
@@ -104,6 +121,8 @@ export const PROMPT_SPECS = [
         evaluationNotes: [
             'Render tests should assert the canonical Neal-executable execution-shape contract stays present.',
             'Fixture cases should cover single-scope vs multi-scope decisions and cleanup of planning-only scaffolding.',
+            'Prompt tests should preserve repository grounding while rejecting exhaustive implementation inventories.',
+            'Planner and response prompts should narrow self-imposed global verification guarantees unless they are necessary for the requested change to be correct.',
         ],
         firstMigrationPriority: 1,
         currentHome: 'src/neal/prompts',
@@ -156,8 +175,23 @@ export const PROMPT_SPECS = [
     },
     {
         id: 'plan_reviewer',
+        version: 3,
+        changelog: [
+            {
+                version: 1,
+                renderSha: 'c84e630d1463590eda463726a0529dab6277f1980a2c9c586a3fe3673e44d2ee',
+            },
+            {
+                version: 2,
+                renderSha: '43a6f77d767bb5a010203f37b2c1ac980f0d7c6e1eb104f038c33afcea97c658',
+            },
+            {
+                version: 3,
+                renderSha: 'fa0309ed0e394c690dfc3135da3c98a74dd5413ccb754fefa100171bf35b72b6',
+            },
+        ],
         role: 'reviewer',
-        purpose: 'Review Neal-executable plans for execution-shape correctness, verification concreteness, and resume safety.',
+        purpose: 'Review human-reviewable Neal-executable plans for material approach, scope, verification, and resume-safety defects.',
         requiredContext: PLAN_REVIEWER_CONTEXT,
         schemaTarget: {
             kind: 'structured_json',
@@ -179,7 +213,8 @@ export const PROMPT_SPECS = [
         providerVariants: SHARED_PROVIDER_VARIANTS,
         evaluationNotes: [
             'Render tests should assert the reviewer prompt requires executionShape confirmation.',
-            'Render tests should assert shared adversarial plan-readiness posture and verification skepticism without adding implementation diff-review instructions.',
+            'Render tests should assert independent material plan review without adding implementation diff-review instructions or exhaustive detail requirements.',
+            'Reviewer tests should distinguish requested-change correctness from incomplete enforcement of broader guarantees introduced by the plan.',
             'Fixture cases should cover ordinary plans and derived plans.',
         ],
         firstMigrationPriority: 1,
@@ -202,8 +237,7 @@ export const PROMPT_SPECS = [
                         field('planDoc', 'prompt_argument', true, 'Path to the plan artifact under review.'),
                         field('round', 'orchestrator_state', true, 'Plan-review round number.'),
                         field('reviewMarkdownPath', 'run_artifact', true, 'Review history artifact path.'),
-                        field('inlineContext', 'repository_state', false, "Optional Neal-inlined plan/review-history context; only valid with the 'no-read' access mode, whose prompt contains no repository-access instructions."),
-                        field('accessMode', 'orchestrator_state', false, "Optional explicit doctrine access mode ('tool-access', 'read-only', or 'no-read'); when absent the builder derives 'no-read' from inline-context presence, else 'tool-access'."),
+                        field('accessMode', 'orchestrator_state', false, "Optional explicit doctrine access mode ('tool-access' or 'read-only'); defaults to 'tool-access' when absent."),
                     ]),
                 },
                 schemaTarget: {
@@ -226,8 +260,7 @@ export const PROMPT_SPECS = [
                         field('planDoc', 'prompt_argument', true, 'Path to the derived plan artifact under review.'),
                         field('parentPlanDoc', 'prompt_argument', false, 'Path to the parent plan artifact.'),
                         field('derivedFromScopeNumber', 'orchestrator_state', false, 'Parent scope number that the derived plan replaces.'),
-                        field('inlineContext', 'repository_state', false, "Optional Neal-inlined derived-plan/parent-plan/review-history context; only valid with the 'no-read' access mode, whose prompt contains no repository-access instructions."),
-                        field('accessMode', 'orchestrator_state', false, "Optional explicit doctrine access mode ('tool-access', 'read-only', or 'no-read'); when absent the builder derives 'no-read' from inline-context presence, else 'tool-access'."),
+                        field('accessMode', 'orchestrator_state', false, "Optional explicit doctrine access mode ('tool-access' or 'read-only'); defaults to 'tool-access' when absent."),
                     ]),
                 },
                 schemaTarget: {
@@ -241,6 +274,13 @@ export const PROMPT_SPECS = [
     },
     {
         id: 'scope_coder',
+        version: 1,
+        changelog: [
+            {
+                version: 1,
+                renderSha: 'c579d65db51be90fa81dbe3b7dd260083bc4960cc4cba32ccf2cd802d19703bc',
+            },
+        ],
         role: 'coder',
         purpose: 'Execute exactly one bounded implementation scope and respond to in-scope review feedback without starting new scopes.',
         requiredContext: SCOPE_CODER_CONTEXT,
@@ -343,6 +383,17 @@ export const PROMPT_SPECS = [
     },
     {
         id: 'scope_reviewer',
+        version: 2,
+        changelog: [
+            {
+                version: 1,
+                renderSha: '38a19da2b70dc10f6f4d8c4b955ece084bbe6e1291151de9c557dca194411386',
+            },
+            {
+                version: 2,
+                renderSha: '431a75ad341a531535606af607187239a31d12cf921575eb17774b317ad639a0',
+            },
+        ],
         role: 'reviewer',
         purpose: 'Review execute-scope results for correctness, verification coverage, and meaningful progress toward the active parent objective.',
         requiredContext: SCOPE_REVIEWER_CONTEXT,
@@ -396,8 +447,7 @@ export const PROMPT_SPECS = [
                         field('reviewMarkdownPath', 'run_artifact', true, 'Review history artifact path.'),
                         field('parentScopeLabel', 'orchestrator_state', true, 'Active parent objective label.'),
                         field('scratchDir', 'run_artifact', true, 'Run-local scratch directory for reviewer verification artifacts.'),
-                        field('inlineContext', 'repository_state', false, "Optional Neal-inlined diff/plan/review-history context; only valid with the 'no-read' access mode, whose prompt contains no repository-access instructions."),
-                        field('accessMode', 'orchestrator_state', false, "Optional explicit doctrine access mode ('tool-access', 'read-only', or 'no-read'); when absent the builder derives 'no-read' from inline-context presence, else 'tool-access'."),
+                        field('accessMode', 'orchestrator_state', false, "Optional explicit doctrine access mode ('tool-access' or 'read-only'); defaults to 'tool-access' when absent."),
                     ]),
                 },
                 schemaTarget: {
@@ -432,6 +482,13 @@ export const PROMPT_SPECS = [
     },
     {
         id: 'completion_coder',
+        version: 1,
+        changelog: [
+            {
+                version: 1,
+                renderSha: 'f88b43d206de28212ad7f6f3ae84576718934b0a5e36953e35afee89c4d7ce5e',
+            },
+        ],
         role: 'coder',
         purpose: 'Summarize whole-plan completion state in compact structured JSON.',
         requiredContext: COMPLETION_CODER_CONTEXT,
@@ -485,6 +542,17 @@ export const PROMPT_SPECS = [
     },
     {
         id: 'completion_reviewer',
+        version: 2,
+        changelog: [
+            {
+                version: 1,
+                renderSha: 'e5d104d46899f01cf69db9d2e6d109aa32d0faf645d6d908aae443558900a131',
+            },
+            {
+                version: 2,
+                renderSha: 'cc06cea4a8de6366f07a6943718fc1ae219e4c9092a5cf52542fa9de0caa02da',
+            },
+        ],
         role: 'reviewer',
         purpose: 'Judge whole-plan completion and decide whether Neal should accept completion, continue execution, or block for operator input.',
         requiredContext: COMPLETION_REVIEWER_CONTEXT,
@@ -529,8 +597,7 @@ export const PROMPT_SPECS = [
                         field('packet', 'orchestrator_state', true, 'Whole-plan completion packet.'),
                         field('summary', 'review_history', true, 'Coder-authored completion summary.'),
                         field('scratchDir', 'run_artifact', true, 'Run-local scratch directory for final-completion reviewer artifacts.'),
-                        field('inlineContext', 'repository_state', false, "Optional Neal-inlined aggregate-diff/plan context; only valid with the 'no-read' access mode, whose prompt contains no repository-access instructions."),
-                        field('accessMode', 'orchestrator_state', false, "Optional explicit doctrine access mode ('tool-access', 'read-only', or 'no-read'); when absent the builder derives 'no-read' from inline-context presence, else 'tool-access'."),
+                        field('accessMode', 'orchestrator_state', false, "Optional explicit doctrine access mode ('tool-access' or 'read-only'); defaults to 'tool-access' when absent."),
                     ]),
                 },
                 schemaTarget: {
@@ -542,7 +609,145 @@ export const PROMPT_SPECS = [
             },
         ],
     },
+    {
+        id: 'consultant',
+        version: 1,
+        changelog: [
+            {
+                version: 1,
+                renderSha: '42e41552be1e8cceb0596a26f09892e13cc31adf07e58479d939d289c8b469e3',
+            },
+        ],
+        role: 'reviewer',
+        purpose: 'Triage a blocked Neal run entirely from Neal-inlined context and decide whether the block is an in-scope recoverable misunderstanding or a genuine wall that must escalate to a human.',
+        requiredContext: CONSULTANT_CONTEXT,
+        schemaTarget: {
+            kind: 'structured_json',
+            schemaBuilder: 'buildConsultantSchema',
+            parser: 'validateConsultantVerdictPayload',
+            providerSurface: 'neal_json_block_protocol',
+        },
+        baseInstructions: {
+            kind: 'builder',
+            modulePath: 'src/neal/agents/prompts.ts',
+            exportName: 'buildConsultantPrompt',
+            inputShape: context('BuildConsultantPromptArgs', [
+                field('blockedReason', 'prompt_argument', true, 'Blocked reason string.'),
+                field('inlineContext', 'repository_state', true, 'Neal-inlined adjudication context.'),
+            ]),
+        },
+        providerVariants: SHARED_PROVIDER_VARIANTS,
+        evaluationNotes: [
+            'Render tests should assert the consultant judges entirely from inlined context and its static instructions carry no repository-access phrasing.',
+            'A golden render test pins the exact prompt bytes, including the ALL-CAPS emphasis lines.',
+        ],
+        firstMigrationPriority: 3,
+        currentHome: 'mixed',
+        ownershipNotes: [
+            'Prompt spec owns the consultant instructions and required context only; anti-thrash guarding, recovery routing, and verdict persistence stay in src/neal/adjudicator/ outside the prompt-spec library.',
+        ],
+        variants: [
+            {
+                kind: 'primary',
+                status: 'adjacent',
+                description: 'Read-only blocked-run adjudication round.',
+                currentRoundEntrypoints: ['runConsultantRound'],
+                baseInstructions: {
+                    kind: 'builder',
+                    modulePath: 'src/neal/agents/prompts.ts',
+                    exportName: 'buildConsultantPrompt',
+                    inputShape: context('BuildConsultantPromptArgs', [
+                        field('blockedReason', 'prompt_argument', true, 'Blocked reason string.'),
+                        field('inlineContext', 'repository_state', true, 'Neal-inlined adjudication context.'),
+                    ]),
+                },
+                schemaTarget: {
+                    kind: 'structured_json',
+                    schemaBuilder: 'buildConsultantSchema',
+                    parser: 'validateConsultantVerdictPayload',
+                    providerSurface: 'neal_json_block_protocol',
+                },
+            },
+        ],
+    },
 ];
+// SHA-256 of `text` as lowercase hex. Used to pin the render matrix (via the
+// changelog `renderSha`) and, in the render-integrity test, the builder-module
+// source tripwire.
+export function sha256Hex(text) {
+    return createHash('sha256').update(text, 'utf8').digest('hex');
+}
+// Canonical, order-independent serialization of a render matrix. Each cell is a
+// `{ key, render }` pair; cells are sorted by `key` and joined as
+// `=== <key> ===\n<render>\n` blocks so the output is deterministic regardless
+// of generation order and stays human-diffable in the versioned goldens.
+export function serializeRenderMatrix(cells) {
+    return [...cells]
+        .sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0))
+        .map((cell) => `=== ${cell.key} ===\n${cell.render}\n`)
+        .join('');
+}
+// Structural validation of a spec's integer version and sha-anchored changelog.
+// This is format/shape enforcement only; it does not compare the recorded
+// `renderSha` against any live render (that is verifyRenderVersionContract's
+// job) so it can run cheaply at module load for every spec.
+export function validatePromptSpecVersioning(spec) {
+    const { id, version, changelog } = spec;
+    if (!Number.isSafeInteger(version) || version < 1) {
+        throw new Error(`Prompt spec ${id} version must be a safe integer >= 1, received ${String(version)}`);
+    }
+    if (changelog.length === 0) {
+        throw new Error(`Prompt spec ${id} changelog must not be empty`);
+    }
+    let previousVersion = 0;
+    for (const entry of changelog) {
+        if (!Number.isSafeInteger(entry.version) || entry.version < 1) {
+            throw new Error(`Prompt spec ${id} changelog entry version must be a safe integer >= 1, received ${String(entry.version)}`);
+        }
+        if (entry.version <= previousVersion) {
+            throw new Error(`Prompt spec ${id} changelog entry versions must be strictly increasing, received ${entry.version} after ${previousVersion}`);
+        }
+        previousVersion = entry.version;
+        if (!/^[0-9a-f]{64}$/.test(entry.renderSha)) {
+            throw new Error(`Prompt spec ${id} changelog entry renderSha must be 64-char lowercase hex, received ${entry.renderSha}`);
+        }
+    }
+    const last = changelog[changelog.length - 1];
+    if (last.version !== version) {
+        throw new Error(`Prompt spec ${id} last changelog entry version ${last.version} must equal spec version ${version}`);
+    }
+}
+// Internal-consistency and change-visibility contract over a spec's live render
+// matrix and its versioned goldens. Throws when the last changelog entry does
+// not match the spec version, when the live matrix sha does not match the last
+// recorded `renderSha`, or when any changelog entry's golden is missing or does
+// not hash to its recorded `renderSha`. This is not tamper evidence: an author
+// who edits the live render, the golden, and the recorded sha together produces
+// an internally consistent state that passes here; catching that coordinated
+// same-version repin is the documented review/CI append-only rule, not this
+// unit contract.
+export function verifyRenderVersionContract(args) {
+    const { specId, version, changelog, liveMatrix, readGolden } = args;
+    const last = changelog[changelog.length - 1];
+    if (!last || last.version !== version) {
+        throw new Error(`Prompt spec ${specId} last changelog entry version ${String(last?.version)} must equal spec version ${version}`);
+    }
+    const liveSha = sha256Hex(liveMatrix);
+    if (liveSha !== last.renderSha) {
+        throw new Error(`Prompt spec ${specId} live render matrix sha ${liveSha} does not match recorded renderSha ${last.renderSha} for version ${version}. ` +
+            'The render changed: re-audit the builder axes, bump the version, add a new versioned golden, and re-pin the recorded renderSha.');
+    }
+    for (const entry of changelog) {
+        const golden = readGolden(entry.version);
+        if (golden === undefined) {
+            throw new Error(`Prompt spec ${specId} is missing the versioned golden for version ${entry.version}`);
+        }
+        const goldenSha = sha256Hex(golden);
+        if (goldenSha !== entry.renderSha) {
+            throw new Error(`Prompt spec ${specId} golden for version ${entry.version} sha ${goldenSha} does not match recorded renderSha ${entry.renderSha}`);
+        }
+    }
+}
 function getContractFieldKeys(contract) {
     return new Set(contract.fields.map((field) => field.key));
 }
@@ -555,6 +760,7 @@ function validateBuilderInputShape(spec, builder, label) {
 }
 function validatePromptSpecContracts(specs) {
     for (const spec of specs) {
+        validatePromptSpecVersioning(spec);
         validateBuilderInputShape(spec, spec.baseInstructions, 'baseInstructions');
         for (const variant of spec.variants) {
             validateBuilderInputShape(spec, variant.baseInstructions, `variant ${variant.kind}/${variant.baseInstructions.exportName}`);

package/dist/neal/providers/agent-settings-isolation.js

@@ -0,0 +1,35 @@
+/**
+ * Whether neal-driven agent runs should be isolated from the operator's
+ * interactive agent config.
+ *
+ * The native adapters drive the Codex and Claude SDKs, which by default load
+ * the operator's own config — the Codex `notify` hook, the Claude
+ * `Stop`/`Notification` hooks, `CLAUDE.md`, permissions. In normal use
+ * (pipeline, local `neal go`) that is correct: it is the operator's machine
+ * and their configured agent behavior, so neal honors it.
+ *
+ * The one exception is the compat qualification harness (`neal compat`, which
+ * `scripts/qualify-sdk.sh` drives). It is a hermetic, repeatable capability
+ * probe that runs the whole planner/coder/reviewer matrix — many turns — and
+ * must not fire the operator's per-turn notifier hooks or let ambient config
+ * skew the verdict. So `runCompat` turns isolation ON for its process, and the
+ * native adapters read it here.
+ *
+ * A process-level env flag (matching NEAL_STOP_AFTER_CURRENT_SCOPE_FILE /
+ * NEAL_GUIDANCE_DIR) rather than a threaded option, because compat drives the
+ * adapters through the full orchestrator, and the flag would otherwise have to
+ * cross every layer between the command and adapter construction.
+ */
+const ISOLATION_ENV_FLAG = 'NEAL_ISOLATE_AGENT_SETTINGS';
+export function enableAgentSettingsIsolation() {
+    process.env[ISOLATION_ENV_FLAG] = '1';
+}
+// Symmetric off switch. Production only ever enables (compat, once), but tests
+// that exercise the isolated path need a clean teardown so the process-level
+// flag does not leak into sibling tests.
+export function disableAgentSettingsIsolation() {
+    delete process.env[ISOLATION_ENV_FLAG];
+}
+export function agentSettingsIsolated() {
+    return process.env[ISOLATION_ENV_FLAG] === '1';
+}