@agentsfleet/orly 0.6.1 → 0.6.3

package/AGENTS.md

@@ -20,7 +20,7 @@ You are this repository's coding agent: deterministic, autonomous, command-line-
 
 MacBook. Languages: Python, Go, Rust, TypeScript, Zig. Tooling: `mise` first, `brew` fallback. Forges: `gh`/`glab`. Commit identity from `git config`, never here.
 
-Dates: `MMM DD, YYYY: HH:MM AM/PM`. Filenames: `{MMM}_{DD}_{HH_MM}`.
+Dates in session notes and log entries: `MMM DD, YYYY: HH:MM AM/PM`. Filenames: `{MMM}_{DD}_{HH_MM}`. Published pages use ISO 8601 (`DOC-23`).
 
 **Banned vocabulary:** "contract" and "phase". Use **Prototype → Milestone → Workstream → Section → Dimension → Batch** for the hierarchy; **Punch List**/**Slices** for finer units; **stages** for lifecycle steps (CHORE(open), PLAN, etc.); **rules** / **operating model** for what AGENTS.md enforces. Real-world commercial agreements keep "contract" only when no clearer term exists — prefer `external commitment` / `vendor agreement`.
 
@@ -28,10 +28,13 @@ Dates: `MMM DD, YYYY: HH:MM AM/PM`. Filenames: `{MMM}_{DD}_{HH_MM}`.
 
 **Pre-send self-checks (invariant).** Before any message or durable artifact: scan `\b[A-Z][A-Z0-9]{1,5}\b` for unexpanded acronyms, and whole-word **`phase`** / **`contract`** for banned vocabulary. Skipping = `ACRONYM CHECK: SKIPPED per user override (reason: ...)` / `BANNED-VOCAB CHECK: SKIPPED per user override (reason: ...)`; reasonable only for a verbatim quote that would be distorted, or a real commercial agreement with no clearer word.
 
+
 **Evidence invariant (pre-send).** Every claim about repository or system state carries its source where the claim is made: `file:line`, the command run and the line of output that decided it, or the `git` / `gh` result. A claim I have not checked opens with `unverified:` and names what would settle it. Numbers name the command that produced them. "The tests pass", "it is merged", "nothing else reads this file", and any count are claims, not context. Skipping = `EVIDENCE CHECK: SKIPPED per user override (reason: ...)`.
 
 **Why it is an invariant, not a preference.** An unchecked claim reads exactly like a checked one. Indy cannot tell them apart, so he either trusts a guess or re-derives the work himself, and both cost more than the check did. When the evidence is not reachable, say which decision is blocked on it rather than filling the hole with a plausible sentence. A wrong fact I stated confidently is the one failure he has no defence against.
 
+**Self-repair boundary (invariant).** An agent repairs a finding unprompted only when the repair has exactly one form and the failure itself names it — a regenerate command, a named set of allowed resolutions, a restore command such as `orly update` for a managed file reported missing. Everything else is reported, not repaired. A finding that turns on what a rule *means*, what a word is worth, or whether the rule is calibrated right is the user's call: report it with the evidence — the finding, its count, the pages it lands on — and stop. Never weaken a rule, add a suppression, or grandfather findings into a baseline to make a check pass; a baseline that excuses existing violations is a list of work pretending to be a gate (patching a harness to silence its hit is already forbidden under Hard Safety — this draws the same line at the finding rather than at the gate). An agent never clears its own gate: it raises findings and repairs the single-form ones, while merging, overriding, and accepting a deferral stay with the user — a worker that both raises and clears its own findings is not gated at all. Detection is always safe and should run continuously; repair is the bounded half. `orly gate`'s `docs.language` criterion is the working shape — it reports a counted finding list and changes nothing.
+
 ## Documentation voice
 
 Published docs and OpenAPI prose read `docs/DOCUMENTATION_RULES.md` first via `write_documentation`.

package/README.md

@@ -129,11 +129,39 @@ Three checkpoints, all running your own declared commands:
 The spec is a file on disk, and **its directory is the status**. Only the stages named in the rules move it.
 
 ```mermaid
-flowchart LR
-    you["🤠 you: add webhook retries"] --> agent["🦉 agent writes the spec"]
-    agent --> pending["docs/v1/pending/"]
-    pending -->|"CHORE(open)"| active["docs/v1/active/"]
-    active -->|"CHORE(close)"| done["docs/v1/done/"]
+flowchart TB
+    you["🤠 you<br/>add webhook retries"]
+    agent["🦉 agent<br/>writes the spec"]
+    pending["📄 docs/v1/pending/<br/><small>spec committed on main</small>"]
+
+    you --> agent
+    agent --> pending
+    pending -->|"CHORE(open)"| plan
+
+    subgraph active["⚙️ docs/v1/active/"]
+        direction TB
+
+        plan["PLAN<br/><small>understand spec · record baseline</small>"]
+        execute["EXECUTE<br/><small>make the change</small>"]
+        conform["CONFORM<br/><small>apply matching rule pages</small>"]
+        verify["VERIFY<br/><small>run deterministic gates</small>"]
+        review["REVIEW<br/><small>review the resulting diff</small>"]
+        document["DOCUMENT<br/><small>update docs / evidence</small>"]
+        commit["COMMIT<br/><small>record the completed unit</small>"]
+
+        plan --> execute
+        execute --> conform
+        conform --> verify
+        verify --> review
+        review --> document
+        document --> commit
+
+        conform -. "gate fails" .-> execute
+        verify -. "gate fails" .-> execute
+        review -. "changes required" .-> execute
+    end
+
+    commit -->|"CHORE(close)"| done["✅ docs/v1/done/<br/><small>all gates green</small>"]
     done --> pr["Pull Request"]
 ```
 
@@ -143,11 +171,19 @@ flowchart LR
 | `docs/v1/active/` | branch cut, baseline recorded, no code until it commits |
 | `docs/v1/done/` | gates green, Pull Request opens |
 
-Inside `active/`, work runs through: **PLAN → EXECUTE → CONFORM → VERIFY → REVIEW → DOCUMENT → COMMIT**.
+Inside `active/`, work runs through the stages: **PLAN → EXECUTE → CONFORM → VERIFY → REVIEW → DOCUMENT → COMMIT**.
 
-Each edit trips the rule page for its file kind. A red gate sends the agent back to EXECUTE. No stage can be skipped quietly.
+The stages are not a status. `active/` is the status. The stages are the loop that runs on the spec sitting there.
 
----
+Three things do three different jobs, and keeping them apart is what makes the lifecycle mechanical:
+
+| | Job |
+|---|---|
+| **Directories** | lifecycle state — where the spec sits |
+| **Stages** | execution machinery — what moves the work |
+| **Gates** | transition authority — whether it may advance |
+
+Each edit activates the rule page for that file kind. A gate proves whether the work may advance, and any red returns the agent to EXECUTE. No stage can be skipped quietly.
 
 ## Your files stay yours
 

package/audits/rule-ledger-lib.sh

@@ -31,6 +31,7 @@ EXCLUDED_DOCS=(
   "docs/DISPATCH_ARCHITECTURE.md"
   "docs/ORLY_ARCHITECTURE.md"
   "docs/TEMPLATE.md"
+  "docs/RELEASE_TEMPLATE.md"
   "docs/EXECUTE_DOC_READS.md"
   "docs/HARNESS_VERIFY_OUTPUT.md"
   "docs/AUTH.md"

package/core/operating-model.md

@@ -15,7 +15,7 @@ You are this repository's coding agent: deterministic, autonomous, command-line-
 
 MacBook. Languages: Python, Go, Rust, TypeScript, Zig. Tooling: `mise` first, `brew` fallback. Forges: `gh`/`glab`. Commit identity from `git config`, never here.
 
-Dates: `MMM DD, YYYY: HH:MM AM/PM`. Filenames: `{MMM}_{DD}_{HH_MM}`.
+Dates in session notes and log entries: `MMM DD, YYYY: HH:MM AM/PM`. Filenames: `{MMM}_{DD}_{HH_MM}`. Published pages use ISO 8601 (`DOC-23`).
 
 **Banned vocabulary:** "contract" and "phase". Use **Prototype → Milestone → Workstream → Section → Dimension → Batch** for the hierarchy; **Punch List**/**Slices** for finer units; **stages** for lifecycle steps (CHORE(open), PLAN, etc.); **rules** / **operating model** for what AGENTS.md enforces. Real-world commercial agreements keep "contract" only when no clearer term exists — prefer `external commitment` / `vendor agreement`.
 
