@mnstry/atelier 0.2.0-alpha.13 → 0.2.0-alpha.15

package/src/knowledge/ontology-guide.mjs

@@ -0,0 +1,152 @@
+import { createHash } from 'node:crypto'
+import { isDeepStrictEqual } from 'node:util'
+import { validateKnowledgePlan as validatePlan } from './plan.mjs'
+import { knowledgeQuestionContext as contextForQuestion } from './workspace.mjs'
+
+const sha256 = bytes => createHash('sha256').update(bytes).digest('hex')
+const filled = value => typeof value === 'string' && value.trim().length > 0
+const clone = value => structuredClone(value)
+const object = value => value !== null && typeof value === 'object' && !Array.isArray(value)
+
+// A draft adapter for the existing local workspace. It owns no source store,
+// accepted concept identity, access decision, semantic verdict or apply path.
+export function createOntologyGuide() {
+  function bind(workspace, questionId) {
+    const errors = validatePlan(workspace.plan)
+    if (errors.length) throw new Error(`invalid current plan: ${errors.join('; ')}`)
+    const question = workspace.plan.questions.find(q => q.id === questionId)
+    if (!question) throw new Error('unknown knowledge question')
+    const context = contextForQuestion(workspace, questionId)
+    if (context.schema !== 'atelier-knowledge-context@v1' || context.planSha256 !== workspace.sha256)
+      throw new Error('context is not bound to the current plan')
+    return { question, context }
+  }
+
+  function prompts(workspace, questionId, entry = 'corpus') {
+    const { question } = bind(workspace, questionId)
+    if (!['corpus', 'blank'].includes(entry)) throw new Error('unknown entry route')
+    return [
+      { id: 'decision', view: 'onboard', field: 'concept', question: 'What decision will this help?', hint: question.work },
+      { id: 'concept', view: 'model', field: 'concept', question: 'What is the thing you are naming?', hint: 'Choose an existing concept by identity; propose a definition only where it leaves a concrete gap.' },
+      { id: 'identity', view: 'model', field: 'identity', question: 'How would you recognize the same thing next week?', hint: 'Give a stable identifying observation or key, and an example. A similar name or alias alone does not establish identity.' },
+      { id: 'counterexample', view: 'model', field: 'identity', question: 'What close example should stay separate?', hint: 'Explain the difference and name any existing concept with which it could be confused.' },
+      { id: 'evidence', view: 'deepen', field: 'test', question: 'Which source supports it?', hint: entry === 'blank' ? 'Write a permitted observation or interview note, or keep the answer unknown. A synthetic practice note stays labelled synthetic.' : 'Choose a permitted source already read by the current context; inspect the exact passage and qualifications.' },
+      { id: 'relation', view: 'model', field: 'relation', question: 'What does this relationship mean in each direction?', hint: 'Describe the forward claim and how to read it from the other endpoint. The reverse reading creates no inverse assertion.' },
+      { id: 'change', view: 'apply', field: 'test', question: 'What would change your mind?', hint: 'Give a disconfirming observation, unresolved evidence and next test; return to Learn after the outcome is observed.' },
+    ]
+  }
+
+  function inspect(workspace, questionId, draft) {
+    const { question, context } = bind(workspace, questionId)
+    const diagnostics = []
+    const add = (code, field, next) => diagnostics.push({ code, field, next })
+    if (!object(draft)) return { status: 'needs-guidance', diagnostics: [{ code: 'draft-required', field: 'draft', next: 'Start a structured draft from the current question and workspace.' }], evidence: [], contextStatus: context.status }
+    if (draft.snapshot !== workspace.snapshot || draft.basePlanSha256 !== workspace.sha256)
+      add('changed-source', 'snapshot', 'Refresh the workspace, inspect changed sources and rebind a new draft; retain this one as historical.')
+    if (!['corpus', 'blank'].includes(draft.entry)) add('entry-required', 'entry', 'Choose an existing corpus or a blank workspace.')
+    if (!filled(draft.decision)) add('decision-required', 'decision', 'Name the decision this question could change.')
+    const proposedPlan = draft.proposedPlan ?? workspace.plan
+    const planErrors = validatePlan(proposedPlan)
+    for (const error of planErrors) add('invalid-proposed-plan', 'proposedPlan', error)
+    if (planErrors.length) return { status: 'needs-guidance', diagnostics, evidence: [], contextStatus: context.status }
+    const proposedQuestion = proposedPlan.questions.find(q => q.id === question.id)
+    if (!proposedQuestion) add('question-removed', 'proposedPlan', 'Retain the current question or propose its retirement separately with the source owner.')
+    const concepts = proposedPlan.concepts
+    const selected = draft.concepts ?? []
+    if (!Array.isArray(selected) || !selected.length) add('concept-required', 'concepts', 'Choose the smallest existing concept set needed by this question.')
+    const seen = new Set()
+    for (const choice of Array.isArray(selected) ? selected : []) {
+      if (!object(choice)) { add('invalid-concept-choice', 'concepts', 'Choose a concept by its exact plan identity.'); continue }
+      const concept = concepts.find(c => c.id === choice.id)
+      if (!concept) { add('unknown-concept', 'concepts', 'Select an exact concept ID; a name or alias is not an identity mapping.'); continue }
+      if (seen.has(choice.id)) add('duplicate-concept', 'concepts', 'Keep one selection per concept identity.')
+      seen.add(choice.id)
+      for (const field of ['example', 'counterexample', 'identityBasis']) {
+        if (!filled(choice[field])) add(`${field}-required`, `concepts.${choice.id}`, `Give a concrete ${field} for ${choice.id}; review its definition and identity rule.`)
+      }
+      if (filled(choice.example) && choice.example.trim() === choice.counterexample?.trim())
+        add('indistinguishable-example', `concepts.${choice.id}`, 'Use a near miss that the stated identity rule actually keeps separate.')
+      const collisions = concepts.filter(c => c.id !== concept.id && (c.definition.trim().toLowerCase() === concept.definition.trim().toLowerCase() || c.identityRule.trim().toLowerCase() === concept.identityRule.trim().toLowerCase()))
+      for (const other of collisions) {
+        if (!Array.isArray(choice.distinctFrom) || !choice.distinctFrom.some(x => object(x) && x.id === other.id && filled(x.reason)))
+          add('ambiguous-identity', `concepts.${choice.id}`, `Explain how ${choice.id} differs from ${other.id}, or send an explicit mapping proposal for source-owner review. Do not merge them by name.`)
+      }
+      if (!proposedQuestion?.concepts.includes(choice.id)) add('orphan-concept', `concepts.${choice.id}`, 'Link the concept to the current question or remove it from this draft.')
+    }
+    for (const id of proposedQuestion?.concepts ?? []) {
+      if (!seen.has(id)) add('untested-concept', 'concepts', `Inspect the definition, identity and near miss for ${id}.`)
+    }
+    for (const id of proposedQuestion?.relations ?? []) {
+      const relation = proposedPlan.relations.find(r => r.id === id)
+      const reading = Array.isArray(draft.relations) ? draft.relations.find(r => object(r) && r.id === id) : null
+      if (!reading || !filled(reading.forward) || !filled(reading.reverse))
+        add('directed-meaning-required', 'relations', `Explain ${relation.from} → ${relation.to} (${relation.predicate}) and its reverse reading; neither wording proves an accepted edge.`)
+    }
+    const evidence = []
+    if (!Array.isArray(draft.evidence)) add('evidence-list-required', 'evidence', 'Select exact passages, or retain an empty list for an honest unknown.')
+    for (const pin of Array.isArray(draft.evidence) ? draft.evidence : []) {
+      if (!object(pin)) { add('invalid-evidence-pin', 'evidence', 'Choose a current source digest and exact passage.'); continue }
+      const matches = context.sources.filter(s => s.id === pin.id)
+      if (matches.length !== 1) { add('unavailable-or-ambiguous-source', 'evidence', 'Select one unambiguous source from the current permitted context; inspect omissions separately.'); continue }
+      const source = matches[0]
+      if (pin.sha256 !== source.sha256) { add('stale-evidence', 'evidence', 'Read the changed source and propose new pins explicitly; keep the old pin in history.'); continue }
+      const lines = source.text.split('\n')
+      if (source.text.endsWith('\n')) lines.pop()
+      if (!Number.isSafeInteger(pin.start) || !Number.isSafeInteger(pin.end) || pin.start < 1 || pin.end < pin.start || pin.end > lines.length) {
+        add('invalid-passage', 'evidence', 'Choose a complete existing line range in the selected source.'); continue
+      }
+      const passage = lines.slice(pin.start - 1, pin.end).join('\n')
+      if (!filled(pin.quote) || pin.quote !== passage) { add('changed-passage', 'evidence', 'Copy the exact current passage, including its qualifications.'); continue }
+      evidence.push({ id: source.id, repo: source.repo, path: source.path, sha256: source.sha256, start: pin.start, end: pin.end, quote: passage })
+    }
+    if (!['supported', 'abstain'].includes(draft.answer?.status) || !filled(draft.answer?.text))
+      add('answer-required', 'answer', 'Write a source-supported proposed answer or an explicit abstention.')
+    if (draft.answer?.status === 'supported' && !evidence.length)
+      add('unsupported-answer', 'answer', 'Narrow the claim to an inspected source, or abstain and name the evidence needed.')
+    if (draft.answer?.certainty !== 'qualified' || !filled(draft.answer?.limits))
+      add('unsupported-certainty', 'answer', 'State scope, uncertainty, contradictions and alternative explanations. A retrieved passage alone does not establish certainty.')
+    if (!filled(draft.wouldChangeMind)) add('disconfirmation-required', 'wouldChangeMind', 'Name an observation that could disconfirm the answer, or the next evidence needed to resolve the unknown.')
+    return {
+      status: diagnostics.length ? 'needs-guidance' : 'ready-for-human-review', diagnostics, evidence,
+      contextStatus: context.status, coverage: clone(context.coverage), omissions: clone(context.omissions),
+      abstention: draft.answer?.status === 'abstain' ? context.coverage.omitted ? 'unverified-omissions' : 'proposed' : null,
+      assurance: 'Draft completeness and source binding only. The reviewer judges support, identity, meaning and the decision.',
+    }
+  }
+
+  function prepareReview(workspace, questionId, draft, { basePlanText, planRef = 'knowledge-plan.json' }) {
+    const result = inspect(workspace, questionId, draft)
+    if (result.diagnostics.length) return { ok: false, ...result }
+    if (sha256(Buffer.from(basePlanText, 'utf8')) !== workspace.sha256 || !isDeepStrictEqual(JSON.parse(basePlanText.replace(/^\uFEFF/, '')), workspace.plan))
+      throw new Error('raw plan bytes differ from the bound source')
+    if (!filled(planRef) || planRef.length > 500 || planRef.includes('\\') || planRef.split('/').some(p => !p || p.startsWith('.')) || planRef.startsWith('/'))
+      throw new Error('visible workspace-relative plan reference required')
+    const next = draft.proposedPlan ?? workspace.plan
+    const proposedText = isDeepStrictEqual(next, workspace.plan) ? basePlanText : `${JSON.stringify(next, null, 2)}\n`
+    const changes = Object.keys(next).filter(key => !isDeepStrictEqual(workspace.plan[key], next[key])).sort()
+      .map(key => ({ path: `/${key}`, before: clone(workspace.plan[key]), after: clone(next[key]) }))
+    const payload = {
+      kind: 'ontology-guidance-draft', basePlanSha256: workspace.sha256, snapshot: workspace.snapshot, questionId,
+      sourceEditsApplied: false, canonicalAdmission: false, reviewRequired: true,
+      beforeText: basePlanText, proposedText, changes, evidence: result.evidence,
+      retrieval: { status: result.contextStatus, coverage: result.coverage, omissions: result.omissions, abstention: result.abstention },
+      guidance: { entry: draft.entry, decision: draft.decision, concepts: draft.concepts, relations: draft.relations ?? [], answer: draft.answer, wouldChangeMind: draft.wouldChangeMind },
+      coauthor: { flow: 'model', fields: {
+        concept: JSON.stringify({ decision: draft.decision, concepts: draft.concepts }),
+        identity: JSON.stringify(draft.concepts.map(({ id, identityBasis, example, counterexample, distinctFrom }) => ({ id, identityBasis, example, counterexample, distinctFrom: distinctFrom ?? [] }))),
+        relation: JSON.stringify(draft.relations ?? []),
+        test: JSON.stringify({ evidence: result.evidence, answer: draft.answer, wouldChangeMind: draft.wouldChangeMind }),
+      } },
+    }
+    // Existing copy-only store bounds each JSON/text payload at 50,000 chars.
+    // Refuse rather than silently truncate the reviewable source or draft.
+    const diff = JSON.stringify(changes, null, 2)
+    if (JSON.stringify(payload).length > 49000 || diff.length > 49000) throw new Error('review draft exceeds the copy-only store bound; narrow the change')
+    return { ok: true, status: 'proposed', sourceEditsApplied: false,
+      body: { path: planRef, action: 'copy.repoPath', intent: 'Review a source-bound knowledge-plan proposal',
+        capability: 'proposal.copy-only', directWrite: false, applyEndpoint: null,
+        diff, proposal: payload },
+    }
+  }
+  return { prompts, inspect, prepareReview }
+}

