@hassangameryt/freeflow 0.4.0 → 0.6.0

package/skills/track-work/scripts/lib/schema.mjs

@@ -0,0 +1,277 @@
+import { fail } from "./model.mjs";
+import { CHECKPOINT_RESULTS, CHECKPOINT_TYPES, DECISION_OPERATIONS, UPDATE_INPUT_KEYS } from "./contract.mjs";
+
+const COMMON = `All existing-record mutations require --expected-sha from a confirmed view or prior confirmed result.
+Semantic JSON is supplied with --input <json-file|->. Unknown fields and incompatible types fail before persistence.`;
+
+const SCHEMAS = {
+  init: {
+    purpose: "Create a new ignored schema-v2 Working Record.",
+    input: `{
+  "taskName": "...",
+  "goal": "...",
+  "whatDefinesTask": "...",
+  "settled": "...",
+  "tentative": "...",
+  "open": "...",
+  "currentDirection": "...",
+  "boundaries": "...",
+  "route": "...",
+  "nextAction": "...",
+  "blockers": ["..."],
+  "upcomingCheckpoints": ["..."]
+}`,
+    rules: [
+      "The CLI supplies --root and --name; JSON supplies optional task context.",
+      "Context fields are scalar strings; blockers and upcomingCheckpoints are arrays of strings.",
+      "Use the dedicated start path for an explicitly authorized Current Slice.",
+    ],
+  },
+  update: {
+    purpose: "Apply one precise current-state or entity mutation without starting or settling a slice.",
+    examples: [
+      {
+        title: "Precise field edit",
+        input: `{
+  "edits": [
+    {
+      "target": "currentContext.currentDirection",
+      "replaceText": { "old": "old text", "new": "new text" }
+    }
+  ]
+}`,
+      },
+      {
+        title: "Add proposal",
+        input: `{
+  "edits": [
+    {
+      "target": { "kind": "proposals" },
+      "addEntity": {
+        "title": "Implement the bounded result",
+        "type": "Delivery",
+        "intendedResult": "The accepted result",
+        "expectedEvidence": "Focused verification"
+      }
+    }
+  ]
+}`,
+      },
+      {
+        title: "Add decision",
+        input: `{
+  "edits": [
+    {
+      "target": { "kind": "decisions" },
+      "addEntity": {
+        "title": "Keep one coherent slice",
+        "decision": "Keep related verification inside the same result",
+        "establishedBy": "User discussion"
+      }
+    }
+  ]
+}`,
+      },
+      {
+        title: "Select pending checkpoint",
+        input: `{
+  "currentSlice": {
+    "selectedCheckpoints": ["Focused review"]
+  },
+  "upcomingCheckpoints": [
+    "Focused review — selected by User discussion — review before continuation"
+  ]
+}`,
+      },
+      {
+        title: "Resolve pending checkpoint — Add checkpoint History",
+        input: `{
+  "edits": [
+    {
+      "target": { "kind": "checkpoints" },
+      "addEntity": {
+        "title": "Focused review",
+        "type": "Independent review",
+        "selectedBy": "User explicitly selected the review",
+        "condition": "Review before continuation",
+        "result": "Completed",
+        "judgment": "Pass",
+        "evidence": "Focused regression suite",
+        "effect": "Continuation is allowed"
+      }
+    },
+    {
+      "target": "currentWork.upcomingCheckpoints",
+      "set": []
+    }
+  ]
+}`,
+      },
+      {
+        title: "Add Note",
+        input: `{
+  "edits": [
+    {
+      "target": { "kind": "notes" },
+      "addEntity": {
+        "title": "Retained context",
+        "source": "User instruction",
+        "body": "Context worth preserving without active task effect."
+      }
+    }
+  ]
+}`,
+      },
+      {
+        title: "Reorder proposal",
+        input: `{
+  "edits": [
+    {
+      "target": { "kind": "proposal", "title": "First proposal" },
+      "moveAfter": "Second proposal"
+    }
+  ]
+}`,
+      },
+      {
+        title: "Supersede decision",
+        input: `{ "decision": { "operation": "supersede", "id": "D-001", "supersededBy": "D-002" } }`,
+      },
+    ],
+    rules: [
+      "Choose one example form; do not combine edits with direct semantic fields.",
+      "Use one edit per affected field or entity; unspecified values are preserved.",
+      "For a direct context field target use a scalar set value or replaceText {old, new}; context fields are scalar strings.",
+      "For an entity target use {field: {old, new}}; list add/remove operations apply only to editable list fields.",
+      "replaceText accepts one exact semantic match after line-ending normalization; ambiguous or missing matches fail.",
+      `Decision operations are limited to: ${[...DECISION_OPERATIONS].join(", ")}. Decision state and supersession links are controlled by the atomic decision operation, not precise field edits.`,
+      `Checkpoint types: ${[...CHECKPOINT_TYPES].join(", ")}. Terminal results: ${[...CHECKPOINT_RESULTS].join(", ")}.`,
+      "Use the exact same title in selectedCheckpoints and checkpoint History so settlement can reconcile the boundary.",
+      "Selecting a checkpoint preserves its source and condition in upcomingCheckpoints; resolving it adds terminal History and removes its upcoming entry atomically.",
+      "Titles are non-empty single-line strings; checkpoint history requires type, selectedBy, condition, and result.",
+      `Accepted top-level update fields: ${[...UPDATE_INPUT_KEYS].join(", ")}.`,
+      "Whole-object or whole-collection replacement is not accepted; use explicit edits with a target and operation.",
+      "Batch related edits in one command for one atomic write.",
+    ],
+  },
+  start: {
+    purpose: "Move one authorized proposal or direct result into Current Work.",
+    input:
+      '{ "proposalTitle": "...", "authoritySource": "...", "reasonAndScope": "...", "expectedEvidence": "...", "stopCondition": "..." }',
+    rules: ["The script assigns the S-NNN ID; the caller cannot supply one.", "There may be only one Current Slice."],
+  },
+  block: {
+    purpose: "Move the current In progress slice to Blocked.",
+    input:
+      '{ "sliceId": "S-NNN", "blocker": { "blocker": "...", "why": "...", "required": "..." }, "resumeWhen": "..." }',
+    rules: ["Record why continuation is unsafe and what resolution is required."],
+  },
+  resume: {
+    purpose: "Return the same currently Blocked slice to In progress.",
+    input: '{ "sliceId": "S-NNN", "resolutionSource": "..." }',
+    rules: ["Use reopen for historical slices."],
+  },
+  reopen: {
+    purpose: "Return a historical outcome to Current Work with the same ID.",
+    input:
+      '{ "sliceId": "S-NNN", "authoritySource": "...", "reopenReason": "...", "reasonAndScope": "...", "expectedEvidence": "...", "stopCondition": "..." }',
+    rules: ["Fresh active declarations are required; a full historical snapshot is never restored."],
+  },
+  close: {
+    purpose: "Compact and settle the current slice.",
+    input:
+      '{ "sliceId": "S-NNN", "finalState": "Completed", "outcome": "...", "evidence": ["..."], "reviewSummary": "...", "taskEffect": "..." }',
+    rules: [
+      "finalState must be Completed, Blocked, or Abandoned; Completed requires settled evidence, resolved checkpoints, and no pending boundaries.",
+      "Blocked requires deliberate park authority.",
+      "Abandoned requires authority, reason, residual effects, and evidence.",
+    ],
+  },
+  unlock: {
+    purpose: "Remove one explicitly identified stale mutation lock without touching the record.",
+    input:
+      '{ "scope": "record", "authoritySource": "...", "lockPid": 999999, "lockCreatedAt": "2000-01-01T00:00:00.000Z" }',
+    rules: [
+      "The lock must be older than the stale threshold and owned by a dead process.",
+      "scope is record by default or init for the repository init lock.",
+      "The supplied PID, creation timestamp, and owner path must match the current lock exactly.",
+      "Live or changed locks are never removed.",
+    ],
+  },
+  migrate: {
+    purpose: "Convert explicitly selected legacy or unsupported content to schema-v2 without semantic compression.",
+    input: `{
+  "authoritySource": "...",
+  "reason": "...",
+  "candidateText": "<complete schema-v2 record Markdown>",
+  "coverage": [
+    {
+      "unitId": "U-001",
+      "startByte": 0,
+      "endByte": 42,
+      "sourceSha256": "<exact source-unit hash>",
+      "kind": "content|blank",
+      "line": 1,
+      "disposition": "verbatim|represented|projection-only|formatting-normalized",
+      "targetPaths": ["currentContext.goal"]
+    }
+  ]
+}`,
+    rules: [
+      "Start with inspect and copy each sourceUnits unitId, byte boundary, hash, and kind into coverage.",
+      "Every exact source unit must appear once with matching boundaries, hash, and kind.",
+      "verbatim requires one exact, unconsumed candidate source unit; every other disposition requires existing targetPaths.",
+      "projection-only targets must belong to currentContext or currentWork.",
+      "Summarization, consolidation, and removal are rejected; use compress for semantic compaction.",
+      "Existing task and slice identities, state, and type cannot change during migration.",
+    ],
+  },
+  compress: {
+    purpose: "Compact an explicitly scoped schema-v2 representation with recoverable source evidence.",
+    input: `{
+  "authoritySource": "...",
+  "reason": "...",
+  "preservation": "<semantic preservation declaration>",
+  "scope": ["history.slices"],
+  "candidateText": "<complete schema-v2 record Markdown>"
+}`,
+    rules: [
+      "The candidate may change only paths inside scope.",
+      "Task state, IDs and ordering, Current Slice ownership and lifecycle, authority, blockers, pending boundaries, decision links, and strongest evidence are protected.",
+      "The source snapshot and operation manifest are created only on apply, never on dry run.",
+    ],
+  },
+};
+
+function renderSchema(command) {
+  const names = command === "all" ? Object.keys(SCHEMAS) : [command];
+  for (const name of names)
+    if (!SCHEMAS[name]) fail("invalid-schema-command", `No input schema exists for command: ${name}`);
+  return [
+    "# Track Work command schema",
+    "",
+    `Command: ${command}`,
+    "",
+    COMMON,
+    "",
+    ...names.flatMap((name) => {
+      const schema = SCHEMAS[name];
+      const examples = schema.examples ?? [{ title: "Input", input: schema.input }];
+      return [
+        `## ${name}`,
+        schema.purpose,
+        "",
+        ...examples.flatMap(({ title, input }) =>
+          [title ? `### ${title}` : null, title ? "" : null, "```json", input, "```", ""].filter(Boolean),
+        ),
+        "Rules:",
+        ...schema.rules.map((rule) => `- ${rule}`),
+        "",
+      ];
+    }),
+  ].join("\n");
+}
+
+export function renderCommandSchema(command = "all") {
+  return renderSchema(command);
+}

