create-pmos 0.46.0 → 0.48.0

package/payload/mods/pmos-cockpit/hooks/register.tsx

@@ -15,6 +15,8 @@ import { SECTION_ID, buildSection } from './lib/prompt-section.mjs'
 import { PROBES, aheadProbe, interpretGit } from './lib/probes.mjs'
 import { describeMode, detectMode, slicePolicy } from './lib/mode.mjs'
 import { UNPUSHED_PROBES, cloudBandText, interpretUnpushed } from './lib/unpushed.mjs'
+import { HANDOVER_PROBES, buildPlan, countSince, interpretSince, notePaths, parseNote, planStillGood, renderNote, resumeText, sinceProbes, subjectsProbe } from './lib/handover.mjs'
+import { carryOut } from './lib/handover-run.mjs'
 import { REVIEWER_AGENT, REVIEWER_PROMPT, REVIEWER_TOOLS, REVIEWER_TYPE, buildReviewPrompt, offerText, parseVerdict, pickReviewerModel, planEval } from './lib/review.mjs'
 
 const status = atom({ plugin: 'pmos-cockpit', key: 'status' } as const, null)
@@ -28,6 +30,12 @@ const factsCache = atom({ plugin: 'pmos-cockpit', key: 'factsCache' } as const,
 // Where this session runs (M12). Read from two environment variables when the mod loads and kept here;
 // nothing a tool call does afterwards moves it. It changes what is drawn, never what is guarded.
 const modeAtom = atom({ plugin: 'pmos-cockpit', key: 'mode' } as const, null)
+// Continuity (M13). The plan `/pmos-handover` showed, waiting for a person's confirmation; it holds the
+// facts of the checkout it was made for. The resume summary read at session start, and whether the
+// person dismissed it. None of the three is ever given to the model.
+const handoverPlan = atom({ plugin: 'pmos-cockpit', key: 'handoverPlan' } as const, null)
+const resume = atom({ plugin: 'pmos-cockpit', key: 'resume' } as const, null)
+const resumeGone = atom({ plugin: 'pmos-cockpit', key: 'resumeGone' } as const, false)
 // The independent evaluator (M14). `review` is the one reviewer in flight; `reviewOffer` is its answer,
 // held until a person presses Record or types /pmos-record-review. Neither is ever written to a ledger.
 const review = atom({ plugin: 'pmos-cockpit', key: 'review' } as const, null)
@@ -81,10 +89,12 @@ async function whoAmI($: any, root: string): Promise<string> {
   return r.exitCode === 0 && out(r) !== '' ? out(r) : 'pm'
 }
 
-// The local gate for one initiative. It reports what it ran, and what it cannot see.
-async function localGate($: any, layout: any, root: string, id: string | null, branch: string | null) {
-  if (id === null) return { ran: false, failed: false, text: 'Local gate not run: the branch names no initiative.' }
-  const lines: string[] = []
+// The local gate for one initiative. It reports what it ran, and what it cannot see. `fromGrant` is true
+// when the id comes from the grant (Run 7) because the branch names none: the kit's gate then reads the
+// id from `Initiative: <id>` in the PR body, the form the CI gate accepts in place of the branch name.
+async function localGate($: any, layout: any, root: string, id: string | null, branch: string | null, fromGrant = false) {
+  if (id === null) return { ran: false, failed: false, text: 'Local gate not run: the branch names no initiative, and neither does the grant.' }
+  const lines: string[] = fromGrant ? [`Local gate run for initiative ${id}, named on the grant.`] : []
   let failed = false
   let ran = false
   const ws = layout.kind === 'kit' ? `${root}/pmos/scripts/workflow-state.js` : `${root}/scripts/workflow-state.js`
@@ -95,7 +105,7 @@ async function localGate($: any, layout: any, root: string, id: string | null, b
     lines.push(`workflow-state --gate ${id}: ${r.exitCode === 0 ? 'passed' : `FAILED. ${out(r).split('\n').slice(-3).join(' ')}`}`)
   }
   if (layout.kind === 'kit' && (await $.fs.exists(`${root}/pmos/scripts/gate-initiative.sh`))) {
-    const r = await sh($, ['bash', `${root}/pmos/scripts/gate-initiative.sh`], { cwd: root, env: { HEAD_REF: branch ?? '', PR_BODY: '', PR_LABELS: '', KIT_ROOT: 'pmos' } })
+    const r = await sh($, ['bash', `${root}/pmos/scripts/gate-initiative.sh`], { cwd: root, env: { HEAD_REF: branch ?? '', PR_BODY: fromGrant ? `Initiative: ${id}` : '', PR_LABELS: '', KIT_ROOT: 'pmos' } })
     ran = true
     if (r.exitCode !== 0) failed = true
     lines.push(`gate-initiative.sh: ${r.exitCode === 0 ? 'passed' : `FAILED. ${(out(r) || r.stderr).split('\n').slice(-2).join(' ')}`}`)
@@ -155,10 +165,17 @@ async function judge($: any, e: any): Promise<string | null> {
   // the gate needs the branch, whatever the action was
   if (!needsBranch) facts = await gitFacts($, root)
 
+  // the initiative the branch names, if any: a grant minted for another one never covers this action
+  const initiative = resolveInitiative({
+    branch: facts.branch,
+    recordExists: facts.branch ? await $.fs.exists(recordPath(layout, facts.branch.replace(/^initiative\//, '')) ?? '/nonexistent') : null,
+    commitsAhead: facts.commitsAhead,
+  })
+
   const grantsFile = layout.stateRoot ? `${layout.stateRoot}/grants.jsonl` : null
   const text = grantsFile ? ((await readText($, grantsFile)) ?? '') : ''
   const now: number = await $.clock.now()
-  const used: { id: string; action: string }[] = []
+  const used: { id: string; action: string; initiative: string | null }[] = []
   for (const f of merges) {
     if (grantsFile === null) return denyMerge(f, 'there is no PMOS state here to hold a grant.')
     let checks: { kind: string; target: string }[]
@@ -173,21 +190,22 @@ async function judge($: any, e: any): Promise<string | null> {
     let hit: any = null
     let why = ''
     for (const c of checks) {
-      const r = checkGrant(text, c, now)
+      const r = checkGrant(text, { ...c, branchInitiative: initiative.id }, now)
       if (r.ok) { hit = r.grant; break }
       why = r.reason
     }
     if (hit === null) return denyMerge(f.publish ? { ...f, target: checks[0].target } : f, `${why}`)
-    used.push({ id: hit.id, action: `${f.action}${f.target ? ` ${f.target}` : ''}` })
+    used.push({ id: hit.id, action: `${f.action}${f.target ? ` ${f.target}` : ''}`, initiative: hit.initiative ?? null })
   }
 
-  // every grant is live; now the local gate, which can still stop the action
-  const initiative = resolveInitiative({
-    branch: facts.branch,
-    recordExists: facts.branch ? await $.fs.exists(recordPath(layout, facts.branch.replace(/^initiative\//, '')) ?? '/nonexistent') : null,
-    commitsAhead: facts.commitsAhead,
-  })
-  const gate = await localGate($, layout, root, initiative.id, facts.branch)
+  // every grant is live; now the local gate, which can still stop the action. It runs for the branch's
+  // initiative, or else for the one the grants name. Grants that name different ones decide nothing.
+  const named = [...new Set(used.map((u) => u.initiative).filter((x): x is string => x !== null))]
+  if (initiative.id === null && named.length > 1) {
+    return `Blocked by pmos-cockpit: the grants for this action name different initiatives (${named.join(', ')}), so there is no one initiative to run the local gate against. Ask the PM for grants that name one.`
+  }
+  const gateId = initiative.id ?? named[0] ?? null
+  const gate = await localGate($, layout, root, gateId, facts.branch, initiative.id === null && gateId !== null)
   $.ui.toast(`pmos-cockpit: ${gate.text}`)
   if (gate.failed) return `Blocked by pmos-cockpit: the local gate failed, and a grant does not override it. ${gate.text}`
 
@@ -326,6 +344,111 @@ async function repair($: any): Promise<CockpitStatus> {
   return gather($, done, error)
 }
 
+// ── continuity (M13) ─────────────────────────────────────────────────────────────────────────────
+// What the checkout looks like to a handover: git, the initiative the branch names, and what is changed
+// or unpushed. Read-only; every process has the 5 second limit.
+async function readCheckout($: any, root: string, layout: any) {
+  const run = (argv: string[], limit = PROCESS_LIMIT_MS) => sh($, argv, { cwd: root, timeoutMs: limit })
+  const r: Record<string, any> = {}
+  for (const k of ['inside', 'branch', 'sha', 'dirs', 'defaultBranch'] as const) r[k] = await run(PROBES[k])
+  const g = interpretGit(r)
+  const idGuess = g.branch?.startsWith('initiative/') ? g.branch.slice('initiative/'.length) : null
+  const rp = idGuess ? recordPath(layout, idGuess) : null
+  const initiative = resolveInitiative({ branch: g.noGit ? null : g.branch, recordExists: rp ? await $.fs.exists(rp) : null, commitsAhead: null })
+  let porcelain = ''
+  let hasOrigin = false
+  let unpushed = { unpushed: false }
+  if (!g.noGit) {
+    const st = await run(HANDOVER_PROBES.status as string[])
+    porcelain = st.exitCode === 0 ? st.stdout : ''
+    hasOrigin = (await run(HANDOVER_PROBES.origin as string[])).exitCode === 0
+    const u: Record<string, any> = {}
+    for (const [k, argv] of Object.entries(UNPUSHED_PROBES)) u[k] = await run(argv as string[])
+    unpushed = interpretUnpushed(u)
+  }
+  return { run, g, initiative, porcelain, hasOrigin, unpushed }
+}
+
+// What the plan, and the confirmation that follows it, compare: the facts a plan was made for.
+const keyOf = (c: any, words: string) => ({ branch: c.g.branch, sha: c.g.sha, porcelain: c.porcelain, words })
+
+async function planHandover($: any, words: string): Promise<string> {
+  const { root, layout } = await rootAndLayout($)
+  const c = await readCheckout($, root, layout)
+  const p = buildPlan({ layout, root, initiative: c.initiative, git: c.g, porcelain: c.porcelain, hasOrigin: c.hasOrigin, unpushed: c.unpushed, words, nowMs: await $.clock.now() })
+  if (!p.ok) { await update($, handoverPlan, () => null); return p.text }
+  await update($, handoverPlan, () => p.plan)
+  return p.text
+}
+
+// Called only from a person's typed command or press. The plan must still match the checkout.
+async function confirmHandover($: any, push: boolean): Promise<string> {
+  const plan: any = await read($, handoverPlan)
+  const { root, layout } = await rootAndLayout($)
+  const c = await readCheckout($, root, layout)
+  const now: number = await $.clock.now()
+  const good = planStillGood(plan, plan ? keyOf(c, plan.words) : { branch: null, sha: null, porcelain: '', words: '' }, now)
+  if (!good.ok) {
+    await update($, handoverPlan, () => null)
+    return `Nothing was written. ${good.why}${plan ? ' Run /pmos-handover again to see a new plan.' : ''}`
+  }
+  // the note's facts, read fresh: the ladder for this initiative, and how far the branch is from the default
+  await refreshView($, true)
+  const v: any = await read($, view)
+  const def: string = c.g.defaultBranch ?? 'main'
+  const ahead = await c.run(['git', 'rev-list', '--count', `${def}..HEAD`])
+  const subj = await c.run(subjectsProbe(def) as string[])
+  const noteText = renderNote({
+    id: plan.id, branch: plan.branch, sha: c.g.sha, summary: v?.initiative?.id === plan.id ? v.summary : null,
+    commits: ahead.exitCode === 0 && /^\d{1,9}$/.test(out(ahead)) ? Number(out(ahead)) : 0, defaultBranch: def,
+    subjects: subj.exitCode === 0 ? out(subj).split('\n').filter(Boolean) : [], paths: plan.paths, words: plan.words, atIso: new Date(now).toISOString(),
+  })
+  // a note path that is a link, or that sits behind one, is never written through
+  const rootReal = (await $.fs.stat(root, { resolve: true }).catch(() => undefined))?.realPath ?? root
+  const noteDir = plan.noteRel.split('/').slice(0, -1).join('/')
+  const write = async (path: string, text: string) => {
+    for (const [p, expect] of [[path, `${rootReal}/${plan.noteRel}`], [`${root}/${noteDir}`, `${rootReal}/${noteDir}`]] as const) {
+      const st = await $.fs.stat(p, { resolve: true }).catch(() => undefined)
+      if (st && (st.isLink || (st.realPath && st.realPath !== expect))) throw new Error(`${p} is, or sits behind, a link`)
+    }
+    await $.fs.write(path, text)
+  }
+  const r = await carryOut({ plan, push, noteText, run: c.run, write })
+  await update($, handoverPlan, () => null)
+  await update($, resume, () => null)
+  await refreshView($, true)
+  return r.text
+}
+
+async function pressHandover($: any, push: boolean) {
+  try { $.ui.toast(`pmos-cockpit: ${await confirmHandover($, push)}`) } catch (e: any) { $.ui.toast(`pmos-cockpit: the handover did not run. ${String(e?.message ?? e)}`) }
+}
+
+// At session start: the newest note for this branch's initiative, and how far the branch has moved.
+async function loadResume($: any): Promise<void> {
+  try {
+    const { root, layout } = await rootAndLayout($)
+    const v: any = await read($, view)
+    const id: string | null = v?.initiative?.state === 'ok' ? v.initiative.id : null
+    const np = id === null ? null : notePaths(layout, root, id)
+    const text = np === null ? null : await readText($, np.abs)
+    const note = text === null ? null : parseNote(text)
+    if (id === null || np === null || note === null || note.id !== id || note.headSha === null) { await update($, resume, () => null); return }
+    const run = (argv: string[]) => sh($, argv, { cwd: root, timeoutMs: PROCESS_LIMIT_MS })
+    const pr = sinceProbes(note, np.rel) as any
+    const r: Record<string, any> = { ancestor: await run(pr.ancestor) }
+    if (r.ancestor.exitCode === 0) {
+      r.handoverCommit = await run(pr.handoverCommit)
+      const h = out(r.handoverCommit)
+      r.count = await run(countSince(/^[0-9a-f]{40,64}$/.test(h) ? h : note.headSha) as string[])
+    }
+    const line = resumeText(note, id, interpretSince(r))
+    await update($, resume, () => (line === null ? null : { text: line }))
+  } catch {
+    await update($, resume, () => null)
+  }
+}
+
 // Recording a reviewer's verdict: called only from a person's press or typed command. The offer is
 // cleared before the writer runs, so a second press records nothing.
 async function recordReview($: any): Promise<{ ok: boolean; text: string }> {
@@ -470,8 +593,9 @@ export const register: Register = (on) => {
   on('session.start', async ($, e, next) => {
     await $.command.register({ name: 'pmos-status', description: 'Show the PMOS layout, profile and skill registration' })
     await $.command.register({ name: 'pmos-repair-skills', description: 'Link the kit skills that are not registered in .claude/skills' })
-    await $.command.register({ name: 'pmos-grant', description: 'Mint one single-use grant: /pmos-grant merge:<PR> | publish:<artifact> [minutes] [your words]' })
+    await $.command.register({ name: 'pmos-grant', description: 'Mint one single-use grant: /pmos-grant merge:<PR> | publish:<artifact> [minutes] [initiative:<id>] [your words]' })
     await $.command.register({ name: 'pmos-slice', description: 'Open the initiative slice: the ladder, step by step, for the branch you are on' })
+    await $.command.register({ name: 'pmos-handover', description: 'Hand the branch over: /pmos-handover [your words] shows a plan; /pmos-handover confirm [local] commits and pushes it' })
     await $.command.register({ name: 'pmos-accept', description: 'Record your Acceptance of a run: /pmos-accept <run_id> pass|fail <note>' })
     await $.command.register({ name: 'pmos-review', description: 'Ask a read-only reviewer on another model to judge the newest run: /pmos-review [model]' })
     await $.command.register({ name: 'pmos-record-review', description: 'Record the reviewer verdict that is waiting (the same as pressing Record)' })
@@ -483,6 +607,8 @@ export const register: Register = (on) => {
     const s = await gather($)
     await update($, status, () => s)
     await refreshView($)
+    await update($, resumeGone, () => false)
+    await loadResume($)
     if (s.skills && s.skills.missing.length > 0) {
       $.ui.toast(`PMOS: ${s.skills.missing.length} kit skill(s) are not registered. Run /pmos-repair-skills.`)
     }
@@ -497,6 +623,8 @@ export const register: Register = (on) => {
     const lines = [summary(s)]
     const m: any = await read($, modeAtom)
     if (m) lines.push(describeMode(m))
+    const rs: any = await read($, resume)
+    if (rs?.text) lines.push(`resume   ${String(rs.text).replace(/^PMOS: /, '')}`)
     try { lines.push(`surfaces ${(await $.session.surfaces()).join(', ') || 'none reported'}`) } catch { lines.push('surfaces unavailable') }
     if (v?.summary) lines.push(`stage    ${v.summary.stage}${v.summary.next ? ` (next: ${v.summary.next.key})` : ''}${v.summary.gateFailures.length ? `; blocking: ${v.summary.gateFailures.join(', ')}` : ''}`)
     else if (v?.unavailable) lines.push(`stage    unavailable: ${v.unavailable}`)
@@ -652,10 +780,31 @@ export const register: Register = (on) => {
   on('command.run', { command: 'pmos-grant' }, async ($, e) => {
     if (!isPerson(e)) return { text: 'A grant is minted only by your own typed command or press. This run did not come from you, so nothing was written.' }
     const { root, layout } = await rootAndLayout($)
-    const plan = planGrant(e.args, { layout, root, pm: await whoAmI($, root) })
+    // the branch's initiative is recorded on the grant by default, when its record exists
+    const facts = await gitFacts($, root)
+    const idGuess = facts.branch?.startsWith('initiative/') ? facts.branch.slice('initiative/'.length) : null
+    const rp = idGuess ? recordPath(layout, idGuess) : null
+    const bi = resolveInitiative({ branch: facts.branch, recordExists: rp ? await $.fs.exists(rp) : null, commitsAhead: null })
+    const plan = planGrant(e.args, { layout, root, pm: await whoAmI($, root), branchInitiative: bi.state === 'ok' ? bi.id : null })
     if (!plan.ok) return { text: plan.text }
+    if (plan.initiative !== null) {
+      const rec = recordPath(layout, plan.initiative)
+      if (rec === null || !(await $.fs.exists(rec))) return { text: `No grant written. Initiative ${plan.initiative} has no record${rec ? ` at ${rec.replace(`${root}/`, '')}` : ''}.` }
+    }
     const r = await sh($, plan.argv, { cwd: root, env: plan.env })
-    return { text: r.exitCode === 0 ? `Granted ${plan.scope.kind}:${plan.scope.target}, single use, ${plan.ttl} minutes. ${out(r).split('\n').pop()}` : `No grant written. ${(r.stderr || out(r)).trim()}` }
+    return { text: r.exitCode === 0 ? `Granted ${plan.scope.kind}:${plan.scope.target}, single use, ${plan.ttl} minutes. ${plan.note} ${out(r).split('\n').pop()}` : `No grant written. ${(r.stderr || out(r)).trim()}` }
+  })
+
+  // A handover is a person's act: a plan first, and only a typed confirm or a press carries it out.
+  on('command.run', { command: 'pmos-handover' }, async ($, e) => {
+    if (!isPerson(e)) return { text: 'A handover commits and pushes only on your own typed command or press. This run did not come from you, so nothing was done.' }
+    const args = String(e.args ?? '').trim()
+    const m = /^confirm(?:[ \t]+(local))?$/.exec(args)
+    try {
+      return { text: m ? await confirmHandover($, m[1] !== 'local') : await planHandover($, args) }
+    } catch (err: any) {
+      return { text: `Nothing was done. The handover could not run: ${String(err?.message ?? err)}` }
+    }
   })
 
   on('command.run', { command: 'pmos-accept' }, async ($, e) => {
@@ -692,6 +841,18 @@ export const register: Register = (on) => {
         </Box>
       )
     }
+    const hp: any = await read($, handoverPlan)
+    if (hp && !e.props.hasSurvey) {
+      const { Box, Button, Text } = $.ui.resolve(e)
+      return (
+        <Box>
+          <Text>PMOS: handover plan for {hp.id}, {hp.paths.length} path(s){hp.push.run ? `, then ${hp.push.text}` : ', no push'}. </Text>
+          {hp.push.run && <Button key="go" label="Commit and push" variant="primary" onPress={() => pressHandover($, true)} />}
+          <Button key="local" label="Commit only" onPress={() => pressHandover($, false)} />
+          <Button key="cancel" label="Cancel" onPress={() => update($, handoverPlan, () => null)} />
+        </Box>
+      )
+    }
     const rv: any = await read($, reviewOffer)
     if (rv && !e.props.hasSurvey) {
       const { Box, Button, Text } = $.ui.resolve(e)
@@ -736,6 +897,16 @@ export const register: Register = (on) => {
         </Box>
       )
     }
+    const rs: any = await read($, resume)
+    if (!hasDrift(s) && rs?.text && !(await read($, resumeGone))) {
+      const { Box, Button, Text } = $.ui.resolve(e)
+      return (
+        <Box>
+          <Text>{clean(rs.text, 400)} </Text>
+          <Button key="dismiss" label="Dismiss" onPress={() => update($, resumeGone, () => true)} />
+        </Box>
+      )
+    }
     if (!hasDrift(s)) return next(e)
     const { Box, Button, Text } = $.ui.resolve(e)
     const k = s!.skills!

package/payload/mods/pmos-cockpit/types/index.d.ts

@@ -54,8 +54,23 @@ export type ViewState = {
 
 export type FactsCache = { id: string | null; sha: string; at: number; summary: NonNullable<ViewState['summary']> }
 
+export type HandoverPlan = {
+  id: string
+  branch: string
+  noteRel: string
+  noteAbs: string
+  paths: string[]
+  addPaths: string[]
+  push: { run: boolean; argv: string[] | null; text: string }
+  message: string
+  words: string
+  key: string
+  at: number
+  sha: string | null
+}
+
 declare module 'claude-code' {
   interface PluginState {
-    'pmos-cockpit': { status: CockpitStatus | null; isHidden: boolean; offer: { run_id: string; initiative_id: string; message: string } | null; view: ViewState | null; factsCache: FactsCache | null; mode: { mode: 'local' | 'hosted' | 'cloud'; signal: string | null } | null; review: { agentId: string; run_id: string; initiative_id: string; rubric_path: string; model: string } | null; reviewOffer: { run_id: string; initiative_id: string; rubric_path: string; verdict: string; score: number; evaluator_model: string; findings: string } | null }
+    'pmos-cockpit': { status: CockpitStatus | null; isHidden: boolean; offer: { run_id: string; initiative_id: string; message: string } | null; view: ViewState | null; factsCache: FactsCache | null; mode: { mode: 'local' | 'hosted' | 'cloud'; signal: string | null } | null; review: { agentId: string; run_id: string; initiative_id: string; rubric_path: string; model: string } | null; reviewOffer: { run_id: string; initiative_id: string; rubric_path: string; verdict: string; score: number; evaluator_model: string; findings: string } | null; handoverPlan: HandoverPlan | null; resume: { text: string } | null; resumeGone: boolean }
   }
 }

package/payload/okf/core/concepts/frontmatter-format.md

@@ -46,9 +46,10 @@ OKF's reserved filenames carry **no** frontmatter and are skipped by both the mi
 The enforced list lives in [`scripts/frontmatter_registry.txt`](/scripts/frontmatter_registry.txt) — the single source `frontmatter_lint.py` reads. A `type:` value not in it fails CI (this catches typos).
 
 - **OKF core:** `Concept`, `ADR`, `Template`, `Playbook`, `Reference`
-- **Planning:** `Initiative`, `PRD`, `Story`, `Rubric`, `OKR`, `Radar`, `Checklist`, `Calibration`, `Research`, `Design`, `Prototype`
+- **Planning:** `Initiative`, `PRD`, `Story`, `Rubric`, `OKR`, `Radar`, `Checklist`, `Calibration`, `Research`, `Design`, `Prototype`, `Handover`
   - `Initiative` is the repo-native initiative record in [`planning/initiatives/`](/planning/initiatives/), read by the [Initiative Gate](/.github/scripts/initiative-gate.sh). Its D56 **work-type lane** rides a separate `lane:` key — not `type:` — so the lane vocabulary and this registry never collide.
   - `Story` is a **user-story document** — the decomposition of a spec into the units of work handed to whoever builds them. It is the one type in this registry that is also **checked positionally** (see below), and it may carry an optional `jira:` / `confluence:` / `google_doc:` key naming the tracker record it corresponds to. That key is a *declaration* the workspace displays, never a lookup: PMOS holds no credential and makes no outbound request.
+  - `Handover` is the note the cockpit mod's `/pmos-handover` writes (`planning/handovers/<id>.md`, or `pmos/state/handovers/<id>.md` in a kit): one per initiative, replaced on each handover, with checked fields (`id`, `head_sha`, `branch`, `stage`, `next`, `commits`, `files`, `handover_at`) read back by the resume summary ([D81](/okf/products/pmos/adr/d81-cockpit-mod-and-grants.md)).
 - **Root governance:** `Decision`, `Principle`, `Debt`, `Discovery`, `Guide`
 
 ### When the path decides the type
@@ -72,6 +73,10 @@ Add **one line** to `scripts/frontmatter_registry.txt` and a matching row above.
 - [`scripts/frontmatter_lint.py`](/scripts/frontmatter_lint.py) — deterministic, no secrets; asserts the three required keys (and `type` ∈ registry) on every non-reserved tracked `.md`. Run in `.github/workflows/frontmatter-ci.yml`.
 - [`scripts/backfill_frontmatter.py`](/scripts/backfill_frontmatter.py) — the one-time migration: prepend-only, idempotent; reuses a file's already-declared `type`/`date` when present, else infers from path (`type`), the first H1 (`title`), and the last git-commit date (`timestamp`).
 
+## Typed relation keys (opt-in)
+
+A document may carry `supersedes`, `amended_by`, `cites` and `initiative` as one-line lists of paths to `.md` files. The knowledge graph (`pmos kg`) reads them as stated edges of that type. The keys are optional and are not backfilled. See [the knowledge-graph guide](/workspace/guide/knowledge-graph.md).
+
 ## Tenant repositories follow OKF v0.2 (D73)
 
 Since [D74](/okf/products/pmos/adr/d74-pmos-self-drops-timestamp.md) PMOS's own repository follows OKF v0.2 too: the Frontmatter Gate requires `type` and `title`, `timestamp` is optional and still checked when present, and `generated`, `sources`, `status`, `verified` and `stale_after` are accepted. Nothing was backfilled. The documents PMOS and its agents write into a **tenant** repository, such as a PM's, follow [OKF v0.2](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) instead: `type`, `title` and `description`, then `generated: {by, at}` in place of `timestamp`, `sources` in place of a body `# Citations` list, and `status` (`draft | stable | deprecated`), `verified` and `stale_after` as they apply. Every key sits on **one line**, because five of PMOS's frontmatter readers stop at the first indented line. Actors are `claude-code/<skill>` for an agent run, `human:<id>` for a person and `process:<name>` for a tool.

package/payload/planning/evals/eval-calibration.md

@@ -2,7 +2,7 @@
 type: Reference
 title: "Eval calibration log"
 description: "Append-only record of every PM override of an evaluator verdict."
-generated: {by: process:create-pmos, at: "2026-10-04T09:45:16Z"}
+generated: {by: process:create-pmos, at: "2026-10-04T21:21:45Z"}
 status: stable
 ---
 

package/payload/planning/okrs/health-budgets.md

@@ -2,7 +2,7 @@
 type: Reference
 title: "Health budgets"
 description: "Closed registry of health-budget anchors (D59), edited only by the PM."
-generated: {by: process:create-pmos, at: "2026-10-04T09:45:16Z"}
+generated: {by: process:create-pmos, at: "2026-10-04T21:21:45Z"}
 status: stable
 ---
 

package/payload/scripts/pmos-log.sh

@@ -14,13 +14,15 @@
 #   pmos-log.sh accept   <run_id> <initiative_id> <pass|fail> <note>
 #   pmos-log.sh outcome  <initiative_id> <validated|refuted|inconclusive> [evidence]
 #   pmos-log.sh friction <note...>
-#   pmos-log.sh grant    <merge:<PR or branch>|publish:<artifact>> <pm> <instruction> [ttl_minutes]
+#   pmos-log.sh grant    <merge:<PR or branch>|publish:<artifact>> <pm> <instruction> [ttl_minutes] [initiative_id]
 #   pmos-log.sh grant-use <grant_id> <action>
 #
 # `grant` and `grant-use` belong to the cockpit mod (D81). A grant is the PM's typed permission for
 # ONE action: single use, 120 minutes unless a shorter time is given (24 hours at most), one target. A
 # standing scope (docs-sync, outward:*) and any other scope is refused. The mod mints a grant only from
-# the PM's typed /pmos-grant or a press, and denies a model that runs either subcommand.
+# the PM's typed /pmos-grant or a press, and denies a model that runs either subcommand. A grant may
+# name its initiative (a slug with a record in state/initiatives/), so the mod's local gate has an
+# initiative to run against on a branch that names none (Run 7). Without it the row is unchanged.
 # PMOS_STATE_DIR names the folder of the ledgers when it is not <kit>/state (PMOS's own repository).
 set -euo pipefail
 
@@ -167,11 +169,11 @@ case "$cmd" in
     echo "✅ appended to state/discoveries.md: - $today $* #friction"
     ;;
   grant)
-    [ $# -ge 3 ] || fail "usage: grant <merge:<PR or branch>|publish:<artifact>> <pm> <instruction> [ttl_minutes]"
+    [ $# -ge 3 ] || fail "usage: grant <merge:<PR or branch>|publish:<artifact>> <pm> <instruction> [ttl_minutes] [initiative_id]"
     nonempty pm "$2"; nonempty instruction "$3"
-    row="$(python3 - "$1" "$2" "$3" "${4:-120}" <<'PY'
-import datetime, json, re, secrets, sys
-scope, pm, instruction, ttl = sys.argv[1:5]
+    row="$(python3 - "$1" "$2" "$3" "${4:-120}" "${5:-}" "$STATE" <<'PY'
+import datetime, json, os, re, secrets, sys
+scope, pm, instruction, ttl, initiative, state = sys.argv[1:7]
 def die(m):
     sys.stderr.write("pmos-log: ERROR — %s\n" % m); sys.exit(1)
 if re.match(r"^(docs-sync|outward)(:|$)", scope):
@@ -184,10 +186,18 @@ if not re.match(pat, target) or "*" in target or ".." in target:
     die('"%s" is not a single %s. A grant names one target; a wildcard is refused.' % (target, "PR number or branch name" if kind == "merge" else "artifact name"))
 if not re.match(r"^[0-9]{1,4}$", ttl) or not (1 <= int(ttl) <= 1440):
     die("ttl_minutes must be a whole number from 1 to 1440, got '%s'." % ttl)
+if initiative:
+    if not re.match(r"^[a-z0-9][a-z0-9._-]{0,99}$", initiative):
+        die('initiative "%s" is not a plain lowercase slug.' % initiative)
+    if not os.path.isfile(os.path.join(state, "initiatives", initiative + ".md")):
+        die('initiative "%s" has no record at state/initiatives/%s.md.' % (initiative, initiative))
 now = datetime.datetime.now(datetime.timezone.utc).replace(microsecond=0)
 fmt = lambda d: d.strftime("%Y-%m-%dT%H:%M:%SZ")
-print(json.dumps({"type": "grant", "id": "g-%d-%s" % (int(now.timestamp()), secrets.token_hex(3)), "scope": kind, "target": target,
-                  "pm": pm, "at": fmt(now), "expires_at": fmt(now + datetime.timedelta(minutes=int(ttl))), "uses": 1, "instruction": instruction}, separators=(",", ":")))
+row = {"type": "grant", "id": "g-%d-%s" % (int(now.timestamp()), secrets.token_hex(3)), "scope": kind, "target": target,
+       "pm": pm, "at": fmt(now), "expires_at": fmt(now + datetime.timedelta(minutes=int(ttl))), "uses": 1, "instruction": instruction}
+if initiative:
+    row["initiative"] = initiative
+print(json.dumps(row, separators=(",", ":")))
 PY
 )" || exit 1
     append grants.jsonl "$row"