session-orchestrator 3.16.0

package/scripts/lib/state-md/mission-status.mjs

@@ -0,0 +1,247 @@
+/**
+ * Mission-status helpers for STATE.md.
+ *
+ * Handles both the frontmatter `mission-status:` block-seq field and the
+ * `## Mission Status` body section (body-level per-task status lines).
+ *
+ * Pure functions — no file I/O.
+ *
+ * Plus on-disk wrappers (`writeMissionStatusOnDisk`, `setMissionStatusOnDisk`)
+ * added for PRD 2026-05-22 § 4 Pattern 1 (issue #518). The on-disk wrappers
+ * delegate to the pure helpers above and route the read+write cycle through
+ * `writeStateMd` from frontmatter-mutators.mjs, which acquires
+ * `.orchestrator/state.lock` for mechanical serialization (PSA-004).
+ */
+
+import { parseStateMd, serializeStateMd } from './yaml-parser.mjs';
+import { updateFrontmatterFields, writeStateMd } from './frontmatter-mutators.mjs';
+
+/**
+ * Parses the optional `mission-status:` block from a STATE.md frontmatter object
+ * (as returned by `parseStateMd(...).frontmatter`).
+ *
+ * Returns `null` when the `mission-status` key is absent (backward-compat: pre-#340
+ * STATE.md files). Returns `[]` when the key is present but the value is an empty
+ * array. Returns the array of entries when present and non-empty.
+ *
+ * Does NOT validate individual entry shapes — callers that need schema validation
+ * should use `validateMissionStatusEntry` from mission-status-schema.mjs.
+ *
+ * @param {object} frontmatter
+ * @returns {object[]|null}
+ */
+export function parseMissionStatus(frontmatter) {
+  if (frontmatter === null || typeof frontmatter !== 'object' || Array.isArray(frontmatter)) {
+    return null;
+  }
+  if (!Object.prototype.hasOwnProperty.call(frontmatter, 'mission-status')) {
+    return null;
+  }
+  const raw = frontmatter['mission-status'];
+  if (!Array.isArray(raw)) {
+    // Present but not an array (e.g. null scalar from empty key) — treat as absent
+    return null;
+  }
+  // Return a shallow copy to prevent mutation of the parsed frontmatter
+  return raw.slice();
+}
+
+/**
+ * Writes (or replaces) the `mission-status:` field in STATE.md frontmatter.
+ *
+ * - When `missionStatusArray` is an empty array, writes `mission-status:` with an
+ *   empty block sequence — preserving the key so consumers know the feature is active.
+ * - When `missionStatusArray` is null or undefined, DELETES the key (opt-out / reset).
+ * - Works on string input (pure — no file I/O). Returns the updated STATE.md contents.
+ * - No-ops if `contents` has no parseable frontmatter (returns input unchanged).
+ *
+ * Individual entry objects must conform to the shape validated by
+ * `validateMissionStatusEntry` in mission-status-schema.mjs, but this function does
+ * NOT enforce that constraint — callers are responsible for pre-validation.
+ *
+ * @param {string} contents
+ * @param {object[]|null|undefined} missionStatusArray
+ * @returns {string}
+ */
+export function writeMissionStatus(contents, missionStatusArray) {
+  if (missionStatusArray === null || missionStatusArray === undefined) {
+    return updateFrontmatterFields(contents, { 'mission-status': null });
+  }
+  if (!Array.isArray(missionStatusArray)) {
+    return contents;
+  }
+  // isBlockSeqOfMappings requires at least 1 entry to classify as block-seq; for an empty
+  // array we store it as an empty block seq by treating it as a plain empty array which
+  // serializeScalar renders as `[]`.  For non-empty arrays of objects, use the block format.
+  return updateFrontmatterFields(contents, { 'mission-status': missionStatusArray.slice() });
+}
+
+/**
+ * Sets (or updates) the mission status for a single task in the `## Mission Status` body
+ * section of STATE.md. Creates the section if it does not exist.
+ *
+ * Format of each entry in the section:
+ *   - <taskId>: <status> (updated <ISO timestamp>)
+ *
+ * Pure function — no I/O. Returns original `contents` unchanged on bad input.
+ *
+ * @param {string} contents - Current STATE.md file contents (string)
+ * @param {string} taskId - Task identifier (e.g. 'm-1', 'docs-2')
+ * @param {string} status - One of: brainstormed | validated | in-dev | testing | completed
+ * @returns {string}
+ */
+export function setMissionStatus(contents, taskId, status) {
+  if (typeof contents !== 'string') return contents;
+  if (!taskId || typeof taskId !== 'string') return contents;
+  if (!status || typeof status !== 'string') return contents;
+  const parsed = parseStateMd(contents);
+  if (parsed === null) return contents;
+
+  const timestamp = new Date().toISOString();
+  const bullet = `- ${taskId}: ${status} (updated ${timestamp})`;
+  const lines = parsed.body.split('\n');
+
+  // Find existing ## Mission Status section
+  let headingIdx = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (/^##\s+Mission Status\b/.test(lines[i])) {
+      headingIdx = i;
+      break;
+    }
+  }
+
+  if (headingIdx === -1) {
+    // Section does not exist — append it at the end
+    let bodyOut = parsed.body;
+    if (!bodyOut.endsWith('\n')) bodyOut += '\n';
+    bodyOut += `\n## Mission Status\n\n${bullet}\n`;
+    return serializeStateMd({ frontmatter: parsed.frontmatter, body: bodyOut });
+  }
+
+  // Find end of section: next ## heading or end of lines
+  let sectionEnd = lines.length;
+  for (let i = headingIdx + 1; i < lines.length; i++) {
+    if (/^##\s+/.test(lines[i])) {
+      sectionEnd = i;
+      break;
+    }
+  }
+
+  // Look for an existing entry with this taskId within the section
+  const entryRe = new RegExp(`^-\\s+${taskId.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}:`);
+  let existingIdx = -1;
+  for (let i = headingIdx + 1; i < sectionEnd; i++) {
+    if (entryRe.test(lines[i])) {
+      existingIdx = i;
+      break;
+    }
+  }
+
+  if (existingIdx !== -1) {
+    // Replace existing entry in-place
+    lines[existingIdx] = bullet;
+  } else {
+    // Append after the last bullet in this section (or right after heading if empty)
+    let lastBulletIdx = -1;
+    for (let i = headingIdx + 1; i < sectionEnd; i++) {
+      if (/^-\s+/.test(lines[i])) lastBulletIdx = i;
+    }
+    if (lastBulletIdx !== -1) {
+      lines.splice(lastBulletIdx + 1, 0, bullet);
+    } else {
+      // No bullets yet — insert after heading with blank line
+      let insertAt = headingIdx + 1;
+      while (insertAt < sectionEnd && lines[insertAt].trim() === '') insertAt++;
+      const before = lines.slice(0, headingIdx + 1);
+      const after = lines.slice(insertAt);
+      const rebuilt = [...before, '', bullet, ...after];
+      return serializeStateMd({ frontmatter: parsed.frontmatter, body: rebuilt.join('\n') });
+    }
+  }
+
+  return serializeStateMd({ frontmatter: parsed.frontmatter, body: lines.join('\n') });
+}
+
+/**
+ * Reads the current mission status for a single task from the `## Mission Status` body
+ * section of STATE.md.
+ *
+ * Returns the status string (e.g. `'in-dev'`) or `null` if the task is not found or the
+ * section does not exist. Never throws — returns `null` on any bad input.
+ *
+ * @param {string} contents - Current STATE.md file contents (string)
+ * @param {string} taskId - Task identifier to look up (e.g. 'm-1')
+ * @returns {string|null}
+ */
+export function readMissionStatus(contents, taskId) {
+  if (typeof contents !== 'string') return null;
+  if (!taskId || typeof taskId !== 'string') return null;
+  const parsed = parseStateMd(contents);
+  if (parsed === null) return null;
+
+  const lines = parsed.body.split('\n');
+  let headingIdx = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (/^##\s+Mission Status\b/.test(lines[i])) {
+      headingIdx = i;
+      break;
+    }
+  }
+  if (headingIdx === -1) return null;
+
+  let sectionEnd = lines.length;
+  for (let i = headingIdx + 1; i < lines.length; i++) {
+    if (/^##\s+/.test(lines[i])) {
+      sectionEnd = i;
+      break;
+    }
+  }
+
+  // Match: - <taskId>: <status> (updated ...)
+  const escapedId = taskId.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const entryRe = new RegExp(`^-\\s+${escapedId}:\\s+(\\S+)`);
+  for (let i = headingIdx + 1; i < sectionEnd; i++) {
+    const m = entryRe.exec(lines[i]);
+    if (m) return m[1];
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// On-disk wrappers (PRD 2026-05-22 § 4 — Pattern 1, issue #518)
+// ---------------------------------------------------------------------------
+
+/**
+ * Lock-guarded `writeMissionStatus` — replaces the frontmatter `mission-status`
+ * block-seq under the state-lock.
+ *
+ * @param {string|undefined} repoRoot
+ * @param {object[]|null|undefined} missionStatusArray
+ * @param {object} [opts]
+ * @returns {Promise<{ written: boolean, path: string, contents: string|null }>}
+ */
+export async function writeMissionStatusOnDisk(repoRoot, missionStatusArray, opts = {}) {
+  return writeStateMd(
+    repoRoot,
+    (contents) => writeMissionStatus(contents, missionStatusArray),
+    opts
+  );
+}
+
+/**
+ * Lock-guarded `setMissionStatus` — sets or replaces a single task entry in
+ * the `## Mission Status` body section under the state-lock.
+ *
+ * @param {string|undefined} repoRoot
+ * @param {string} taskId
+ * @param {string} status   brainstormed | validated | in-dev | testing | completed
+ * @param {object} [opts]
+ * @returns {Promise<{ written: boolean, path: string, contents: string|null }>}
+ */
+export async function setMissionStatusOnDisk(repoRoot, taskId, status, opts = {}) {
+  return writeStateMd(
+    repoRoot,
+    (contents) => setMissionStatus(contents, taskId, status),
+    opts
+  );
+}

package/scripts/lib/state-md/recommendations.mjs

@@ -0,0 +1,57 @@
+/**
+ * Recommendation-fields contract for STATE.md v1.1 (extracted from state-md.mjs, issue #358).
+ *
+ * Self-contained leaf module — no imports from state-md.mjs (avoids circular deps).
+ * Re-exported from scripts/lib/state-md.mjs for callsite compatibility.
+ */
+
+/**
+ * Parses the 5 v1.1 Recommendation fields from a STATE.md frontmatter object
+ * (as returned by `parseStateMd(...).frontmatter`).
+ *
+ * Returns `null` when NONE of the 5 fields are present (backward-compat:
+ * pre-v1.1 STATE.md files).
+ *
+ * When a subset is present, populates the object with the parsed values and
+ * sets missing fields to null. Type-mismatched fields are also coerced to
+ * null (defensive — do not propagate garbage into downstream Mode-Selector).
+ * Caller is responsible for emitting partial/type-mismatch warn events.
+ *
+ * @param {object} frontmatter
+ * @returns {{mode: string|null, priorities: number[]|null, carryoverRatio: number|null, completionRate: number|null, rationale: string|null}|null}
+ */
+export function parseRecommendations(frontmatter) {
+  if (frontmatter === null || typeof frontmatter !== 'object' || Array.isArray(frontmatter)) {
+    return null;
+  }
+  const keys = [
+    'recommended-mode',
+    'top-priorities',
+    'carryover-ratio',
+    'completion-rate',
+    'rationale',
+  ];
+  const anyPresent = keys.some((k) => Object.prototype.hasOwnProperty.call(frontmatter, k));
+  if (!anyPresent) return null;
+
+  const mode = typeof frontmatter['recommended-mode'] === 'string'
+    ? frontmatter['recommended-mode']
+    : null;
+  const priorities = Array.isArray(frontmatter['top-priorities'])
+    && frontmatter['top-priorities'].every((x) => Number.isInteger(x))
+    ? frontmatter['top-priorities'].slice()
+    : null;
+  const carryoverRatio = typeof frontmatter['carryover-ratio'] === 'number'
+    && !Number.isNaN(frontmatter['carryover-ratio'])
+    ? frontmatter['carryover-ratio']
+    : null;
+  const completionRate = typeof frontmatter['completion-rate'] === 'number'
+    && !Number.isNaN(frontmatter['completion-rate'])
+    ? frontmatter['completion-rate']
+    : null;
+  const rationale = typeof frontmatter.rationale === 'string'
+    ? frontmatter.rationale
+    : null;
+
+  return { mode, priorities, carryoverRatio, completionRate, rationale };
+}

package/scripts/lib/state-md/yaml-parser.mjs

@@ -0,0 +1,234 @@
+/**
+ * Minimal hand-rolled YAML-subset parser + serializer for the fields used by
+ * the session-orchestrator STATE.md contract. Not a general-purpose YAML
+ * implementation — handles:
+ *   - Scalar strings, booleans, integers, nulls
+ *   - Flow-style integer arrays (`[1, 2, 3]`)
+ *   - Block-style sequences of mappings (issue #244), e.g. `docs-tasks:` with
+ *     indented `- key: value` entries. Only one nesting level supported.
+ *
+ * That is the full grammar permitted by skills/_shared/state-ownership.md.
+ *
+ * Never throws. Returns null for unparseable input rather than raising.
+ *
+ * Inverse property (#747 — root-fix for the 6.3-MB balloon incident #739):
+ * `parseScalar` and `serializeScalar` are mutually inverse for scalars the
+ * SERIALIZER produced. Concretely:
+ *   - serialize∘parse is a BYTE-fixpoint for any file this serializer emitted:
+ *     double-quoted scalars are JSON-escaped on emit and JSON.parse-unescaped
+ *     on read, so a literal `"` / `\` / newline no longer accretes an extra
+ *     backslash layer per round-trip (the compounding-growth mechanism).
+ *   - parse∘serialize preserves the VALUE and its runtime type exactly:
+ *     bool/null/number-SHAPED strings ('true', 'null', '42', '1.0') are
+ *     force-quoted on emit so they survive as strings instead of coercing to a
+ *     boolean/null/number on the next parse.
+ *   - KNOWN non-byte-fixpoint: a SINGLE-quoted source line normalises to
+ *     double-quoted on first serialize (content identical, bytes differ), then
+ *     converges to a byte-fixpoint after one cycle. The serializer never emits
+ *     single-quoted, so this only affects hand-authored input.
+ *
+ * Leaf module — no imports from peer state-md submodules (avoids circular deps).
+ */
+
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
+
+/**
+ * Parses a STATE.md file into frontmatter + body.
+ *
+ * @param {string} contents
+ * @returns {{frontmatter: object, body: string}|null}
+ */
+export function parseStateMd(contents) {
+  if (typeof contents !== 'string') return null;
+  const match = FRONTMATTER_RE.exec(contents);
+  if (!match) return null;
+  const [, fmText, body] = match;
+  const frontmatter = parseFrontmatter(fmText);
+  if (frontmatter === null) return null;
+  return { frontmatter, body: body.startsWith('\n') ? body.slice(1) : body };
+}
+
+/**
+ * Serializes a frontmatter object + body back into STATE.md format.
+ *
+ * @param {{frontmatter: object, body: string}} input
+ * @returns {string}
+ */
+export function serializeStateMd({ frontmatter, body }) {
+  const fmLines = [];
+  for (const [k, v] of Object.entries(frontmatter)) {
+    if (isBlockSeqOfMappings(v)) {
+      fmLines.push(`${k}:`);
+      for (const entry of v) {
+        serializeBlockSeqEntry(entry, fmLines);
+      }
+    } else {
+      fmLines.push(`${k}: ${serializeScalar(v)}`);
+    }
+  }
+  const bodyOut = body.startsWith('\n') ? body : `\n${body}`;
+  return `---\n${fmLines.join('\n')}\n---\n${bodyOut}`;
+}
+
+function parseFrontmatter(text) {
+  const out = {};
+  const lines = text.split(/\r?\n/);
+  let i = 0;
+  while (i < lines.length) {
+    const rstripped = lines[i].replace(/\s+$/, '');
+    if (rstripped === '' || /^\s*#/.test(rstripped)) {
+      i++;
+      continue;
+    }
+    if (/^\s/.test(rstripped)) return null;
+    const idx = rstripped.indexOf(':');
+    if (idx === -1) return null;
+    const key = rstripped.slice(0, idx).trim();
+    if (key === '') return null;
+    const valuePart = rstripped.slice(idx + 1).trim();
+    if (valuePart === '') {
+      const result = parseBlockValue(lines, i + 1);
+      if (result === null) return null;
+      out[key] = result.value;
+      i = result.nextIndex;
+    } else {
+      out[key] = parseScalar(valuePart);
+      i++;
+    }
+  }
+  return out;
+}
+
+/**
+ * Parses an optional block-sequence-of-mappings value following an empty
+ * `key:` line. Returns `{ value, nextIndex }` where:
+ *   - `value === null` means no block sequence was present (the `key:` has
+ *     no body) and `nextIndex === start` so the caller resumes at `start`.
+ *   - `value === [...]` means a block sequence was consumed.
+ * Returns `null` on malformed block syntax.
+ */
+function parseBlockValue(lines, start) {
+  let i = start;
+  while (i < lines.length) {
+    const rstripped = lines[i].replace(/\s+$/, '');
+    if (rstripped === '' || /^\s*#/.test(rstripped)) {
+      i++;
+      continue;
+    }
+    break;
+  }
+  if (i >= lines.length) return { value: null, nextIndex: start };
+  const peek = lines[i].replace(/\s+$/, '');
+  const bulletMatch = peek.match(/^(\s+)- /);
+  if (!bulletMatch) return { value: null, nextIndex: start };
+  const indent = bulletMatch[1];
+  const contIndent = indent + '  ';
+  const entries = [];
+  while (i < lines.length) {
+    const rstripped = lines[i].replace(/\s+$/, '');
+    if (rstripped === '' || /^\s*#/.test(rstripped)) {
+      i++;
+      continue;
+    }
+    if (!rstripped.startsWith(indent + '- ')) break;
+    const firstBody = rstripped.slice(indent.length + 2);
+    const firstColon = firstBody.indexOf(':');
+    if (firstColon === -1) return null;
+    const firstKey = firstBody.slice(0, firstColon).trim();
+    if (firstKey === '') return null;
+    const entry = {};
+    entry[firstKey] = parseScalar(firstBody.slice(firstColon + 1).trim());
+    i++;
+    while (i < lines.length) {
+      const inner = lines[i].replace(/\s+$/, '');
+      if (inner === '' || /^\s*#/.test(inner)) {
+        i++;
+        continue;
+      }
+      if (!inner.startsWith(contIndent) || inner.startsWith(indent + '- ')) break;
+      const body = inner.slice(contIndent.length);
+      if (/^\s/.test(body)) return null;
+      const colon = body.indexOf(':');
+      if (colon === -1) return null;
+      const key = body.slice(0, colon).trim();
+      if (key === '') return null;
+      entry[key] = parseScalar(body.slice(colon + 1).trim());
+      i++;
+    }
+    entries.push(entry);
+  }
+  return { value: entries, nextIndex: i };
+}
+
+function parseScalar(raw) {
+  if (raw === '' || raw === 'null' || raw === '~') return null;
+  if (raw === 'true') return true;
+  if (raw === 'false') return false;
+  if (/^-?\d+$/.test(raw)) return parseInt(raw, 10);
+  if (/^-?\d+\.\d+$/.test(raw)) return parseFloat(raw);
+  if (raw.startsWith('[') && raw.endsWith(']')) {
+    const inner = raw.slice(1, -1).trim();
+    if (inner === '') return [];
+    return inner.split(',').map((s) => parseScalar(s.trim()));
+  }
+  if (raw.startsWith('"') && raw.endsWith('"')) {
+    // Double-quoted: the serializer emits these via JSON.stringify, so JSON.parse
+    // is the exact inverse (unescapes `\"`, `\\`, `\n`, `\t`, `\uXXXX`, …). Fall
+    // back to a naive quote-strip if the interior is not valid JSON (hand-authored
+    // or already-corrupt content) — this module's never-throw contract holds.
+    try {
+      return JSON.parse(raw);
+    } catch {
+      return raw.slice(1, -1);
+    }
+  }
+  if (raw.startsWith("'") && raw.endsWith("'")) {
+    // Single-quoted: the serializer never emits this form (it always uses
+    // double-quotes via JSON.stringify), so a plain quote-strip is correct and
+    // no unescaping is defined. Sources like this normalise to double-quoted on
+    // the next serialize — a KNOWN non-byte-fixpoint (value preserved).
+    return raw.slice(1, -1);
+  }
+  return raw;
+}
+
+function isBlockSeqOfMappings(v) {
+  return (
+    Array.isArray(v) &&
+    v.length > 0 &&
+    v.every((x) => x !== null && typeof x === 'object' && !Array.isArray(x))
+  );
+}
+
+function serializeBlockSeqEntry(entry, fmLines) {
+  const entries = Object.entries(entry);
+  if (entries.length === 0) {
+    fmLines.push('  - {}');
+    return;
+  }
+  const [firstKey, firstValue] = entries[0];
+  fmLines.push(`  - ${firstKey}: ${serializeScalar(firstValue)}`);
+  for (let idx = 1; idx < entries.length; idx++) {
+    const [key, value] = entries[idx];
+    fmLines.push(`    ${key}: ${serializeScalar(value)}`);
+  }
+}
+
+/** Characters permitted in an unquoted (bare) scalar emission. */
+const BARE_SCALAR_RE = /^[\w\-./:+@]+$/;
+
+function serializeScalar(v) {
+  if (v === null || v === undefined) return 'null';
+  if (typeof v === 'boolean') return v ? 'true' : 'false';
+  if (typeof v === 'number') return String(v);
+  if (Array.isArray(v)) return `[${v.map(serializeScalar).join(', ')}]`;
+  const s = String(v);
+  // Emit bare ONLY when the value would round-trip back to the identical STRING.
+  // `parseScalar(s) === s` force-quotes bool/null/number-shaped strings
+  // ('true'/'false'/'null'/'42'/'1.0'), which would otherwise re-parse to a
+  // boolean/null/number — the silent type-coercion asymmetry (#747). Otherwise
+  // JSON.stringify, whose exact inverse is the JSON.parse branch in parseScalar.
+  // (parseScalar is a hoisted function declaration — safe to reference here.)
+  if (BARE_SCALAR_RE.test(s) && parseScalar(s) === s) return s;
+  return JSON.stringify(s);
+}