package/skills/track-work/scripts/lib/source-inventory.mjs

@@ -0,0 +1,162 @@
+import { Buffer } from "node:buffer";
+import { sha256 } from "./model.mjs";
+
+export function sourceUnits(text) {
+  const chunks = text.split(/(?<=\n)/);
+  let offset = 0;
+  return chunks.map((chunk, index) => {
+    const startByte = offset;
+    offset += Buffer.byteLength(chunk, "utf8");
+    const content = chunk.endsWith("\n") ? chunk.slice(0, -1) : chunk;
+    return {
+      unitId: `U-${String(index + 1).padStart(3, "0")}`,
+      startByte,
+      endByte: offset,
+      sourceSha256: sha256(chunk),
+      kind: content.trim() ? "content" : "blank",
+      line: index + 1,
+      text: chunk,
+    };
+  });
+}
+
+export function publicSourceUnits(text) {
+  return sourceUnits(text).map(({ text: _text, ...unit }) => unit);
+}
+
+export function sourceEntities(text) {
+  const entities = [];
+  let section = "";
+  let group = "";
+  for (const line of text.split(/\r\n?|\n/)) {
+    const match = /^(#{1,4})[ \t]+(.+?)\s*$/.exec(line);
+    if (!match) continue;
+    const level = match[1].length;
+    const title = match[2];
+    if (level === 2) {
+      section = title;
+      group = "";
+      continue;
+    }
+    if (level === 3) {
+      group = title;
+      if (section === "Proposed Slices") entities.push({ key: `proposal:${title}` });
+      else if (section === "Notes") entities.push({ key: `note:${title}` });
+      continue;
+    }
+    if (level !== 4 || section !== "History" || !["Decisions", "Checkpoints", "Slices"].includes(group)) continue;
+    const idMatch = /^([A-Z]-\d{3,})\s+—\s+(.+)$/.exec(title);
+    const kind = group === "Decisions" ? "decision" : group === "Checkpoints" ? "checkpoint" : "slice";
+    const identity = idMatch ? `${idMatch[1]}|${idMatch[2]}` : title;
+    entities.push({ key: `${kind}:${identity}` });
+  }
+  return entities;
+}
+
+export function sourceUnitOwners(text) {
+  const owners = new Map();
+  const topSections = new Set(["Current Context", "Current Work", "Proposed Slices", "History", "Notes"]);
+  const contextHeadings = new Set([
+    "Goal",
+    "What defines this task",
+    "Settled",
+    "Tentative",
+    "Open",
+    "Current direction",
+    "Boundaries",
+    "Active Decisions",
+  ]);
+  const workHeadings = new Set([
+    "Current route",
+    "Current Slice",
+    "Blockers",
+    "Upcoming checkpoints",
+    "Next useful action",
+  ]);
+  const historyGroups = new Set(["Decisions", "Checkpoints", "Slices"]);
+  let section = "";
+  let group = "";
+  let owner = null;
+  for (const unit of sourceUnits(text)) {
+    const line = unit.text.endsWith("\n") ? unit.text.slice(0, -1) : unit.text;
+    const match = /^(#{1,4})[ \t]+(.+?)\s*$/.exec(line);
+    if (match) {
+      const level = match[1].length;
+      const title = match[2];
+      let recognized = false;
+      if (level === 1) {
+        owner = "taskName";
+        recognized = /^Working Record:\s+/.test(title);
+      } else if (level === 2) {
+        section = title;
+        group = "";
+        owner = section === "Current Context" ? "currentContext" : section === "Current Work" ? "currentWork" : null;
+        recognized = topSections.has(section);
+      } else if (level === 3) {
+        group = title;
+        if (section === "Current Context") {
+          owner = "currentContext";
+          recognized = contextHeadings.has(title);
+        } else if (section === "Current Work") {
+          owner = title === "Current Slice" ? "currentWork.currentSlice" : "currentWork";
+          recognized = workHeadings.has(title);
+        } else if (section === "Proposed Slices") {
+          owner = `proposals[title=${JSON.stringify(title)}]`;
+          recognized = true;
+        } else if (section === "Notes") {
+          owner = `notes[title=${JSON.stringify(title)}]`;
+          recognized = true;
+        } else if (section === "History") {
+          owner = `history.${title.toLowerCase()}`;
+          recognized = historyGroups.has(title);
+        }
+      } else if (level === 4 && section === "History" && historyGroups.has(group)) {
+        const idMatch = /^([A-Z]-\d{3,})\s+—\s+(.+)$/.exec(title);
+        if (group === "Decisions")
+          owner = `history.decisions[${idMatch ? `id=${JSON.stringify(idMatch[1])}` : `title=${JSON.stringify(title)}`}]`;
+        else if (group === "Slices")
+          owner = `history.slices[${idMatch ? `id=${JSON.stringify(idMatch[1])}` : `title=${JSON.stringify(title)}`}]`;
+        else
+          owner = `history.checkpoints[${idMatch ? `id=${JSON.stringify(idMatch[1])}` : `title=${JSON.stringify(title)}`}]`;
+        recognized = true;
+      }
+      owners.set(unit.unitId, { owner, structural: true, recognized, entityKey: entityKeyForOwner(owner) });
+      continue;
+    }
+    if (!section) {
+      if (/^State:\s*/.test(line)) owner = "taskState";
+      else if (/^Last updated:\s*/.test(line)) owner = "lastUpdated";
+      else if (/^Schema:\s*/.test(line)) owner = "schemaVersion";
+      else if (line.trim()) owner = null;
+    }
+    owners.set(unit.unitId, { owner, structural: false, recognized: false, entityKey: entityKeyForOwner(owner) });
+  }
+  return owners;
+}
+
+function entityKeyForOwner(owner) {
+  if (!owner) return null;
+  const match = /^(proposals|notes|history\.decisions|history\.checkpoints|history\.slices)\[(?:id|title)=(.+)\]$/.exec(
+    owner,
+  );
+  if (match) {
+    const kind =
+      match[1] === "history.decisions"
+        ? "decision"
+        : match[1] === "history.checkpoints"
+          ? "checkpoint"
+          : match[1] === "history.slices"
+            ? "slice"
+            : match[1].slice(0, -1);
+    let identity = match[2];
+    if (identity.startsWith('"')) {
+      try {
+        identity = JSON.parse(identity);
+      } catch {
+        /* keep source identity */
+      }
+    }
+    return `${kind}:${identity}`;
+  }
+  return null;
+}