@printpractical/cruze 0.0.13 → 0.0.15

package/skills/triage/SKILL.md

@@ -1,37 +0,0 @@
----
-name: cruze-triage
-description: Handles a bug report by reproducing it, finding its root cause against the living docs, and fixing a code defect with a failing test first, or sending a spec gap to architect and a design flaw to rethink.
----
-
-# Triage
-
-Triage starts from a symptom and ends with a fix, or with the right step to fix it. A bug has three possible causes, and each goes somewhere different. When the code doesn't do what the specs say, triage fixes it. When the specs never covered the case, it goes to `architect` as a tweak. When the design can't deliver the specs, it goes to `rethink`.
-
-## Steps
-
-1. **Capture the symptom.** Get the exact steps, what happened (output, error, exit code), what the user expected, and the environment. Done when you can write the steps as commands.
-2. **Reproduce it.** Run the steps against the real system. Done when you can make it fail on demand and have quoted the output. When you can't reproduce it, ask the user for what differs in their environment, and stop until you can.
-3. **Place it in the living docs.** Find the requirement and scenarios in `docs/specs/` that cover this behaviour, and the flow in `docs/architecture.md` that runs it, with `cruze show --index` and `cruze show <ID>`. Then classify it:
-   - **Code defect:** a scenario says what should happen, and the code does something else.
-   - **Spec gap:** no scenario covers this case.
-   - **Design flaw:** the design as written can't deliver what the scenario says.
-4. **Confirm the diagnosis.** Tell the user the classification, the scenario or its absence, and your evidence. They confirm it before anything changes. For a spec gap, stop and hand off to `architect "<tweak>"`. For a design flaw, stop and hand off to `rethink`.
-5. **Find the root cause.** Trace the failing path through the code until you can name the line that is wrong and why. The cause is the first wrong decision, not the place the error surfaces.
-6. **Write the failing test first.** On a branch such as `fix/<slug>`, add a test at the seam of the violated scenario, following `.agents/skills/cruze-behavioural-testing/SKILL.md`. It carries the scenario's ID and reproduces the bug. Run it, and see it fail for this bug's reason.
-7. **Fix it.** Make the smallest change in the module that owns the wrong decision, following `.agents/skills/cruze-hexagonal-design/SKILL.md`. Run `cruze check` on the files you changed, then the full test suite. Done when the new test passes and nothing else broke.
-8. **Commit** with a message such as `fix(<scope>): <what the user saw> (SCN-<id>)`.
-9. **Record it** with `cruze journal add bug --set summary="<what the user saw>" --set cause="<the root cause>" --set scenario=<SCN id> --set escaped="<the step that should have caught it>"`. `escaped` names the Cruze step that let the bug through, such as `verify`, or `none` when no step could have.
-
-## Rules
-
-- A missing test is part of the cause. When the violated scenario had a test that passed anyway, say why it missed the bug, and strengthen it in the same fix.
-- Fix the cause only. Clean-ups you notice nearby go to the user as suggestions.
-- Never change a scenario to match the code. That is a spec change, and it goes through `architect`.
-
-## Next step
-
-- Code defect fixed: `land`, which lands bug fixes too.
-- Spec gap: `architect "<tweak>"`.
-- Design flaw: `rethink`.
-
-Start it in a new session, so its context starts empty.

package/skills/verify/SKILL.md

