@intentius/chant 0.102.0 → 0.104.0

package/src/workspace/factory-rules.test.ts

@@ -0,0 +1,62 @@
+/**
+ * The factory's rules (#3406, ws-087): readiness, understand, retry, done
+ * and the implements proposals, as pure functions. The Op that runs them is
+ * tested in ../op/factory.e2e.test.ts.
+ */
+
+import { describe, expect, test } from "vitest";
+import { isAsk, pickable, retryState, doneVerdict, proposeImplements, understandOutcome, type FactoryContext, type FactoryItem } from "./factory-rules";
+
+describe("the factory's rules", () => {
+  const base: FactoryItem = { id: "W-1", state: "open", openState: "open", proposedState: "proposed", ready: true, data: {}, tier: null, contract: null, warnings: [], answers: [], leased: false };
+  const ctx: FactoryContext = { intentDecided: null, claims: [], attempts: { exhausted: false }, branch: null, questions: { tier: null, understand: null } };
+  const hold = (i: Partial<FactoryItem>, c: Partial<FactoryContext> = {}) => {
+    const v = pickable({ ...base, ...i }, { ...ctx, ...c });
+    return v.ok ? "ok" : v.hold;
+  };
+
+  test("readiness", () => {
+    expect(hold({})).toBe("ok");
+    expect(hold({}, { intentDecided: false })).toBe("intent-undecided");
+    expect(hold({ ready: false })).toBe("not-ready");
+    expect(hold({ ready: false, state: "proposed", data: { source: { ask: { said: "x", by: "a" } } } })).toBe("ok");
+    expect(hold({ contract: { id: "C-1", state: "draft" }, warnings: ["work-contract-undecided"] })).toBe("contract-not-approved");
+    expect(hold({}, { branch: { state: "done", applied: false } })).toBe("built-not-applied");
+    expect(hold({}, { branch: { state: "done", applied: true } })).toBe("ok");
+    expect(hold({}, { branch: { state: "dropped", applied: false } })).toBe("dropped-on-branch");
+    expect(hold({}, { attempts: { exhausted: true } })).toBe("attempts-exhausted");
+    const failed = { claims: [{ token: "t1", ended: "released", outcome: "not_done", attempt: true }] };
+    expect(hold({}, failed)).toBe("awaiting-retry");
+    expect(hold({ data: { retry: { after: "t1", by: "alice" } } }, failed)).toBe("ok");
+    expect(hold({ data: { retry: { after: "t0", by: "alice" } } }, failed)).toBe("awaiting-retry");
+    expect(hold({}, { questions: { tier: { state: "escalated", answer: null }, understand: null } })).toBe("question-open");
+    expect(hold({ tier: "large" }, { questions: { tier: { state: "escalated", answer: null }, understand: null } })).toBe("ok");
+    const ask = { data: { source: { ask: { said: "x", by: "a" } } } };
+    expect(hold(ask, { questions: { tier: null, understand: { state: "answered", answer: "redraft" } } })).toBe("redraft-or-ask");
+    expect(hold({ leased: true })).toBe("leased");
+  });
+
+  test("understand, retry, done and implements", () => {
+    expect(isAsk({ source: { intent: { answer: "x" } } })).toBe(true);
+    expect([understandOutcome("proceed"), understandOutcome("refuse"), understandOutcome("redraft"), understandOutcome("ask")]).toEqual([null, "dropped", "redraft", "ask"]);
+    const claims = [{ token: "t1", ended: "released", outcome: "not_done", attempt: true }];
+    expect(retryState({}, claims, { exhausted: false }, false)).toEqual({ possible: true, after: "t1", asked: false });
+    expect(retryState({ retry: { after: "t1", by: "a" } }, claims, { exhausted: false }, false)).toMatchObject({ asked: true });
+    expect(retryState({}, claims, { exhausted: true }, false)).toMatchObject({ possible: false, reason: "attempts-exhausted" });
+    expect(retryState({}, [], { exhausted: false }, false)).toMatchObject({ possible: false, reason: "no-failed-build" });
+    const unit = { id: "AC-1", verification: "unit", met: true };
+    expect(doneVerdict({ finished: true, reverted: [] }, { ran: true, ok: true }, [unit])).toEqual({ done: true });
+    expect(doneVerdict({ finished: true, reverted: [] }, { ran: true, ok: true }, [unit, { id: "AC-2", verification: "manual", met: false }])).toMatchObject({ done: false });
+    expect(doneVerdict({ finished: true, reverted: ["x"] }, { ran: true, ok: true }, [unit])).toMatchObject({ done: false });
+    expect(doneVerdict({ finished: true, reverted: [] }, { ran: true, ok: false }, [unit])).toMatchObject({ done: false });
+    expect(
+      proposeImplements(
+        [
+          { path: "a.ts", decisions: [{ id: "d-1", state: "decided", granularity: "path" }, { id: "d-2", state: "decided", granularity: "member" }, { id: "d-3", state: "proposed", granularity: "path" }] },
+          { path: "b.ts", decisions: [{ id: "d-1", state: "decided", granularity: "path" }, { id: "d-4", state: "ratified", granularity: "path" }] },
+        ],
+        ["d-4"],
+      ),
+    ).toEqual([{ decision: "d-1", paths: ["a.ts", "b.ts"] }]);
+  });
+});

