@maycombhq/atticus 0.0.0-stage → 2.0.0-beta.2

package/dist/chunk-L6SGQIR3.js

@@ -0,0 +1,471 @@
+import { createRequire as __atticusCreateRequire } from "node:module";
+import { fileURLToPath as __atticusFileURLToPath } from "node:url";
+var require = __atticusCreateRequire(import.meta.url);
+var __atticusUrl = (p) => new URL("./" + p, import.meta.url).href;
+var __atticusPath = (p) => __atticusFileURLToPath(__atticusUrl(p));
+import {
+  FLOW_STEP_KINDS,
+  FLOW_TRIGGER_KINDS,
+  QuestionDraft,
+  changesDirOf,
+  external_exports,
+  require_dist
+} from "./chunk-S2A7YC3Q.js";
+import {
+  __toESM
+} from "./chunk-TV45EUGM.js";
+
+// packages/planner/dist/stages/schema.js
+var STAGE_SCHEMA_VERSION = 1;
+var V = external_exports.literal(STAGE_SCHEMA_VERSION);
+var text = () => external_exports.string().trim().min(1);
+var Id = external_exports.string().regex(/^[a-z0-9][a-z0-9._-]*$/, "an id is lower case: letters, digits, . _ -");
+var STAGES = ["feature", "architecture", "stories", "small"];
+var Stage = external_exports.enum(STAGES);
+var STAGE_PHASE = {
+  feature: "define",
+  architecture: "design",
+  stories: "plan",
+  small: "plan"
+};
+var Backing = external_exports.enum(["existing", "new", "unbacked"]);
+var DesignField = external_exports.strictObject({
+  /** The node id in the design file. */
+  figmaId: text(),
+  label: text(),
+  /** existing: the estate has it today; new: this change adds it; unbacked: nothing provides it. */
+  backing: Backing,
+  /** For existing: the API field and column, in words. */
+  mapsTo: external_exports.string().optional(),
+  /** Catalog or flow ids the mapping rests on (each one is checked to exist). */
+  refs: external_exports.array(Id).default([]),
+  /** What is missing, for new and unbacked (and existing data that still needs a link). */
+  gap: external_exports.string().optional()
+});
+var DesignAction = external_exports.strictObject({
+  figmaId: text(),
+  label: text(),
+  does: external_exports.string().optional(),
+  /** The call it makes today, "METHOD /path", or "none" for navigation. */
+  endpoint: external_exports.string().optional(),
+  /** The flow it starts, when one exists. */
+  flow: Id.optional(),
+  gap: external_exports.string().optional()
+});
+var DesignScreen = external_exports.strictObject({
+  figmaId: text(),
+  name: text(),
+  /** The UI flow (or page) it extends, when there is one. */
+  flow: Id.optional(),
+  fields: external_exports.array(DesignField).default([]),
+  actions: external_exports.array(DesignAction).default([])
+});
+var FeaturePlacement = external_exports.strictObject({
+  schemaVersion: V,
+  change: Id,
+  /** What the stage started from. */
+  entry: external_exports.enum(["brief", "stories", "figma"]),
+  /** What the feature is, in two or three plain sentences. */
+  summary: text(),
+  /** Existing features (Capability records) it touches. */
+  features: external_exports.array(external_exports.strictObject({ id: Id, why: text() })).default([]),
+  /** Existing flows (repo specs) it touches. */
+  flows: external_exports.array(external_exports.strictObject({
+    id: Id,
+    why: text(),
+    /** changed: the flow's steps change; read: it only reads what the flow gives. */
+    how: external_exports.enum(["changed", "read"]).default("changed")
+  })).default([]),
+  /** Flows that don't exist yet. */
+  newFlows: external_exports.array(external_exports.strictObject({ name: text(), repo: Id, why: text() })).default([]),
+  gaps: external_exports.array(external_exports.strictObject({
+    what: text(),
+    why: text(),
+    /** The design element or flow it comes from. */
+    from: external_exports.string().optional()
+  })).default([]),
+  /** Other open changes that touch the same flows or systems; Atticus fills these. */
+  conflicts: external_exports.array(external_exports.strictObject({
+    change: Id,
+    flows: external_exports.array(Id).default([]),
+    systems: external_exports.array(Id).default([]),
+    why: text()
+  })).default([]),
+  /** The design's screens, read from the export and mapped (Figma entry only). */
+  design: external_exports.strictObject({
+    file: text(),
+    screens: external_exports.array(DesignScreen).default([]),
+    /** Elements the reader found that aren't data or actions (a static title), with why. */
+    ignored: external_exports.array(external_exports.strictObject({ figmaId: text(), why: text() })).default([])
+  }).optional(),
+  /** Questions for a person; Atticus writes them to questions/. */
+  questions: external_exports.array(QuestionDraft).default([])
+});
+var DeltaFields = external_exports.strictObject({
+  sends: external_exports.array(text()).optional(),
+  returns: external_exports.array(text()).optional(),
+  reads: external_exports.array(text()).optional(),
+  checks: external_exports.array(text()).optional(),
+  from: external_exports.array(text()).optional(),
+  to: external_exports.array(text()).optional(),
+  /**
+   * A write's sent fields that are stored as, or match rows by, a column of another name, as
+   * the delta says it (ADR 0111 addendum, R3): `{ id: chat_id }` for a path parameter id that
+   * is the chat_id column. Optional and additive: the flow delta stays at version 2.
+   */
+  as: external_exports.record(external_exports.string(), text()).optional(),
+  /**
+   * A field the step works out from columns, and how (W3b): `{ edited: "edited_at is not null" }`.
+   * The expression names columns a step reads or writes, or of their tables; checked as a fact.
+   * Optional and additive: the flow delta stays at version 2.
+   */
+  derived: external_exports.record(external_exports.string(), text()).optional(),
+  /**
+   * An entry step: the request fields it requires once the change is in (ADR 0125). A field
+   * neither today's entry nor the catalog has, or one the catalog has as optional, breaks who
+   * calls it. Optional and additive: the flow delta stays at version 2.
+   */
+  required: external_exports.array(text()).optional()
+});
+function parseAt(at) {
+  const t = at.trim().replace(/\\/g, "/");
+  const m = /^(.+?)(?::(\d+)|:([A-Za-z_$][\w$.#]*)(?:\(\))?)?$/.exec(t);
+  if (!m)
+    return void 0;
+  const path = m[1].replace(/^\.\//, "");
+  if (!path || path.startsWith("/") || /^[A-Za-z]:/.test(path) || path.split("/").includes(".."))
+    return void 0;
+  return {
+    path,
+    ...m[2] ? { line: Number(m[2]) } : {},
+    ...m[3] ? { function: m[3] } : {}
+  };
+}
+var usesOf = (s) => s.uses === void 0 ? [] : Array.isArray(s.uses) ? s.uses : [s.uses];
+function parseNewFile(path) {
+  const p = parseAt(path);
+  return p && p.line === void 0 && p.function === void 0 ? p.path : void 0;
+}
+var fieldNames = (f) => f ? ["sends", "returns", "reads", "checks", "from", "to"].flatMap((k) => f[k] ?? []) : [];
+var ON_DELETE = ["set-null", "cascade", "restrict", "no-action"];
+var StoreKey = external_exports.strictObject({
+  references: external_exports.string().trim().regex(/^[^.\s]+(\.[^.\s]+){2,}$/, "write the column it references as <db>.<table>.<column>"),
+  onDelete: external_exports.enum(ON_DELETE)
+});
+var DeltaStep = external_exports.strictObject({
+  op: external_exports.enum(["add", "change", "remove"]),
+  /** change and remove: the step's position in today's flow, from 1. */
+  step: external_exports.number().int().positive().optional(),
+  /** add: the position it goes after (0: first). */
+  after: external_exports.number().int().min(0).optional(),
+  /**
+   * add: where the new step's code goes into code the repo has (ADR 0124 addendum B-places),
+   * `path:line` of the line it goes after: that code changes. B-place: only an edit there; code
+   * the step only calls is `uses`, a file the change creates is `new`, and the check refuses a
+   * place with no line (`path:function` and the path alone read as before, for older answers).
+   * Checked against the repo's checkout and the catalog; the step's and its task's citation.
+   * Left out, a step of a modify flow is placed after the step before it and says so.
+   * Optional and additive: version 2 stays.
+   */
+  at: external_exports.string().trim().min(1).optional(),
+  /**
+   * add (B-place): the new file the step's code goes in, a path the change creates, in the
+   * folder of its nearest kin (the check asks that the folder exists). Steps naming the same
+   * file are one task. Optional and additive: version 2 stays.
+   */
+  new: external_exports.string().trim().min(1).optional(),
+  /**
+   * B-place: existing code the step calls or reuses, `path:line`, one or several. It doesn't
+   * change: a task names it as code it calls, never as a file to touch. A step whose `uses`
+   * line already does what the step does (an existing flow's step there, the same write, read
+   * or call) is already done. Optional and additive: version 2 stays.
+   */
+  uses: external_exports.union([external_exports.string().trim().min(1), external_exports.array(external_exports.string().trim().min(1)).min(1)]).optional(),
+  kind: external_exports.enum(FLOW_STEP_KINDS).optional(),
+  /** What the step does once the change is in, in one plain sentence. */
+  what: external_exports.string().optional(),
+  /** call-out and publish: where it goes. `new` when the component or entry doesn't exist yet. */
+  to: external_exports.strictObject({ component: Id, entry: text(), new: external_exports.boolean().default(false) }).optional(),
+  /** read, lookup and write: the table and columns. `new` for a table this change adds. */
+  store: external_exports.strictObject({
+    table: Id,
+    columns: external_exports.array(text()).default([]),
+    new: external_exports.boolean().default(false),
+    /** The database type of each column this change adds, e.g. { fraud_verdict: varchar(20) }. */
+    types: external_exports.record(external_exports.string(), text()).optional(),
+    /** The classification of each column this change adds, from the org pack's levels. */
+    classification: external_exports.record(external_exports.string(), text()).optional(),
+    /** The migration file that makes the change, e.g. V4__add_fraud_verdict.sql. */
+    migration: external_exports.string().optional(),
+    /** A new table: how long its rows are kept. */
+    retention: external_exports.string().optional(),
+    /**
+     * The foreign keys of the columns this change adds (ADR 0111 addendum, S4): each column to
+     * the `<db>.<table>.<column>` it references, and what a delete of that row does. Optional
+     * and additive, on the table's one definition: the flow delta stays at version 2.
+     */
+    keys: external_exports.record(external_exports.string(), StoreKey).optional(),
+    /**
+     * The components that read or write the table, from the map (ADR 0124 addendum B-arch):
+     * given when the step's change to the table breaks them (a column the table has gets
+     * another type, or the step is marked breaking). Optional and additive: version 2 stays.
+     */
+    consumers: external_exports.array(Id).optional()
+  }).optional(),
+  fields: DeltaFields.optional(),
+  /**
+   * The drafter says the step's change breaks who uses it today, where no field is dropped
+   * (ADR 0124 addendum B-arch): a field whose meaning changes (a field now required is said
+   * under the entry step's `fields.required`, ADR 0125). On a step
+   * that stores into a table it is the table's change; on any other, the flow's entry's.
+   */
+  breaking: external_exports.boolean().optional(),
+  /** loop and retry: the steps it repeats, by their numbers in the target flow (ADR 0095). */
+  repeats: external_exports.strictObject({ from: external_exports.number().int().positive(), to: external_exports.number().int().positive() }).optional(),
+  why: external_exports.string().optional()
+});
+var FLOW_DELTA_SCHEMA_VERSION = 2;
+var FlowDelta = external_exports.strictObject({
+  schemaVersion: external_exports.union([external_exports.literal(1), external_exports.literal(FLOW_DELTA_SCHEMA_VERSION)]),
+  /** The flow's id: an existing flow in specs/<repo>/, or the new flow's id (<component>.<name>). */
+  flow: Id,
+  repo: Id,
+  change: external_exports.enum(["modify", "new", "remove"]),
+  /** new: what a person calls the flow. */
+  name: external_exports.string().optional(),
+  /** new: what starts it. */
+  trigger: external_exports.strictObject({ kind: external_exports.enum(FLOW_TRIGGER_KINDS), what: text(), entry: external_exports.string().optional() }).optional(),
+  why: text(),
+  /**
+   * The components (or systems) that call the flow's entry today, from the map (ADR 0124
+   * addendum B-arch): given when the change breaks what the entry reads or returns, or removes
+   * the flow. Optional and additive: the flow delta stays at version 2.
+   */
+  consumers: external_exports.array(Id).optional(),
+  /**
+   * A new flow of a component the catalog doesn't have yet: where that component runs, as the
+   * architecture places it (ADR 0132). What a knowledge source's scope (sources.yaml appliesTo)
+   * is matched against before the component exists. Optional and additive: version 2 stays.
+   */
+  runsOn: external_exports.strictObject({
+    component: Id,
+    system: Id.optional(),
+    platform: external_exports.string().trim().min(1).optional(),
+    cloud: external_exports.string().trim().min(1).optional(),
+    framework: external_exports.string().trim().min(1).optional()
+  }).optional(),
+  steps: external_exports.array(DeltaStep).default([]),
+  /**
+   * Written by Atticus, never the assistant (ADR 0111): the sha-256 of today's flow's steps (each
+   * step's kind, what, to and store, in order) when this delta was written. A spec drafted again
+   * since then gives another hash, so the merge says the step numbers may be stale.
+   */
+  base: external_exports.strictObject({ steps: external_exports.string().regex(/^[0-9a-f]{64}$/) }).optional()
+});
+var DeployStep = external_exports.strictObject({
+  repo: Id,
+  migration: external_exports.string().trim().min(1).optional(),
+  /** Why it sits where it does, in one plain sentence. */
+  why: external_exports.string().optional()
+});
+var LoopFinding = external_exports.strictObject({
+  /** sha-256 (first 12 hex) of rule, target and evidence. */
+  fingerprint: external_exports.string().regex(/^[0-9a-f]{12}$/),
+  rule: text(),
+  target: text(),
+  /** path:line, metarepo-relative, when there is one. */
+  evidence: external_exports.string().optional(),
+  message: text(),
+  blocking: external_exports.boolean(),
+  /** stage: the stage's own checks; critic: a critic round's finding. */
+  source: external_exports.enum(["stage", "critic"]),
+  /** The iterations it was found in. */
+  seenIn: external_exports.array(external_exports.number().int().positive()),
+  /** The question it became once it came back unchanged twice or flipped. */
+  question: external_exports.string().optional(),
+  /**
+   * decision: a person can decide it (the product, the data, the design), so a repeat or a
+   * flip becomes a question; drafting: the shape of what the assistant wrote, so a repeat or
+   * a flip stops the loop with a message instead (see finding-kind.ts). Left out: decision.
+   */
+  kind: external_exports.enum(["decision", "drafting"]).optional(),
+  /** The iteration a drafting finding stopped the loop in; earlier sightings don't count again. */
+  stoppedAt: external_exports.number().int().positive().optional(),
+  /**
+   * What a judge refused, so a person's answer to the finding's question is stored as their
+   * verdict on exactly that (ADR 0117 addendum, V1): each field and the criterion it was claimed for.
+   */
+  judged: external_exports.array(external_exports.strictObject({ field: text(), criterion: text(), task: text() })).optional(),
+  /**
+   * A critic's risk finding (ADR 0115 addendum, 2026-10-25): it never blocks, and goes back to
+   * the drafter with its fix for one more draft.
+   */
+  risk: external_exports.boolean().optional()
+});
+var StageLoop = external_exports.strictObject({
+  schemaVersion: V,
+  change: Id,
+  stage: Stage,
+  /** Drafts so far. */
+  iteration: external_exports.number().int().min(0),
+  /** stopped: a drafting finding came back and the loop stopped for a person to fix a file. */
+  state: external_exports.enum(["drafting", "waiting", "questions", "stopped", "done"]),
+  updatedAt: external_exports.string(),
+  /** The hand-off run being waited for. */
+  run: external_exports.string().optional(),
+  /** Every finding seen in any iteration, current or not, so a flip is seen. */
+  findings: external_exports.array(LoopFinding).default([]),
+  /** Questions this stage raised, by id. */
+  questions: external_exports.array(external_exports.string()).default([]),
+  /** Answered questions whose answers a draft has read. */
+  read: external_exports.array(external_exports.string()).default([]),
+  /**
+   * Questions held back once and handed to the drafter with an answer on file that may decide
+   * them, by the id they would have had (ADR 0117 addendum, 2026-10-24). One asked again after
+   * that goes to a person. Also the critic's risks handed back for their one draft, as
+   * `risk:<rule>:<file>` (ADR 0115 addendum, 2026-10-25).
+   */
+  handedBack: external_exports.array(external_exports.string()).optional(),
+  /**
+   * An answer that didn't read, copied into the change folder when the loop stopped on it (S5),
+   * change-folder relative: the file the stop tells a person to fix, read back on the next run.
+   */
+  failedAnswer: external_exports.string().optional(),
+  /** A read-again of an answer that isn't YAML, handed off and waited for (S5): no draft spent. */
+  readAgain: external_exports.string().optional(),
+  /**
+   * The stage's source, change-folder relative (ADR 0087 addendum, 2026-10-25): the file or folder
+   * a person edits (feature.yaml, target-flows/, stage/stories-answer.yaml). Every other file
+   * under `written` is rendered from it, so a fix to one of those is refused with a pointer here.
+   */
+  source: external_exports.string().optional(),
+  /**
+   * The questions due that the last stop didn't ask, over the change policy's questionsPerStop
+   * (ADR 0117 addendum, 2026-10-25): their words and evidence, so a person sees what comes next
+   * (`atticus questions list`). They are asked once the open ones are answered.
+   */
+  waiting: external_exports.array(external_exports.strictObject({ question: text(), evidence: external_exports.array(external_exports.string()) })).optional(),
+  /** The critic rounds the loop ran, newest last. */
+  critic: external_exports.array(external_exports.strictObject({ gate: text(), round: external_exports.number().int().positive() })).default([]),
+  /**
+   * What Atticus last wrote, by change-folder path: the sha-256 of each file (ADR 0087 addendum,
+   * 2026-10-24). A file that differs, or one under the stage's source that isn't listed, is a
+   * person's edit: their version is the stage's answer, and it is never drafted over.
+   */
+  written: external_exports.record(external_exports.string(), external_exports.string()).optional(),
+  /**
+   * The drafts that were a person's: the iteration, when, the files they edited and where
+   * Atticus kept a copy of them before writing anything. Who wrote each draft, for provenance.
+   */
+  byPerson: external_exports.array(external_exports.strictObject({
+    iteration: external_exports.number().int().positive(),
+    at: external_exports.string(),
+    files: external_exports.array(external_exports.string()),
+    kept: external_exports.string(),
+    /** checked: their version was checked as the stage's draft; redrafted: the assistant drafted again from it (--force, or with answers). */
+    how: external_exports.enum(["checked", "redrafted"])
+  })).optional(),
+  /**
+   * A draft whose critic round is waiting for its AI lenses, handed off one at a time (ADR
+   * 0115): the round, the draft's run and files, and what the stage's checks and the critic's
+   * rules found in it, which join the lenses' findings once every lens is in.
+   */
+  review: external_exports.strictObject({
+    gate: text(),
+    round: external_exports.number().int().positive(),
+    draft: external_exports.string().optional(),
+    /** person: the draft under review is a person's edit, so a blocking finding stops for them. */
+    by: external_exports.enum(["person"]).optional(),
+    files: external_exports.array(external_exports.string()).default([]),
+    /**
+     * The files the draft's write changed on disk (B-place): a run that resumes the review says
+     * what the draft wrote, not "nothing changed". Optional and additive.
+     */
+    changed: external_exports.array(external_exports.string()).optional(),
+    /**
+     * The questions the draft raised (ADR 0117 addendum, 2026-10-24): the stage's file doesn't
+     * keep them, so they wait here with the draft until its lenses are in, and are raised then.
+     */
+    questions: external_exports.array(QuestionDraft).optional(),
+    issues: external_exports.array(external_exports.strictObject({
+      rule: text(),
+      target: text(),
+      evidence: external_exports.string().optional(),
+      message: text(),
+      blocking: external_exports.boolean(),
+      repo: external_exports.string().optional(),
+      kind: external_exports.enum(["decision", "drafting"]).optional(),
+      // The rest of a stage's issue (loop.ts StageIssue), kept for when the lenses are in:
+      // a judged doubt goes back once, then is asked with its options, citing its line.
+      options: external_exports.array(external_exports.strictObject({ label: text(), means: text(), changes: text() })).optional(),
+      ask: external_exports.string().optional(),
+      holdOnce: external_exports.boolean().optional(),
+      locateText: external_exports.string().optional(),
+      judged: external_exports.array(external_exports.strictObject({ field: text(), criterion: text(), task: text() })).optional(),
+      risk: external_exports.boolean().optional(),
+      // An assistant's proposal waiting on a person (ADR 0115 addendum, 2026-10-25).
+      proposed: external_exports.strictObject({
+        finding: text(),
+        gate: text(),
+        by: text(),
+        reason: external_exports.string().optional()
+      }).optional()
+    })).default([])
+  }).optional()
+});
+
+// packages/planner/dist/stages/waiting.js
+var import_yaml = __toESM(require_dist(), 1);
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+function rerunOf(stage, change) {
+  return stage === "stories" ? `atticus plan stories ${change}` : `atticus change ${stage} ${change}`;
+}
+async function waitingQuestions(root) {
+  const out = [];
+  const changes = (await readdir(changesDirOf(root), { withFileTypes: true }).catch(() => [])).filter((d) => d.isDirectory() && d.name !== "archive").map((d) => d.name).sort();
+  for (const change of changes) {
+    const files = (await readdir(join(changesDirOf(root), change, "stage")).catch(() => [])).filter((f) => f.endsWith(".yaml")).sort();
+    for (const f of files) {
+      let loop;
+      try {
+        const r = StageLoop.safeParse((0, import_yaml.parse)(await readFile(join(changesDirOf(root), change, "stage", f), "utf8")));
+        if (!r.success)
+          continue;
+        loop = r.data;
+      } catch {
+        continue;
+      }
+      for (const w of loop.waiting ?? [])
+        out.push({ change, stage: loop.stage, ...w, rerun: rerunOf(loop.stage, change) });
+    }
+  }
+  return out;
+}
+
+export {
+  STAGE_SCHEMA_VERSION,
+  STAGES,
+  Stage,
+  STAGE_PHASE,
+  Backing,
+  DesignField,
+  DesignAction,
+  DesignScreen,
+  FeaturePlacement,
+  DeltaFields,
+  parseAt,
+  usesOf,
+  parseNewFile,
+  fieldNames,
+  ON_DELETE,
+  StoreKey,
+  DeltaStep,
+  FLOW_DELTA_SCHEMA_VERSION,
+  FlowDelta,
+  DeployStep,
+  LoopFinding,
+  StageLoop,
+  rerunOf,
+  waitingQuestions
+};