@@ -1,45 +0,0 @@
----
-name: cruze-verify
-description: Verifies a built change before it lands, with the mechanical checks, a fresh-context verifier that runs the real system, a two-lane code review and a manual test script, ending with your decision to accept it or send it back.
----
-
-# Verify
-
-Verify answers one question: does this change work when someone uses it? Green tests are evidence, not proof. A verifier in a fresh context runs the real system through each scenario, reviewers check the code against the spec and the architecture, and the user gets a script to try it themselves. The user decides whether it lands.
-
-## Steps
-
-1. **Check it is ready.** Run `cruze next`. It must name `verify` for this change, on this branch. Find the base commit the change branched from with `git merge-base main HEAD`. The code review's base is the same, unless `cruze journal list --event verification --item <ref>` shows an earlier verify: then it is that entry's commit, or `git rev-list -1 --before=<its at> HEAD` for one without, since the code before it was reviewed.
-2. **Run the mechanical checks.** Run `cruze validate`, `cruze check --ci` and `cruze trace --change <ref>`, and quote each result.
-   - Run `cruze journal list --event checks --item <ref>`. When its last entry's commit has no code changes since, that is when `git diff --quiet <commit> HEAD -- . ':(exclude)docs' ':(exclude).cruze'` succeeds, quote that entry for the format, lint, build and test commands instead of running them again.
-   - Otherwise run the format, lint and build commands and the full suite, as `.agents/skills/cruze-formats/reference/config.md` defines it under `commands`. When they pass, record them with `cruze journal add checks --set commit=<commit> --item <ref>`, where the commit is the output of `git rev-parse --short HEAD`.
-   - When one fails, fix the code in a commit and run them again. When a fix needs design, stop and offer `rethink`.
-3. **Check the dependencies.** Follow "Checking" in `.agents/skills/cruze-dependency-approval/SKILL.md` against the merge base. An unrecorded dependency is a blocker.
-4. **Run the verifier.** Run the verifier role from `.agents/skills/cruze-roles/SKILL.md` for the change, with the mechanical checks' results and the commit they ran at. It must be able to build and run the system. When it runs through `cruze review`, check that `review.command` in `.cruze/config.yaml` allows the project's build and run commands, and add them with the user's agreement. Done when you have its report, with a result for every delivered scenario.
-5. **Review the code.** Run the review in the roles skill with the code reviewer, `review=code`, `--item <ref>` and the code review's base. Fix each finding whose disposition is `fixed` in a commit, through a detail amendment when it needs one, running the tests each fix touches, and `test` when `commands:` has a `test_full`. Then check the fixes yourself, as round 2 in the roles skill says.
-6. **Write the manual test script** as `manual-test.md` in the change folder, following [manual-test.md](manual-test.md). Commit it.
-7. **Check the fixes once.** When code changed since the last `checks` entry, run the format, lint and build commands and the full suite once more, and record them as in step 2. Done when the last `checks` entry is at a commit with no code changes since.
-8. **Report.** Show the user four things:
-   - The mechanical checks, one line each.
-   - The verifier's result for every scenario.
-   - The review's outcome, with each finding's disposition.
-   - The path to `manual-test.md`, with a recommendation to run it before accepting.
-9. **Ask for the decision:** "Do you accept this change, or send it back?"
-10. **Record it** with `cruze journal add verification --set result=<accepted|sent-back> --set summary="<one line>" --set commit=<commit> --item <ref>`, where the commit is the output of `git rev-parse --short HEAD`, adding `--set back_to=<build|rethink>` when it is sent back. On sent-back, say what goes back:
-   - A defect in code a task already built: `back_to=build`, then `cruze task reopen T<n> "<reason>"`.
-   - A design that can't deliver the scenario: `back_to=rethink`. Leave the tasks to the rethink, which reopens the ones its amendment changes, and `cruze next` names `rethink` until it is recorded.
-
-Done when the decision is recorded.
-
-## Rules
-
-- A scenario the verifier couldn't run isn't passed. Mark it clearly in the report and in `manual-test.md`.
-- Findings from the review are dispositions in the journal. They edit `change.md` only through a detail amendment.
-- Fixes made during verify are code commits that stay within the tasks' files. When a fix needs a new file or owner, or a detail, handle it exactly as build does.
-
-## Next step
-
-- Accepted: `land`.
-- Sent back: `build` for reopened tasks, or `rethink` for design.
-
-Start it in a new session, so its context starts empty.

package/skills/verify/manual-test.md

@@ -1,23 +0,0 @@
-# The manual test script
-
-`manual-test.md` in the change folder is what a person runs to see the change work with their own eyes. Write it for someone who knows the product but not the code.
-
-```markdown
-# Manual test: <change title>
-
-Setup, once:
-1. <build or install command, from the project's commands>
-2. <any configuration file to create, with its full content>
-
-## SCN-<id>: <scenario title>
-1. <exact command or action>
-2. <next action>
-Expected: <what they see, quoted from the scenario's THEN>
-Verifier: pass | fail | could not run (<what it needs>)
-```
-
-- One section per scenario the change delivers, in the order of the spec delta.
-- Every step is a command they can paste or an action they can take, with real values.
-- Expected results are quoted from the scenario.
-- Scenarios the verifier couldn't run come first, since they carry the most risk. Say what each needs, such as a serial device or a jump host.
-- Finish with how to clean up anything the setup created.

package/src/adapters/inbound/cli/argument_files.ts

@@ -1,29 +0,0 @@
-import { mkdir, readFile, writeFile } from "node:fs/promises";
-import { dirname, resolve } from "node:path";
-import { UsageError } from "./cli_context.ts";
-
-// Files a person or agent names on the command line, such as a scratch file of review blockers or
-// the path for an exported bundle. They may be anywhere, unlike project files, and relative paths
-// resolve against the working directory.
-
-export async function readArgumentFile(path: string): Promise<string> {
-  try {
-    return await readFile(resolve(path), "utf8");
-  } catch (error) {
-    throw new UsageError(`cannot read ${path}: ${reason(error)}`);
-  }
-}
-
-export async function writeArgumentFile(path: string, text: string): Promise<void> {
-  try {
-    await mkdir(dirname(resolve(path)), { recursive: true });
-    await writeFile(resolve(path), text, "utf8");
-  } catch (error) {
-    throw new UsageError(`cannot write ${path}: ${reason(error)}`);
-  }
-}
-
-function reason(error: unknown): string {
-  if (error instanceof Error && "code" in error && typeof error.code === "string") return error.code;
-  return error instanceof Error ? error.message : String(error);
-}