package/src/workspace/factory-rules.ts

@@ -0,0 +1,218 @@
+/**
+ * The factory's rules (#3406, ws-087): what every orchestrator of a factory
+ * must agree on, as pure functions over what the read contract prints. The
+ * reference Op (`../op/factory.ts`) runs them; an orchestrator supplies only
+ * execution (the builder, the context, the check).
+ *
+ * - Readiness ({@link pickable}): on top of the work kind's `ready`, the box's
+ *   intent is decided, a contract the item builds is approved and in force,
+ *   the item is under its attempt limit, it is not done and waiting to be
+ *   applied on its branch, its slice-tier and understand questions are not
+ *   open, an understand answer of redraft or ask holds it, and a failed last
+ *   build holds it until a person asks for a retry ({@link retryState}).
+ * - The understand point's answers ({@link understandOutcome}): proceed
+ *   builds; refuse drops the item on its branch; redraft and ask build
+ *   nothing and leave it for its author. Each maps to a lease outcome, and
+ *   only a build's outcome counts as an attempt (#3147).
+ * - Done ({@link doneVerdict}): the builder finished, the check ran and
+ *   passed, and every criterion the factory may tick has passing evidence. A
+ *   criterion verified `manual` or `runtime` is not the factory's to tick, so
+ *   an item with one is not done by the factory.
+ * - Retry ({@link retryState}): a failed build is never tried again on its
+ *   own. A person's request, the item's `retry: { after, by, at }`, names the
+ *   lease token of the failed build it follows, so one request starts one run.
+ * - Implements ({@link proposeImplements}): a build recorded done proposes
+ *   each decision in force that constrains, by path, a path it changed.
+ */
+
+/** The decision point that gates every build of a person's ask (#3150). */
+export const UNDERSTAND_POINT = "understand";
+/** The decision point that picks a builder tier (ws-057, #3150). */
+export const TIER_POINT = "slice-tier";
+
+/** What the understand point answers. */
+export const UNDERSTAND_ANSWERS = ["proceed", "redraft", "ask", "refuse"] as const;
+export type UnderstandAnswer = (typeof UNDERSTAND_ANSWERS)[number];
+
+/** Why an item is not picked. Closed. */
+export const FACTORY_HOLDS = [
+  "not-ready",
+  "intent-undecided",
+  "contract-not-approved",
+  "attempts-exhausted",
+  "awaiting-retry",
+  "built-not-applied",
+  "dropped-on-branch",
+  "question-open",
+  "redraft-or-ask",
+  "leased",
+] as const;
+export type FactoryHold = (typeof FACTORY_HOLDS)[number];
+
+/** A work item as the factory reads it: its record from `records --json`, trimmed to what the rules use. */
+export interface FactoryItem {
+  id: string;
+  state: string | null;
+  /** The kind's open state, such as open. */
+  openState: string;
+  /** The kind's first state for a proposal, such as proposed; an ask in it is a candidate too. */
+  proposedState: string | null;
+  ready: boolean;
+  data: Record<string, unknown> | null;
+  /** The item's own tier, or null. */
+  tier: string | null;
+  /** The contract it builds, with that record's state, or null. */
+  contract: { id: string; state: string | null } | null;
+  /** The record's warnings' codes. */
+  warnings: string[];
+  /** The answers about it, as records --json joins them. */
+  answers: { id: string; point: string | null; state: string | null; answer: string | boolean | null }[];
+  /** Someone holds its lease now. */
+  leased: boolean;
+}
+
+/** One claim of the item's lease history, as `work history --json` prints it. */
+export interface FactoryClaim {
+  token: string;
+  ended: string;
+  outcome: string | null;
+  attempt: boolean;
+}
+
+/** What the factory knows besides the item. */
+export interface FactoryContext {
+  /** null when no box names an intent; else whether that decision is decided. */
+  intentDecided: boolean | null;
+  claims: FactoryClaim[];
+  attempts: { exhausted: boolean };
+  /** The item as its work branch holds it, when the branch exists: its state there and whether the branch is in the checkout. */
+  branch: { state: string | null; applied: boolean } | null;
+  /** The current question of each point for the item as it is now (a dry run), or null when not asked yet. */
+  questions: { tier: { state: string; answer: string | boolean | null } | null; understand: { state: string; answer: string | boolean | null } | null };
+}
+
+/** Whether a work item is a person's ask: its source names what they said, or it is the box's first build from its intent. */
+export function isAsk(data: Record<string, unknown> | null): boolean {
+  const source = data?.source as { ask?: unknown; intent?: unknown } | undefined;
+  return !!(source && typeof source === "object" && (source.ask || source.intent));
+}
+
+/** The retry request on an item: `retry: { after, by, at }`, or null. */
+export function retryRequest(data: Record<string, unknown> | null): { after: string; by: string; at: string } | null {
+  const r = data?.retry as { after?: unknown; by?: unknown; at?: unknown } | undefined;
+  if (!r || typeof r !== "object" || typeof r.after !== "string" || typeof r.by !== "string") return null;
+  return { after: r.after, by: r.by, at: typeof r.at === "string" ? r.at : "" };
+}
+
+export type RetryState =
+  /** The last claim was a failed build and a person may ask for one more. */
+  | { possible: true; after: string; asked: boolean }
+  | { possible: false; reason: "no-failed-build" | "attempts-exhausted" | "held"; message: string };
+
+/**
+ * Whether a person may ask for item `data`'s failed build to run again: the
+ * last claim is a failed build, nobody holds the lease, and attempts remain.
+ * `asked` says a request naming that build is already on the item.
+ */
+export function retryState(data: Record<string, unknown> | null, claims: readonly FactoryClaim[], attempts: { exhausted: boolean }, leased: boolean): RetryState {
+  if (leased) return { possible: false, reason: "held", message: "someone holds the item's lease now" };
+  const last = claims.at(-1);
+  if (!last || !last.attempt) return { possible: false, reason: "no-failed-build", message: "the item's last claim is not a failed build, so there is nothing to retry" };
+  if (attempts.exhausted) return { possible: false, reason: "attempts-exhausted", message: "the item has used every attempt its limit allows, so it is left to people" };
+  const asked = retryRequest(data)?.after === last.token;
+  return { possible: true, after: last.token, asked };
+}
+
+/** The lease outcome an understand answer leads to: null for proceed, which builds. */
+export function understandOutcome(answer: unknown): "dropped" | "redraft" | "ask" | null {
+  if (answer === "refuse") return "dropped";
+  if (answer === "redraft" || answer === "ask") return answer;
+  return null;
+}
+
+const OPEN = new Set(["escalated", "proposed"]);
+
+/**
+ * Whether the factory picks `item` now, or why not. Asks are candidates while
+ * proposed as well as open; any other item only when the work kind reads it
+ * ready.
+ */
+export function pickable(item: FactoryItem, ctx: FactoryContext): { ok: true } | { ok: false; hold: FactoryHold; message: string } {
+  const no = (hold: FactoryHold, message: string) => ({ ok: false as const, hold, message });
+  if (ctx.intentDecided === false) return no("intent-undecided", "the box's intent is not decided yet, so nothing is picked");
+  if (item.leased) return no("leased", `${item.id} is leased`);
+  const ask = isAsk(item.data);
+  const candidate = item.ready || (ask && item.proposedState !== null && item.state === item.proposedState);
+  if (!candidate) return no("not-ready", `${item.id} is ${item.state ?? "in no state"} and not ready`);
+  if (item.contract && (item.warnings.includes("work-contract-undecided") || item.warnings.includes("work-contract-unknown"))) {
+    return no("contract-not-approved", `${item.id} builds ${item.contract.id}, which is not approved and in force`);
+  }
+  if (ctx.branch && !ctx.branch.applied && ctx.branch.state === "done") return no("built-not-applied", `${item.id} is built on its branch and waits to be applied`);
+  if (ctx.branch && !ctx.branch.applied && ctx.branch.state === "dropped") return no("dropped-on-branch", `${item.id} was dropped on its branch`);
+  if (ctx.attempts.exhausted) return no("attempts-exhausted", `${item.id} has used every attempt, so it is left to people`);
+  const last = ctx.claims.at(-1);
+  if (last?.attempt && retryRequest(item.data)?.after !== last.token) {
+    return no("awaiting-retry", `${item.id}'s last build failed; a person asks for another with retry.after: ${last.token}`);
+  }
+  for (const [name, q] of [[TIER_POINT, item.tier === null ? ctx.questions.tier : null], [UNDERSTAND_POINT, ask ? ctx.questions.understand : null]] as const) {
+    if (q && OPEN.has(q.state)) return no("question-open", `${item.id}'s ${name} question is ${q.state}; a person answers it first`);
+  }
+  const u = ask ? ctx.questions.understand : null;
+  if (u && u.state === "answered" && (u.answer === "redraft" || u.answer === "ask")) {
+    return no("redraft-or-ask", `${item.id}'s understand question was answered ${String(u.answer)}; its author changes the item, which asks again`);
+  }
+  return { ok: true };
+}
+
+/** One acceptance criterion's state, as records --json lists it. */
+export interface CriterionView {
+  id: string;
+  verification: string;
+  met: boolean;
+}
+
+/** Whether a build is done, or why not. */
+export function doneVerdict(build: { finished: boolean; reverted: string[] }, check: { ran: boolean; ok: boolean }, criteria: readonly CriterionView[]): { done: true } | { done: false; reason: string } {
+  if (!build.finished) return { done: false, reason: "the builder did not finish" };
+  if (build.reverted.length > 0) return { done: false, reason: `the guard put back what the builder changed out of scope: ${build.reverted.join(", ")}` };
+  if (!check.ran) return { done: false, reason: "no check ran" };
+  if (!check.ok) return { done: false, reason: "the check failed" };
+  const people = criteria.filter((c) => c.verification === "manual" || c.verification === "runtime");
+  if (people.length > 0) return { done: false, reason: `criteria ${people.map((c) => c.id).join(", ")} are verified ${people.map((c) => c.verification).join("/")}, which the factory never ticks` };
+  const unmet = criteria.filter((c) => !c.met);
+  if (unmet.length > 0) return { done: false, reason: `criteria ${unmet.map((c) => c.id).join(", ")} have no passing evidence` };
+  return { done: true };
+}
+
+/**
+ * The decisions a done build proposes it implements (studio#243): from the
+ * intent graph's `constrains` edges of granularity `path` to each changed
+ * path, the decisions in force, less those the item already implements.
+ */
+export function proposeImplements(
+  changed: readonly { path: string; decisions: readonly { id: string; state: string | null; granularity: string }[] }[],
+  already: readonly string[],
+  inForce: readonly string[] = ["decided", "ratified"],
+): { decision: string; paths: string[] }[] {
+  const out = new Map<string, string[]>();
+  for (const c of changed) {
+    for (const d of c.decisions) {
+      if (d.granularity !== "path" || d.state === null || !inForce.includes(d.state) || already.includes(d.id)) continue;
+      const paths = out.get(d.id) ?? [];
+      if (!paths.includes(c.path)) paths.push(c.path);
+      out.set(d.id, paths);
+    }
+  }
+  return [...out].map(([decision, paths]) => ({ decision, paths }));
+}
+
+/**
+ * The key of the state an item was read in, for a steward's ready step: a
+ * new key is work no run was started for. It names the item, its last claim
+ * and its open questions, so a person's answer to either point is a new key.
+ */
+export function readyKey(item: Pick<FactoryItem, "id">, ctx: Pick<FactoryContext, "claims" | "questions">, data: Record<string, unknown> | null): string {
+  const last = ctx.claims.at(-1)?.token ?? "none";
+  const q = (x: { state: string; answer: unknown } | null) => (x ? `${x.state}:${String(x.answer)}` : "-");
+  return `${item.id}@${last}#tier=${q(ctx.questions.tier)}#understand=${q(ctx.questions.understand)}#retry=${retryRequest(data)?.after ?? "-"}`;
+}

