fix(rails): close review guidance and coverage gaps (#1873)

packages/bus/src/refusals.mjs

@@ -49,9 +49,14 @@ group(
   "Ask the owner to inspect the scoped access and binding state through the supported access controls; do not supply credentials in a call or widen your own grants."
 );
 group(
-  "confirm-required outcome-unknown outcome-unknown-revoked revision-conflict revision-conflict-revoked",
+  "outcome-unknown outcome-unknown-revoked revision-conflict revision-conflict-revoked",
   "R2/R3: current revision and verified effect",
-  "Read the latest status, revision and receipts before retrying. Obtain the required confirmation through the supported human path."
+  "Read the latest status, revision and receipts before retrying. Verify whether an uncertain effect already happened, and use the current revision for any new attempt."
+);
+group(
+  "confirm-required",
+  "R2/R3: explicit confirmation of the current operation",
+  "Read the current status and obtain the required confirmation through the supported human path."
 );
 group(
   "decision-closed decision-consumed decision-mismatch decision-not-approved decision-not-eligible decision-not-found decision-not-held decision-stale supersede-refused",
@@ -79,10 +84,15 @@ group(
   "Read the permitted configuration/status and ask the owner or configured chief to repair it through the supported path. Do not edit policy to bypass the refusal."
 );
 group(
-  "field-writer task-already-archived task-archived task-conflict task-create-conflict task-create-uncertain task-not-archived task-not-found task-position-full task-project-refused task-required task-scope-required task-subject-required",
+  "field-writer task-already-archived task-archived task-conflict task-create-conflict task-create-uncertain task-not-archived task-not-found task-position-full task-project-refused task-scope-required task-subject-required",
   "Role task ownership, allowed fields and current task state",
   "Read the current task and assigned role. Use the permitted task operation with current evidence; ask the PM for scope or assignment changes through the decision path."
 );
+group(
+  "task-required",
+  "Role decisions: a blocking decision belongs to a task",
+  "Supply the task_ref for this work, or raise with blocking false when there is no task."
+);
 group(
   "fork-foreign gitea-admin-unavailable gitea-failed gitea-not-configured gitea-not-declared host-busy host-changed host-creative-role host-enrolled host-failed host-in-use host-key-mismatch host-line-left host-not-configured host-not-declared host-not-enrolled host-not-granted host-not-ready host-remove-failed host-unknown publish-busy publish-unknown",
   "Role access: declared service, host or remote and verified outcome",
@@ -158,6 +168,73 @@ group(
   "R3/role tools: bounded protocol and available capacity",
   "Check the tool schema and narrow oversized requests. For a timeout, inspect status and receipts before retrying; never assume an uncertain operation did not happen."
 );
+// Finite error vocabularies forwarded by the project's, library's and request's
+// typed adapters are part of the same table, not an unhelpful unknown-code path.
+group(
+  "project-busy library-sync-busy",
+  "Role storage: exclusive write or sync already in progress",
+  "Wait for the current operation to finish, read its status, then retry once the lock is clear."
+);
+group(
+  "stale-base library-accept-stale",
+  "R2/R3: current file or served revision",
+  "Read the latest file or library status and its current revision. Reconcile the intended change before retrying with that base; never overwrite a newer change blindly."
+);
+group(
+  "citation-cross-universe citation-invalid citation-missing citation-unavailable citation-unfetched citations-over-limit playground-cited-as-canon reply-invalid",
+  "Role replies: validated citations, provenance and scope",
+  "Use permitted library, spec or web reads and supply a valid reply with current citations in the allowed universe and scope. Narrow oversized citation lists; never invent provenance."
+);
+group(
+  "invalid-request-admission invalid-request-effect invalid-request-event invalid-request-plan invalid-request-projects artifact-path-invalid artifact-type-refused",
+  "R3: typed request plan, delivery and evidence schema",
+  "Check the current request's tool schema and correct the plan, artifact path or evidence. Delivery requires the supported self-contained HTML artifact and matching verification evidence."
+);
+group(
+  "prd-admission-revoked prd-author-invalid prd-candidate-invalid prd-candidate-required prd-candidate-size prd-candidate-stale prd-requirement-invalid",
+  "Role PRD workflow: current candidate, authors and admission",
+  "Read the current request, candidate, requirements, mode and approval. Ask the PM to correct or submit the current candidate through the supported workflow; never approve your own authorship."
+);
+group(
+  "request-question-open request-question-closed request-question-mismatch request-phase-refused request-attachment-mismatch request-delivery-required request-document-refused",
+  "Role request workflow: current phase, question and selected attachment",
+  "Read intake_status and follow its current question, wait or delivery step. A pending question needs its answer before another question; use only the operation and attachment valid for the current phase."
+);
+group(
+  "request-effect-conflict request-effect-unprepared request-mode-revision-conflict request-operation-conflict request-plan-binding-refused request-plan-path-collision request-plan-path-refused request-project-collision",
+  "R2/R3: current request revision and bound operation",
+  "Read the current request status, plan and operation receipts. Recover an existing operation before retrying; use a new operation ID only for a new intended operation, and never bypass a path or project collision."
+);
+group(
+  "request-notification-unavailable request-services-unavailable library-credential-missing library-human-missing library-mapping-invalid library-problem-code library-remote-invalid library-state-invalid library-diverged library-accept-invalid",
+  "R1/R3: owner-configured service, mapping and accepted library state",
+  "Read the supported service or library status and ask the owner to repair the missing binding, mapping or accepted state. Check existing operation receipts before retrying an uncertain effect."
+);
+group(
+  "library-commit library-git library-push-failed project-commit-uncertain project-init-cleanup",
+  "R2/R3: verified repository effect and recovery",
+  "Read current repository status and receipts to determine what already happened. Report an uncertain commit, push or cleanup to the owner before any new write; do not retry an uncertain effect blindly."
+);
+group(
+  "project-author project-dirty project-git project-id project-invalid project-no-commit project-not-declared project-not-empty project-path project-read-commit project-read-content project-read-missing project-read-path project-record-path project-records-conflict project-records-missing project-remote project-repository tester-project-area",
+  "Role project scope: declared repository, clean state and allowed paths",
+  "Read the permitted project status and file metadata. Correct the declared project or allowed path when possible; ask the owner to repair repository state or identity. Preserve existing changes and never bypass repository or path checks."
+);
+group(
+  "project-record-unchanged",
+  "R2: no new record effect for unchanged content",
+  "Read the current record and its existing commit receipt. If it already matches the intended content, use that evidence instead of retrying the same write."
+);
+group(
+  "library-write-story-path library-revert-not-agent",
+  "Role library writes: supporting paths and permitted agent-owned commits",
+  "Use only the supporting paths and agent-owned commit reversals permitted by the library tool. Preserve story and canon files; ask the owner when the requested edit is outside that scope."
+);
+group(
+  "query-argument-invalid query-chapter-ambiguous query-item-too-large query-universe-unknown",
+  "Role library reads: known universe, unambiguous selection and bounded result",
+  "Read the permitted library index, choose a known universe and an unambiguous book or chapter, and narrow the query or requested range before retrying."
+);
 export const REFUSALS = Object.freeze(Object.fromEntries(entries));
 const UNKNOWN = Object.freeze({ rail: "R3: fail closed", nextStep: "Report the refusal code to the responsible owner and inspect supported status; do not bypass the refusal." });
 export const refusalGuidance = code => Object.hasOwn(REFUSALS, code) ? REFUSALS[code] : UNKNOWN;

packages/bus/tests/rails.test.mjs

@@ -1,6 +1,6 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
-import { mkdtempSync, rmSync, readFileSync, writeFileSync } from 'node:fs';
+import { mkdtempSync, rmSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
 import { connect } from 'node:net';
@@ -14,6 +14,7 @@ import { Client } from '../src/client.mjs';
 import { resolveInstance, validateBusinessDocument } from '../../organization/src/index.mjs';
 import { businessDoc, REPO_ROLES, systemFor } from '../../organization/tests/helpers.mjs';
 import { railsText } from '../../organization/src/rails.mjs';
+import { GUARD_CODES } from '../../library/src/reply-protocol.mjs';
 const SECRET = 'sk-test-NOT-A-SECRET-1234';
 function fixture(t) {
   const root = mkdtempSync(join(tmpdir(), 'rails-'));
@@ -80,6 +81,16 @@ test('cross-role refusal envelope names its rail and next step without changing
   const cross = await raw(path, { cap: f.cap, verb: 'decision.resolve', args: { id: decision.id, choice: 'yes' } });
   assert.equal(cross.error, 'not-resolver'); assert.match(cross.rail, /resolve right/); assert.match(cross.nextStep, /routed resolver/);
   assert.equal(f.store.get('SELECT count(*) n FROM decision_events WHERE decision=?', decision.id).n, 0);
+  // Exercise an actual cross-role action without its required decision, not just resolve.
+  const live = busOrganization(f.business, f.resolved);
+  live.roles.coder.authority.crossRole.push('role.end');
+  f.broker.reloadBusiness('acme', live);
+  const decisions = f.store.get('SELECT count(*) n FROM decisions').n;
+  const required = await raw(path, { cap: f.cap, verb: 'role.revoke', args: { role: 'reviewer', reason: SECRET } });
+  assert.equal(required.ok, false); assert.equal(required.error, 'decision-required');
+  assert.deepEqual({ rail: required.rail, nextStep: required.nextStep }, REFUSALS['decision-required']);
+  assert.ok(!JSON.stringify(required).includes(SECRET));
+  assert.equal(f.store.get('SELECT count(*) n FROM decisions').n, decisions);
 });
 
 test('every literal fail branch in broker has static guidance; guidance never contains payload values', () => {
@@ -105,7 +116,7 @@ test('every literal fail branch in broker has static guidance; guidance never co
     assert.equal(depth, 0, 'balanced fail call');
   }
   // Finite delegated fail(code) sources must be covered as well as literal branches.
-  for (const code of [...PROXY_PAGE_CODES, 'remote-host-mismatch', 'remote-not-fork',
+  for (const code of [...PROXY_PAGE_CODES, ...GUARD_CODES, 'project-busy', 'remote-host-mismatch', 'remote-not-fork',
     'processing-control-unsafe', 'processing-uninitialized', 'processing-generation-changed']) {
     assert.ok(Object.hasOwn(REFUSALS, code), code);
   }
@@ -116,3 +127,21 @@ test('every literal fail branch in broker has static guidance; guidance never co
   }
   assert.deepEqual(refusalGuidance(SECRET), refusalGuidance('unknown-external-code'));
 });
+
+test('finite forwarded project, library and request errors have static next steps', () => {
+  const modules = [
+    ...['index', 'git', 'paths'].map(name => new URL(`../../project/src/${name}.mjs`, import.meta.url)),
+    ...readdirSync(new URL('../../library/src/', import.meta.url)).filter(f => f.endsWith('.mjs'))
+      .map(name => new URL(`../../library/src/${name}`, import.meta.url)),
+    ...['request-store', 'request-lifecycle'].map(name => new URL(`../src/${name}.mjs`, import.meta.url)),
+  ];
+  for (const file of modules) {
+    const source = readFileSync(file, 'utf8');
+    for (const match of source.matchAll(/\b(?:new\s+(?:ProjectError|LibraryError|RequestError|GuardError)|raise|refuse|fail)\s*\(\s*['"]([a-z][a-z0-9-]*)['"]/g)) {
+      assert.ok(Object.hasOwn(REFUSALS, match[1]), `${file.pathname}: ${match[1]}`);
+    }
+  }
+  assert.doesNotMatch(REFUSALS['outcome-unknown'].nextStep, /confirmation|human/);
+  assert.doesNotMatch(REFUSALS['revision-conflict'].nextStep, /confirmation|human/);
+  assert.match(REFUSALS['task-required'].nextStep, /task_ref.*blocking false/);
+});

packages/harness/tests/rails.test.mjs

@@ -52,3 +52,11 @@ test('fixed domains, arbiter self-raises and hard waits describe existing routes
     { action: 'policy.change', routes: [{ domain: 'delivery', to: 'pm' }] },
   ]);
 });
+
+test('hire and fire are unavailable to a chief that is not the configured launcher', t => {
+  const { rails } = resolvedFor(t, 'chief', doc => { delete doc.launch; });
+  for (const action of ['role.hire', 'role.fire']) {
+    assert.deepEqual(rails.actions.find(a => a.action === action).routes, [{ to: 'unavailable' }]);
+  }
+  assert.match(railsText(rails), /role.hire: unavailable here; only the configured chief can hire or fire/);
+});

packages/organization/src/rails.mjs

@@ -13,9 +13,10 @@ export function ownRails({ instance, authority, network, credentials = [], messa
   const actions = [];
   for (const [kind, held] of Object.entries(authority ?? {})) {
     for (const action of held) {
+      const chiefOnly = ['role.hire', 'role.fire'].includes(action) && launcher !== instance;
       const hard = GATED_ONLY.includes(action) || (action === 'role.launch' && launcher !== instance);
       const domains = DOMAINS[action] ? [DOMAINS[action]] : ['delivery', 'technical'];
-      const routes = hard ? [{ to: 'human' }] : kind === 'withinRole' ? [{ to: 'alone' }]
+      const routes = chiefOnly ? [{ to: 'unavailable' }] : hard ? [{ to: 'human' }] : kind === 'withinRole' ? [{ to: 'alone' }]
         : domains.map(domain => ({ domain, to: arbiters[domain] === instance ? 'human' : arbiters[domain] ?? 'unconfigured' }));
       actions.push({ action, routes });
     }
@@ -36,7 +37,7 @@ export function ownRails({ instance, authority, network, credentials = [], messa
 export function railsText(rails) {
   const lines = ['## Your rails', '', 'These are your resolved rails. Call my_rails for the current rails after a narrowing.'];
   for (const { action, routes } of rails.actions) {
-    const route = routes.map(({ domain, to }) => `${domain ? `${domain}${domain === 'delivery' && routes.length > 1 ? ' (default)' : ''}: ` : ''}${to === 'human' ? 'a person' : to === 'alone' ? 'alone' : to === 'unconfigured' ? 'unconfigured; report missing arbiter' : `arbiter instance ${JSON.stringify(to)}`}`).join('; ');
+    const route = routes.map(({ domain, to }) => `${domain ? `${domain}${domain === 'delivery' && routes.length > 1 ? ' (default)' : ''}: ` : ''}${to === 'human' ? 'a person' : to === 'alone' ? 'alone' : to === 'unavailable' ? 'unavailable here; only the configured chief can hire or fire' : to === 'unconfigured' ? 'unconfigured; report missing arbiter' : `arbiter instance ${JSON.stringify(to)}`}`).join('; ');
     lines.push(`- ${action}: ${route}.`);
   }
   if (!rails.actions.length) lines.push('- Held actions: none.');