create-pmos 0.43.0 → 0.44.0

package/bin/cockpit-install.js

@@ -0,0 +1,130 @@
+'use strict';
+/* cockpit-install.js — the two things create-pmos does for the cockpit mod (D81).
+ *
+ *   mergeSettings(repoRoot)  offer the mod through the repository's .claude/settings.json
+ *   linkSkills(repoRoot)     register the kit's skills where Claude Code looks (.claude/skills)
+ *
+ * Both are conservative on purpose. They add; they never replace. A settings key that already holds a
+ * value is kept, a settings file that is not valid JSON is left alone, and a name already taken in
+ * .claude/skills is left alone, because it may be the product's own skill. Zero dependencies, no
+ * network. Kept in its own module so a test can import it; create-pmos.js runs its CLI at load.
+ */
+const fs = require('fs');
+const path = require('path');
+
+const MARKETPLACE = 'pmos-mods';
+const PLUGIN = 'pmos-cockpit';
+const NAME_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+
+const isPlainObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+/** What the settings file must carry for Claude Code to offer the mod. */
+function wanted() {
+  return {
+    extraKnownMarketplaces: { [MARKETPLACE]: { source: { source: 'directory', path: './pmos/mods' } } },
+    enabledPlugins: { [`${PLUGIN}@${MARKETPLACE}`]: true },
+  };
+}
+
+/** The two commands that do by hand what the settings entry does, for `--no-mod` and for a refusal. */
+function manualCommands() {
+  return [`claude plugin marketplace add ./pmos/mods`, `claude plugin install ${PLUGIN}@${MARKETPLACE}`];
+}
+
+/**
+ * Deep-merge the marketplace entry and `enabledPlugins` into `<repo>/.claude/settings.json`.
+ * Existing keys are kept as they are. Nothing is written when nothing is missing.
+ * @returns {{ changed: boolean, created: boolean, kept: string[], refused: string|null, file: string }}
+ */
+function mergeSettings(repoRoot) {
+  const file = path.join(repoRoot, '.claude', 'settings.json');
+  const existed = fs.existsSync(file);
+  let cur = {};
+  if (existed) {
+    try { cur = JSON.parse(fs.readFileSync(file, 'utf8')); }
+    catch (e) { return { changed: false, created: false, kept: [], refused: `${file} is not valid JSON (${e.message}); left untouched`, file }; }
+    if (!isPlainObject(cur)) return { changed: false, created: false, kept: [], refused: `${file} is not a JSON object; left untouched`, file };
+  }
+  const kept = [];
+  let changed = false;
+  const want = wanted();
+  for (const top of Object.keys(want)) {
+    if (cur[top] === undefined) { cur[top] = want[top]; changed = true; continue; }
+    if (!isPlainObject(cur[top])) { kept.push(`${top} (not an object, kept)`); continue; }
+    for (const key of Object.keys(want[top])) {
+      if (cur[top][key] === undefined) { cur[top][key] = want[top][key]; changed = true; }
+      else if (JSON.stringify(cur[top][key]) !== JSON.stringify(want[top][key])) kept.push(`${top}.${key} (kept your value)`);
+    }
+  }
+  if (changed) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(cur, null, 2) + '\n');
+  }
+  return { changed, created: changed && !existed, kept, refused: null, file };
+}
+
+/** Does a SKILL.md carry a description with text? A bare block-scalar indicator (">") does not. */
+function descriptionHasText(text) {
+  const lines = String(text).split('\n');
+  if (lines[0].trim() !== '---') return false;
+  const end = lines.findIndex((l, i) => i > 0 && l.trim() === '---');
+  const fm = lines.slice(1, end === -1 ? lines.length : end);
+  const at = fm.findIndex((l) => /^description:/.test(l));
+  if (at === -1) return false;
+  const rest = fm[at].replace(/^description:\s*/, '').trimEnd();
+  if (!/^[>|][-+]?$/.test(rest)) return rest.replace(/^(["'])(.*)\1$/, '$2').trim() !== '';
+  for (const l of fm.slice(at + 1)) {
+    if (l.trim() === '' || /^[ \t]/.test(l)) { if (l.trim()) return true; continue; }
+    break;
+  }
+  return false;
+}
+
+const lstat = (p) => { try { return fs.lstatSync(p); } catch { return null; } };
+const real = (p) => { try { return fs.realpathSync(p); } catch { return null; } };
+
+/**
+ * Link `.claude/skills/<name>` to `pmos/skills-native/<name>` for every kit skill that has none.
+ * @returns {{ linked: string[], ok: string[], blocked: {name:string, reason:string}[], badDescription: string[], errors: string[] }}
+ */
+function linkSkills(repoRoot) {
+  const out = { linked: [], ok: [], blocked: [], badDescription: [], errors: [] };
+  const native = path.join(repoRoot, 'pmos', 'skills-native');
+  if (!fs.existsSync(native)) return out;
+  const dest = path.join(repoRoot, '.claude', 'skills');
+  for (const e of fs.readdirSync(native, { withFileTypes: true })) {
+    if (!e.isDirectory() || !NAME_RE.test(e.name)) continue;
+    const skillMd = path.join(native, e.name, 'SKILL.md');
+    let text = '';
+    try { text = fs.readFileSync(skillMd, 'utf8'); } catch { /* reported as no description */ }
+    if (!descriptionHasText(text)) { out.badDescription.push(e.name); continue; }
+
+    const link = path.join(dest, e.name);
+    const target = `../../pmos/skills-native/${e.name}`;
+    const st = lstat(link);
+    if (st === null) {
+      try { fs.mkdirSync(dest, { recursive: true }); fs.symlinkSync(target, link, 'dir'); out.linked.push(e.name); }
+      catch (err) { out.errors.push(`${e.name}: ${err.message}`); }
+      continue;
+    }
+    if (st.isSymbolicLink()) {
+      const r = real(link);
+      if (r !== null && r === real(path.join(native, e.name))) { out.ok.push(e.name); continue; }
+      if (r === null) {
+        let was = '';
+        try { was = fs.readlinkSync(link); } catch { /* keep blocked */ }
+        if (/(^|\/)pmos\/skills-native\//.test(was)) {
+          try { fs.unlinkSync(link); fs.symlinkSync(target, link, 'dir'); out.linked.push(e.name); }
+          catch (err) { out.errors.push(`${e.name}: ${err.message}`); }
+          continue;
+        }
+      }
+      out.blocked.push({ name: e.name, reason: 'a link that points somewhere else' });
+      continue;
+    }
+    out.blocked.push({ name: e.name, reason: 'a file or folder that is not a link (it may be a product skill)' });
+  }
+  return out;
+}
+
+module.exports = { MARKETPLACE, PLUGIN, wanted, manualCommands, mergeSettings, linkSkills, descriptionHasText };

package/bin/create-pmos.js

@@ -26,6 +26,7 @@ const { spawnSync } = require('child_process');
 const PAYLOAD = path.join(__dirname, '..', 'payload');       // the assembled pmos/ kit (file-mode)
 const WORKSPACE = path.join(__dirname, '..', 'workspace');   // the bundled Terminal Workspace app (D62)
 const PKG = require(path.join(__dirname, '..', 'package.json'));
+const cockpit = require('./cockpit-install.js');                 // D81 — the mod offer and the skill links
 
 // Kernel paths (relative to the kit root) that --update may rewrite. Everything else is state.
 const KERNEL = [
@@ -38,6 +39,7 @@ const KERNEL = [
   'okf/core',
   'scripts',
   'templates',
+  'mods',                                  // D81 — the cockpit mod; --update refreshes it, never the settings entry
   'planning/evals/check_rubrics.py',
 ];
 
@@ -59,6 +61,35 @@ function stampInstall(kitDir, mode) {
   fs.appendFileSync(path.join(kitDir, 'KIT-VERSION'), stamp);
 }
 
+/* D81 — register the kit's skills where Claude Code looks, and (unless --no-mod) offer the cockpit mod
+ * through the repository's own settings. Additive only: it never replaces a settings key or a name
+ * already taken in .claude/skills. Claude Code asks the person to trust the project; this cannot
+ * install the mod silently. */
+function reportSkillLinks(r) {
+  if (r.linked.length) console.log(`   skills: linked ${r.linked.length} into .claude/skills (${r.linked.join(', ')})`);
+  if (r.ok.length && !r.linked.length) console.log(`   skills: ${r.ok.length} already registered in .claude/skills`);
+  for (const b of r.blocked) console.log(`   skills: left ${b.name} alone — ${b.reason}`);
+  if (r.badDescription.length) console.log(`   skills: not linked, no description: ${r.badDescription.join(', ')}`);
+  for (const e of r.errors) console.log(`   skills: could not link ${e}`);
+}
+function offerMod(repoRoot, opts) {
+  if (opts && opts.noMod) {
+    console.log('   mod: skipped (--no-mod). To add it later:');
+    for (const c of cockpit.manualCommands()) console.log(`        ${c}`);
+    return;
+  }
+  const m = cockpit.mergeSettings(repoRoot);
+  if (m.refused) {
+    console.log(`   mod: not offered — ${m.refused}. To add it by hand:`);
+    for (const c of cockpit.manualCommands()) console.log(`        ${c}`);
+    return;
+  }
+  if (m.changed) console.log(`   mod: pmos-cockpit offered in ${path.relative(repoRoot, m.file) || m.file}${m.created ? ' (created)' : ''}. If Claude Code does not offer it after you trust the project, run the two commands below.`);
+  if (m.changed) for (const c of cockpit.manualCommands()) console.log(`        ${c}`);
+  else console.log('   mod: already offered in .claude/settings.json');
+  for (const k of m.kept) console.log(`   mod: kept ${k}`);
+}
+
 function vendor(targetRoot, opts) {
   payloadOrDie();
   const kit = path.join(targetRoot, 'pmos');
@@ -85,6 +116,8 @@ function vendor(targetRoot, opts) {
   }
   console.log(`✅ PMOS kit vendored at ${kit} (${kitVersion().split('\n')[0]})`);
   console.log(`   profile: ${fs.readFileSync(profileFile, 'utf8').split('\n')[0]} (${profileFile})`);
+  reportSkillLinks(cockpit.linkSkills(targetRoot));
+  offerMod(targetRoot, opts);
   console.log(`
 Next steps in ${targetRoot}:
   1. If the repo is not git yet:  git init
@@ -94,7 +127,7 @@ Next steps in ${targetRoot}:
   4. Commit the pmos/ folder. Then follow pmos/AGENTS.md for every run.`);
 }
 
-function update(dirArg) {
+function update(dirArg, opts) {
   payloadOrDie();
   // Accept either the kit dir itself or its parent repo root.
   let kit = path.resolve(dirArg || '.');
@@ -104,6 +137,7 @@ function update(dirArg) {
   if (!fs.existsSync(path.join(kit, 'state'))) {
     die(`${kit} does not look like a vendored kit (no state/) — refusing to update.`);
   }
+  const hadMods = fs.existsSync(path.join(kit, 'mods'));
   for (const rel of KERNEL) {
     const src = path.join(PAYLOAD, rel);
     if (!fs.existsSync(src)) continue;
@@ -118,6 +152,14 @@ function update(dirArg) {
   }
   stampInstall(kit, 'update');
   console.log(`✅ kit kernel updated at ${kit} (${kitVersion().split('\n')[0]})`);
+  reportSkillLinks(cockpit.linkSkills(path.dirname(kit)));
+  // --update never edits .claude/settings.json on its own. A kit that had no mod before gets one line
+  // saying how to offer it; --offer-mod does the same merge a fresh vendor does.
+  if (opts && opts.offerMod) offerMod(path.dirname(kit), {});
+  else if (!hadMods && fs.existsSync(path.join(kit, 'mods'))) {
+    console.log('   mod: pmos-cockpit is now in pmos/mods. To offer it, re-run with --offer-mod, or by hand:');
+    for (const c of cockpit.manualCommands()) console.log(`        ${c}`);
+  }
   console.log('state/, planning/ (beyond check_rubrics.py), and okf/product/ were not touched. Review the diff as a normal PR.');
 }
 
@@ -285,7 +327,8 @@ if (args.includes('--help') || args.includes('-h')) {
   console.log('usage:');
   console.log('  create-pmos [target-dir]              vendor the file-mode kit into a repo (pm-artifacts profile, D68)');
   console.log('  create-pmos [target-dir] --code       …as a product-code repository instead (code lanes and ladder)');
-  console.log('  create-pmos --update [kit-or-repo]    refresh only the kit kernel');
+  console.log('  create-pmos [target-dir] --no-mod     …without offering the pmos-cockpit mod in .claude/settings.json');
+  console.log('  create-pmos --update [kit-or-repo]    refresh only the kit kernel (add --offer-mod to offer the mod in .claude/settings.json)');
   console.log('  create-pmos workspace [repo-dir]      install/upgrade + launch the Terminal Workspace GUI');
   console.log('  create-pmos workspace --reinstall     force-reinstall the workspace app (drop a stale global copy)');
   console.log('  create-pmos --version                 print version + bundled kernel provenance');
@@ -296,7 +339,7 @@ if (args.includes('--help') || args.includes('-h')) {
 } else if (positional[0] === 'workspace') {
   workspace(positional[1], { reinstall: args.includes('--reinstall') });
 } else if (args.includes('--update')) {
-  update(positional[0]);
+  update(positional[0], { offerMod: args.includes('--offer-mod') });
 } else {
-  vendor(path.resolve(positional[0] || '.'), { code: args.includes('--code') });
+  vendor(path.resolve(positional[0] || '.'), { code: args.includes('--code'), noMod: args.includes('--no-mod') });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pmos",
-  "version": "0.43.0",
+  "version": "0.44.0",
   "description": "Scaffold the PMOS portable kit — run the PMOS product-management workflow (initiative → lane-fit spec → contract → build → three gates, with work-type lanes for features, research, maintenance, incidents, and content) entirely inside your own repo, with all state as git-versioned files. Includes `workflow-sweep`, which audits the state every board derives from and separates real defects from work you simply have not done. `create-pmos workspace` also installs + launches the local Terminal Workspace GUI. No database, no network, no telemetry.",
   "license": "MIT",
   "bin": {

package/payload/AGENTS-HUMAN.md

@@ -6,22 +6,12 @@ timestamp: 2026-07-18
 
 # AGENTS-HUMAN.md — the PMOS kit for a human builder (D58)
 
-You're a person, not an agent — same loop, plain terms, one helper. The full protocol lives in
-[AGENTS.md](AGENTS.md); this page is everything you need day-to-day. **Never edit `pmos/state/`
-files by hand — use the helper**, which validates and appends (records are append-only; a
-correction is a new record, never an edit).
+You're a person, not an agent — same loop, plain terms, one helper. The full protocol lives in [AGENTS.md](AGENTS.md); this page is everything you need day-to-day. **Never edit `pmos/state/` files by hand — use the helper**, which validates and appends (records are append-only; a correction is a new record, never an edit).
 
 ## The loop (per piece of work)
 
-1. **Open the work.** Create `pmos/state/initiatives/<id>.md` with a lane
-   (`type: feature | discovery | chore | incident | content`) and its artifact — feature: PRD +
-   rubric (copy the templates from `pmos/okf/core/templates/`); discovery: a spike brief; chore:
-   an `intent:` line; incident: fix first, record within 48h; content: a content brief. Anchor to
-   a KR in `pmos/planning/okrs/` — or, for maintenance work with no honest KR, to a declared
-   health budget (`parent_kr: health:<id>` from `pmos/planning/okrs/health-budgets.md`). Always
-   one or the other; never unanchored.
-2. **Branch `initiative/<id>`, do the work.** For feature work, write your tests first where you
-   can — the CI you wired via `templates/product-ci-starter.yml` is your Quality Gate.
+1. **Open the work.** Create `pmos/state/initiatives/<id>.md` with a lane (`type: feature | discovery | chore | incident | content`) and its artifact — feature: PRD + rubric (copy the templates from `pmos/okf/core/templates/`); discovery: a spike brief; chore: an `intent:` line; incident: fix first, record within 48h; content: a content brief. Anchor to a KR in `pmos/planning/okrs/` — or, for maintenance work with no honest KR, to a declared health budget (`parent_kr: health:<id>` from `pmos/planning/okrs/health-budgets.md`). Always one or the other; never unanchored.
+2. **Branch `initiative/<id>`, do the work.** For feature work, write your tests first where you can — the CI you wired via `templates/product-ci-starter.yml` is your Quality Gate.
 3. **Record as you go** (each command prints exactly what it appended):
 
    ```sh
@@ -32,18 +22,13 @@ correction is a new record, never an edit).
    pmos/scripts/pmos-log.sh friction "what fought you"
    ```
 
-   The helper rejects bad values with a clear message (wrong verdict/disposition, a
-   validated/refuted outcome with no evidence, malformed score) — the same rules the hosted
-   backend enforces.
-4. **Merge = the Acceptance Gate.** The **accepting human (the PM)** merges and records it
-   (`accept … pass`) — if you built it and someone else accepts, they merge, not you. A solo
-   operator is their own PM and merges with that hat on. If
-   you declared an `outcome_metric` on the initiative, you're not done until you dispose it at
-   its horizon (`outcome …`).
-5. **Weekly (15 min):** run `python3 pmos/scripts/metrics.py` and read the red first; skim
-   `pmos/state/discoveries.md`.
+   Two more subcommands belong to the Claude Code mod and to you, not to an agent: `pmos/scripts/pmos-log.sh grant <merge:<PR>|publish:<artifact>> <you> "<your words>" [minutes]` mints one single-use grant, and `grant-use` records that it was spent. A standing scope (`docs-sync`, `outward:*`) is refused. The mod denies an agent that runs `accept`, `grant` or `grant-use`.
+
+   The helper rejects bad values with a clear message (wrong verdict/disposition, a validated/refuted outcome with no evidence, malformed score). It also refuses an acceptance that has no note, an acceptance for a run you have not logged with `run`, and any ledger file that is a symlink or has another hard link. Nothing is written when it refuses.
+
+4. **Merge = the Acceptance Gate.** The **accepting human (the PM)** merges and records it (`accept … pass`) — if you built it and someone else accepts, they merge, not you. A solo operator is their own PM and merges with that hat on. If you declared an `outcome_metric` on the initiative, you're not done until you dispose it at its horizon (`outcome …`).
+5. **Weekly (15 min):** run `python3 pmos/scripts/metrics.py` and read the red first; skim `pmos/state/discoveries.md`.
 
 ## Working with an agent sometimes?
 
-Mixed teams are fine: agents follow `AGENTS.md`, you follow this page — both write the same state
-through the same conventions, and `metrics.py` doesn't care who built.
+Mixed teams are fine: agents follow `AGENTS.md`, you follow this page — both write the same state through the same conventions, and `metrics.py` doesn't care who built.

package/payload/AGENTS.md

@@ -88,6 +88,10 @@ Every initiative carries a `type` — the lane picks what the gate requires **be
    + `pmos/planning/evals/check_rubrics.py`); **Review** = score against the rubric with the evaluator skill (adversarial, outcome-only, default-to-refute) and append to `evals.jsonl`; **Acceptance** = the human PM merges and disposes — final and non-delegable. Never merge your own PR.
 8. Log the run (`runs.jsonl`) and any friction (`discoveries.md`, `#friction`).
 
+## The Claude Code mod (D81)
+
+If `pmos/mods` is installed in Claude Code, it guards the session. A hand-write to a `*.jsonl` ledger is denied: write ledger rows with `pmos/scripts/pmos-log.sh`. You cannot write `acceptances.jsonl` or `grants.jsonl`, run `record-acceptance.js`, or run `pmos-log.sh accept`, `grant` or `grant-use`: only the PM does, by typing `/pmos-accept` or `/pmos-grant` or by pressing a button. A merge, a push to the default branch, a forced push and a publish are denied unless the PM has granted exactly that target, once. A cloud-mutating command is denied and the PM runs it. A Confluence, Jira, Slack or Gmail write asks the PM each time. When the mod denies a call, it names what to do next: do that, and do not look for another route to the same action.
+
 ## Human builders & multi-repo initiatives (D58)
 
 - **A human building instead of an agent?** Same loop, plain terms: [AGENTS-HUMAN.md](AGENTS-HUMAN.md). State is written with `scripts/pmos-log.sh` (validated, append-only) — never hand-edited. Mixed human+agent teams write the same state through the same conventions.

package/payload/KIT-VERSION

@@ -1,3 +1,3 @@
-kernel-source: pmos@e4f29fe
+kernel-source: pmos@7879e0c
 assembled: 2026-10-04
 mode: vendor

package/payload/mods/.claude-plugin/marketplace.json

@@ -0,0 +1,12 @@
+{
+  "name": "pmos-mods",
+  "owner": { "name": "PMOS" },
+  "metadata": { "description": "Claude Code mods that ship with the PMOS kit." },
+  "plugins": [
+    {
+      "name": "pmos-cockpit",
+      "source": "./pmos-cockpit",
+      "description": "Guards one Claude Code session for a PMOS repository and shows where the work stands."
+    }
+  ]
+}

package/payload/mods/pmos-cockpit/.claude-plugin/plugin.json

@@ -0,0 +1,9 @@
+{
+  "name": "pmos-cockpit",
+  "version": "0.2.0",
+  "description": "Checks that the kit's skills are registered, shows where a PMOS repository stands, and guards merge-class actions, ledgers and the acceptance and grants ledgers with typed single-use grants (D81).",
+  "types": "./types/index.d.ts",
+  "author": {
+    "name": "PMOS"
+  }
+}

package/payload/mods/pmos-cockpit/README.md

@@ -0,0 +1,60 @@
+---
+type: Reference
+title: "pmos-cockpit — the PMOS Claude Code mod"
+---
+
+# pmos-cockpit
+
+A Claude Code mod that ships in the PMOS kit as `pmos/mods/pmos-cockpit`. It is a plugin of function hooks. It makes no network request and sends no telemetry. The decision behind it is [D81](/okf/products/pmos/adr/d81-cockpit-mod-and-grants.md).
+
+## What it does
+
+**Skills and layout (Run 1).**
+
+- **Checks skill registration.** The kit ships its skills in `pmos/skills-native/`. Claude Code reads project skills from `.claude/skills/`. At session start the mod compares the two and names every kit skill that is not registered.
+- **Repairs it on request.** `/pmos-repair-skills`, or the Repair button in the band above the prompt, creates a symbolic link `.claude/skills/<name>` for each missing skill. It never replaces a file or folder that is already there, because that may be your own skill. It never links a skill that has no description.
+- **Shows the layout, profile and initiative.** `/pmos-status` names the layout (a vendored kit or PMOS's own repository), the state root, the profile and the initiative. A missing `.pmos-profile` is read as `product-code`. The initiative is the `<id>` in a branch named `initiative/<id>`, the same rule as the workspace. Any other branch gives "no initiative"; the mod never guesses from a similar name.
+
+**Guards and grants (Run 2).** The guards run on every tool call. Reading, editing and testing are never blocked. When the guard itself fails, it allows an ordinary call and denies the routes below, and it says so.
+
+| Route | What the guard does |
+|---|---|
+| Hand-write to a `*.jsonl` ledger in the state root (Edit, Write, redirect, heredoc, `tee`, `sed -i`, an inline interpreter, a write through a link) | Denies. The message names the writer: `pmos/scripts/pmos-log.sh`, or in PMOS's own repository `log-run.js`, `record-eval.js` and `record-outcome.js`. A read is allowed. |
+| Write to `acceptances.jsonl` or `grants.jsonl`, `record-acceptance.js`, `pmos-log.sh accept`, `grant` or `grant-use` | Denies. These are yours. |
+| Write to the installed mod (`pmos/mods`), `.claude/pmos-cockpit.json` or the plugin entries in `.claude/settings.json` | Denies. In PMOS's own repository `kit/mods/**` is source and is not protected. |
+| `gh pr merge`, the GitHub merge tools, a push to the default branch, a forced push, `npm publish` | Denies unless there is a live grant for exactly that PR, branch or package, and the local gate passes. The use of the grant is recorded before the action runs. |
+| A cloud-mutating command from `AGENTS.md` (`supabase db push` and the rest) | Denies. No grant covers it in this release. You run it. |
+| A Confluence, Jira, Slack, Gmail, Drive or Calendar write tool | Asks you for each item. The answer is not stored as a grant. |
+
+A grant is one line in `grants.jsonl`. You mint it by typing `/pmos-grant merge:361` or `/pmos-grant publish:create-pmos`, optionally with a number of minutes and your own words. It is single use, lasts 120 minutes unless you give fewer (24 hours at most), and covers one target. A push to the default branch or a forced push takes `merge:<branch>`. There are no standing grants: `docs-sync`, every `outward:` scope and any other scope is refused, and ignored if found in the ledger. The model cannot mint a grant, and the commands refuse a run that did not come from you.
+
+`/pmos-accept <run_id> pass|fail <note>` records your Acceptance through the same writer, with `pm_label` set. When your own message reads as an approval, a band offers Pass, Fail and Not now for the newest run of the branch's initiative that has no acceptance. Your press writes the row; the note quotes your message. Nothing is written from inferred text.
+
+Before a merge-class action the mod runs the local gate for the branch's initiative (`workflow-state.js --gate`, and `gate-initiative.sh` in a kit) and shows the result. A failing gate stops the action even with a grant. It does not see anchors, which only CI resolves, or anything on a remote. When the branch names no initiative, the gate is reported as not run and the grant alone decides.
+
+## What it does not cover
+
+A shell can do what a matcher does not name. The guards are defence in depth. The writers validate, and branch protection or CI stays the real gate where a remote exists. These routes are not caught, and `hooks/lib/bypass.test.mjs` asserts that so the list stays honest:
+
+- a script written first and run second (`bash /tmp/x.sh`);
+- a path built from pieces no pattern can join (`'runs' + '.js' + 'onl'`);
+- a patch that touches a ledger (`git apply`);
+- a Bash write through a link that points at a ledger (Edit and Write are resolved to where the link leads; Bash is not);
+- `cd npm-pkg && npm publish`: the mod reads the package name from the session root, so a publish from another folder finds no matching grant and is denied. Run it yourself, or run it from the folder.
+
+The outward ask depends on the permission mode's decider. It is not a guard when permissions are bypassed.
+
+## Install
+
+`create-pmos` writes a marketplace entry and `enabledPlugins` into your `.claude/settings.json`. Claude Code asks you to trust the project, then offers the plugin. To skip the entry, run `create-pmos` with `--no-mod`. To install by hand, run `claude plugin marketplace add ./pmos/mods` and then `claude plugin install pmos-cockpit@pmos-mods`.
+
+New links are read by Claude Code in the next session.
+
+## Test
+
+- `node --test "kit/mods/pmos-cockpit/hooks/lib/*.test.mjs"` runs the pure logic with plain node.
+- `claude plugin validate kit/mods/pmos-cockpit` and `claude plugin test kit/mods/pmos-cockpit` run the manifest checks and the hook tests. They need the Claude Code CLI.
+
+## Limits
+
+Verified only in a terminal on Claude Code 2.1.289. Whether the desktop app, VS Code or the web load a function-hook mod is not verified, and Claude Code's documentation says a cloud session does not load a marketplace that a repository lists in its settings. The registration check runs in a vendored kit only. A project-relative marketplace path in project settings is not verified.

package/payload/mods/pmos-cockpit/hooks/hooks.json

@@ -0,0 +1 @@
+{ "modules": ["./register.tsx"] }

package/payload/mods/pmos-cockpit/hooks/lib/commands.mjs

@@ -0,0 +1,53 @@
+// What the person's two commands do, as plain data. The module that wires them runs the argv through
+// `$.process`; keeping the planning here lets a node test check it without raising a command as the
+// person, which no test can do.
+import { DEFAULT_TTL_MINUTES, parseScope } from './grants.mjs';
+
+/** The kit's writer, and where it writes. PMOS's own repository has no grants writer, so it uses the kit's over planning/runs. */
+export function writerOf(layout, root) {
+  const r = String(root).replace(/\/+$/, '');
+  if (layout.kind === 'kit') return { argv: ['bash', `${r}/pmos/scripts/pmos-log.sh`], env: {} };
+  if (layout.kind === 'self') return { argv: ['bash', `${r}/kit/scripts/pmos-log.sh`], env: { PMOS_STATE_DIR: layout.stateRoot } };
+  return null;
+}
+
+/** /pmos-grant <scope> [minutes] [your words] -> the writer call, or the reason there is none. */
+export function planGrant(argsText, { layout, root, pm }) {
+  const words = String(argsText).trim().split(/\s+/).filter(Boolean);
+  const scope = parseScope(words[0] ?? '');
+  if (!scope.ok) return { ok: false, text: `No grant written. ${scope.reason}` };
+  const rest = words.slice(1);
+  let ttl = DEFAULT_TTL_MINUTES;
+  if (rest.length > 0 && /^\d+$/.test(rest[0])) ttl = Number(rest.shift());
+  const instruction = rest.join(' ') || `/pmos-grant ${String(argsText).trim()}`;
+  const w = writerOf(layout, root);
+  if (w === null) return { ok: false, text: 'No grant written. There is no PMOS state here.' };
+  return { ok: true, argv: [...w.argv, 'grant', `${scope.kind}:${scope.target}`, pm, instruction, String(ttl)], env: w.env, scope, ttl };
+}
+
+/** /pmos-accept <run_id> pass|fail <note>. The note is required. */
+export function parseAccept(argsText) {
+  const m = /^(\S+)\s+(pass|fail)\s+([\s\S]+)$/.exec(String(argsText).trim());
+  if (!m) return { ok: false, text: 'Usage: /pmos-accept <run_id> pass|fail <note>. The note is required.' };
+  return { ok: true, run_id: m[1], label: m[2], note: m[3].trim() };
+}
+
+/** The writer call that records one acceptance, or the reason there is none. */
+export function planAcceptance({ layout, root, run, label, note, pm, atIso }) {
+  const r = String(root).replace(/\/+$/, '');
+  if (layout.kind === 'kit') {
+    const w = writerOf(layout, root);
+    return { ok: true, argv: [...w.argv, 'accept', run.run_id, run.initiative_id, label, note], env: w.env };
+  }
+  if (layout.kind === 'self') {
+    const row = { run_id: run.run_id, initiative_id: run.initiative_id, accepted: label === 'pass', pm_label: label, pm, at: atIso, note };
+    return { ok: true, argv: ['node', `${r}/scripts/record-acceptance.js`, JSON.stringify(row)], env: {} };
+  }
+  return { ok: false, text: 'There is no PMOS state here, so there is nowhere to record an acceptance.' };
+}
+
+/** The note a press writes: the person's own message, and the press, and no claim of hand-verification. */
+export function pressNote(message, label, runId) {
+  const quoted = String(message).replace(/\s+/g, ' ').trim().slice(0, 300);
+  return `Accepted on the PM's message "${quoted}" and the PM's press of ${label === 'pass' ? 'Pass' : 'Fail'} on run ${runId}. Recorded by the cockpit mod. NO HAND-VERIFICATION IS CLAIMED ON THE PM SIDE and none is invented.`;
+}

package/payload/mods/pmos-cockpit/hooks/lib/grants.mjs

@@ -0,0 +1,88 @@
+// Grants (D81, M7): what the PM typed, read back as a decision the guards can act on.
+//
+// A grant is one line in `grants.jsonl` in the state root, minted by the typed /pmos-grant command or
+// a person's press through the kit's writer, never by a model tool call. A use is a second line,
+// because the ledger is append-only.
+//
+//   {"type":"grant","id":"g-…","scope":"merge","target":"361","pm":"…","at":"…","expires_at":"…","uses":1,"instruction":"…"}
+//   {"type":"use","grant_id":"g-…","at":"…","action":"…"}
+//
+// This release has two scopes and no standing grant. `merge` covers one PR number (or one branch name
+// for a push), `publish` covers one artifact. A scope the code does not know, including `docs-sync`
+// and every `outward:` scope, is refused when minted and ignored when read. A grant for one target
+// never covers another. A grant is live when it has not expired and has not been used.
+//
+// Pure: it reads text and a clock value it is given.
+
+export const SCOPES = ['merge', 'publish'];
+export const DEFAULT_TTL_MINUTES = 120;
+export const MAX_TTL_MINUTES = 24 * 60;
+
+const TARGET = {
+  merge: /^(?:\d{1,9}|[A-Za-z0-9][A-Za-z0-9._\/-]{0,79})$/,
+  publish: /^[A-Za-z0-9@][A-Za-z0-9@._\/-]{0,99}$/,
+};
+
+/** Parse "merge:361" into its parts, or say why not. */
+export function parseScope(text) {
+  const raw = String(text ?? '').trim();
+  if (raw === '') return { ok: false, reason: 'a scope is required, for example merge:361 or publish:create-pmos' };
+  if (/^docs-sync(?::|$)/.test(raw) || /^outward(?::|$)/.test(raw)) {
+    return { ok: false, reason: `"${raw}" is a standing scope. Standing grants are not allowed in this release (D81). Mint one single-use grant per action.` };
+  }
+  const at = raw.indexOf(':');
+  if (at === -1) return { ok: false, reason: `unknown scope "${raw}". Use merge:<PR number or branch> or publish:<artifact>.` };
+  const kind = raw.slice(0, at);
+  const target = raw.slice(at + 1);
+  if (!SCOPES.includes(kind)) return { ok: false, reason: `unknown scope "${kind}". Use merge:<PR number or branch> or publish:<artifact>.` };
+  if (target === '' || target.includes('*') || target.includes('..') || !TARGET[kind].test(target)) {
+    return { ok: false, reason: `"${target}" is not a single ${kind === 'merge' ? 'PR number or branch name' : 'artifact name'}. A grant names one target; a wildcard is refused.` };
+  }
+  return { ok: true, kind, target };
+}
+
+/** Parse the ledger text. Rows that are not valid grants or uses are counted and ignored. */
+export function parseLedger(text) {
+  const grants = new Map();
+  const uses = new Map();
+  let ignored = 0;
+  for (const line of String(text ?? '').split('\n')) {
+    const l = line.trim();
+    if (l === '') continue;
+    let r;
+    try { r = JSON.parse(l); } catch { ignored += 1; continue; }
+    if (r === null || typeof r !== 'object' || Array.isArray(r)) { ignored += 1; continue; }
+    if (r.type === 'use' && typeof r.grant_id === 'string') { uses.set(r.grant_id, (uses.get(r.grant_id) ?? 0) + 1); continue; }
+    if (r.type !== 'grant' || typeof r.id !== 'string' || !SCOPES.includes(r.scope) || typeof r.target !== 'string') { ignored += 1; continue; }
+    if (!TARGET[r.scope].test(r.target) || r.target.includes('*') || r.target.includes('..')) { ignored += 1; continue; }
+    const at = Date.parse(r.at);
+    const exp = Date.parse(r.expires_at);
+    if (Number.isNaN(at) || Number.isNaN(exp) || exp <= at || exp - at > MAX_TTL_MINUTES * 60_000 || r.uses !== 1) { ignored += 1; continue; }
+    grants.set(r.id, { id: r.id, scope: r.scope, target: r.target, at, expires: exp, pm: r.pm, instruction: r.instruction });
+  }
+  return { grants, uses, ignored };
+}
+
+/**
+ * Is there a live grant for exactly this action?
+ * @returns {{ ok: true, grant: object } | { ok: false, reason: string }}
+ */
+export function checkGrant(text, want, nowMs) {
+  const { grants, uses } = parseLedger(text);
+  let sawExpired = false;
+  let sawUsed = false;
+  let sawOther = false;
+  for (const g of grants.values()) {
+    if (g.scope !== want.kind) continue;
+    if (g.target !== String(want.target)) { sawOther = true; continue; }
+    if (g.at > nowMs + 5 * 60_000) continue; // minted in the future: not trusted
+    if ((uses.get(g.id) ?? 0) >= 1) { sawUsed = true; continue; }
+    if (nowMs >= g.expires) { sawExpired = true; continue; }
+    return { ok: true, grant: g };
+  }
+  const named = `${want.kind}:${want.target}`;
+  if (sawUsed) return { ok: false, reason: `the grant for ${named} was already used. A grant is single use.` };
+  if (sawExpired) return { ok: false, reason: `the grant for ${named} has expired.` };
+  if (sawOther) return { ok: false, reason: `there is a grant, but not for ${named}. A grant covers one target.` };
+  return { ok: false, reason: `there is no grant for ${named}.` };
+}