@@ -23,10 +23,13 @@ Dates: `MMM DD, YYYY: HH:MM AM/PM`. Filenames: `{MMM}_{DD}_{HH_MM}`.
 
 **Pre-send self-checks (invariant).** Before any message or durable artifact: scan `\b[A-Z][A-Z0-9]{1,5}\b` for unexpanded acronyms, and whole-word **`phase`** / **`contract`** for banned vocabulary. Skipping = `ACRONYM CHECK: SKIPPED per user override (reason: ...)` / `BANNED-VOCAB CHECK: SKIPPED per user override (reason: ...)`; reasonable only for a verbatim quote that would be distorted, or a real commercial agreement with no clearer word.
 
+<!-- oracle-packs:end -->
+
 **Evidence invariant (pre-send).** Every claim about repository or system state carries its source where the claim is made: `file:line`, the command run and the line of output that decided it, or the `git` / `gh` result. A claim I have not checked opens with `unverified:` and names what would settle it. Numbers name the command that produced them. "The tests pass", "it is merged", "nothing else reads this file", and any count are claims, not context. Skipping = `EVIDENCE CHECK: SKIPPED per user override (reason: ...)`.
 
 **Why it is an invariant, not a preference.** An unchecked claim reads exactly like a checked one. Indy cannot tell them apart, so he either trusts a guess or re-derives the work himself, and both cost more than the check did. When the evidence is not reachable, say which decision is blocked on it rather than filling the hole with a plausible sentence. A wrong fact I stated confidently is the one failure he has no defence against.