package/src/workspace/graph-cli.ts

@@ -59,7 +59,7 @@ export type GraphErrorCode = (typeof GRAPH_ERROR_CODES)[number];
 const LIVE_AT_REVISION = "--live reads the account as it stands now, and --at reads the source at a revision; chant workspace graph takes one of them";
 
 const USAGE =
-  "chant workspace graph [dir] [--at <rev>] [--member <name>] [--kind <kind file>] [-o <file>] [--env <env>] [--live [--overlay] [--traffic <level>]] [--no-cache] [--dry-run] | chant workspace graph --composites [--at <rev>] [--member <name>] [-o <file>] | chant workspace graph --intent <path[:start-end]> [--at <rev>] [--kind <kind file>...] [--json]";
+  "chant workspace graph [dir] [--at <rev>] [--member <name>] [--kind <kind file>] [-o <file>] [--env <env>] [--live [--overlay] [--traffic <level>]] [--no-cache] [--dry-run] | chant workspace graph --composites [--at <rev>] [--member <name>] [-o <file>] | chant workspace graph --intent <path[:start-end]|path#symbol> [--at <rev>] [--kind <kind file>...] [--follow-squash] [--json]";
 
 interface Head {
   $schema: string;
@@ -260,7 +260,7 @@ export async function workspaceGraph(query: GraphQuery): Promise<GraphResult> {
     // Links (#2539) resolve against the declaration that was read, the revision's for --at, and the kinds installed now.
     const graph = composeWorkspaceGraph({ name: declaration.name, root: located.root }, inputs, { declaration, kinds });
     // The box's factory and listing (#3146), from the declaration read, so --at gives them at that revision.
-    for (const member of graph.members) member.box = graphBox(declaration.members.find((m) => m.name === member.name)?.box ?? null, located.tree);
+    for (const member of graph.members) member.box = graphBox(declaration.members.find((m) => m.name === member.name)?.box ?? null, located.tree, declaration.members);
     // Nested workspaces (#2551, ws-071): read-only, through their own chant workspace graph.
     const nestedFailed = await expandNested(graph, declaration.members, query, located.rootOnDisk, located.at);
     let recordsFailed = false;

package/src/workspace/graph.schema.json

@@ -1114,6 +1114,8 @@
         "check",
         "checks",
         "builders",
+        "tiers",
+        "builderFor",
         "publish"
       ],
       "properties": {
@@ -1168,6 +1170,71 @@
           ],
           "description": "The member that declares the builder agents, or null."
         },