package/src/adapters/inbound/cli/commands/diff.ts

@@ -1,23 +0,0 @@
-import { upstreamDiff, type UpstreamDiffReport } from "../../../../app/use_cases/upstream_diff.ts";
-import { requireArgs, type CliContext, type CommandResult } from "../cli_context.ts";
-
-export async function runDiff(context: CliContext, args: string[]): Promise<CommandResult> {
-  requireArgs(args, ["ref"]);
-  const report = await upstreamDiff(context, args[0] ?? "");
-  return { json: report, human: render(report) };
-}
-
-function render(report: UpstreamDiffReport): string {
-  const lines = [`${report.artifact}: ${report.state}`];
-  if (report.changes.length === 0) lines.push("Nothing it cites changed since its approval.");
-  for (const change of report.changes) {
-    lines.push("", `${change.key}${change.path === undefined ? "" : ` in ${change.path}`}:`);
-    lines.push(...(change.diff ?? [change.note ?? ""]).map((line) => `  ${line}`));
-  }
-  if (report.rebase.length > 0) {
-    lines.push("", `Its delta changes ${report.rebase.join(", ")}: rewrite the delta to keep the new text, then approve with ${report.rebase.map((id) => `--rebase ${id}`).join(" ")}.`);
-  } else if (report.ref !== undefined && report.state === "upstream-changed") {
-    lines.push("", `No rebase needed. When the work still holds against this, re-stamp it with cruze approve ${report.ref} --restamp-unchanged.`);
-  }
-  return lines.join("\n");
-}

package/src/adapters/inbound/cli/commands/journal.ts

@@ -1,32 +0,0 @@
-import { exportFeedback, listEvents, recordEvent } from "../../../../app/use_cases/journal_events.ts";
-import { writeArgumentFile } from "../argument_files.ts";
-import { UsageError, requireArgs, type CliContext, type CommandResult, type Options } from "../cli_context.ts";
-
-export async function runJournal(context: CliContext, args: string[], options: Options): Promise<CommandResult> {
-  requireArgs(args, ["add|list"]);
-  if (args[0] === "add") {
-    requireArgs(args, ["add", "event"]);
-    const fields = Object.fromEntries(options.set.map((pair) => {
-      const at = pair.indexOf("=");
-      if (at < 1) throw new UsageError(`--set takes key=value, not "${pair}"`);
-      return [pair.slice(0, at), pair.slice(at + 1)];
-    }));
-    const entry = await recordEvent(context, args[1] ?? "", fields, options.item);
-    return { json: entry, human: `Recorded ${entry.event}.` };
-  }
-  if (args[0] === "list") {
-    const entries = await listEvents(context, options.event, options.item, options.all);
-    return { json: entries, human: entries.map((e) => `${e.at} ${e.event} ${JSON.stringify({ ...e, at: undefined, event: undefined, by: undefined })}`).join("\n") || "No entries." };
-  }
-  throw new UsageError(`cruze journal takes add or list, not "${args[0]}"`);
-}
-
-export async function runFeedback(context: CliContext, args: string[], options: Options): Promise<CommandResult> {
-  if (args[0] !== "export") throw new UsageError("usage: cruze feedback export [--out <file>] [--no-redact]");
-  const bundle = await exportFeedback(context, options.redact);
-  if (options.out !== undefined) {
-    await writeArgumentFile(options.out, `${JSON.stringify(bundle, null, 2)}\n`);
-    return { json: { out: options.out, entries: bundle.entries.length }, human: `Wrote ${bundle.entries.length} entries to ${options.out}.` };
-  }
-  return { json: bundle, human: `${bundle.entries.length} journal entries${bundle.redacted ? ", redacted" : ""}.` };
-}

package/src/adapters/inbound/cli/commands/progress.ts