-<!-- oracle-packs:end -->
+
+**Self-repair boundary (invariant).** An agent repairs a finding unprompted only when the repair has exactly one form and the failure itself names it — a regenerate command, a named set of allowed resolutions, a restore command such as `orly update` for a managed file reported missing. Everything else is reported, not repaired. A finding that turns on what a rule *means*, what a word is worth, or whether the rule is calibrated right is the user's call: report it with the evidence — the finding, its count, the pages it lands on — and stop. Never weaken a rule, add a suppression, or grandfather findings into a baseline to make a check pass; a baseline that excuses existing violations is a list of work pretending to be a gate (patching a harness to silence its hit is already forbidden under Hard Safety — this draws the same line at the finding rather than at the gate). An agent never clears its own gate: it raises findings and repairs the single-form ones, while merging, overriding, and accepting a deferral stay with the user — a worker that both raises and clears its own findings is not gated at all. Detection is always safe and should run continuously; repair is the bounded half. `orly gate`'s `docs.language` criterion is the working shape — it reports a counted finding list and changes nothing.
 
 ## Documentation voice
 

package/docs/DOCUMENTATION_RULES.md

@@ -164,7 +164,7 @@ not 36 defects. They keep every other rule.
     the retry count and delay, what data is lost, and what survives.
 22. **DOC-22 — Audience boundary.** User pages state guarantees, not internals.
     Operator pages state exact dependencies and versions.
-23. **DOC-23 — Units and time.** Numbers carry units. Dates use ISO 8601. Times
+23. **DOC-23 — Units and time.** Numbers carry units. Dates on a published page use ISO 8601. Times
     use Coordinated Universal Time (UTC).
 24. **DOC-24 — Stable errors.** Every product error has a stable Identifier (ID)
     and an anchor that explains why it happened, how to fix it, and how to
@@ -195,10 +195,11 @@ not 36 defects. They keep every other rule.
 
 ## Enforcement
 
-33. **DOC-33 — Mechanical checks.** Pre-commit checks block banned words,
-    undefined abbreviations, long sentences, long paragraphs, missing front
-    matter, missing or unordered sections, command blocks without output,
-    options without defaults, heading violations, and procedures in tables.
+33. **DOC-33 — Mechanical checks.** `orly gate verify` checks banned words,
+    long sentences, long paragraphs, the em-dash budget, and heading order.
+    Front matter, section order, command blocks without output, options
+    without defaults, and procedures in tables are rules a reader enforces;
+    no check reads them yet. This list names what runs, not what is wished.
 34. **DOC-34 — Review checks.** Review checks one-idea sentences, pronoun
     clarity, resource lifecycle, failure behavior, implementation leaks, and
     meaning preserved by simplification.

package/package.json

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

package/src/config.test.ts

@@ -182,6 +182,33 @@ describe("managedDrift", () => {
     expect(findings[1]).toContain("zzz.md");
     expect(findings[0]).toContain("orly update");
   });