package/src/knowledge-health/proof/installed-check.mjs

@@ -33,7 +33,7 @@ await scenario('public-quickstart',async()=>{
   return {init,graph:shellBin(['graph'],workspace),project:shellBin(['project'],workspace),scope:'Exact macOS public quickstart command sequence, supported baseline only'};
 });
 await scenario('installed-document-references',async()=>{
-  const references=['README.md','docs/knowledge-graph.md','docs/coauthor-session.md'];
+  const references=['README.md','docs/reference/knowledge-graph.md','docs/reference/coauthor-session.md'];
   const documents=references.map(relativePath=>{const file=fs.realpathSync(path.join(packageRoot,relativePath));assert.ok(file.startsWith(fs.realpathSync(packageRoot)+path.sep));const bytes=fs.readFileSync(file);return {relativePath,bytes:bytes.length,sha256:digest(bytes)};});
   for(const subpath of ['./graph','./project','./coauthor']){assert.ok(pkg.exports[subpath]);await import(pkg.name+'/'+subpath.slice(2));}
   return {documents,apiReferences:['@mnstry/atelier/graph','@mnstry/atelier/project','@mnstry/atelier/coauthor'],scope:'Public quickstart references resolve in the actual installed package'};
@@ -72,7 +72,7 @@ await scenario('installed-public-graph-project-baseline',async()=>{
   assert.ok(Array.isArray(graph.nodes));assert.ok(Array.isArray(graph.edges));assert.ok(Array.isArray(graph.errors));assert.equal(graph.errors.length,0);
   return {init,graphCommand,projectCommand,graph,agentCIOutput:'Actual machine-readable canonical graph; structural evidence only, no model/provider or semantic acceptance.'};
 });
-const docs=[];for(const candidate of ['README.md','docs/knowledge.md','docs/coauthor.md','docs/coauthor-session.md','docs/upgrade.md','docs/graph.md','docs/knowledge-graph.md','docs/release-engineering.md']){const full=path.join(packageRoot,candidate);if(fs.existsSync(full)){const b=fs.readFileSync(full);docs.push({path:candidate,sha256:digest(b),bytes:b.length});}}
+const docs=[];for(const candidate of ['README.md','docs/guides/knowledge-workspace.md','docs/reference/coauthor-session.md','docs/guides/upgrade.md','docs/reference/knowledge-graph.md','docs/maintainers/release-engineering.md']){const full=path.join(packageRoot,candidate);if(fs.existsSync(full)){const b=fs.readFileSync(full);docs.push({path:candidate,sha256:digest(b),bytes:b.length});}}
 for(const id of ['assessment-to-guided-authoring','full-native-finding-reference','preview-owning-source-correction-readback-reassessment','keyboard-focus-undo','native-withdrawal-recovery','participant-usefulness'])gaps.push({id,owner:id==='participant-usefulness'?'Facilitator/participant':'Foundation and existing AW Integration/Journey',action:'Receive exact public Dev Day installed entry/bindings and native allocation; inherited native or fixture proof cannot satisfy installed or human evidence.'});
 const bindings=profile.deliveryBindings;
 if(bindings){

package/src/knowledge-health/rule-identity.mjs

@@ -1,7 +1,7 @@
 export const ruleIdentity = Object.freeze({
   "profile": "source-qualified-required-direction/r1",
-  "commit": "fcfdbe5ded672d41c717f49e0cfdf68b6060834d",
-  "tree": "400e181cd0cb55976f3ef7ab1a1405531dacd521",
+  "commit": "43a6d6a9d4718e735576bdd878cbea1f9b7e454a",
+  "tree": "306d92f8f3a36fa8938419bf8df32cb3b30f6704",
   "files": [
     {
       "path": "src/knowledge/plan.mjs",
@@ -17,15 +17,15 @@ export const ruleIdentity = Object.freeze({
     },
     {
       "path": "src/graph/graph.mjs",
-      "bytes": 9934,
-      "sha256": "1f01fbeab7e6fcaed127c8fe84c9a48b08f1fec13d21f486c48726715a5bbb92",
-      "blob": "6bce4e1213098457097e025f8ead53e6b4403336"
+      "bytes": 10397,
+      "sha256": "0200feb42d59aa8e0f2e9b0e7dd49bbd68f25bc09710aa1ecce92bc82596adb5",
+      "blob": "96f6f05f8df1b3cf9c75d050359d11e9bad39aa2"
     },
     {
       "path": "src/graph/knowledge-graph.mjs",
-      "bytes": 65477,
-      "sha256": "94895598d388e80a70b7bbe92ad57138dccd94896699a6c472e635d885b1139f",
-      "blob": "283ef86ad08a6360bc006cc75ca5cedb2718e14d"
+      "bytes": 66377,
+      "sha256": "ee62867895c7a8ab16295365120c2b4a69754066bf2258fc9156708d9b61bc96",
+      "blob": "fc6c543d08bef5de449709674122994cb1c51b75"
     },
     {
       "path": "templates/knowledge-workspace/knowledge-plan.schema.json",
@@ -39,6 +39,11 @@ export const ruleIdentity = Object.freeze({
   "supersededQualification": {
     "commit": "b1bdc9279a99f7c884ddfdfe0e2a24315d6f3666",
     "tree": "2797f44baf89007d3808675d897e55a943fc0d65",
-    "note": "The supplier qualified against this earlier commit. The five pinned files are byte-identical there and at the source authority above."
+    "note": "The supplier qualified against this earlier commit. The pinned plan, context and schema files are byte-identical there and at the source authority above; src/graph/graph.mjs and src/graph/knowledge-graph.mjs are not, and that qualification does not cover their current bytes."
+  },
+  "previousSourceAuthority": {
+    "commit": "0a77cdc0f4f949d9aef29e3567303e2a6588a610",
+    "tree": "4aaadc77690868921c1748e15079e0965e06faae",
+    "note": "Regenerated by the source owner for a changed candidate: workspace link resolution in src/graph/knowledge-graph.mjs now recognises Markdown sources by the existing isMarkdownPath test, so links from uppercase .MD files resolve. One line changes; the file keeps its size. The other pinned files are byte-identical; the Knowledge Health tests pass on the current bytes."
   }
 })

package/src/knowledge-health/workshop.mjs

@@ -28,12 +28,32 @@ function read(file) {
   } finally { fs.closeSync(fd) }
 }
 
+// Every directory is created by this copy and every file is created exclusively, so an entry that arrived meanwhile
+// refuses instead of being merged. Nothing is overwritten, and nothing unknown is cleaned up on failure.
+function copyExclusive(source, target) {
+  const stat = fs.lstatSync(source)
+  if (stat.isDirectory()) {
+    fs.mkdirSync(target, { recursive: false })
+    for (const name of fs.readdirSync(source)) copyExclusive(path.join(source, name), path.join(target, name))
+  } else if (stat.isFile()) fs.copyFileSync(source, target, fs.constants.COPYFILE_EXCL)
+  else throw Error('The workshop fixture holds an entry that is neither a file nor a directory')
+}
+
+// Entries created inside these new directories after they were made are not ours either; refuse before Git sees them.
+function assertExactCopy(source, target) {
+  const expected = fs.readdirSync(source).sort(), actual = fs.readdirSync(target).sort()
+  if (expected.length !== actual.length || expected.some((name, index) => name !== actual[index]))
+    throw Object.assign(Error('The new workshop holds entries this initialization did not create'), { code: 'EEXIST' })
+  for (const name of expected) if (fs.lstatSync(path.join(source, name)).isDirectory()) assertExactCopy(path.join(source, name), path.join(target, name))
+}
+
 /** Copy the actual shipped public fixture into a NEW disposable workspace. */
 export function initializeKnowledgeHealthWorkshop(destination) {
   const root = path.resolve(destination)
   fs.mkdirSync(root, { recursive: false })
-  fs.cpSync(fileURLToPath(new URL('../../fixtures/knowledge-health/workshop/', import.meta.url)), root,
-    { recursive: true, force: false, errorOnExist: true })
+  const fixture = fileURLToPath(new URL('../../fixtures/knowledge-health/workshop/', import.meta.url))
+  for (const name of fs.readdirSync(fixture)) copyExclusive(path.join(fixture, name), path.join(root, name))
+  assertExactCopy(fixture, root)
   fs.writeFileSync(path.join(root, '.gitignore'), '.atelier-local/\noutput/\n', { flag: 'wx' })
   const git = spawnSync('git', ['init', '--quiet'], { cwd: root, encoding: 'utf8', timeout: 15000,
     env: { PATH: process.env.PATH, GIT_CONFIG_NOSYSTEM: '1',

package/src/personal-workspace/index.mjs

@@ -26,7 +26,7 @@ const resolvedInputs = new WeakSet()
 const plans = new WeakSet()
 const freeze = (v) => { if (v && typeof v === 'object') { Object.values(v).forEach(freeze); Object.freeze(v) } return v }
 
-export { selectPersonalGeneration, selectionConfirmDigest, readPersonalSelection, inventoryPersonalHome, planPersonalRestore, restorePersonalInputs } from './selection.mjs'
+export { selectPersonalGeneration, selectionConfirmDigest, readPersonalSelection, readPersonalSelectionHead, inventoryPersonalHome, planPersonalRestore, restorePersonalInputs } from './selection.mjs'
 export class PersonalWorkspaceRefusal extends Error {
   constructor(code) { super(`Personal workspace refused: ${code}`); this.name = 'PersonalWorkspaceRefusal'; this.code = code }
 }

package/src/personal-workspace/selection.mjs

@@ -19,6 +19,7 @@ const MAX_RECORD = 1024 * 1024
 const MAX_GENERATION_FILE = 8 * 1024 * 1024
 const MAX_RESTORE_RECORD = 4 * MAX_RECORD
 const ID = /^[0-9a-f]{64}$/
+const CONFIRMATION_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/
 // Every temporary name this module writes, including restore aside copies
 // (.restore-<uuid>-aside-<key>.json).
 const TEMPORARY = /^\.(selection|restore|validate)-[0-9a-f-]{36}(-[a-z]+)*\.json$/
@@ -45,8 +46,10 @@ function privateHome(personalHome) {
   if (stat.uid !== process.getuid() || (stat.mode & 0o022) !== 0) refuse('not-private-location')
   return personalHome
 }
+// Opened without waiting on it: a FIFO or a device in a record's place refuses instead of blocking the caller, which
+// may be a service's event loop.
 function readBytes(file, limit, tooLarge = 'malformed-input') {
-  const fd = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW)
+  const fd = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | (fs.constants.O_NONBLOCK ?? 0))
   try {
     const stat = fs.fstatSync(fd)
     if (!stat.isFile()) refuse('malformed-input')
@@ -134,7 +137,7 @@ function readHistory(personalHome) {
     let record
     try { record = JSON.parse(bytes) } catch { refuse('selection-history-corrupt') }
     if (record?.schema !== SELECTION_SCHEMA || record.sequence !== index + 1 || record.previous !== head || !ID.test(record.generationId ?? '') ||
-      canonical(record) !== bytes.toString('utf8')) refuse('selection-history-corrupt')
+      (record.confirmationId !== undefined && !CONFIRMATION_ID.test(record.confirmationId)) || canonical(record) !== bytes.toString('utf8')) refuse('selection-history-corrupt')
     records.push(record)
     head = hash(bytes)
     files.push({ name, bytes: bytes.length, digest: head })
@@ -161,7 +164,7 @@ export function selectPersonalGeneration(options) {
     const { eligible, reason } = eligibility(personalHome, generationId)
     if (!eligible) refuse(reason)
     const dir = privateDir(personalHome, 'selections', true)
-    const record = { schema: SELECTION_SCHEMA, sequence: records.length + 1, previous: head, generationId }
+    const record = { schema: SELECTION_SCHEMA, sequence: records.length + 1, previous: head, generationId, confirmationId: randomUUID() }
     const content = canonical(record)
     try { publishExclusive(dir, `${String(record.sequence).padStart(6, '0')}.json`, content, 'selection') }
     catch (error) { if (error.code === 'EEXIST') refuse('selection-concurrent'); throw error }
@@ -182,6 +185,34 @@ export function readPersonalSelection(options) {
   }, 'personal-home-unavailable')
 }
 
+// The current selection from the history alone. Nothing is composed, so nothing
+// here says whether the selected generation is still eligible: a host that
+// composes elsewhere reads this first, and reads it again to compare the head it
+// acted on with the head now. `sequence` is 0 while nothing is selected.
+export function readPersonalSelectionHead(options) {
+  return safe(() => {
+    const { personalHome } = options ?? {}
+    privateHome(personalHome)
+    const { records, head } = readHistory(personalHome)
+    const current = records.at(-1) ?? null
+    return freeze({ selected: current?.generationId ?? null, sequence: current?.sequence ?? 0, head })
+  }, 'personal-home-unavailable')
+}
+
+// Package-internal snapshot for a host that keeps continuity across starts. The public head reader keeps its exact
+// result. These identities come from the same verified history read, including every previously confirmed prefix.
+export function readPersonalSelectionSnapshot(options) {
+  return safe(() => {
+    const { personalHome } = options ?? {}
+    privateHome(personalHome)
+    const { records, files, head } = readHistory(personalHome)
+    const current = records.at(-1) ?? null
+    return freeze({ selected: current?.generationId ?? null, sequence: current?.sequence ?? 0, head,
+      confirmationId: current?.confirmationId ?? null, recordDigests: files.map((file) => file.digest),
+      confirmationIds: records.flatMap((record) => record.confirmationId === undefined ? [] : [record.confirmationId]) })
+  }, 'personal-home-unavailable')
+}
+
 // Lists entries without failing the whole inventory: a concurrently removed entry
 // is skipped; an unreadable, foreign or oversized one is reported without a digest.
 function listFiles(dir, keep) {

package/src/project/config.mjs

@@ -557,7 +557,7 @@ export function validateProjectConfigDoc(doc, { neutralTemplate = false } = {})
     errors.push('setup.profile is invalid')
   }
   // The census reads these as path patterns relative to the project config's
-  // folder (docs/knowledge-graph.md), under the contract's pathString rules.
+  // folder (docs/reference/knowledge-graph.md), under the contract's pathString rules.
   for (const key of ['include', 'exclude']) {
     errors.push(...stringPathErrors(setup[key], `setup.${key}`))
     if (typeof setup[key] === 'string' && (setup[key].includes('\u0000') || /^[a-z][a-z0-9+.-]*:/.test(setup[key]) || path.isAbsolute(setup[key]))) {

package/src/project/path-match.mjs

@@ -47,7 +47,8 @@ export function matchesPathPattern(pattern, rel) {
   const normalizedRel = normalizeRelPath(rel)
   if (!normalizedPattern || !normalizedRel) return false
   const candidate = normalizedPattern.includes('/') ? normalizedRel : path.posix.basename(normalizedRel)
-  return new RegExp(`^${globSource(normalizedPattern)}$`, 'i').test(candidate)
+  // dotAll: `**` crosses a newline in a name as well as a slash.
+  return new RegExp(`^${globSource(normalizedPattern)}$`, 'is').test(candidate)
 }
 
 export const basenameOf = (pattern) => path.posix.basename(normalizeRelPath(pattern))

package/src/project/providers/github.mjs

@@ -0,0 +1,24 @@
+import { execFileSync } from 'node:child_process'
+
+export const PROVIDER_HOSTS = Object.freeze({ 'github.com': 'github' })
+
+const lower = (value) => String(value ?? '').trim().toLowerCase()
+
+// Ask the provider to resolve the recorded ref. GitHub follows the rename redirect
+// and answers with the stable numeric id plus the current full name, which is the
+// only signal that survives a rename.
+export function githubLookup({ owner, name }) {
+  try {
+    const out = execFileSync('gh', ['api', `repos/${owner}/${name}`, '--jq', '{id: .id, fullName: .full_name}'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    })
+    const parsed = JSON.parse(out)
+    if (!parsed?.id) return null
+    return { id: String(parsed.id), fullName: lower(parsed.fullName), currentName: lower(String(parsed.fullName).split('/').pop()) }
+  } catch {
+    return null
+  }
+}
+
+export const defaultLookups = { github: githubLookup }

package/src/project/repo-identity.mjs

@@ -1,9 +1,9 @@
-import { execFileSync } from 'node:child_process'
 import { SUPPORTED_IDENTITY_PROVIDERS, gitRemoteUrl, remoteHost } from './config.mjs'
+import { PROVIDER_HOSTS, defaultLookups } from './providers/github.mjs'
 
-export const SUPPORTED_PROVIDERS = Object.freeze([...SUPPORTED_IDENTITY_PROVIDERS])
+export { githubLookup } from './providers/github.mjs'
 
-const PROVIDER_HOSTS = Object.freeze({ 'github.com': 'github' })
+export const SUPPORTED_PROVIDERS = Object.freeze([...SUPPORTED_IDENTITY_PROVIDERS])
 
 const lower = (value) => String(value ?? '').trim().toLowerCase()
 
@@ -23,25 +23,6 @@ export function parseRemoteRef(url) {
   return { host, provider: PROVIDER_HOSTS[host] ?? null, owner: lower(parts[0]), name: lower(parts.slice(1).join('/')) }
 }
 
-// Ask the provider to resolve the recorded ref. GitHub follows the rename redirect
-// and answers with the stable numeric id plus the current full name, which is the
-// only signal that survives a rename.
-export function githubLookup({ owner, name }) {
-  try {
-    const out = execFileSync('gh', ['api', `repos/${owner}/${name}`, '--jq', '{id: .id, fullName: .full_name}'], {
-      encoding: 'utf8',
-      stdio: ['ignore', 'pipe', 'ignore'],
-    })
-    const parsed = JSON.parse(out)
-    if (!parsed?.id) return null
-    return { id: String(parsed.id), fullName: lower(parsed.fullName), currentName: lower(String(parsed.fullName).split('/').pop()) }
-  } catch {
-    return null
-  }
-}
-
-const defaultLookups = { github: githubLookup }
-
 /**
  * Resolve a clone's stable identity.
  *

package/src/projection/obsidian/contracts.mjs

@@ -404,7 +404,7 @@ export function cutName(value, maxBytes) {
 
 // One file or folder name made safe for macOS, Linux, Windows and Obsidian
 // links, or '' when nothing is left of it. The author's casing and words are
-// kept; see "File names" in docs/obsidian-contract.md for each rule.
+// kept; see "File names" in docs/reference/obsidian-contract.md for each rule.
 export function vaultName(value, maxBytes = NAME_BYTES) {
   const cleaned = trimName(String(value ?? '')
     .toWellFormed()

package/src/projection/obsidian/materialize/path-registry.mjs

@@ -7,7 +7,7 @@ import { refuse } from './byte-lens.mjs'
 
 export { collisionKey }
 
-// Vault paths of layout 2 (see "Vault layout" in docs/obsidian-contract.md):
+// Vault paths of layout 2 (see "Vault layout" in docs/reference/obsidian-contract.md):
 //
 //   <repository folder>/<source directory>/<title>.md           a Markdown note
 //   <repository folder>/<source directory>/<file name>          a wrapped file