@@ -1,55 +0,0 @@
-import { addFutureFeature, completeTask, dropFutureFeature, updateFeatureSummary, pruneRoadmap, recordDeviation, reopenTask } from "../../../../app/use_cases/record_progress.ts";
-import { abandonWork } from "../../../../app/use_cases/abandon_work.ts";
-import { UsageError, requireArgs, requireOption, type CliContext, type CommandResult, type Options } from "../cli_context.ts";
-
-export async function runTask(context: CliContext, args: string[], options: Options): Promise<CommandResult> {
-  requireArgs(args, ["done|deviation|reopen", "task"]);
-  const change = options.change === undefined ? {} : { change: options.change };
-  if (args[0] === "done") {
-    const report = await completeTask(context, args[1] ?? "", { ...change, ...(options.commit === undefined ? {} : { commit: options.commit }) });
-    return { json: report, human: `${report.task} done in ${report.change} (${report.done}/${report.total}).` };
-  }
-  if (args[0] === "deviation") {
-    requireArgs(args, ["deviation", "task", "text"]);
-    const report = await recordDeviation(context, args[1] ?? "", args.slice(2).join(" "), change);
-    return { json: report, human: `Recorded a deviation on ${report.task} in ${report.change}.` };
-  }
-  if (args[0] === "reopen") {
-    requireArgs(args, ["reopen", "task", "reason"]);
-    const report = await reopenTask(context, args[1] ?? "", args.slice(2).join(" "), change);
-    return { json: report, human: `Reopened ${report.task} in ${report.change}.` };
-  }
-  throw new UsageError(`cruze task takes done, deviation or reopen, not "${args[0]}"`);
-}
-
-export async function runFeatures(context: CliContext, args: string[], options: Options): Promise<CommandResult> {
-  requireArgs(args, ["add|update|drop", "slug"]);
-  if (args[0] === "add") {
-    const goals = (options.goals ?? "").split(",").map((g) => g.trim()).filter((g) => g !== "");
-    const report = await addFutureFeature(context, args[1] ?? "", requireOption(options.summary, "--summary"), goals);
-    return { json: report, human: `Added ${report.feature} to the future list.` };
-  }
-  if (args[0] === "update") {
-    const report = await updateFeatureSummary(context, args[1] ?? "", requireOption(options.summary, "--summary"));
-    return { json: report, human: `Updated the summary of ${report.feature} on the ${report.list === "Future" ? "future" : "implemented"} list.` };
-  }
-  if (args[0] === "drop") {
-    const report = await dropFutureFeature(context, args[1] ?? "", requireOption(options.reason, "--reason"));
-    return { json: report, human: `Dropped ${report.feature} from the future list.` };
-  }
-  throw new UsageError(`cruze features takes add, update or drop, not "${args[0]}"`);
-}
-
-export async function runRoadmap(context: CliContext, args: string[]): Promise<CommandResult> {
-  requireArgs(args, ["prune"]);
-  if (args[0] !== "prune") throw new UsageError(`cruze roadmap takes prune, not "${args[0]}"`);
-  const report = await pruneRoadmap(context);
-  return { json: report, human: report.removed.length === 0 ? "No landed items to clear." : `Cleared ${report.removed.join(", ")} from the roadmap status.` };
-}
-
-export async function runAbandon(context: CliContext, args: string[], options: Options): Promise<CommandResult> {
-  requireArgs(args, ["ref"]);
-  const report = await abandonWork(context, args[0] ?? "", requireOption(options.reason, "--reason"));
-  const back = report.futureList === undefined ? "" : ` ${report.futureList} is back on the future list.`;
-  return { json: report, human: `Abandoned ${report.ref}; archived to ${report.archivedTo}.${back}` };
-}

package/src/adapters/inbound/cli/commands/realign.ts

@@ -1,28 +0,0 @@
-import { realignDone } from "../../../../app/use_cases/realign_done.ts";
-import { realignStatus } from "../../../../app/use_cases/realign_status.ts";
-import { UsageError, requireArgs, type CliContext, type CommandResult, type Options } from "../cli_context.ts";
-
-export async function runRealign(context: CliContext, args: string[], options: Options): Promise<CommandResult> {
-  requireArgs(args, ["status|done"]);
-  if (args[0] === "status") {
-    const report = await realignStatus(context, { full: options.full });
-    const lines = [`Code meets Cruze ${report.standards}; the installed skills are ${report.target}${report.full ? " (full audit)" : ""}.`];
-    for (const note of report.notes) {
-      const open = note.findings.filter((f) => !f.waived);
-      const how = note.detect !== undefined ? `${open.length} open finding(s) from ${note.detect}` : `for the auditor: ${note.ask ?? ""}`;
-      lines.push(`${note.version} ${note.id}: ${note.title} (${how})`);
-      for (const f of open) lines.push(`  ${f.path}${f.line === undefined ? "" : `:${f.line}`} ${f.message}`);
-    }
-    if (report.newWorkOnly.length > 0) lines.push(`New work only, nothing to move: ${report.newWorkOnly.join(", ")}`);
-    if (report.notes.length === 0) lines.push("Nothing to realign.");
-    return { json: report, human: lines.join("\n") };
-  }
-  if (args[0] === "done") {
-    const report = await realignDone(context, options.change === undefined ? {} : { change: options.change });
-    const lines = [report.from === report.to ? `The code already meets Cruze ${report.to}.` : `The code now meets Cruze ${report.to}, up from ${report.from}.`];
-    if (report.scheduled !== undefined) lines.push(`${report.scheduled} fixes the rest.`);
-    if (report.excepted.length > 0) lines.push(`Listed under check.exceptions until it lands: ${report.excepted.join(", ")}`);
-    return { json: report, human: lines.join("\n") };
-  }
-  throw new UsageError(`cruze realign takes status or done, not "${args[0]}"`);
-}

package/src/adapters/inbound/cli/commands/show.ts