+
+  // The failure this pair exists for: agentsfleet ignored .claude/skills/ while
+  // .oracle/orly.json declared four files under it managed. Every local
+  // checkout passed `orly doctor` because the files sat on disk, and CI failed
+  // against a clone that never received them.
+  test("a managed file git refuses to track is drift, even though it is present", async () => {
+    const root = scratch();
+    Bun.spawnSync(["git", "init"], { cwd: root });
+    mkdirSync(join(root, ".claude/skills/orly-spec-new"), { recursive: true });
+    writeFileSync(join(root, ".claude/skills/orly-spec-new/SKILL.md"), "skill\n");
+    writeFileSync(join(root, ".gitignore"), ".claude/skills/\n");
+    const config = { ...(await seedConfig(root)), managed: [".claude/skills/orly-spec-new/SKILL.md"] };
+    const findings = managedDrift(root, config);
+    expect(findings).toHaveLength(1);
+    expect(findings[0]).toContain("ignored by git");
+    expect(findings[0]).toContain(".claude/skills/orly-spec-new/SKILL.md");
+  });
+
+  test("the same file reports nothing once the ignore is scoped to spare it", async () => {
+    const root = scratch();
+    Bun.spawnSync(["git", "init"], { cwd: root });
+    mkdirSync(join(root, ".claude/skills/orly-spec-new"), { recursive: true });
+    writeFileSync(join(root, ".claude/skills/orly-spec-new/SKILL.md"), "skill\n");
+    writeFileSync(join(root, ".gitignore"), ".claude/skills/*\n!.claude/skills/orly-spec-new/\n");
+    const config = { ...(await seedConfig(root)), managed: [".claude/skills/orly-spec-new/SKILL.md"] };
+    expect(managedDrift(root, config)).toEqual([]);
+  });
 });
 
 describe("writeConfig", () => {

package/src/config.ts

@@ -2,6 +2,7 @@ import { existsSync, mkdirSync, readdirSync, readFileSync } from "node:fs";
 import { dirname, extname, join, relative } from "node:path";
 
 import { assertWritableInside, isObject, isString, JsonObject, objectValue, OrlyError, readJsonObject, RulesModel, stringArray } from "./model";
+import { UNSCOPED_ENVIRONMENT } from "./git_env";
 import { validateCommands, validateSurfaces } from "./validation";
 
 const ORACLE_DIRECTORY = ".oracle";
@@ -117,14 +118,41 @@ export function staleVersion(config: RepoConfig, installedVersion: string): stri
   return `ruleset was installed by orly ${config.orly_version || "an unrecorded version"}, installed engine is ${installedVersion} — run \`orly update\``;
 }
 
-// A managed file that is gone. Edits are not drift: the tree is a git
-// repository, so `git diff` shows a hand edit and shows `orly update` replacing
-// it, both before either is committed.
+const PIPE_OUTPUT = "pipe";
+
+// Which of these paths git refuses to track. `check-ignore` prints one ignored
+// path per line and exits 1 when none match, which is not an error here.
+function ignoredPaths(targetRoot: string, paths: string[]): Set<string> {
+  if (paths.length === 0) return new Set();
+  const result = Bun.spawnSync(["git", "check-ignore", "--", ...paths], {
+    cwd: targetRoot,
+    env: UNSCOPED_ENVIRONMENT,
+    stdout: PIPE_OUTPUT,
+    stderr: PIPE_OUTPUT,
+  });
+  const printed = result.stdout.toString().trim();
+  if (printed.length === 0) return new Set();
+  return new Set(printed.split(/\r?\n/).map((line) => line.trim()).filter(Boolean));
+}
+
+// A managed file that is gone, or one git will not carry. Edits are not drift:
+// the tree is a git repository, so `git diff` shows a hand edit and shows
+// `orly update` replacing it, both before either is committed.
+//
+// An ignored file is drift even though it sits right there on disk. orly wrote
+// it, the local checkout gates on it, and a clone never receives it — so the
+// author passes and everybody else fails, which is the one failure the install
+// record exists to rule out.
 export function managedDrift(targetRoot: string, config: RepoConfig): string[] {
-  return config.managed
-    .filter((relativePath) => !existsSync(join(targetRoot, relativePath)))
-    .map((relativePath) => `managed file is missing: ${relativePath} — run \`orly update\` to restore it`)
-    .sort();
+  const missing = config.managed.filter((relativePath) => !existsSync(join(targetRoot, relativePath)));
+  const present = config.managed.filter((relativePath) => !missing.includes(relativePath));
+  const ignored = ignoredPaths(targetRoot, present);
+  return [
+    ...missing.map((relativePath) => `managed file is missing: ${relativePath} — run \`orly update\` to restore it`),
+    ...present
+      .filter((relativePath) => ignored.has(relativePath))
+      .map((relativePath) => `managed file is ignored by git: ${relativePath} — orly wrote it and a clone will not receive it; scope the .gitignore rule that excludes it`),
+  ].sort();
 }
 
 // Key order is fixed so a rewrite produces a reviewable diff: orly's own two