@hassangameryt/freeflow 0.6.0 → 0.7.1

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

@@ -1,277 +0,0 @@
-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

@@ -1,162 +0,0 @@
-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;
-}

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

@@ -1,134 +0,0 @@
-import { execFile as execFileCallback } from "node:child_process";
-import { access, lstat, realpath } from "node:fs/promises";
-import { promisify } from "node:util";
-import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
-import { ensureString, fail } from "./model.mjs";
-
-const execFile = promisify(execFileCallback);
-
-export function pathInside(root, candidate) {
-  const rootPath = resolve(root);
-  const candidatePath = resolve(candidate);
-  const rel = relative(rootPath, candidatePath);
-  return rel === "" || (!rel.startsWith(`..${sep}`) && rel !== ".." && !isAbsolute(rel));
-}
-
-export async function assertNoSymlinkPath(path, stopAt) {
-  let current = resolve(path);
-  const boundary = resolve(stopAt);
-  while (pathInside(boundary, current)) {
-    try {
-      const entry = await lstat(current);
-      if (entry.isSymbolicLink()) fail("unsafe-symlink", `Mutable path contains a symlink: ${current}`);
-    } catch (error) {
-      if (error?.code !== "ENOENT") throw error;
-    }
-    if (current === boundary) break;
-    const parent = dirname(current);
-    if (parent === current) break;
-    current = parent;
-  }
-}
-
-export async function exists(path) {
-  try {
-    await access(path);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-export async function gitInfo(root) {
-  try {
-    const result = await execFile("git", ["-C", root, "rev-parse", "--show-toplevel"], { maxBuffer: 1024 * 1024 });
-    const gitRoot = await realpath(result.stdout.trim());
-    return { available: true, root: gitRoot };
-  } catch {
-    return { available: false, root: null };
-  }
-}
-
-export async function gitCommand(root, args) {
-  try {
-    const result = await execFile("git", ["-C", root, ...args], { maxBuffer: 1024 * 1024 });
-    return { ok: true, stdout: result.stdout, stderr: result.stderr };
-  } catch (error) {
-    return { ok: false, code: error.code, stdout: error.stdout ?? "", stderr: error.stderr ?? "" };
-  }
-}
-
-export async function versionControlEvidence(root, path) {
-  const git = await gitInfo(root);
-  if (!git.available) return { available: false, ignored: null, tracked: null, gitRoot: null };
-  const rootReal = await realpath(root).catch(() => resolve(root));
-  const canonicalize = (candidate) => {
-    const fromRoot = relative(resolve(root), candidate);
-    return resolve(rootReal, fromRoot);
-  };
-  const relativePath = relative(git.root, canonicalize(path)).split(sep).join("/");
-  const ignored = await gitCommand(git.root, ["check-ignore", "--no-index", "-q", "--", relativePath]);
-  const parentPaths = [dirname(path), dirname(dirname(path))];
-  let ignoredParent = { ok: false };
-  if (!ignored.ok) {
-    for (const parentPath of parentPaths) {
-      const parentRelativePath = relative(git.root, canonicalize(parentPath)).split(sep).join("/");
-      ignoredParent = await gitCommand(git.root, ["check-ignore", "--no-index", "-q", "--", parentRelativePath]);
-      if (ignoredParent.ok) break;
-    }
-  }
-  const tracked = await gitCommand(git.root, ["ls-files", "--error-unmatch", "--", relativePath]);
-  return {
-    available: true,
-    ignored: ignored.ok || ignoredParent.ok,
-    tracked: tracked.ok,
-    gitRoot: git.root,
-    relativePath,
-  };
-}
-
-export function displayPath(root, path) {
-  const rel = relative(resolve(root), resolve(path));
-  return rel && !rel.startsWith(`..${sep}`) && rel !== ".." ? rel.split(sep).join("/") : path;
-}
-
-export function taskRoot(root) {
-  return resolve(root, ".freeflow", "tasks");
-}
-
-export function assertTaskRecordPath(root, recordPath) {
-  const tasks = taskRoot(root);
-  const resolved = resolve(recordPath);
-  if (!pathInside(tasks, resolved) || basename(resolved) !== "record.md")
-    fail("unsafe-path", `Record must be a record.md under ${displayPath(root, tasks)}`);
-  const taskDirectory = basename(dirname(resolved));
-  if (!/^task-\d{3}-[a-z0-9][a-z0-9-]*$/.test(taskDirectory))
-    fail("unsafe-path", `Invalid task directory: ${taskDirectory}`);
-  return resolved;
-}
-
-export function resolveRecordPath(root, options, positionals = []) {
-  const supplied = options["--record"] ?? options["--task"] ?? positionals[0];
-  if (!supplied) fail("invalid-arguments", "A record path or task directory is required");
-  const candidate = isAbsolute(supplied) ? supplied : resolve(root, supplied);
-  const path = basename(candidate) === "record.md" ? candidate : join(candidate, "record.md");
-  return assertTaskRecordPath(root, path);
-}
-
-export function nextTaskNumber(entries) {
-  const used = new Set();
-  for (const entry of entries) {
-    const match = /^task-(\d{3})-/.exec(entry.name);
-    if (entry.isDirectory() && match) used.add(Number(match[1]));
-  }
-  let number = 1;
-  while (used.has(number)) number += 1;
-  return number;
-}
-
-export function safeShortName(value) {
-  const shortName = ensureString(value).trim();
-  if (!/^[a-z0-9][a-z0-9-]*$/.test(shortName))
-    fail("invalid-short-name", "Short name must contain lowercase letters, digits, and hyphens only");
-  return shortName;
-}