@@ -1,96 +0,0 @@
-import { showElements, showIndex } from "../../../../app/use_cases/show_elements.ts";
-import { showNotes } from "../../../../app/use_cases/show_notes.ts";
-import type { Note, NotesFor } from "../../../../domain/project/notes.ts";
-import { showScope, type ScopeReport } from "../../../../app/use_cases/show_scope.ts";
-import { isId } from "../../../../domain/ids.ts";
-import type { ElementIndex } from "../../../../domain/project/element_lookup.ts";
-import type { ShownElement } from "../../../../domain/project/scope_view.ts";
-import { UsageError, requireArgs, type CliContext, type CommandResult, type Options } from "../cli_context.ts";
-
-export async function runShow(context: CliContext, args: string[], options: Options): Promise<CommandResult> {
-  if (options.notes) {
-    if (args.length > 1 || options.index) throw new UsageError("--notes takes at most one target: project, a step, a feature slug or a context");
-    const report = await showNotes(context, args[0]);
-    return { json: report, human: "target" in report ? renderNotesFor(report).join("\n").trimEnd() : renderNotes(report.notes) };
-  }
-  if (options.index) {
-    if (args.length > 1) throw new UsageError("--index takes at most one context or capability");
-    const index = await showIndex(context, args[0]);
-    return { json: index, human: renderIndex(index) };
-  }
-  requireArgs(args, ["ref"]);
-  if (args.every(isId)) {
-    const report = await showElements(context, args);
-    return { json: report, human: blocks(report.elements).join("\n").trimEnd() };
-  }
-  if (args.length > 1) throw new UsageError("show takes one feature or change, or one or more element IDs");
-  const report = await showScope(context, args[0] ?? "");
-  return { json: report, human: render(report) };
-}
-
-/** The index as a list an agent scans for what exists, before fetching bodies with `cruze show <ID>`. */
-function renderIndex(index: ElementIndex): string {
-  const { architecture, specs } = index.words;
-  const lines = [`# Elements`, "", `docs/architecture.md holds ${architecture} words, and docs/specs/ ${specs}. Read an element's body with \`cruze show <ID>\`.`];
-  let source = "";
-  for (const entry of [...index.entries].sort((a, b) => Number(a.addedBy !== undefined) - Number(b.addedBy !== undefined))) {
-    const heading = entry.addedBy === undefined ? entry.source : "In flight, not yet merged";
-    if (heading !== source) lines.push("", `## ${heading}`, "");
-    source = heading;
-    const facts = [
-      entry.status,
-      entry.place,
-      entry.scenarios === undefined ? undefined : `${entry.scenarios} scenarios`,
-      entry.addedBy === undefined ? undefined : `added by ${entry.addedBy}`,
-      entry.changedBy.length === 0 ? undefined : `changed by ${entry.changedBy.join(", ")}`,
-    ].filter((f) => f !== undefined);
-    lines.push(`- ${entry.id}: ${entry.title}${facts.length === 0 ? "" : ` (${facts.join("; ")})`}`);
-  }
-  return lines.join("\n");
-}
-
-/** The scope as a document an agent reads in place of the living docs. */
-function render(report: ScopeReport): string {
-  const lines = [`# ${report.ref}${report.feature === undefined ? "" : ` (feature ${report.feature})`}`, ""];
-  lines.push("## Elements", "", ...blocks(report.elements), "## Scenarios", "", ...blocks(report.scenarios));
-  lines.push("## Cited, not shown", "");
-  lines.push(...(report.cited.length === 0 ? ["None."] : report.cited.map((c) => `- ${c.id}: ${c.title} (${c.source})`)), "");
-  if (report.feature === undefined) lines.push("## Settled decisions", "", ...(report.decisions.length === 0 ? ["None."] : report.decisions), "");
-  else {
-    lines.push("## Settled decisions of the feature", "", ...(report.decisions.length === 0 ? ["None."] : report.decisions), "");
-    lines.push("## Settled decisions of the change", "", ...(report.changeDecisions.length === 0 ? ["None."] : report.changeDecisions), "");
-  }
-  lines.push("## Dispositions", "");
-  lines.push(...(report.dispositions.length === 0 ? ["None."] : report.dispositions.map((d) => `- [${d.disposition}, ${d.review}] ${d.finding}: ${d.reason}`)), "");
-  if (report.references.length > 0) lines.push("## References", "", ...report.references.map((r) => `- \`${r.path}\`: ${r.use}`), "");
-  lines.push(...renderNotesFor(report.notes));
-  if (report.missing.length > 0) lines.push("## Missing", "", ...report.missing.map((id) => `- ${id} is defined nowhere`), "");
-  return lines.join("\n").trimEnd();
-}
-
-function blocks(elements: ShownElement[]): string[] {
-  if (elements.length === 0) return ["None.", ""];
-  return elements.flatMap((element) => [`<!-- ${element.source} -->`, ...element.body.join("\n").trimEnd().split("\n"), ""]);
-}
-
-/** The notes about a piece of work and the parts of the user's input handed to it; nothing when there are none. */
-function renderNotesFor(found: NotesFor): string[] {
-  if (found.notes.length === 0 && found.handoffs.length === 0) return [];
-  return [
-    "## Notes",
-    "",
-    ...found.notes.map((n) => `- \`${n.path}\`: ${n.title}${n.kind === undefined ? "" : ` (${n.kind})`}`),
-    ...found.handoffs.map((h) => `- ${h.part}, from ${h.source} (${h.status}, handed off in \`${h.note}\`)`),
-    "",
-  ];
-}
-
-function renderNotes(notes: Note[]): string {
-  if (notes.length === 0) return "No notes.";
-  return notes
-    .flatMap((n) => [
-      `- \`${n.path}\`: ${n.title} (${n.kind ?? "no kind"}; about ${n.about.length === 0 ? "nothing named" : n.about.join(", ")})`,
-      ...n.handoff.map((h) => `  - ${h.part} goes to ${h.goesTo} (${h.status})`),
-    ])
-    .join("\n");
-}