+        "tiers": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "tier",
+              "agent",
+              "kinds",
+              "session"
+            ],
+            "properties": {
+              "tier": {
+                "type": "string"
+              },
+              "agent": {
+                "type": "string"
+              },
+              "kinds": {
+                "oneOf": [
+                  {
+                    "type": "null"
+                  },
+                  {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    }
+                  }
+                ]
+              },
+              "session": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              }
+            }
+          },
+          "description": "Which builder agent builds at which tier, as declared (#3152, ws-094), each { tier, agent, kinds, session } with kinds and session null when not declared; empty when none is. Added in contract 1 by chant 0.103.0."
+        },
+        "builderFor": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "object",
+              "required": [
+                "agent",
+                "session"
+              ],
+              "properties": {
+                "agent": {
+                  "type": "string"
+                },
+                "session": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                }
+              }
+            }
+          },
+          "description": "The builder for each member the factory builds, by tier (#3152): member name, then tier, then { agent, session }. For a member the entry naming its kind is used, else the tier's entry with no kinds; a tier with neither is left out. Added in contract 1 by chant 0.103.0."
+        },
         "publish": {
           "description": "Where a finished build is published, or null when the factory doesn't publish past the box.",
           "oneOf": [

package/src/workspace/identity.test.ts

@@ -161,6 +161,29 @@ describe.skipIf(!hasSshKeygen)("identity.gates", () => {
     expect(unknown.refuses(signed(alice, approval("github:alice")))).toMatch(/no pinned package supplies/);
   });
 
+  test("a relayed approval: the seal covers relayedBy, and status lists it (#3402)", () => {
+    const { alice } = keys();
+    const policy = policyWith([{ principal: "github:alice", key: alice.pub }]);
+    const rule = gateAdmissionFrom({ declaration: decl({ gates: { ship: {} } }), policy, classes: coreClassRegistry() }, "ship")!;
+    const relayed = signed(alice, approval("github:alice", { relayedBy: "github:hud-follower" }));
+    expect(rule.refuses(relayed)).toBeNull();
+    // The relay can't be changed, dropped or added after sealing.
+    expect(rule.refuses({ ...relayed, relayedBy: "github:mallory" })).toMatch(/does not verify/);
+    const { relayedBy: _dropped, ...unrelayed } = relayed;
+    expect(rule.refuses(unrelayed)).toMatch(/does not verify/);
+    expect(rule.refuses({ ...signed(alice, approval("github:alice")), relayedBy: "github:hud-follower" })).toMatch(/does not verify/);
+    // A seal made before #3402, with no relay, still verifies.
+    expect(rule.refuses(signed(alice, approval("github:alice")))).toBeNull();
+
+    const pending: PendingGateRecord = { version: 1, kind: "pending", op: "web", gate: "ship", environment: "prod", planDigest: "sha256:" + "a".repeat(64), timestamp: "2026-10-03T11:00:00.000Z", expiresAt: "2026-10-10T11:00:00.000Z" };
+    const ledger = [pending, relayed, approval("bob")].map((l) => JSON.stringify(l)).join("\n");
+    const gate = gatesInLedger("web", ledger, ["prod"], "2026-10-03T13:00:00.000Z").gates[0];
+    expect(gate.approvals).toEqual([
+      { principal: "github:alice", channel: null, relayedBy: "github:hud-follower", at: "2026-10-03T12:00:00.000Z" },
+      { principal: "bob", channel: null, relayedBy: null, at: "2026-10-03T12:00:00.000Z" },
+    ]);
+  });
+
   test("a run and workspace status leave out approvals the rule refuses", async () => {
     const { alice } = keys();
     const policy = policyWith([{ principal: "github:alice", key: alice.pub }]);

package/src/workspace/init.ts

@@ -21,10 +21,18 @@
  *   never written.
  *
  * Nothing here runs project code: it reads file names and package.json files.
+ *
+ * `--profile ideation|app|infra` starts a workspace from one of the reference
+ * workspace's profiles instead (#3174, ws-096): records only with a stub app,
+ * an app with its factory, or an estate with a factory and no app. It is
+ * `chant init --from` on `reference-workspace/profiles/<profile>` of the chant
+ * repository at this chant's release tag, or of the repository or directory
+ * `--from` names, so the new workspace gets a lineage lock and can be upgraded
+ * like any template copy.
  */
 
 import { execFileSync } from "node:child_process";
-import { existsSync, readdirSync, writeFileSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, join, resolve } from "node:path";
 import { formatError, formatSuccess } from "../cli/format";
 import type { CommandContext } from "../cli/registry";
@@ -36,12 +44,34 @@ import {
   rootExclusions,
   WorkspaceReadError,
   isInside,
+  readerVersion,
 } from "./declaration";
 import { expandGlob } from "./glob";
+import { setProperty } from "./json-edit";
 import { holdsChantProject } from "./kinds";
 import { gitTop, skippedDir, workingTree, type WorkspaceTree } from "./tree";
 
-const USAGE = "chant workspace init [dir] [--name <name>] [--yes] [--verbose]";
+const USAGE = "chant workspace init [dir] [--name <name>] [--yes] [--verbose]\n       chant workspace init --profile ideation|app|infra [dir] [--name <name>] [--param name=<display name>] [--from <repo>@<ref>|<chant checkout>] [--yes]";
+
+/** The profiles `--profile` takes (#3174), each a directory under {@link PROFILES_DIR} in the chant repository. */
+export const PROFILES = ["ideation", "app", "infra"] as const;
+export type Profile = (typeof PROFILES)[number];
+
+/** Where the profiles live in the chant repository. */
+export const PROFILES_DIR = "reference-workspace/profiles";
+
+/** The repository the profiles are read from by default, at this chant's release tag. */
+export const PROFILES_REPO = "https://github.com/INTENTIUS/chant";
+
+/**
+ * The `chant init --from` source for a profile: `from` (a `<repo>@<ref>` or
+ * a directory holding a chant checkout) when given, else the chant repository
+ * at the tag of the chant reading, `chant-v<version>`.
+ */
+export function profileSource(profile: Profile, from: string | undefined, version: string): string {
+  const base = from ?? `${PROFILES_REPO}@chant-v${version}`;
+  return `${base}#${PROFILES_DIR}/${profile}`;
+}
 
 /** Directory names whose children are examples or test fixtures, not members. */
 const EXAMPLE_DIRS = new Map<string, "examples" | "fixtures">([
@@ -544,6 +574,8 @@ export async function runWorkspaceInit(ctx: CommandContext): Promise<number> {
     return 1;
   }
 
+  if (args.profile !== undefined) return initProfile(args, root);
+
   let proposal: Proposal;
   try {
     proposal = proposeWorkspace(root, { name: args.selectName });
@@ -583,3 +615,51 @@ export async function runWorkspaceInit(ctx: CommandContext): Promise<number> {
   console.log(formatSuccess(`Wrote ${target}. chant workspace ls lists what it declares.`));
   return 0;
 }
+
+/** `chant workspace init --profile <profile>` (#3174): copy a profile with `chant init --from`, then name the workspace. */
+async function initProfile(args: CommandContext["args"], root: string): Promise<number> {
+  const profile = args.profile as Profile;
+  if (!(PROFILES as readonly string[]).includes(profile)) {
+    console.error(formatError({ message: `--profile ${JSON.stringify(args.profile)} is not a profile; the profiles are ${PROFILES.join(", ")}`, hint: USAGE }));
+    return 1;
+  }
+  const { parseParamArgs } = await import("./template-manifest");
+  let params: Record<string, string>;
+  try {
+    params = parseParamArgs(args.param ?? []);
+  } catch (err) {
+    console.error(formatError({ message: (err as Error).message, hint: USAGE }));
+    return 1;
+  }
+  const from = profileSource(profile, args.migrateFrom, readerVersion());
+  console.log(`chant workspace init --profile ${profile} copies ${from} into ${root}, as chant init --from would, with a lineage lock.`);
+  if (args.selectName !== undefined) console.log(`The workspace is named ${args.selectName}.`);
+  console.log("");
+  let write = !!args.yes;
+  if (!write) {
+    if (!process.stdin.isTTY) {
+      console.log("Nothing written. Re-run with --yes to write it.");
+      return 0;
+    }
+    write = await confirm(`Make the ${profile} workspace? [y/N] `);
+  }
+  if (!write) {
+    console.log("Nothing written.");
+    return 0;
+  }
+  const { initFromCommand } = await import("./lineage-init");
+  const result = await initFromCommand({ from, path: root, params, force: args.force });
+  if (!result.success) {
+    console.error(formatError({ message: result.error ?? `the ${profile} profile could not be copied`, hint: USAGE }));
+    return 1;
+  }
+  if (args.selectName !== undefined) {
+    const file = join(root, "chant.workspace.json");
+    writeFileSync(file, setProperty(readFileSync(file, "utf-8"), false, "", "name", args.selectName));
+  }
+  console.log(formatSuccess(`Made a ${profile} workspace in ${root}:`));
+  for (const f of result.createdFiles) console.log(`  ${f}`);
+  console.log("");
+  console.log("chant workspace check checks it, and chant workspace upgrade takes a later version of the profile.");
+  return 0;
+}

package/src/workspace/intent-cli.ts

@@ -1,5 +1,5 @@
 /**
- * `chant workspace graph --intent <path[:start-end]|path#symbol> [--at <rev>] [--kind <kind file>...] [--json]`
+ * `chant workspace graph --intent <path[:start-end]|path#symbol> [--at <rev>] [--kind <kind file>...] [--follow-squash] [--json]`
  * (#2651, #3034): the intent graph over one region (`intent.ts`), printed as JSON
  * with `--json` or as a walk, one line per node, in the order of #2650
  * section B: the region, its decisions, their artifacts, the commits, and the
@@ -16,8 +16,8 @@ import type { CommandContext } from "../cli/registry";
 import { intentRecord, type IntentRecordDocument } from "./intent-record";
 import { intentGraph, type ArtifactNode, type CommitNode, type DecisionNode, type IntentDocument, type IntentEdge, type IntentNode, type RunNode, type WhyAnswer, type WorkNode } from "./intent";
 
-const USAGE = "chant workspace graph --intent <path[:start-end]|path#symbol> [--at <rev>] [--kind <kind file>...] [--json]";
-const RECORD_USAGE = "chant workspace graph --intent --record <id> [--at <rev>] [--kind <kind file>...] [--json]";
+const USAGE = "chant workspace graph --intent <path[:start-end]|path#symbol> [--at <rev>] [--kind <kind file>...] [--follow-squash] [--json]";
+const RECORD_USAGE = "chant workspace graph --intent --record <id> [--at <rev>] [--kind <kind file>...] [--follow-squash] [--json]";
 
 type Result = Exclude<IntentDocument, { error: unknown }>;
 type RecordResult = Exclude<IntentRecordDocument, { error: unknown }>;
@@ -110,11 +110,27 @@ function commitLine(doc: Result, c: CommitNode): string[] {
     for (const s of edgesFrom(doc, e.to, "cites-evidence")) out.push(`  evidence  ${s.to.slice("evidence:".length)}`);
   }
   out.push(...joinLines(c.joins));
+  if (c.squash) {
+    const s = c.squash;
+    out.push(`  squash    #${s.pullRequest}${s.followed ? `: ${s.commits.length} original ${s.commits.length === 1 ? "commit" : "commits"} from ${s.ref}${s.fetched ? ", fetched" : ""}` : ", not followed"}`);
+    for (const o of s.commits) {
+      const carried = [...o.joins.records.map((r) => `${r.kind}:${r.id}`), ...(o.joins.lease ? [`lease ${o.joins.lease.token}`] : []), ...(o.joins.run ? [`run ${o.joins.run}`] : [])];
+      out.push(`  original  ${short(o.sha)} ${o.subject}; ${o.signature.level}${carried.length > 0 ? `; ${carried.join(", ")}` : ""}`);
+    }
+  }
   for (const e of edgesFrom(doc, c.id, "made-by")) {
     const r = doc.nodes.find((n): n is RunNode => n.kind === "run" && n.id === e.to);
     if (!r) continue;
     const what = r.recorded ? `${[r.harness?.name, r.model].filter(Boolean).join("/") || "no model recorded"}${r.by ? ` for ${r.by}` : ""}${r.cost ? `, ${r.cost.amount} ${r.cost.currency}` : ", unpriced"}` : "not in the run ledger";
-    out.push(`  run       ${r.run}: ${what}`);
+    const content =
+      e.kind !== "made-by"
+        ? ""
+        : e.joinedBy.includes("patch-id")
+          ? `; joined by content${e.recordedAs ? `, as ${short(e.recordedAs)}` : ""}`
+          : e.joinedBy.length === 1 && e.joinedBy[0] === "squash"
+            ? `; through the squash, by ${(e.via ?? []).map(short).join(", ")}`
+            : "";
+    out.push(`  run       ${r.run}: ${what}${content}`);
   }
   return out;
 }
@@ -139,7 +155,7 @@ export function whyLines(doc: Result, why: WhyAnswer): string[] {
     out.push(`  decision  ${record(d.decision)} ${d.relevance}${d.lines > 0 ? `, ${d.lines} ${d.lines === 1 ? "line" : "lines"}` : ""}${d.current ? "" : ", superseded"}${d.closed ? ", closed" : ""}`);
   }
   for (const b of why.blame) {
-    const by = b.runs.length > 0 ? `; ${b.runs.map(runLabel).join(", ")}${b.narrowedBy ? " (by its hunks)" : ""}` : b.sha ? "; no run" : "";
+    const by = b.runs.length > 0 ? `; ${b.runs.map(runLabel).join(", ")}${b.narrowedBy ? " (by its hunks)" : ""}${b.joinedBy?.includes("patch-id") ? " (joined by content)" : ""}${b.via && b.via.length > 0 ? ` (squashed from ${b.via.map(short).join(", ")})` : ""}` : b.sha ? "; no run" : "";
     out.push(`  lines     ${span(b)} ${b.sha ? short(b.sha) : "uncommitted"}${by}`);
   }
   for (const g of why.gaps) out.push(`  gap       ${g.code}: ${g.message}${g.lines ? ` (lines ${g.lines.map(span).join(", ")})` : ""}`);
@@ -195,8 +211,9 @@ export function formatIntentRecord(doc: RecordResult): string {
           : c.bucket === "within-other"
             ? `within ${c.alsoWithin.map((w) => w.record).join(", ")}`
             : "nothing else accounts for it";
-    const runs = (c.runs ?? []).map((r) => `run ${r.id}${r.model ? ` (${r.model})` : ""}`).join(", ");
-    out.push(`${c.bucket.padEnd(12)} ${short(c.sha)} ${c.date.slice(0, 10)} ${c.subject}; ${why}${runs ? `; ${runs}` : ""}; ${c.files.join(", ") || c.entries.join(", ")}`);
+    const runs = (c.runs ?? []).map((r) => `run ${r.id}${r.model ? ` (${r.model})` : ""}${r.joinedBy?.includes("squash") && !r.joinedBy.some((j) => j !== "squash") ? " through the squash" : ""}`).join(", ");
+    const squash = c.squash ? `; squash of #${c.squash.pullRequest}${c.squash.followed ? `, ${c.squash.commits.length} original ${c.squash.commits.length === 1 ? "commit" : "commits"}` : ", not followed"}` : "";
+    out.push(`${c.bucket.padEnd(12)} ${short(c.sha)} ${c.date.slice(0, 10)} ${c.subject}; ${why}${runs ? `; ${runs}` : ""}${squash}; ${c.files.join(", ") || c.entries.join(", ")}`);
   }
   for (const x of doc.reasons) out.push(`reason    ${x.code}: ${x.message}`);
   const n = doc.counts;
@@ -206,7 +223,7 @@ export function formatIntentRecord(doc: RecordResult): string {
 
 async function runRecord(ctx: CommandContext, cwd: string, kinds: string[] | undefined): Promise<number> {
   const { args } = ctx;
-  const { doc, failed } = await intentRecord({ cwd, record: args.record!, at: args.at, kinds: kinds?.map((k) => resolve(k)) });
+  const { doc, failed } = await intentRecord({ cwd, record: args.record!, at: args.at, kinds: kinds?.map((k) => resolve(k)), followSquash: args.followSquash });
   if (args.json) console.log(JSON.stringify(doc, null, 2));
   if ("error" in doc) {
     console.error(formatError({ message: `${doc.error.code}: ${doc.error.message}`, hint: RECORD_USAGE }));
@@ -231,7 +248,7 @@ export async function runWorkspaceIntent(ctx: CommandContext, cwd: string): Prom
   }
   // No --kind: undefined, so the walk reads the kinds the declaration names (#2680).
   const kinds = args.kinds ?? (args.kind !== undefined ? [args.kind] : undefined);
-  const { doc, failed } = await intentGraph({ cwd, region: args.intent, at: args.at, kinds: kinds?.map((k) => resolve(k)) });
+  const { doc, failed } = await intentGraph({ cwd, region: args.intent, at: args.at, kinds: kinds?.map((k) => resolve(k)), followSquash: args.followSquash });
   if (args.json) console.log(JSON.stringify(doc, null, 2));
   if ("error" in doc) {
     console.error(formatError({ message: `${doc.error.code}: ${doc.error.message}`, hint: USAGE }));