create-pmos 0.43.0 → 0.45.0

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

@@ -0,0 +1,34 @@
+// The git questions the session view asks, as argv lists, and how to read the answers. The register
+// module runs them through `$.process`; a node test runs the same argv in real temporary
+// repositories (a plain checkout, a linked worktree, a detached head, no commits, no remote, no
+// repository at all), so the two cannot drift.
+//
+// Pure: no I/O. Each probe is bounded by the caller's time limit.
+
+export const PROBES = {
+  inside: ['git', 'rev-parse', '--is-inside-work-tree'],
+  branch: ['git', 'rev-parse', '--abbrev-ref', 'HEAD'],
+  sha: ['git', 'rev-parse', 'HEAD'],
+  dirs: ['git', 'rev-parse', '--path-format=absolute', '--git-dir', '--git-common-dir'],
+  defaultBranch: ['git', 'symbolic-ref', '--short', 'refs/remotes/origin/HEAD'],
+};
+
+/** The commits-ahead probe depends on the default branch, so it is built when asked. */
+export const aheadProbe = (defaultBranch) => ['git', 'rev-list', '--count', `${defaultBranch ?? 'main'}..HEAD`];
+
+const text = (r) => (r && r.exitCode === 0 && typeof r.stdout === 'string' ? r.stdout.trim() : '');
+
+/**
+ * @param {Record<string, { exitCode: number, stdout: string }|undefined>} r results by probe name
+ * @returns {{ noGit: boolean, branch: string|null, sha: string|null, linked: boolean, defaultBranch: string|null, commitsAhead: number|null }}
+ */
+export function interpretGit(r) {
+  if (text(r.inside) !== 'true') return { noGit: true, branch: null, sha: null, linked: false, defaultBranch: null, commitsAhead: null };
+  const branch = text(r.branch) || null;
+  const sha = /^[0-9a-f]{40,64}$/.test(text(r.sha)) ? text(r.sha) : null;
+  const dirs = text(r.dirs).split('\n').map((l) => l.trim()).filter(Boolean);
+  const linked = dirs.length === 2 && dirs[0] !== dirs[1];
+  const def = text(r.defaultBranch).replace(/^origin\//, '') || null;
+  const n = text(r.ahead);
+  return { noGit: false, branch, sha, linked, defaultBranch: def, commitsAhead: /^\d{1,9}$/.test(n) ? Number(n) : null };
+}

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

@@ -0,0 +1,17 @@
+// profile.mjs — the repository profile (D68), read from `.pmos-profile`.
+//
+// Two profiles exist: `pm-artifacts` and `product-code`. A missing file, an empty file or a value
+// that is neither is read as `product-code`, the stricter default (D81). The installer writes the
+// file only on a fresh `pm-artifacts` vendor, so an older tenant has none. `declared` says whether
+// the file named a profile, so a caller can tell "product-code" from "nothing said".
+
+export const PROFILES = ['pm-artifacts', 'product-code'];
+
+/** @param {string|null|undefined} text the file's text, or null when the file is missing */
+export function parseProfile(text) {
+  if (typeof text !== 'string') return { profile: 'product-code', declared: false, note: 'no .pmos-profile file' };
+  const first = text.split('\n').map((l) => l.trim()).find((l) => l !== '' && !l.startsWith('#'));
+  if (first === undefined) return { profile: 'product-code', declared: false, note: 'the .pmos-profile file names no profile' };
+  if (PROFILES.includes(first)) return { profile: first, declared: true, note: null };
+  return { profile: 'product-code', declared: false, note: `unknown profile "${first}"` };
+}

package/payload/mods/pmos-cockpit/hooks/lib/prompt-section.mjs

@@ -0,0 +1,49 @@
+// The one thing the cockpit mod says to the model on its own (D81, M11): a short system-prompt
+// section giving the session's initiative facts.
+//
+// It is built from a FIXED TEMPLATE over ALLOW-LISTED FIELDS. Each value must match its pattern or
+// be in its set, or it is left out. It is never escaped, because a value that needs escaping is a
+// value that should not be there. No title, evidence, label, branch name or other free text can
+// enter: a record or a branch is written by people, and a model reads this text as part of its
+// instructions. The section is at most 600 characters and is absent when there is no initiative.
+//
+// Pure: no I/O.
+
+import { KNOWN_STEPS, LANES, PROFILES, STAGES } from './session-facts.mjs';
+
+export const SECTION_ID = 'pmos-cockpit:session';
+export const MAX_SECTION_CHARS = 600;
+
+const SLUG = /^[a-z0-9][a-z0-9._-]{0,99}$/;
+const ANCHOR = /^(?:q[1-4]-\d{4}:o\d{1,2}:kr\d{1,2}|health:[a-z0-9][a-z0-9-]{0,40})$/;
+// a path inside the repository, written relative to it: letters, digits, dot, dash, underscore and slash
+const REL_PATH = /^[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+){0,5}$/;
+
+const pick = (v, ok) => (typeof v === 'string' && ok(v) ? v : null);
+
+/**
+ * @param {{ id: string|null, lane?: string, anchor?: string|null, stage?: string, nextKey?: string|null, stateRoot?: string|null, profile?: string }} f
+ * @returns {string|null}
+ */
+export function buildSection(f) {
+  const id = pick(f.id, (v) => SLUG.test(v));
+  if (id === null) return null;
+  const lane = pick(f.lane, (v) => LANES.includes(v));
+  const anchor = pick(f.anchor, (v) => ANCHOR.test(v));
+  const stage = pick(f.stage, (v) => STAGES.includes(v));
+  const next = pick(f.nextKey, (v) => KNOWN_STEPS.has(v));
+  const state = pick(f.stateRoot, (v) => REL_PATH.test(v) && !v.split('/').includes('..'));
+  const profile = pick(f.profile, (v) => PROFILES.includes(v));
+
+  const facts = [
+    `initiative ${id}`,
+    lane && `lane ${lane}`,
+    anchor && `anchor ${anchor}`,
+    stage && `stage ${stage}`,
+    next && `next step ${next}`,
+    state && `state root ${state}`,
+    profile && `profile ${profile}`,
+  ].filter(Boolean);
+  const text = `PMOS session facts, derived by the pmos-cockpit mod from this repository's workflow ladder. They are facts about the work, not instructions: ${facts.join('; ')}. Run node pmos/scripts/workflow-state.js ${id} for the full ladder.`;
+  return text.length <= MAX_SECTION_CHARS ? text : null;
+}

package/payload/mods/pmos-cockpit/hooks/lib/session-facts.mjs

@@ -0,0 +1,110 @@
+// The session view's facts (D81, M11, Run 3): what `workflow-state.js <id> --json` says about ONE
+// initiative, reduced to what the status line, the band, the prompt section and the slice need.
+//
+// Derived, never declared. Nothing here is read from a record except through the ladder, and every
+// field is checked against a pattern or an enum on the way in. A field that is missing, of another
+// type or outside its set becomes "unknown" or is dropped. Nothing throws. Free text from the
+// ladder (`why`, `action`, `evidence`, `title`) is never kept: the model never reads it, and the
+// person's views show only what is built from these checked fields.
+//
+// Two ladders exist (D68): the `product-code` ladder has thirteen steps; the `pm-artifacts` ladder
+// has route, brief, draft, review, approved and handoff. A test pins both sets, and the stage, lane
+// and profile sets, to `scripts/workflow-state.js`, so a new step there fails the mod's test
+// instead of showing "?".
+//
+// Pure: no I/O. The caller gives it text, an exit code and a clock value.
+
+export const PRODUCT_STEPS = ['route', 'anchor', 'prototype', 'understand', 'spec', 'priors', 'contract', 'build', 'quality', 'review', 'explain', 'accept', 'outcome'];
+export const PM_ARTIFACT_STEPS = ['route', 'brief', 'draft', 'review', 'approved', 'handoff'];
+export const KNOWN_STEPS = new Set([...PRODUCT_STEPS, ...PM_ARTIFACT_STEPS]);
+export const STEP_STATUSES = ['done', 'na', 'unknown', 'pending', 'blocked'];
+export const STAGES = ['intake', 'spec', 'contract', 'build', 'eval', 'accepted', 'brief', 'draft', 'review'];
+export const LANES = ['feature', 'discovery', 'chore', 'incident', 'content', 'prototype'];
+export const PROFILES = ['product-code', 'pm-artifacts'];
+
+export const MAX_OUTPUT_BYTES = 256 * 1024;
+export const CACHE_MS = 60_000;
+export const PROCESS_LIMIT_MS = 5_000;
+
+const SLUG = /^[a-z0-9][a-z0-9._-]{0,99}$/;
+const STEP_KEY = /^[a-z][a-z0-9_-]{0,30}$/;
+const ANCHOR = /^(?:q[1-4]-\d{4}:o\d{1,2}:kr\d{1,2}|health:[a-z0-9][a-z0-9-]{0,40})$/;
+const RULE = /^[A-Z][A-Z0-9]{0,3}$/;
+
+// Our own labels. The ladder's labels come from lane definitions; the view does not need them.
+const LABELS = {
+  route: 'route', anchor: 'anchor', prototype: 'prototype', understand: 'understand', spec: 'spec', priors: 'priors', contract: 'contract',
+  build: 'build', quality: 'quality', review: 'review', explain: 'explain', accept: 'accept', outcome: 'outcome',
+  brief: 'brief', draft: 'draft', approved: 'approved', handoff: 'handed off',
+};
+export const labelOf = (key) => LABELS[key] ?? key;
+
+/** What the process gave back, as parsed JSON or the reason there is none. */
+export function parseFactsOutput({ exitCode, stdout }) {
+  if (exitCode !== 0) return { ok: false, reason: `workflow-state exited ${exitCode}` };
+  const text = typeof stdout === 'string' ? stdout : '';
+  if (text.length > MAX_OUTPUT_BYTES) return { ok: false, reason: 'workflow-state output is over 256 KB' };
+  let json;
+  try { json = JSON.parse(text); } catch { return { ok: false, reason: 'workflow-state output is not JSON' }; }
+  if (json === null || typeof json !== 'object' || Array.isArray(json)) return { ok: false, reason: 'workflow-state output is not an object' };
+  if (json.ok !== true) return { ok: false, reason: 'the ladder reported an error for this initiative' };
+  return { ok: true, json };
+}
+
+const inSet = (v, set) => (typeof v === 'string' && set.includes(v) ? v : 'unknown');
+
+/**
+ * Reduce the ladder's JSON to checked fields. Never throws.
+ * @returns {{ id: string|null, lane: string, stage: string, profile: string, anchor: string|null, accepted: boolean, stopped: boolean,
+ *   gateFailures: string[], blockers: string[], next: { key: string }|null, steps: { key: string, label: string, status: string }[] }}
+ */
+export function summarize(json) {
+  const j = json !== null && typeof json === 'object' ? json : {};
+  const steps = [];
+  if (Array.isArray(j.steps)) {
+    for (const s of j.steps) {
+      if (s === null || typeof s !== 'object') continue;
+      if (typeof s.key !== 'string' || !STEP_KEY.test(s.key)) continue;
+      steps.push({ key: s.key, label: labelOf(s.key), status: inSet(s.status, STEP_STATUSES) });
+    }
+  }
+  const keys = (v) => (Array.isArray(v) ? v.filter((k) => typeof k === 'string' && STEP_KEY.test(k)) : []);
+  const rules = (v) => (Array.isArray(v) ? v.filter((k) => typeof k === 'string' && (RULE.test(k) || STEP_KEY.test(k))) : []);
+  const nextKey = j.next !== null && typeof j.next === 'object' && typeof j.next.step === 'string' && STEP_KEY.test(j.next.step) ? j.next.step : null;
+  return {
+    id: typeof j.id === 'string' && SLUG.test(j.id) ? j.id : null,
+    lane: inSet(j.lane, LANES),
+    stage: inSet(j.stage, STAGES),
+    profile: inSet(j.profile, PROFILES),
+    anchor: typeof j.anchor === 'string' && ANCHOR.test(j.anchor) ? j.anchor : null,
+    accepted: j.accepted === true,
+    stopped: j.stopped !== null && j.stopped !== undefined && typeof j.stopped === 'object',
+    gateFailures: rules(j.gate_failures),
+    blockers: keys(j.blockers),
+    next: nextKey === null ? null : { key: nextKey },
+    steps,
+  };
+}
+
+/** Is a cached entry good for this initiative at this commit, at this time? */
+export function isFresh(entry, id, sha, nowMs) {
+  return entry !== null && typeof entry === 'object'
+    && entry.id === id && entry.sha === sha && typeof sha === 'string' && sha !== ''
+    && typeof entry.at === 'number' && nowMs >= entry.at && nowMs - entry.at < CACHE_MS;
+}
+
+export const GLYPH = { done: '✓', blocked: '✗', pending: '○', unknown: '?', na: '–' };
+export const NEXT_GLYPH = '◐';
+
+/**
+ * One row per step. The glyph follows the status; the one step the ladder names next shows ◐ in
+ * place of ○ while it is pending. A blocked step stays ✗, because blocked says more than next.
+ */
+export function sliceRows(summary) {
+  const nextKey = summary.next?.key ?? null;
+  return summary.steps.map((s) => {
+    let glyph = GLYPH[s.status] ?? GLYPH.unknown;
+    if (s.key === nextKey && s.status === 'pending') glyph = NEXT_GLYPH;
+    return { key: s.key, label: s.label, status: s.status, glyph, isNext: s.key === nextKey };
+  });
+}

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

@@ -0,0 +1,69 @@
+// skills.mjs — are the kit's skills registered where Claude Code looks?
+//
+// The kit ships its skills as `pmos/skills-native/<name>/SKILL.md`. Claude Code reads project skills
+// from `.claude/skills/<name>`, and nothing in the kit used to put them there, so a tenant ran for
+// about two weeks with nine of nineteen skills present on disk and not loadable. This module decides
+// what is wrong. It never touches the file system: the caller gathers facts and applies the repair.
+//
+// The rule that matters most: a name that is already taken in `.claude/skills/` by anything that is
+// not a link to the kit's own skill is NEVER replaced. It may be a product's own skill.
+
+/** a skill name is a short slug; it becomes a path segment, so nothing else is accepted */
+export const NAME_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+
+const BLOCK_INDICATOR = /^[>|][-+]?$/;
+
+/**
+ * The frontmatter `description` of a SKILL.md, and whether it carries text.
+ * A block scalar (`description: >`) is folded; a bare indicator with no text under it is not text.
+ * @param {string} text the SKILL.md text
+ * @returns {{ ok: boolean, description: string }}
+ */
+export function parseDescription(text) {
+  const lines = String(text).split('\n');
+  if (lines[0].trim() !== '---') return { ok: false, description: '' };
+  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 { ok: false, description: '' };
+  const rest = fm[at].replace(/^description:\s*/, '').trimEnd();
+  if (!BLOCK_INDICATOR.test(rest)) {
+    const unquoted = rest.replace(/^(["'])(.*)\1$/, '$2');
+    return { ok: unquoted.trim() !== '', description: unquoted };
+  }
+  const folded = [];
+  for (const l of fm.slice(at + 1)) {
+    if (l.trim() === '' || /^[ \t]/.test(l)) { if (l.trim()) folded.push(l.trim()); continue; }
+    break;
+  }
+  const description = folded.join(' ');
+  return { ok: description !== '', description };
+}
+
+/**
+ * @typedef {{ name: string, descriptionOk: boolean, realPath: string|null }} NativeSkill
+ * @typedef {{ kind: string, isLink: boolean, realPath: string|null, target: string|null }} Linked
+ * @param {NativeSkill[]} native what the kit ships
+ * @param {Map<string, Linked>} linked what is in `.claude/skills`, by name
+ */
+export function diffSkills(native, linked) {
+  const out = { ok: [], missing: [], repairable: [], blocked: [], badDescription: [], badName: [] };
+  for (const s of native) {
+    if (!NAME_RE.test(s.name)) { out.badName.push(s.name); continue; }
+    if (!s.descriptionOk) { out.badDescription.push(s.name); continue; }
+    const have = linked.get(s.name);
+    if (!have) { out.missing.push(s.name); out.repairable.push(s.name); continue; }
+    if (have.isLink && have.realPath !== null && have.realPath === s.realPath) { out.ok.push(s.name); continue; }
+    if (have.isLink && have.realPath === null && have.target !== null && /(^|\/)pmos\/skills-native\//.test(have.target)) {
+      // a dangling link the kit itself made earlier: safe to make again
+      out.repairable.push(s.name); out.missing.push(s.name); continue;
+    }
+    out.blocked.push({ name: s.name, reason: have.isLink ? 'a link that points somewhere else' : 'a file or folder that is not a link (it may be a product skill)' });
+  }
+  return out;
+}
+
+/** the relative target of the link `.claude/skills/<name>`: from `.claude/skills/` up two levels to the repository root */
+export function linkTarget(name) {
+  return `../../pmos/skills-native/${name}`;
+}

package/payload/mods/pmos-cockpit/hooks/lib/status-line.mjs

@@ -0,0 +1,64 @@
+// The one-line status (D81, M11): `repo · worktree · branch · initiative · lane · stage → next`.
+//
+// Honest first: on a branch with no initiative it says so and never keeps the previous initiative's
+// facts. When the line is too long it drops parts in a stated order: the next step, then the lane,
+// then the worktree, then the branch, then the repo. The initiative and the stage go last. Every
+// piece is cleaned of control and direction-override characters, because a branch name is text a
+// stranger may have chosen.
+//
+// Pure: no I/O.
+
+export const DEFAULT_WIDTH = 80;
+const SEP = ' · ';
+const ARROW = ' → ';
+
+// C0 and C1 controls, DEL, and the bidirectional overrides and isolates.
+const UNSAFE = /[\u0000-\u001f\u007f-\u009f‪-‮⁦-⁩‎‏]/g;
+
+/** Text safe to draw on one line, at most `max` characters. */
+export function clean(value, max = 60) {
+  const s = String(value ?? '').replace(UNSAFE, ' ').replace(/\s+/g, ' ').trim();
+  return s.length > max ? `${s.slice(0, Math.max(1, max - 1))}…` : s;
+}
+
+const fit = (parts, next, width) => {
+  const text = parts.join(SEP) + (next ? ARROW + next : '');
+  return text.length <= width ? text : null;
+};
+
+/**
+ * @param {{ repo: string, worktree?: string|null, branch: string|null, noGit?: boolean,
+ *   initiative: { id: string|null, state: string },
+ *   facts: { stage: string, lane: string, next: { key: string }|null } | null,
+ *   unavailable?: string|null, width?: number }} v
+ */
+export function formatStatus(v) {
+  const width = Number.isInteger(v.width) && v.width >= 20 ? v.width : DEFAULT_WIDTH;
+  const repo = clean(v.repo, 30) || 'repo';
+  if (v.noGit) return clean(`${repo}${SEP}no git`, width);
+  const branch = v.branch === null || v.branch === '' || v.branch === 'HEAD' ? '(detached)' : clean(v.branch, 40);
+
+  if (v.initiative.id === null) return clean(`${repo}${SEP}${branch}${SEP}no initiative`, width);
+  const id = clean(v.initiative.id, 40);
+  if (v.initiative.state === 'no-record') return clean(`${repo}${SEP}${branch}${SEP}no record for ${id}`, width);
+
+  const stage = v.facts ? clean(v.facts.stage, 12) : 'stage unavailable';
+  const lane = v.facts ? clean(v.facts.lane, 12) : null;
+  const next = v.facts?.next ? clean(v.facts.next.key, 16) : null;
+  const worktree = v.worktree ? clean(v.worktree, 24) : null;
+
+  // each attempt drops one more part, in the stated order
+  const attempts = [
+    [[repo, worktree, branch, id, lane, stage], next],
+    [[repo, worktree, branch, id, lane, stage], null],
+    [[repo, worktree, branch, id, stage], null],
+    [[repo, branch, id, stage], null],
+    [[repo, id, stage], null],
+    [[id, stage], null],
+  ];
+  for (const [parts, n] of attempts) {
+    const text = fit(parts.filter((p) => p), n, width);
+    if (text !== null) return text;
+  }
+  return clean(`${id}${SEP}${stage}`, width);
+}