package/src/app/use_cases/abandon_work.ts

@@ -1,42 +0,0 @@
-import { CruzeError } from "../../domain/cruze_error.ts";
-import { readRows, upsertRow } from "../../domain/edits/managed_tables.ts";
-import { resolveArtifact } from "../../domain/project/artifact_ref.ts";
-import { PATHS } from "../../domain/project/layout.ts";
-import { appendJournal, loadView, type ProjectDeps } from "../project_context.ts";
-
-export interface AbandonReport {
-  ref: string;
-  archivedTo: string;
-  /** The feature-map slug it went back to, for a feature that may return. */
-  futureList?: string;
-}
-
-/**
- * Stops a feature or standalone change for good: archives its folder with the reason, marks it
- * abandoned on the roadmap, and puts a feature back on the future list. Changes that already
- * landed stay in the living docs.
- */
-export async function abandonWork(deps: ProjectDeps, ref: string, reason: string): Promise<AbandonReport> {
-  if (reason.trim() === "") throw new CruzeError("missing-reason", "abandoning work needs a reason");
-  const view = await loadView(deps.files);
-  const { item } = resolveArtifact(view, ref);
-  if (item === undefined || item.archived) throw new CruzeError("not-found", `"${ref}" is not an active feature or standalone change`);
-  if (item.kind === "change") throw new CruzeError("not-abandonable", `${item.ref} belongs to a feature; remove it from the feature's Changes table through rethink instead`);
-
-  const slug = typeof item.doc.frontmatter?.["roadmap"] === "string" ? item.doc.frontmatter["roadmap"] : undefined;
-  const roadmap = view.snapshot.get(PATHS.roadmap);
-  if (slug !== undefined && roadmap !== undefined && roadmap.includes("## Status")) {
-    await deps.files.writeText(PATHS.roadmap, upsertRow(roadmap, "Status", [slug, item.folderName, "abandoned"]));
-  }
-  const report: AbandonReport = { ref: item.ref, archivedTo: `${PATHS.archiveDir}/${item.folderName}` };
-  const vision = view.snapshot.get(PATHS.vision);
-  if (item.kind === "feature" && slug !== undefined && vision !== undefined && vision.includes("### Future")) {
-    if (!readRows(vision, "Future").some((row) => row[0] === slug)) {
-      await deps.files.writeText(PATHS.vision, upsertRow(vision, "Future", [slug, String(item.doc.frontmatter?.["title"] ?? slug), ""]));
-    }
-    report.futureList = slug;
-  }
-  await appendJournal(deps, item.folder, "abandon", { item: item.ref, reason: reason.trim() });
-  await deps.files.move(item.folder, report.archivedTo);
-  return report;
-}

package/src/app/use_cases/approve_artifact.ts

