@awebai/oats 0.27.2 → 0.28.0

package/capabilities/oats-okf/lib/io.mjs

@@ -57,9 +57,16 @@ export function materialize(root, files) {
   safePath(root); fs.mkdirSync(root, { recursive: true });
   for (const [p, content] of Object.entries(files)) atomic(join(root, relPath(p)), Buffer.from(content, 'base64'));
 }
-export function withLock(path, fn) {
+const pause = ms => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+/** Cooperative directory lock. `waitMs` lets a reader queue behind a live
+ *  holder for a bounded time; an abandoned lock is still never reclaimed. */
+export function withLock(path, fn, { waitMs = 0 } = {}) {
   safePath(path); fs.mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
-  try { fs.mkdirSync(path, { mode: 0o700 }); } catch(e) { if(e.code === 'EEXIST') fail('E_LOCKED', `busy or abandoned lock: ${path}; inspect owner.json, never reclaim by age`); throw e; }
+  const deadline = Date.now() + waitMs;
+  for (let delay = 20;; delay = Math.min(delay * 2, 250)) {
+    try { fs.mkdirSync(path, { mode: 0o700 }); break; }
+    catch(e) { if(e.code !== 'EEXIST') throw e; if(Date.now() >= deadline) fail('E_LOCKED', `busy or abandoned lock: ${path}; inspect owner.json, never reclaim by age`); pause(delay); }
+  }
   const owner = { token: randomUUID(), pid: process.pid, host: hostname() };
   save(join(path, 'owner.json'), owner);
   try { return fn(); } finally { if (readJSON(join(path, 'owner.json')).token === owner.token) { fs.rmSync(path, { recursive: true }); syncDir(dirname(path)); } }

package/capabilities/oats-okf/lib/sources.mjs

@@ -1,7 +1,7 @@
 import { randomUUID } from 'node:crypto';
-import { fs, join, dirname, resolve, safePath, readJSON, save, atomic, materialize, hash, withLock, oats, fail, tree, overlaps, syncDir, identifier, relPath } from './io.mjs';
-import { loadBindings, declaration, metadata, resolveNodes, bindingFingerprint, settings, validateBindings } from './config.mjs';
-import { stageBase } from './stores.mjs';
+import { fs, join, dirname, resolve, safePath, readJSON, save, atomic, hash, withLock, oats, fail, tree, overlaps, identifier } from './io.mjs';
+import { loadBindings, declaration, bindingFingerprint, settings, validateBindings } from './config.mjs';
+import { acceptedResolution } from './consult.mjs';
 import { loadInvocationKnowledgeBinding, readPrivateInvocationJson, sourceRuntimeFromKnowledgeBinding } from './binding-wire.mjs';
 import { sameJson } from './portable-binding.mjs';
 import { qualifiedSoulIdentity } from './source-contract.mjs';
@@ -89,44 +89,14 @@ export function service(home) {
   if(fs.existsSync(join(home,'instance.json'))) return readJSON(join(home,'instance.json')).kind==='capability';
   return process.env.OATS_KIND==='capability';
 }
-// Control files live at the view root; arbitrary legal aliases live ONLY in
-// bases/. Receipts use paths relative to the view so moving a prepared view
-// into its final location cannot invalidate its navigation.
-export function views(bindings, decl, target) {
-  target=safePath(target); if(fs.existsSync(target)) fail('E_VIEW','view exists; use a new immutable view destination');
-  const all={}; const receipts={};
-  fs.mkdirSync(dirname(target),{recursive:true});
-  const pending=fs.mkdtempSync(join(dirname(target),'.okf-view-'));
-  try {
-    for(const [alias,base] of Object.entries(bindings.bases)) {
-      const scratch=fs.mkdtempSync(join(bindings.stateDir,'read-'));
-      try {
-        const staged=stageBase(base,join(scratch,'base'),{alias});
-        all[alias]=staged.meta;
-        const path=`bases/${alias}`;
-        materialize(join(pending,path),staged.files);
-        receipts[alias]={path,id:base.id,digest:staged.digest,head:staged.head || null,nodes:staged.meta.nodes};
-      } finally { fs.rmSync(scratch,{recursive:true,force:true}); }
-    }
-    resolveNodes(decl,bindings,all);
-    save(join(pending,'view.json'),{version:1,at:new Date().toISOString(),bases:receipts,owns:decl.owns,reads:decl.reads});
-    // Never expose a partial view or remove/replace a caller's existing view.
-    if(fs.existsSync(target)) fail('E_VIEW','view exists; use a new immutable view destination');
-    fs.renameSync(pending,target);syncDir(dirname(target));
-    return receipts;
-  } finally { fs.rmSync(pending,{recursive:true,force:true}); }
-}
-const registrationView = source => join(source.home,`.okf-view-${source.id}`);
+// okf 3.0.0 materializes no instance copy of any base: registration records
+// the accepted resolution (per base: commit or digest, and its nodes) and the
+// instance consults the bases remotely through `oats okf`. A ./knowledge/ left
+// by okf 2.x is not touched; inspect reports it as a legacy local view.
+const acceptedNodes = view => Object.fromEntries(Object.entries(view).map(([alias,row])=>[alias,row.nodes]));
 function finishRegistration(source) {
-  const pending=safePath(registrationView(source)),target=safePath(join(source.home,'knowledge'));
-  if(fs.existsSync(pending)) {
-    if(fs.existsSync(target)) fail('E_VIEW','knowledge already exists; refusing to replace it with the registered view');
-    fs.renameSync(pending,target);syncDir(source.home);
-  }
   // A durable home pointer precedes publication. Failures after it was saved
-  // resume this same source/view; they never reset captured evidence or IDs.
-  const receipt=readJSON(join(target,'view.json'));
-  if(source.acceptedView && JSON.stringify(receipt.bases)!==JSON.stringify(source.acceptedView)) fail('E_VIEW','registered accepted view receipt differs; preserve it and inspect');
+  // resume this same source; they never reset captured evidence or IDs.
   for(const [p,text] of [['STATE.md','# Working state\n\n# Task\n\n# Next\n'],['log.md','# Instance log\n']]) if(!fs.existsSync(join(source.home,p))) atomic(join(source.home,p),text);
   fs.mkdirSync(join(source.home,'notes'),{recursive:true});
   scheduleSource(source);return source;
@@ -155,8 +125,6 @@ export function registerCaptured(home,receipt) {
     const source=homeSource(home);if(!sameCapturedReceipt(source,receipt,captured)) fail('E_SOURCE','captured registration receipt differs from durable source');
     return finishRegistration(source);
   }
-  safePath(join(home,'knowledge'));
-  if(fs.existsSync(join(home,'knowledge'))) fail('E_VIEW','unregistered knowledge view exists; preserve it and inspect before registering');
   if(['.okf-harvest-record.json','.okf-harvest-record.next.json'].some(path=>fs.existsSync(join(home,path)))) fail('E_MIGRATION','legacy source watermarks require explicit migration before captured registration');
   if(overlaps(home,captured.context) && captured.context.startsWith(home)) fail('E_PATH','captured deployment context cannot be in disposable home');
   const {file:bindingsFile,...bindingsDoc}=captured.binding.bindings;
@@ -167,13 +135,13 @@ export function registerCaptured(home,receipt) {
     bindingFingerprint:bindingFingerprint(bindings),execution:captured.binding.execution,providerBinding:JSON.parse(JSON.stringify(receipt.binding)),
     registration:{schemaVersion:1,kind:'captured'},sourceIdentity:captured.sourceIdentity,executionBinding:captured.execution,
     responsibleHuman:captured.responsibleHuman,created:new Date().toISOString()};
-  const file=join(dir,'source.json'),pending=registrationView(source);fs.mkdirSync(dir,{recursive:true,mode:0o700});
+  const file=join(dir,'source.json');fs.mkdirSync(dir,{recursive:true,mode:0o700});
   try {
-    source.acceptedView=views(bindings,source.decl,pending);source.acceptedNodes=Object.fromEntries(Object.entries(source.acceptedView).map(([alias,row])=>[alias,row.nodes]));
+    source.acceptedView=acceptedResolution(bindings,source.decl);source.acceptedNodes=acceptedNodes(source.acceptedView);
     save(file,source);save(join(dir,'status.json'),{version:1,captured:{notes:[],threads:{},inputs:[]},processed:[],delivered:{},accepted:{},retired:false,auto:true,activeRun:null});
     save(markerPath(home),{version:1,id,source:file});
   } catch(error) {
-    if(!fs.existsSync(markerPath(home))) {fs.rmSync(pending,{recursive:true,force:true});fs.rmSync(dir,{recursive:true,force:true});}
+    if(!fs.existsSync(markerPath(home))) fs.rmSync(dir,{recursive:true,force:true});
     throw error;
   }
   return finishRegistration({...source,file});
@@ -188,8 +156,6 @@ export function register(home) {
   }
   if(service(home)) return {skipped:'service'};
   if(fs.existsSync(markerPath(home))) return finishRegistration(homeSource(home));
-  safePath(join(home,'knowledge'));
-  if(fs.existsSync(join(home,'knowledge'))) fail('E_VIEW','unregistered knowledge view exists; preserve it and inspect before registering');
   if(['.okf-harvest-record.json','.okf-harvest-record.next.json'].some(p=>fs.existsSync(join(home,p))) && !fs.existsSync(join(home,'.okf-v1-migration.json'))) fail('E_MIGRATION','legacy source watermarks require explicit oats okf migrate --source-home PATH before v2 registration; no cursor is silently trusted');
   const meta=fs.existsSync(join(home,'instance.json'))?readJSON(join(home,'instance.json')):{};
   if(!process.env.OATS_SOUL) fail('E_OATS_SOUL_MISSING','OATS_SOUL is not set; oats.okf hooks and commands run only under the OATS kernel');
@@ -213,22 +179,18 @@ export function register(home) {
   if(Buffer.byteLength(role)>128*1024) fail('E_SOURCE','role document exceeds 128KiB; provide a concise role before registering');
   const source={version:1,id,home,work,context,agent,instance,owner:decl.owner,decl,role,bindings,bindingFingerprint:bindingFingerprint(bindings),execution:{runtime:settings()['harvest-runtime']||'pi',model:settings()['harvest-model']||null},created:new Date().toISOString()};
   const file=join(dir,'source.json');
-  const pending=registrationView(source);
   fs.mkdirSync(dir,{recursive:true,mode:0o700});
   try {
-    source.acceptedView=views(bindings,decl,pending);
+    source.acceptedView=acceptedResolution(bindings,decl);
     pinOwner(ownersFile,decl.owner,{id:soulId,soulName:agent,path:soul});
-    source.acceptedNodes=Object.fromEntries(Object.entries(source.acceptedView).map(([alias,r])=>[alias,r.nodes]));
+    source.acceptedNodes=acceptedNodes(source.acceptedView);
     save(file,source);
     save(join(dir,'status.json'),{version:1,captured:{notes:[],threads:{},inputs:[]},processed:[],delivered:{},accepted:{},retired:false,auto:true,activeRun:null});
     save(markerPath(home),{version:1,id,source:file});
   } catch(e) {
     // Until the pointer is durable no capture or schedule can reference these
     // files. Leave an installed pointer's state intact even if fsync failed.
-    if(!fs.existsSync(markerPath(home))) {
-      fs.rmSync(pending,{recursive:true,force:true});
-      fs.rmSync(dir,{recursive:true,force:true});
-    }
+    if(!fs.existsSync(markerPath(home))) fs.rmSync(dir,{recursive:true,force:true});
     throw e;
   }
   return finishRegistration({...source,file});

package/capabilities/oats-okf/lib/stores.mjs

@@ -7,7 +7,7 @@ import { metadata, noGit, gitTimeoutMs } from './config.mjs';
 const validator = fileURLToPath(new URL('../skills/okf/scripts/okf-validate.mjs', import.meta.url));
 // Never let local replace refs reinterpret frozen OIDs, including inside Git's
 // transport subprocesses. Override even an explicitly supplied command env.
-const gitEnv = (env = cleanEnv()) => ({...env,GIT_NO_REPLACE_OBJECTS:'1'});
+export const gitEnv = (env = cleanEnv()) => ({...env,GIT_NO_REPLACE_OBJECTS:'1'});
 export const git = (cwd,args,opts={}) => exec('git',['--no-replace-objects','-c','core.hooksPath=/dev/null','-c','protocol.ext.allow=never','-C',cwd,...args],{cwd,...opts,env:gitEnv(opts.env)});
 function baseError(code,message,base,alias,step,reason) {throw Object.assign(new Error(message),{code,base:alias,repository:base.repository,step,reason});}
 function baseRemedy(alias) {return `fix the binding for base alias "${alias}" in the bindings file, or remove the base from the bindings`;}
@@ -19,22 +19,25 @@ function classifyGitFailure(error) {
   if(/could not resolve host|failed to connect|connection refused|network is unreachable|no route to host|proxy/i.test(text)) return 'network';
   return 'unknown';
 }
-function unavailable(base,alias,step,error) {
+export function unavailable(base,alias,step,error) {
   const reason=classifyGitFailure(error),detail=reason==='unknown'?`; original Git failure: ${String(error?.message || 'unknown failure')}`:'';
   const message=`Git base "${alias}" repository "${base.repository}" is required by the deployment's bindings, but ${step} failed (reason: ${reason}${detail}); ${baseRemedy(alias)}`;
   baseError('E_BASE_UNAVAILABLE',message,base,alias,step,reason);
 }
-function requireNotShallow(base,alias,cwd) {
+export function requireNotShallow(base,alias,cwd) {
   const shallow=git(cwd,['rev-parse','--is-shallow-repository']);
   if(shallow==='true') baseError('E_BASE_SHALLOW',`Git base "${alias}" repository "${base.repository}" is required by the deployment's bindings, but the repository is shallow; oats.okf requires full accepted history before staging; ${baseRemedy(alias)}`,base,alias,'clone','shallow');
 }
-function preflightLocalRepository(base,alias) {
+export function preflightLocalRepository(base,alias) {
   if(!base.repository.startsWith('/')) return;
   if(!fs.existsSync(base.repository)) unavailable(base,alias,'clone',Object.assign(new Error('repository not found'),{code:'ENOENT'}));
   try { requireNotShallow(base,alias,base.repository); }
   catch(e) { if(e.code==='E_BASE_SHALLOW') throw e; unavailable(base,alias,'clone',e); }
 }
 export const baseLock = b => `${b.path}.okf-lock`;
+// okf consult readers hold a directory base's lock briefly; staging and
+// publication queue behind them for a bounded time instead of failing.
+const CONSULT_READER_WAIT_MS = 10000;
 export const journalPath = b => `${b.path}.okf-publication.json`;
 export function validateBase(root, base) {
   const files=tree(root,{git:base.kind==='git' && base.root==='.'}); const meta=metadata(files,base);
@@ -123,7 +126,7 @@ export function stageBase(base, dest, { alias = base.id } = {}) {
     if(fs.existsSync(journalPath(base))) fail('E_RECOVERY',`publication pending: ${journalPath(base)}; retry its recorded run before reading`);
     const result=validateBase(base.path,base); materialize(dest,result.files);
     return {...result,root:dest};
-  });
+  },{waitMs:CONSULT_READER_WAIT_MS});
 }
 export function allowedChanges(before, after, meta, owned) {
   const changed=[...new Set([...Object.keys(before),...Object.keys(after)])].filter(p=>before[p]!==after[p]);
@@ -287,7 +290,7 @@ export function directoryPublish(base, proposal, receipt, persist, { afterWrite
     receipt.status='accepted'; receipt.acceptedDigest=final.digest; receipt.acceptedAt=new Date().toISOString(); persist();
     fs.rmSync(jp); syncParent(jp);
     return receipt;
-  });
+  },{waitMs:CONSULT_READER_WAIT_MS});
 }
 function syncParent(p) { const fd=fs.openSync(dirname(p),'r'); try {fs.fsyncSync(fd);} finally {fs.closeSync(fd);} }
 function prRows(base,branch,cwd,{identity,allBases=false}={}) {
@@ -303,7 +306,7 @@ function prRows(base,branch,cwd,{identity,allBases=false}={}) {
   const raw=exec('gh',['pr','list','--repo',base.pr.repository,'--head',branch,...(allBases?[]:['--base',base.acceptedBranch]),'--state','all','--json',fields],{cwd,env:gitEnv()});
   const rows=JSON.parse(raw); if(!Array.isArray(rows)) fail('E_PR','invalid gh PR list'); return rows;
 }
-function verifyRemote(base,cwd) {
+export function verifyRemote(base,cwd) {
   for(const mode of [[],['--push']]) {
     const urls=git(cwd,['remote','get-url',...mode,'--all','origin']).split('\n');
     if(!urls.length || urls.some(url=>url!==base.repository)) fail('E_OWNER','worker changed frozen Git publication remote or effective push destination');

package/capabilities/oats-okf/lib/worker.mjs

@@ -108,7 +108,7 @@ function spawnWorker(source,run,{parent=false}={}) {
       persist(source,run);throw error;
     }
   }
-  const args=['spawn','memory-harvest','--purpose',`okf-${id}`,'--work','directory','--repo',source.context,'--dir',source.context,'--runtime',source.execution.runtime,'--no-launch','--task-file',taskFile,'--json'];
+  const args=['spawn','memory-harvest','--purpose',`okf-${id}`,'--work','directory','--repo',source.context,'--dir',source.context,harnessFlag(source),source.execution.runtime,'--no-launch','--task-file',taskFile,'--json'];
   if(!['pi','claude','codex'].includes(source.execution.runtime)) fail('E_CONFIG','invalid harvest runtime');
   if(source.execution.model) args.push('--model',source.execution.model);
   if(parent) args.push('--parent',source.instance);
@@ -123,6 +123,14 @@ function spawnWorker(source,run,{parent=false}={}) {
   finally {fs.rmSync(taskFile,{force:true});}
 }
 
+/** OATS 0.27 names the spawn harness --harness (--runtime is its deprecated
+ *  alias). Ask the kernel; an older kernel, or one that cannot answer, gets
+ *  --runtime, which every supported kernel accepts. */
+export function harnessFlag(source) {
+  let version;
+  try {version=oats(['version','--json'],source.context,{native:true,timeout:15000});} catch {return '--runtime';}
+  return Array.isArray(version?.features) && version.features.includes('harness')?'--harness':'--runtime';
+}
 function workerHome(run,source) {
   const home=safePath(run.worker.home);const meta=readJSON(join(home,'instance.json'));
   if(meta.instance!==run.worker.instance || meta.agent!=='memory-harvest' || meta.work!=='directory') fail('E_WORKER','worker receipt does not identify a directory-mode harvester');

package/capabilities/oats-okf/oats.json

@@ -1,12 +1,12 @@
 {
   "capability": "oats.okf",
   "command": "okf",
-  "version": "2.1.5",
+  "version": "3.0.0",
   "compatibility": {
-    "oats": ">=0.24.4"
+    "oats": ">=0.26.0"
   },
   "layer": "knowledge",
-  "description": "External OKF bases with owned nodes, immutable reader views, durable per-source evidence, independent workers, verified Git PR and recoverable non-Git directory delivery.",
+  "description": "External OKF bases with owned nodes, consulted remotely at their accepted state (no per-instance copy), durable per-source evidence, independent workers, verified Git PR and recoverable non-Git directory delivery.",
   "requires": [],
   "settings": {
     "harvest-runtime": {
@@ -29,6 +29,9 @@
     },
     "git-timeout": {
       "description": "Seconds allowed for each Git operation that talks to a remote (clone, fetch, push, ls-remote); default 600. Local object reads keep a short fixed limit. Raise it for large repositories behind slow links."
+    },
+    "consult-max-age": {
+      "description": "Seconds a Git base's host-cached accepted commit may age before an `oats okf` consult read refetches the accepted branch; default 300, 0 fetches on every read. `--fresh` always refetches."
     }
   },
   "agents": [
@@ -44,6 +47,12 @@
     "run-source": "bin/oats-okf.mjs run-source",
     "complete": "bin/oats-okf.mjs complete",
     "retry": "bin/oats-okf.mjs retry",
+    "bases": "bin/oats-okf.mjs bases",
+    "index": "bin/oats-okf.mjs index",
+    "cat": "bin/oats-okf.mjs cat",
+    "ls": "bin/oats-okf.mjs ls",
+    "links": "bin/oats-okf.mjs links",
+    "search": "bin/oats-okf.mjs search",
     "read": "bin/oats-okf.mjs read",
     "refresh": "bin/oats-okf.mjs refresh",
     "init": "bin/oats-okf.mjs init",
@@ -107,7 +116,7 @@
       "kind": "view",
       "command": "inspect",
       "context": "home",
-      "description": "Inspect matching live working-memory documents, durable receipts, bindings, registered view freshness and scheduler health."
+      "description": "Inspect matching live working-memory documents, durable receipts, bindings, the accepted resolution, any legacy local view and scheduler health."
     },
     "harvest": {
       "kind": "action",

package/capabilities/oats-okf/skills/okf/SKILL.md

@@ -4,11 +4,12 @@ description: >-
   Open Knowledge Format (OKF) craft: how to author, maintain, consume, and
   validate OKF knowledge bundles (directories of markdown concepts with YAML
   frontmatter, per Google Cloud's OKF v0.1 spec). Use when writing or editing
-  concepts in a knowledge/ bundle or notes/, adding or renaming concept files,
+  concepts in a knowledge bundle or notes/, adding or renaming concept files,
   updating index.md or log.md, answering questions from a bundle, triaging a
-  knowledge inbox, or when asked to validate a bundle. This skill is HOW to do
-  OKF well; instance session protocol lives in the okf AGENTS.md injection,
-  and promotion judgment in the memory-harvest skill.
+  knowledge inbox, or when asked to validate a bundle. To consult your own
+  soul's knowledge with `oats okf`, load the okf-consultation skill instead.
+  Instance session protocol lives in the okf AGENTS.md injection, and
+  promotion judgment in the memory-harvest skill.
 ---
 
 # OKF craft — author, maintain, consume
@@ -20,6 +21,13 @@ An external base is one bundle and link namespace. Owned nodes are
 nonoverlapping subdirectories, not separate root-link namespaces. Instance
 `notes/` files are task-local concepts; no knowledge lives in the soul.
 
+## Consulting your knowledge
+
+Your soul's knowledge is read remotely with `oats okf` (`index`, `cat`, `ls`,
+`links`, `search`, `bases`): there is no local copy. The **okf-consultation**
+skill teaches the procedure; load it at the start of every task and whenever
+you look something up. This skill is about the format itself.
+
 ## The format in one screen
 
 - **Concept = one file.** Concept ID = path minus `.md`. Small and specific
@@ -144,8 +152,8 @@ Those private mode-0600 files exist only for one synchronous captured invocation
 
 ## External bases and native tools
 
-Ordinary working agents consult `oats okf read --base ALIAS --path node/index.md`
-and `oats okf refresh`. When inspecting a source, treat the additive `authority`
+Ordinary working agents consult with `oats okf index` / `cat` / `search`
+(the okf-consultation skill). When inspecting a source, treat the additive `authority`
 object literally: `captured` includes recorded qualified identity/execution;
 `legacy` or `invalid` means migration/evidence is still required. A
 responsible-human status of `disabled` comes only from explicit null; `unknown`

package/capabilities/oats-okf/skills/okf-consultation/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: okf-consultation
+description: >-
+  Consulting your soul's knowledge with the `oats okf` CLI: reading its
+  external OKF bases remotely at the accepted commit (index, cat, ls, links,
+  search, bases) with no local copy, then citing what you relied on. Use when
+  starting a task or resuming after compaction, when looking up a prior
+  decision, lesson or concept, when asked "what do we know about X" or to
+  "check the knowledge base", before re-deriving a design decision, when a
+  question touches your domain, or when an `oats okf` receipt says STALE or a
+  command errors. Authoring and validating OKF bundles is the okf skill.
+---
+
+# Consulting your knowledge with `oats okf`
+
+Your soul's accumulated judgment — decisions and their rationale, lessons,
+rejected alternatives, limits — lives outside the soul, in external OKF
+**bases**. You read it remotely; nothing is copied into your home. Consulting
+it before you act is how you avoid re-deciding what was already decided.
+
+## The model
+
+- **Base / alias.** Each bound base has an alias (`oats okf bases` lists
+  them). A base is one OKF bundle and one link namespace.
+- **Node.** A subdirectory of a base with its own `index.md`. Your soul
+  **owns** some nodes (you are responsible for them) and **reads** others
+  (starting context). Neither is an access list: every bound base is readable.
+- **Accepted commit.** `oats okf` serves only a base's accepted state: the
+  accepted branch of a Git base, the in-place files of a directory base. An
+  open PR is not accepted knowledge until it is merged.
+- **Host cache, no local copy.** A Git base is read from one host-wide cache
+  that fetches file contents on first read. Your home has no `./knowledge/`
+  and no view directory. A `./knowledge/` left by okf 2.x is stale; ignore it.
+- **Receipts.** Every answer ends with `— alias@<short-oid> (fetched <age>)`.
+  With `--json`, the result carries `receipt: {base, kind, commit|digest,
+  fetchedAt, stale}`.
+
+Run every command from your instance home.
+
+## At the start of every task, and after compaction
+
+1. `oats okf index` prints your owned then read nodes' indexes, each headed
+   `## alias/node (owns|reads)`.
+2. Choose the entries relevant to *this* task by their one-line descriptions.
+3. `oats okf cat --base ALIAS /node/path.md` for each of those, and follow
+   their links only as far as the task needs (see Navigating).
+4. Write down in STATE.md which concepts shaped your plan, with their
+   citations.
+
+Do not skip this because the task looks small: prior decisions are cheapest
+to find before you have written the code that contradicts them.
+
+## Consult again while working
+
+The start-of-task read is not enough. Consult again:
+
+- **Before a design decision.** Search for the decision's subject, and read
+  any prior decision on it before choosing.
+- **Before re-deriving something.** If you are about to work out why
+  something is the way it is, search first; the rationale may be recorded.
+- **When a question touches your domain**, including a teammate's question.
+- **Before saying "we decided…" or "we tried…"**: cite it, or don't claim it.
+- **When something surprises you.** A lesson may already explain it.
+
+## Commands
+
+| Command | What it answers |
+| --- | --- |
+| `oats okf bases [--fresh]` | aliases, accepted commit, freshness, validity, your owns/reads |
+| `oats okf index [--base A] [NODE \| A/NODE]` | one node's `index.md`; no args: all your nodes; `--base A` alone: the base root index |
+| `oats okf cat --base A PATH [--from P]` | one Markdown file, in full |
+| `oats okf ls --base A [DIR]` | directory entries, each concept's `type` / `title` / `description` |
+| `oats okf links --base A PATH` | the file's outgoing links, resolved, `ok` / `MISSING` / `REFUSED` / `external` |
+| `oats okf search [--base A \| --all] [--node N] [--regex] [--case-sensitive] TEXT` | matching lines `{base, path, line, snippet}` |
+
+All take `--json`. `read --base A --path P` is the okf 2.x spelling of `cat`
+and still works.
+
+## Navigating
+
+Paths resolve like OKF links, **from the base root, not the filesystem**:
+
+- `/node/decisions/x.md` is base-root absolute (the usual form in indexes'
+  absolute links and in citations);
+- a relative link (`../lessons/y.md`, `decisions/x.md`) is relative to the file
+  it appeared in: pass that file as `--from`;
+- a bare `node/x.md` without `--from` resolves from the root.
+
+Worked example (a lesson linked from a decision):
+
+```sh
+oats okf index expert
+oats okf cat --base project /expert/decisions/retry-policy.md
+oats okf links --base project /expert/decisions/retry-policy.md
+oats okf cat --base project ../lessons/storm.md --from /expert/decisions/retry-policy.md
+```
+
+`links` shows every target already resolved, so you can `cat` the resolved
+path directly. `ls` is for choosing what to read from its descriptions, not
+for reading everything.
+
+## Searching
+
+`oats okf search TEXT` searches your nodes' bases (fixed string,
+case-insensitive, Markdown only), capped at 50 hits with "and N more". Narrow
+with `--node`, a longer phrase or `--base`; widen with `--all`. Search finds
+words, not meaning: when it finds nothing, try a synonym, then navigate from
+the index. A hit is a pointer: `cat` the concept before relying on it.
+
+## Citing
+
+Cite what you relied on as `alias/node/concept.md@<short-oid>`, using the oid
+from the receipt line (a directory base cites `alias@dir:<digest>`). Cite in
+STATE.md, notes/, PR descriptions and answers, so a reader knows which
+accepted state you saw.
+
+## Freshness
+
+Reads use the cached accepted commit while it is younger than the
+`consult-max-age` setting (default 300 s); after that the accepted branch is
+refetched first. `--fresh` refetches now (for example right after a PR
+merged). If a fetch fails, the last fetched accepted commit is still served,
+marked `stale: true` / `STALE:` with the reason: say so when it matters. With
+nothing cached and no network, the command fails with `E_BASE_UNAVAILABLE`:
+report it, and do not answer from memory or from an old `./knowledge/`.
+
+## Gotchas
+
+- Links resolve from the base root. `/node/x.md` is never a filesystem path,
+  and filesystem paths, `..` escapes, URLs, hidden paths and symlinks are
+  refused (`E_PATH`).
+- Never bulk-`cat` a whole node or loop `cat` over `ls` output. Index first,
+  then follow the few relevant links.
+- Don't edit knowledge. The write path is notes/ → harvest → PR or
+  publication. Write insights to notes/, not into a base.
+- `oats okf refresh` is gone (`E_REMOVED`): every read already sees the
+  accepted state.
+- `cat` reads `.md` files only (`E_NOT_MARKDOWN` otherwise); `E_NOT_FOUND`
+  lists the nearest directory's entries to try instead.
+
+Read [references/consult.md](references/consult.md) for more search examples,
+the error table and freshness edge cases.

package/capabilities/oats-okf/skills/okf-consultation/references/consult.md

@@ -0,0 +1,86 @@
+# okf-consultation — reference detail
+
+The okf-consultation skill's detail. Read this when navigating links, when a search is noisy or empty, when a
+receipt says `STALE`, or when a command errors. Run every command from your
+instance home (`oats okf …` resolves your registered source there).
+
+## Navigation, worked example
+
+Task: "change how retries back off". Your soul owns `project/expert`.
+
+```sh
+oats okf index                      # ## project/expert (owns) … ## project/peer (reads)
+#   * [Retry policy](decisions/retry-policy.md) - Why retries back off exponentially.
+oats okf cat --base project /expert/decisions/retry-policy.md
+#   … "superseded the fixed delay; see [the incident](../lessons/fixed-delay-storm.md)"
+oats okf links --base project /expert/decisions/retry-policy.md
+#   ok        /expert/lessons/fixed-delay-storm.md  (../lessons/fixed-delay-storm.md)
+#   MISSING   /expert/decisions/jitter.md
+oats okf cat --base project ../lessons/fixed-delay-storm.md \
+  --from /expert/decisions/retry-policy.md
+```
+
+- `index` with a node name (`oats okf index expert` or `project/expert`) prints
+  one index; `--base A` alone prints the base's root `index.md`.
+- A link in a concept is relative to **that concept's directory**: pass the
+  concept as `--from`, or use `links` to see every target already resolved.
+- `/node/x.md` is always from the base root; a bare `node/x.md` without
+  `--from` is also from the root.
+- `ls --base A /node/decisions` shows each concept's `type`, `title` and
+  `description` — use it to pick what to `cat`, not to read everything.
+- `MISSING` in `links` is a dangling link (allowed by OKF; not an error).
+  `REFUSED` is a link that would leave the base or is malformed.
+
+## Search
+
+```sh
+oats okf search "backoff"                     # your nodes' bases, case-insensitive
+oats okf search --node expert "jitter"        # one of your nodes
+oats okf search --base project --node peer "rate limit"
+oats okf search --all "idempotency"           # every bound base
+oats okf search --regex "retr(y|ies)"         # opt-in regex
+```
+
+- Fixed string, case-insensitive by default (`--case-sensitive` to change);
+  `--regex` is extended regex in Git bases, JavaScript RegExp in directory ones.
+- Only `.md` files inside the base root; results are `{base, path, line,
+  snippet}`, capped at 50 with "and N more" — narrow with `--node` or a longer
+  phrase rather than paging.
+- Search finds words, not meaning: when it's empty, try a synonym, then
+  navigate from the index. A hit is a pointer; `cat` the concept before
+  relying on it.
+- Git bases search with `git grep` at the accepted commit (the first search of
+  a node fetches its blobs in one batch); directory bases walk the files in
+  place, bounded to 20000 files.
+
+## Citing
+
+Cite what you relied on as `alias/node/concept.md@<short-oid>`, the oid from
+the receipt line (`— project@1a2b3c4d5e6f (fetched 2m ago)`). A directory base
+cites its digest (`project@dir:9f8e…`). Cite in notes/, PR descriptions and
+answers so a reader can see which accepted state you saw.
+
+## Freshness
+
+- Reads use the host cache's accepted commit if it was fetched within
+  `consult-max-age` seconds (setting, default 300); older, the accepted branch
+  is fetched first. `--fresh` fetches now. Neither ever selects another
+  branch or commit: only the accepted one is served.
+- Fetch failed (offline, auth, timeout): the last fetched accepted commit is
+  served with `stale: true` and the reason in the receipt (`STALE:` in text).
+  Say so if it matters to your answer; retry later with `--fresh`.
+- No cached commit and no network → `E_BASE_UNAVAILABLE`: report it, don't
+  guess from memory or from an old `./knowledge/`.
+- Merged a PR a minute ago? `--fresh` sees it once it is on the accepted branch.
+
+## Errors
+
+| Code | Meaning / what to do |
+| --- | --- |
+| `E_BASE_UNKNOWN` | alias not bound; the message lists the bound aliases (`oats okf bases`) |
+| `E_NOT_FOUND` | no such file at the accepted commit; the message lists the nearest directory |
+| `E_NOT_MARKDOWN` | `cat` reads `.md` concepts only; use `ls` for a directory |
+| `E_PATH` | escapes the base root, filesystem path, URL, hidden path, symlink or submodule |
+| `E_RECOVERY` | a directory-base publication is pending; retry after it completes |
+| `E_BASE_UNAVAILABLE` | the base can't be read and nothing is cached; report it |
+| `E_REMOVED` | `refresh` no longer exists; use `index` / `cat` |

package/docs/design/2026-09-24-phase-d-plan.md

@@ -35,6 +35,17 @@ pushes. Agreed by both on 2026-09-24:
   published skills); merges into the other's lane; reverts, force-anything,
   branch or tag deletion. A blocking intent unanswered for about 45 minutes goes
   to the human, never to action.
+- **Amendment (the human, 2026-09-26 ~14:00Z): "do the merge then fix if something broke".**
+  - A PR the lead has reviewed and approved is **merged immediately** by the lead (`gh pr merge --squash --match-head-commit <approved oid>`), without waiting for PR CI. CI runs on main after the merge.
+  - A red main is fixed forward at once, by the author or the lead, before anything else merges.
+  - **Tags still wait for main CI green on their exact SHA** (a tag never moves).
+  - Developers run only the affected suites locally (the nested globs included). The full glob and `smoke:tarball` run in CI, sharded ×6.
+  - The watcher no longer relays merges.
+- **Amendment (the human, 2026-09-26 ~13:10Z): "lets approve and tag ourselves all of these PRs".**
+  - With the co-lead unresponsive since ~10:30Z, the lead's review + green CI is the full Class B gate, in BOTH lanes: merges, okf/aweb tags, catalog pins, releases.
+  - Every such act is logged, with its head/tag oid, in a running account mailed to the co-lead for after-the-fact review.
+  - The co-lead's objections then go to the human, and a revert follows only on the human's word.
+  - This ends when the co-lead resumes and the lead records that here.
 - Every PR is reviewed by the co-lead who did not author it (a helper's PR is
   reviewed by its own lead, inside that lead's lane). A disagreement not settled
   in two mails goes to the human. Standing rules unchanged: PR CI is the full