@agentsfleet/orly 0.10.12 → 0.10.14

package/AGENTS.md

@@ -85,6 +85,7 @@ Auto-memory is **disabled** (`autoMemoryEnabled: false` + `CLAUDE_CODE_DISABLE_A
 - Other dotfiles (`.zshrc`/`.gitconfig`/etc.): timestamped backup; minimal edits.
 - **Check a sibling repository for an existing pattern in the same language before inventing one.** A shape shipping next door is prior art; a new one needs a reason.
 - **Read the reference implementation before designing.** Where the language's dispatch page names a canonical external source, that read is mandatory in review and its guideline identifiers are cited — applied or diverged from. "Broken for us" means the delta was missed: diff our call site against theirs before blaming the principle.
+- Never publish a Claude Artifact unless asked for one in that session. Answer in the terminal.
 - Before commit/push: `gitleaks` must pass.
 - No new `make` targets without a distinct caller (CI job, spec-mandated gate, or a workflow existing targets can't express) — check `make/*.mk` first; extend over near-duplicate wrappers.
 - `*.zig` → read `dispatch/write_zig.md`; ZIG GATE fires.
@@ -288,17 +289,16 @@ Optimise for one thing: he never has to ask twice.
 - **Halve estimates before voicing.** I pad ~2x reliably.
 - **Draw when shape beats prose.** Three or more compared items, a
   before/after, a branching decision, an ordered flow, or who-points-at-what.
-  One picture, then the words.
+  One picture, then the words. A design decision opens with an ELI15 ASCII flow
+  — plain nouns, what a person does, no `file:line` — then the mechanism.
 - **No slop — chat, docs, code comments alike**. Comments say
   why, depth links out. Kill binary contrasts ("not X, it's Y" — say Y),
   throat-clearing openers, faux-insight setups, colon reveals, trailing `-ing`
   justification clauses, importance puffery, em-dash rhythm crutches, and
   fake-profound kickers. End on the clearest concrete sentence. The banned-word
   list lives in `docs/DOCUMENTATION_RULES.md` §DOC-05, §DOC-07, §DOC-14b, and
-  `orly gate verify` REPORTS it — `docs.language` prints its findings and stays
-  green, because the corpus predates the rule and a red on day one gets switched
-  off by the end of the week. Nobody fails a build over this, so the prose is
-  mine to get right.
+  `orly gate verify` REPORTS it — `docs.language` prints findings and stays
+  green. Nobody fails a build over this, so the prose is mine to get right.
 
 ## Reading Indy
 

package/SOUL.md

@@ -37,17 +37,16 @@ Optimise for one thing: he never has to ask twice.
 - **Halve estimates before voicing.** I pad ~2x reliably.
 - **Draw when shape beats prose.** Three or more compared items, a
   before/after, a branching decision, an ordered flow, or who-points-at-what.
-  One picture, then the words.
+  One picture, then the words. A design decision opens with an ELI15 ASCII flow
+  — plain nouns, what a person does, no `file:line` — then the mechanism.
 - **No slop — chat, docs, code comments alike**. Comments say
   why, depth links out. Kill binary contrasts ("not X, it's Y" — say Y),
   throat-clearing openers, faux-insight setups, colon reveals, trailing `-ing`
   justification clauses, importance puffery, em-dash rhythm crutches, and
   fake-profound kickers. End on the clearest concrete sentence. The banned-word
   list lives in `docs/DOCUMENTATION_RULES.md` §DOC-05, §DOC-07, §DOC-14b, and
-  `orly gate verify` REPORTS it — `docs.language` prints its findings and stays
-  green, because the corpus predates the rule and a red on day one gets switched
-  off by the end of the week. Nobody fails a build over this, so the prose is
-  mine to get right.
+  `orly gate verify` REPORTS it — `docs.language` prints findings and stays
+  green. Nobody fails a build over this, so the prose is mine to get right.
 
 ## Reading Indy
 

package/core/operating-model.md

@@ -85,6 +85,7 @@ Auto-memory is **disabled** (`autoMemoryEnabled: false` + `CLAUDE_CODE_DISABLE_A
 - Other dotfiles (`.zshrc`/`.gitconfig`/etc.): timestamped backup; minimal edits.
 - **Check a sibling repository for an existing pattern in the same language before inventing one.** A shape shipping next door is prior art; a new one needs a reason.
 - **Read the reference implementation before designing.** Where the language's dispatch page names a canonical external source, that read is mandatory in review and its guideline identifiers are cited — applied or diverged from. "Broken for us" means the delta was missed: diff our call site against theirs before blaming the principle.
+- Never publish a Claude Artifact unless asked for one in that session. Answer in the terminal.
 - Before commit/push: `gitleaks` must pass.
 - No new `make` targets without a distinct caller (CI job, spec-mandated gate, or a workflow existing targets can't express) — check `make/*.mk` first; extend over near-duplicate wrappers.
 - `*.zig` → read `dispatch/write_zig.md`; ZIG GATE fires. <!-- oracle-packs:language.zig -->

package/dispatch/lifecycle.md

@@ -258,7 +258,12 @@ and every spec criterion runs against it; skip-pass is only for genuinely
 spec-less branches. A deliberately folded spec retains the exact branch header
 and adds `**Folded-into:** \`M178_001\`` naming the owning spec. Discovery
 validates that relation and gates the sole non-folded owner; two non-folded
-specs on one branch remain a hard error. Mechanical criteria: `spec.moved`
+specs on one branch remain a hard error. **The same relation holds in
+`active/`, from the moment the fold is decided.** A second workstream may sit
+beside an open stream while it names that stream through `Folded-into`, and the
+gates run against the owner — a fold is not a second stream, and it was decided
+when the scope was, not when the spec moved. Extra `active/` specs without the
+header are still the hard error they were: one stream per worktree. Mechanical criteria: `spec.moved`
 (`Status: DONE` ⇒ the spec sits under `done/` and was moved on this branch) · `spec.baseline`
 (`Test Baseline:` recorded) · `spec.ordering` (the branch's first commit
 carries the spec — no code before CHORE(open)) · `spec.deferrals` (a deferral

package/dispatch/write_changelog.md

@@ -40,10 +40,9 @@ a gate skip.
   names, money amounts stay verbatim.
 - **Internal cleanup** gets aggressive trimming, not a paragraph.
 - **History is archived, not rewritten** — past entries are an immutable record.
-- **Rate constants** are pinned by `cross_runtime_rates.rs`, which reads the
-  app and Command-Line Interface (CLI) mirrors against the Rust constant. A
-  changelog money or rate claim must match those, and `rates.mdx` in the docs
-  repository, which no test can reach.
+- **Rate constants** are declared once, in `afd_billing`'s `nanos.rs`, with the
+  nanos denominator in `afd_core::money`. A changelog money or rate claim must
+  match those — and `rates.mdx` in the docs repository, which no test reaches.
 
 ## Required output (self-audit line before committing the changelog)
 

package/docs/CHANGELOG_VOICE.md

@@ -14,5 +14,5 @@ Editing `~/Projects/docs/changelog.mdx` or any other Mintlify `<Update>` block.
 - **Internal cleanup / refactor entries get the most aggressive trimming.** One lead paragraph + one bullet list. Skip "Test coverage" sections unless the test count is the headline. Indy's exact direction: *"Keep internal code cleanup, refactor to a minimal."*
 - **Never drop load-bearing facts.** Error codes (`UZ-AUTH-003`), endpoint paths + method + body shape + status code, env var names + defaults, schema column / table names, CLI subcommand + flag names, migration steps, money amounts. Tighten prose, not meaning.
 - **Historical entries are archives.** Brevity-pass them; never rewrite the past. A typo correction (e.g. `$0.001` → `$0.01` when it was never true) is allowed and must be called out in the commit message.
-- **Rate constants stay pinned across the runtime surfaces, and a test says so.** `rustd/crates/afd_billing/tests/cross_runtime_rates.rs` reads `ui/packages/app/lib/types.ts` and `cli/src/constants/billing.ts` and fails when either drifts from `rustd/crates/afd_billing/src/nanos.rs` — a test beside the constant it defends, not a gate nothing invokes. Public docs are the one surface it cannot reach: when a rate changes, update `~/Projects/docs/snippets/rates.mdx` in a paired Pull Request (PR). In `*.mdx`, import its named values rather than hand-typing money amounts.
+- **Rate constants are declared once, so a money claim has one thing to match.** `rustd/crates/afd_billing/src/nanos.rs` holds the rates and `afd_core::money` holds the nanos denominator; the daemon charges from them and every client renders the figure it was served. A changelog rate or money claim is checked against those constants, never against a client. Public docs are the surface nothing reaches: when a rate changes, update `~/Projects/docs/snippets/rates.mdx` in a paired Pull Request (PR). In `*.mdx`, import its named values rather than hand-typing money amounts.
 - **The Mintlify reference Indy pasted (May 1 / May 8 entries) is canonical voice.** Mirror its rhythm, not its product nouns.

package/docs/RULE_ENFORCEMENT.md

@@ -11,10 +11,10 @@ regenerates this file and fails on any difference. To update it, run
 | `docs/SCHEMA_CONVENTIONS.md` | — | 0 | 0 | 0/16 | mechanical |
 | `docs/DOCUMENTATION_RULES.md` | — | 0 | 0 | 0/22 | latent |
 | `docs/LIFECYCLE_PATTERNS.md` | — | 0 | 0 | 0/22 | mechanical |
-| `docs/CHANGELOG_VOICE.md` | — | 0 | 0 | 0/3 | latent |
+| `docs/CHANGELOG_VOICE.md` | — | 0 | 0 | 0/4 | latent |
 | `docs/VERIFY_TIERS.md` | — | 0 | 0 | 0/4 | uncited |
 | `docs/greptile-learnings/RULES.md` | — | 0 | 0 | 0/114 | mechanical |
-| **corpus** | | | | **30/276** | |
+| **corpus** | | | | **30/277** | |
 
 ## How to read this
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentsfleet/orly",
-  "version": "0.10.12",
+  "version": "0.10.14",
   "description": "Repository-scoped engineering harness: renders agent rules, materialises the gates that enforce them, and proves the PR boundary \u2014 for any coding agent.",
   "license": "MIT",
   "type": "module",

package/src/gates.ts

@@ -39,7 +39,7 @@ export type GateReport = {
 };
 
 export type Override = { criterion: string; reason: string };
-type ClosedSpec = {
+type SpecMetadata = {
   path: string;
   identifier: string | undefined;
   branch: string | undefined;
@@ -105,11 +105,34 @@ export function branchOverrides(root: string): Override[] {
   return overrides;
 }
 
+// One stream per worktree, and a fold is not a second stream. Extra specs in
+// active/ are allowed only when each names the one non-folded owner through
+// Folded-into — the same relation closedSpecPath enforces in done/. Without
+// this, folding a workstream into an open stream was impossible during the
+// work and legal only after the close, which is the wrong way round: the fold
+// is decided when the scope is, not when the spec moves.
 export function activeSpecPath(root: string): string | undefined {
-  const specs = specPathsUnder(root, ACTIVE_DIRECTORY);
+  const specs = specPathsUnder(root, ACTIVE_DIRECTORY).map(specMetadata)
+    .filter((spec): spec is SpecMetadata => spec !== undefined);
   if (specs.length === 0) return undefined;
-  if (specs.length > 1) throw new OrlyError(`more than one active spec — one stream per worktree:${NEWLINE}${specs.join(NEWLINE)}`);
-  return specs[0];
+  return owningSpec(specs, "active spec", "active specs").path;
+}
+
+// The fold relation, shared by both discovery paths: exactly one non-folded
+// owner, every other spec naming it, and no spec naming itself.
+function owningSpec(specs: SpecMetadata[], one: string, many: string): SpecMetadata {
+  const owners = specs.filter((spec) => spec.foldedInto === undefined);
+  if (owners.length === 0) throw new OrlyError(`every ${one} is folded — one owning stream is required:${NEWLINE}${specs.map((spec) => spec.path).join(NEWLINE)}`);
+  if (owners.length > 1) throw new OrlyError(`more than one ${one} — one stream per worktree:${NEWLINE}${owners.map((spec) => spec.path).join(NEWLINE)}`);
+  const owner = owners[0];
+  if (!owner) throw new OrlyError(`${one} ownership could not be resolved`);
+  const folded = specs.filter((spec) => spec.foldedInto !== undefined);
+  if (folded.length > 0 && !owner.identifier) throw new OrlyError(`the owning ${one} has no milestone and workstream identifier: ${owner.path}`);
+  const selfFolds = folded.filter((spec) => spec.identifier === spec.foldedInto);
+  if (selfFolds.length > 0) throw new OrlyError(`folded ${many} cannot fold into themselves:${NEWLINE}${selfFolds.map((spec) => spec.path).join(NEWLINE)}`);
+  const invalidFolds = folded.filter((spec) => spec.foldedInto !== owner.identifier);
+  if (invalidFolds.length > 0) throw new OrlyError(`folded ${many} must name their owner ${owner.identifier}:${NEWLINE}${invalidFolds.map((spec) => spec.path).join(NEWLINE)}`);
+  return owner;
 }
 
 // Closed-spec follow-through: CHORE(close) moves the spec to done/, and the
@@ -120,21 +143,10 @@ export function closedSpecPath(root: string): string | undefined {
   const branch = gitOutput(root, ["rev-parse", "--abbrev-ref", "HEAD"]);
   if (!branch || DEFAULT_BRANCHES.includes(branch)) return undefined;
   const specs = specPathsUnder(root, DONE_DIRECTORY)
-    .map(closedSpec)
-    .filter((spec): spec is ClosedSpec => spec !== undefined && spec.branch === branch);
+    .map(specMetadata)
+    .filter((spec): spec is SpecMetadata => spec !== undefined && spec.branch === branch);
   if (specs.length === 0) return undefined;
-  const owners = specs.filter((spec) => spec.foldedInto === undefined);
-  if (owners.length === 0) throw new OrlyError(`every done/ spec naming branch ${branch} is folded — one owning stream is required:${NEWLINE}${specs.map((spec) => spec.path).join(NEWLINE)}`);
-  if (owners.length > 1) throw new OrlyError(`more than one done/ spec names branch ${branch} — one stream per worktree:${NEWLINE}${owners.map((spec) => spec.path).join(NEWLINE)}`);
-  const owner = owners[0];
-  if (!owner) throw new OrlyError(`done/ spec ownership could not be resolved for branch ${branch}`);
-  const folded = specs.filter((spec) => spec.foldedInto !== undefined);
-  if (folded.length > 0 && !owner.identifier) throw new OrlyError(`the owning done/ spec for branch ${branch} has no milestone and workstream identifier: ${owner.path}`);
-  const selfFolds = folded.filter((spec) => spec.identifier === spec.foldedInto);
-  if (selfFolds.length > 0) throw new OrlyError(`folded done/ specs naming branch ${branch} cannot fold into themselves:${NEWLINE}${selfFolds.map((spec) => spec.path).join(NEWLINE)}`);
-  const invalidFolds = folded.filter((spec) => spec.foldedInto !== owner.identifier);
-  if (invalidFolds.length > 0) throw new OrlyError(`folded done/ specs naming branch ${branch} must name their owner ${owner.identifier}:${NEWLINE}${invalidFolds.map((spec) => spec.path).join(NEWLINE)}`);
-  return owner.path;
+  return owningSpec(specs, `done/ spec naming branch ${branch}`, `done/ specs naming branch ${branch}`).path;
 }
 
 // An in-flight (active/) spec wins; otherwise the branch's closed spec gates.
@@ -145,9 +157,9 @@ export function specPathFor(root: string): { path: string; closed: boolean } | u
   return closed ? { path: closed, closed: true } : undefined;
 }
 
-function closedSpec(path: string): ClosedSpec | undefined {
+function specMetadata(path: string): SpecMetadata | undefined {
   try {
-    const metadata: ClosedSpec = {
+    const metadata: SpecMetadata = {
       path,
       identifier: basename(path).match(SPEC_IDENTIFIER_PATTERN)?.[1],
       branch: undefined,

package/src/gates_spec.test.ts

@@ -38,6 +38,66 @@ describe("spec discovery", () => {
 
     expect(() => activeSpecPath(project)).toThrow("one stream per worktree");
   });
+
+  test("a folded active spec yields ownership to the spec it names", async () => {
+    const project = newSpecRepository();
+    mkdirSync(join(project, "docs/v2/active"), { recursive: true });
+    await Bun.write(
+      join(project, "docs/v2/active/M100_001_P2_CLI_FOLDED.md"),
+      specFixture(undefined, undefined, ["**Folded-into:** `M99_001`"]),
+    );
+
+    expect(activeSpecPath(project)).toEndWith("M99_001_P2_CLI_FIXTURE.md");
+  });
+
+  test("a folded active spec must name the exact owner", async () => {
+    const project = newSpecRepository();
+    mkdirSync(join(project, "docs/v2/active"), { recursive: true });
+    await Bun.write(
+      join(project, "docs/v2/active/M100_001_P2_CLI_FOLDED.md"),
+      specFixture(undefined, undefined, ["**Folded-into:** `M404_001`"]),
+    );
+
+    expect(() => activeSpecPath(project)).toThrow("must name their owner M99_001");
+  });
+
+  test("a folded active spec cannot name itself", async () => {
+    const project = newSpecRepository();
+    mkdirSync(join(project, "docs/v2/active"), { recursive: true });
+    await Bun.write(
+      join(project, "docs/v2/active/M100_001_P2_CLI_FOLDED.md"),
+      specFixture(undefined, undefined, ["**Folded-into:** `M100_001`"]),
+    );
+
+    expect(() => activeSpecPath(project)).toThrow("cannot fold into themselves");
+  });
+
+  test("every active spec folded leaves no owning stream", async () => {
+    const project = newRepository();
+    mkdirSync(join(project, "docs/v2/active"), { recursive: true });
+    await Bun.write(
+      join(project, "docs/v2/active/M100_001_P2_CLI_FOLDED.md"),
+      specFixture(undefined, undefined, ["**Folded-into:** `M99_001`"]),
+    );
+    await Bun.write(
+      join(project, "docs/v2/active/M101_001_P2_CLI_ALSO_FOLDED.md"),
+      specFixture(undefined, undefined, ["**Folded-into:** `M99_001`"]),
+    );
+
+    expect(() => activeSpecPath(project)).toThrow("one owning stream is required");
+  });
+
+  test("a folded active spec still gates through its owner", async () => {
+    const project = newSpecRepository();
+    const model = await modelFor(project);
+    mkdirSync(join(project, "docs/v2/active"), { recursive: true });
+    await Bun.write(
+      join(project, "docs/v2/active/M100_001_P2_CLI_FOLDED.md"),
+      specFixture(undefined, undefined, ["**Folded-into:** `M99_001`"]),
+    );
+
+    expect(runGate(model, project, "work").results.find((result) => result.name === "cmd.conform")?.ok).toBeTrue();
+  });
 });
 
 describe("closed-spec follow-through", () => {