@@ -1,197 +0,0 @@
-import { requirePlanReviewClosed, requireUnchangedSinceApproval, type AgentBasis } from "../../domain/approvals/agent_approval.ts";
-import { evaluateApproval } from "../../domain/approvals/evaluate.ts";
-import { fingerprint, isApprovable } from "../../domain/approvals/fingerprint.ts";
-import { rebaseNeeded } from "../../domain/approvals/rebase.ts";
-import { serializeApprovals, withApproval } from "../../domain/approvals/records.ts";
-import { CruzeError } from "../../domain/cruze_error.ts";
-import { updateProgress } from "../../domain/edits/progress_block.ts";
-import { setStatus, stampMissingStatuses } from "../../domain/edits/status_lines.ts";
-import { statusOf } from "../../domain/elements.ts";
-import { elementHash } from "../../domain/hashing.ts";
-import { parseMarkdown } from "../../domain/markdown.ts";
-import { resolveArtifact } from "../../domain/project/artifact_ref.ts";
-import { readDelta } from "../../domain/project/deltas.ts";
-import { PATHS } from "../../domain/project/layout.ts";
-import { isPlanned, readChangesTable } from "../../domain/project/plan_parts.ts";
-import { readProgress } from "../../domain/project/progress.ts";
-import { approvalFolder, approvalsPath, type ProjectView } from "../../domain/project/project_view.ts";
-import { featureOf, type WorkItem } from "../../domain/project/work_items.ts";
-import type { Problem } from "../../domain/validation/problem.ts";
-import { SIZE_RULES } from "../../domain/validation/size_rules.ts";
-import { validateProject } from "../../domain/validation/validate_project.ts";
-import { appendJournal, loadView, withFiles, type ProjectDeps } from "../project_context.ts";
-
-export interface ApproveReport {
-  artifact: string;
-  hash: string;
-  upstream: string[];
-  /** Elements that received a `planned` status. */
-  stamped: string[];
-  /** The branch a change was bound to, when this approval bound it. */
-  bound?: string;
-  /** Built elements this approval set back to planned, because a rethink changed them. */
-  replanned: string[];
-  /** Elements whose current living text this feature accepted after a land conflict. */
-  rebased: string[];
-  /** Why the agent gave this approval for the user, when it did. */
-  basis?: AgentBasis;
-  /** For a re-stamp: the upstream IDs or documents that had changed. */
-  restamped?: string[];
-}
-
-export interface ApproveOptions {
-  /** Architecture elements to set back to `planned`: their design changed and their code must follow. */
-  replan?: string[];
-  /** Elements this work's delta changes whose living text changed since its last approval; the approval accepts the current text. */
-  rebase?: string[];
-  /** Approve for the user: a change whose plan review closed, or work a rethink left unchanged. */
-  agent?: AgentBasis;
-}
-
-/**
- * Records a person's approval of a document: its design hash and the hashes of everything
- * upstream it relies on. Refuses invalid documents and documents whose upstream isn't approved.
- */
-export async function approveArtifact(deps: ProjectDeps, ref: string, options: ApproveOptions = {}): Promise<ApproveReport> {
-  let view = await loadView(deps.files);
-  const { path, item } = resolveArtifact(view, ref);
-  if (!isApprovable(view, path)) throw new CruzeError("not-approvable", `${path} is not something you approve; it changes through approved work`);
-  requireUpstreamApproved(view, path);
-  if (item?.kind === "feature" && readChangesTable(item.doc).length === 0) {
-    throw new CruzeError("not-designed", `${path} has no changes yet; architect designs and splits it before approval`);
-  }
-  if (item !== undefined && item.kind !== "feature" && !isPlanned(item.doc)) {
-    throw new CruzeError("not-planned", `${path} has no test plan or tasks yet; plan it before approving`);
-  }
-  const before = evaluateApproval(view, path);
-  if (options.agent === "plan-review") requirePlanReviewClosed(view.journal, item ?? notWork(path));
-  if (options.agent === "rethink") requireUnchangedSinceApproval(view.journal, item, path, before);
-
-  const edits = new Map<string, string>();
-  let text = view.snapshot.get(path) ?? "";
-  let stamped: string[] = [];
-  if (path === PATHS.architecture) ({ text, stamped } = stampMissingStatuses(text));
-  const replanned = options.replan ?? [];
-  if (replanned.length > 0 && path !== PATHS.architecture) throw new CruzeError("replan-architecture-only", "--replan applies to the architecture");
-  for (const id of replanned) {
-    const element = view.living.elements.get(id);
-    if (element?.path !== PATHS.architecture || statusOf(element.doc, element.element) !== "built") {
-      throw new CruzeError("not-built", `${id} is not a built element of ${PATHS.architecture}`);
-    }
-    text = setStatus(text, id, "planned");
-  }
-  let bound: string | undefined;
-  if (item !== undefined && item.kind !== "feature" && readProgress(parseMarkdown(text)).branch === undefined) {
-    bound = (await deps.repository.currentBranch()) ?? undefined;
-    text = updateProgress(text, (progress) => {
-      if (bound !== undefined) progress.branch = bound;
-    });
-  }
-  if (text !== view.snapshot.get(path)) edits.set(path, text);
-  view = withFiles(view, edits);
-
-  const problems = validateProject(view).filter((p) => p.path === path);
-  const errors = problems.filter((p) => p.severity === "error");
-  if (errors.length > 0) {
-    const listing = errors.map((p) => `  ${p.path}:${p.line ?? ""} ${p.message}`).join("\n");
-    throw new CruzeError("invalid", `${path} has ${errors.length} problem(s) to fix before approval:\n${listing}`);
-  }
-  requireSizesAccepted(problems, path);
-  if (item !== undefined) requireNoDecisionCitations(problems, path);
-
-  const { hash, upstream } = fingerprint(view, path, parseMarkdown(text));
-  const folder = approvalFolder(view, path);
-  const current = view.approvals.get(folder) ?? { version: 1, approvals: [], merged: {} };
-  const rebased = options.rebase ?? [];
-  const deltaIds = item === undefined || item.kind === "change" ? new Set<string>() : readDelta(item.doc).ids;
-  if (item !== undefined) requireRebased(view, item, rebased);
-  const merged = { ...current.merged };
-  for (const id of rebased) {
-    const living = view.living.elements.get(id);
-    if (living === undefined || (merged[id] === undefined && !deltaIds.has(id))) {
-      throw new CruzeError("not-in-delta", `${id} is not a living element that ${item?.ref ?? path} changes or merged`);
-    }
-    if (merged[id] !== undefined) merged[id] = elementHash(living.doc, living.element);
-  }
-  const approvals = withApproval({ ...current, merged }, {
-    artifact: path,
-    hash,
-    upstream,
-    approvedAt: deps.clock.now().toISOString(),
-    by: (await deps.repository.userName()) ?? "unknown",
-    ...(options.agent === undefined ? {} : { basis: options.agent }),
-  });
-  for (const [changed, content] of edits) await deps.files.writeText(changed, content);
-  await deps.files.writeText(approvalsPath(folder), serializeApprovals(approvals));
-  const restamped = options.agent === "rethink" ? before.changed : undefined;
-  await appendJournal(deps, folder, "approve", {
-    artifact: path,
-    hash,
-    ...(replanned.length > 0 ? { replanned } : {}),
-    ...(rebased.length > 0 ? { rebased } : {}),
-    ...(options.agent === undefined ? {} : { basis: options.agent }),
-    ...(restamped === undefined ? {} : { restamped }),
-  });
-  const report: ApproveReport = { artifact: path, hash, upstream: Object.keys(upstream), stamped, replanned, rebased };
-  if (bound !== undefined) report.bound = bound;
-  if (options.agent !== undefined) report.basis = options.agent;
-  if (restamped !== undefined) report.restamped = restamped;
-  return report;
-}
-
-/**
- * A feature or standalone change whose delta changes an element must have been written against
- * that element's current text. When the living element changed since the last approval, through
- * a rethink or another land, the delta would overwrite that edit, so approval waits until the
- * delta is reconciled and the element is named with --rebase.
- */
-function requireRebased(view: ProjectView, item: WorkItem, rebased: string[]): void {
-  const moved = rebaseNeeded(view, item).filter((id) => !rebased.includes(id));
-  if (moved.length > 0) {
-    throw new CruzeError(
-      "rebase-required",
-      `the living text of ${moved.join(", ")} changed since the last approval, and this work's delta changes ${moved.length === 1 ? "it" : "them"}. Rewrite the delta to keep that change, then approve with ${moved.map((id) => `--rebase ${id}`).join(" ")}`,
-    );
-  }
-}
-
-/**
- * A size warning stands until the work is split or the user accepts it under `changes.exceptions`.
- * A 28-task change approved over its warning went on to 26 deviations, so approval waits for one or the other.
- */
-function requireSizesAccepted(problems: Problem[], path: string): void {
-  const standing = problems.filter((p) => SIZE_RULES.includes(p.rule));
-  if (standing.length === 0) return;
-  const listing = standing.map((p) => `  ${p.message} [${p.rule}]`).join("\n");
-  throw new CruzeError(
-    "size-unaccepted",
-    `${path} has ${standing.length} size warning(s). Split the work through rethink, or record the user's acceptance under changes.exceptions in .cruze/config.yaml, as the item's ref and their reason:\n${listing}`,
-  );
-}
-
-/**
- * A delta that cites decisions by number would merge them into the living docs, where they dangle once
- * the work is archived. Existing docs only warn, so approval of new or redesigned work is where it stops.
- */
-function requireNoDecisionCitations(problems: Problem[], path: string): void {
-  const standing = problems.filter((p) => p.rule === "decision-citation");
-  if (standing.length === 0) return;
-  const listing = standing.map((p) => `  ${p.path}:${p.line ?? ""} ${p.message}`).join("\n");
-  throw new CruzeError("decision-cited", `${path} cites decisions by number in its delta, which merges into the living docs:\n${listing}`);
-}
-
-function notWork(path: string): never {
-  throw new CruzeError("needs-user", `${path} is a project document, so the user approves it`);
-}
-
-/** A change needs its feature approved; a feature or standalone change needs the architecture approved. */
-function requireUpstreamApproved(view: ProjectView, path: string): void {
-  const item = view.items.find((i) => i.path === path);
-  if (item === undefined) return;
-  const upstream = item.kind === "change" ? featureOf(view.items, item)?.path : view.snapshot.has(PATHS.architecture) ? PATHS.architecture : undefined;
-  if (upstream === undefined) return;
-  const status = evaluateApproval(view, upstream);
-  if (status.state !== "approved") {
-    throw new CruzeError("upstream-not-approved", `approve ${upstream} first; it is ${status.state}${status.changed.length > 0 ? ` (${status.changed.join(", ")})` : ""}`);
-  }
-}