@geonosis/ledger 1.0.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,387 @@
+# @geonosis/ledger
+
+The tick ledger. It **validates, refuses, and appends one row**. It authors nothing else.
+
+That restraint is the point. The kit survey found Spec Kit writing 2,100 lines of specification for
+600 lines of TypeScript, and this repo's own plans 002–016 were written and never used; the plans
+that shipped were written the day the work happened. So `plan new` writes a skeleton whose one
+criterion is a placeholder that `plan check` **refuses** until a person replaces it, and no command
+here generates a document.
+
+```bash
+npm i -D @geonosis/ledger
+npx geonosis-ledger plan check
+```
+
+Exit codes are the same everywhere: **0** passed · **1** a refusal, with its reason on stdout ·
+**2** the run could not be made at all (bad config, unknown flag), with the reason on stderr.
+
+## `plan check [<file>|<dir>] [--since <NNN>]`
+
+A plan needs three things, and every violation is printed as `<file>: <what is missing>`:
+
+| Refusal | What it means |
+|---|---|
+| `no status header` | nothing in the file matches `plan.statusHeader` |
+| `no "Acceptance criteria" heading` | no heading matches `plan.criteriaHeading` |
+| `no EARS criterion under "Acceptance criteria"` | the heading is there and nothing under it — **under it**, bounded by the next heading of the same depth — matches `plan.criteria` |
+| `no "Verification" heading` | no heading matches `plan.verificationHeading` |
+
+`--since <NNN>` exempts every lower-numbered plan: they print as `<file>: legacy` and hold nothing
+up. A gate that refuses the whole back catalogue on the day it is installed is a gate that gets
+uninstalled.
+
+Only `NNN-slug.md` files are read. A `README.md` in the plans directory is not a plan.
+
+## `plan new <slug>`
+
+Writes `<plans>/<next NNN>-<slug>.md` — twelve lines: the title, the status header, the two
+headings, and two HTML comments. The number is one past the **highest** on disk, never the count,
+because counting reuses a number after a delete. It refuses a slug that is not kebab-case, and a
+slug some existing plan already carries (naming that file).
+
+## `tick --plan <NNN> --commit <hash> --proof <path> [--note "…"]`
+
+The gate. Four refusals, checked in this order, each exit 1 with its reason on stdout:
+
+| Refusal | Why it exists |
+|---|---|
+| `<ref> is not a commit` | a ledger row that names a hash nobody can resolve is a claim |
+| `plan <NNN> does not pass plan check: …` (every violation listed) | a tick against a plan with no criteria has nothing to have satisfied |
+| `no plan <NNN> in <plans>` | the row would point at nothing |
+| `<path> does not exist` | musa's rule and dielime's G3: the proof is the evidence, not the summary |
+| `<hash> ships no runtime code (G0). Its diff: …` | **dielime's G0, returned** (D-025): "a tick MUST deliver real runtime code". Docs, tests and ledger updates may **ride along**; they may never stand alone. The whole diff is printed so the refusal is checkable |
+
+On success it appends **one** row to `ledger.progress` — `| tick | date | plan | commit | proof |
+note |` — creating the file with its header when absent. **That append is the only write it makes,
+and a refused tick makes none at all.** The tick number is one past the highest already in the
+table, never the row count, because counting reuses a number after a delete.
+
+G0 reads `git diff --name-only <hash>~1 <hash>`, which is dielime's own spelling. A root commit has
+no `~1`, so that one case diffs the tree against the empty tree instead — otherwise a repo's first
+commit could never be ticked. This is the only place the kit runs git, and only where it was
+pointed.
+
+## `proof capture <slug> --command "<cmd>" [--url <url>]`
+
+Runs the command in the repo root and writes `<proofs>/<next NNN>-<slug>.md`: the HEAD hash and
+subject, the command, the URL if given, the exit code, and the combined stdout/stderr bounded to
+`ledger.maxLines` (default 200) with `… N more lines` stating what was dropped.
+
+**The process exits with the command's own exit code.** A failing proof is recorded *and* still
+fails; a capture that swallowed the red would be a gate reporting green over a run it had just
+watched break.
+
+## `journal --kind stub|mock|guess|skip --where <path:line> --why "…"`
+
+Appends a dated row to `ledger.journal`. The four kinds are the four ways a delivery is not the
+thing it claims to be, and no kit in the 2026 survey asked an agent to record where it stubbed —
+which is why a stub reads as done in every report after it. An unknown kind is refused (exit 2), as
+is a `--where` without a line number and an empty `--why`. Pipes inside a `why` are escaped, so
+prose cannot break the table.
+
+## `decide --id D-NNN --text "…" --why "…" --evidence "…" --revisit "…" [--status "…"]`
+
+Appends one row to `ledger.decisions`. Values go under the column that **names** them, not under a
+fixed position — during.day's register has no `Status` column and this repo's had no
+`Revisit trigger`, and both are legitimate. A column the flags do not fill gets `—`.
+
+| Refusal | Why |
+|---|---|
+| `a decision needs a revisit trigger …` | **C10.** A register whose entries carry no event that would reopen them is a diary. `PROPOSED` with no stated trigger is a decision nobody ever has to make |
+| `<file> has no "Revisit trigger" column (C10). Its header has to become: <the exact line>` | the tool **prints** the header the register needs and **never writes it**. A tool that rewrites the shape it validates has become the source of truth for that shape |
+| `<file> already carries D-NNN` | ids are unique or the register cannot be cited |
+| `"<id>" is not an id of the form D-NNN` · `<file> does not exist` · `<file> has no table in it` | |
+
+A blank line inside a long register splits the table for a markdown renderer, but the rows after it
+are still the register. `decide` steps over the gap, so a new row lands after the **last** row rather
+than in the hole. (This repo's own register had exactly that gap, at D-039/D-040.)
+
+## `handoff [--dry-run]`
+
+Rewrites the `## SESSION CLOSE` block of `ledger.handoff`, between
+
+```
+<!-- geonosis-ledger:session-close -->  …  <!-- /geonosis-ledger:session-close -->
+```
+
+creating the marked block at the end of the file when the markers are absent, and **leaving
+everything outside them exactly as it was**. The block holds HEAD, uncommitted files, the last tick
+row, the last gate report (`.geonosis/gate-report.json`: tier, ok, finishedAt), and every plan whose
+status is not `DONE`/`SHIPPED`/`CLOSED`/`ABANDONED`.
+
+It is a **pure function of the tree** — no clock, no run id. Two runs over one tree are byte-identical,
+which is a test. The handoff file is excluded from its own uncommitted list: writing the block
+dirties the file, and without that exclusion the second run reports the first run's write.
+
+`--dry-run` prints the block and writes nothing.
+
+## `status [--json]`
+
+The digest: **six lines, always the same six**, whatever the size of the repo behind them — a
+hundred plans and a hundred ticks print six lines. A digest is a perception surface, and an
+unbounded one is the context window it exists to protect. A contract test pins the exact shape.
+
+```
+HEAD      feat(ledger): tick, proof capture and journal
+plans     ACTIVE 2 · DONE 1
+last tick | 1 | 2026-08-30 | 002 | abc12345 | proofs/001-a.md | — |
+gate      full — FAILED at 2026-08-30T10:55:00.000Z
+baseline  6 counter(s)
+journal   0 fallback(s)
+```
+
+Nothing here re-runs or re-judges a gate; it reports what the gate report and the baseline already
+say. A line whose fact is missing says so (`no tick yet`, `no gate report`) rather than disappearing,
+so the shape never moves. The baseline is located from `geonosis.json`'s `ratchet.baseline`, then
+`geonosis.ratchet.json`, then `gate-baseline.json`, and read **as JSON** — the ledger never imports
+the ratchet, so it is never one call from rewriting the number it reports.
+
+## The delivery gates — `commit-msg` and `delivery check`
+
+Two ways a delivery can be nothing while looking like something: the narration outgrows the work,
+and the diff is all comments. Both refuse with exit 1, and **`tick` runs both** on the commit it is
+given.
+
+### `commit-msg <file> | --message "<text>" | --commit <hash>`
+
+Refuses a message longer than `ledger.commitMessageLines` — **default 4: a subject and three body
+lines**. A message that needs a fifth is a delivery that should have been two commits, or a paragraph
+that belongs in a proof file.
+
+What is **not** counted, and why:
+
+| Not counted | Why |
+|---|---|
+| blank lines | they are the format, not the message |
+| lines beginning `#` | a `commit-msg` hook is handed the raw editor file, git's whole `# Please enter…` template included |
+| everything past `# --- >8 ---` | `commit -v` puts the entire diff below the scissors |
+| a **trailing block** of `Token: value` trailers | `Co-authored-by:`, `Signed-off-by:`, `Refs:` are metadata git appends; counting them would ration the body by how much tooling a repo runs |
+
+The trailing block is git's own definition, so a `Note: …` in the *middle* of a body is counted. The
+**subject is never stripped**, even though `feat: a thing` is character-for-character a trailer —
+that bug read every one-line message as empty, and it has a test.
+
+Usable directly as a hook:
+
+```bash
+# .husky/commit-msg  or  lefthook commit-msg
+npx geonosis-ledger commit-msg "$1"
+```
+
+### `delivery check --cached | --commit <hash>`
+
+Refuses a diff whose **every** changed line is a comment or whitespace. Comment tokens are per
+language, chosen by extension — `#` opens a comment in a shell script and a heading in markdown, so
+the token alone cannot decide:
+
+| Extensions | Comment tokens |
+|---|---|
+| `ts tsx js jsx mjs cjs mts cts go rs java kt swift c cc cpp h scss less` | `//` `/*` `*/` `*` `{/*` `*/}` |
+| `css` | `/*` `*/` `*` |
+| `sh bash zsh py rb toml ini cfg conf env properties mk gitignore`, `Dockerfile`, `Makefile` | `#` |
+| `yml yaml` | `#` |
+| `md mdx html xml svg vue svelte astro` | `<!--` `-->` |
+| `sql` | `--` `/*` `*/` `*` |
+
+A blank changed line counts as commentary too, so a whitespace-only change is refused. A file whose
+language is not in the table has its changed lines treated as **code** — the safe direction for a
+gate that refuses.
+
+**Deleting comments counts as a comments-only delivery.** A comment sweep is real work, and it rides
+along with runtime code exactly the way G0 lets docs ride along; it does not stand alone.
+
+### `--prove`
+
+```
+  PROVEN commit-msg: refuses a 40-line commit message
+  PROVEN delivery check: refuses a diff whose every changed line is a comment
+
+prove PASS — every delivery gate refused the thing it forbids.
+```
+
+It plants both forbidden shapes for real — the comments-only diff into a throwaway git repo it
+initialises and deletes — and requires both to be refused. A probe that comes back clean prints
+`CANNOT FAIL` and exits **2**, the same status as a measurement that could not be made: a gate that
+has never been shown refusing is a claim, not a gate.
+
+## `architecture check [--no-workspace]` and `sync` — one table, three spellings (C8)
+
+An allowed-edges table is typically written **three times** in a monorepo's tooling: turbo's
+`boundaries.tags`, per-package `no-restricted-imports`, and `layer-walls`. Three spellings of one
+fact is an SSOT violation inside the enforcement itself. So the table is the source and the three
+configs are generated from it.
+
+`ledger.architecture` must contain a table whose header is `| tag | packages | may depend on |`
+(whitespace- and emphasis-insensitive):
+
+```
+| tag           | packages        | may depend on                   |
+| ------------- | --------------- | ------------------------------- |
+| `domain`      | domains, utils  | —                               |
+| `storage`     | db              | domain                          |
+| `sdk`         | client          | host-worker (TYPE only), domain |
+```
+
+`architecture check` exits 1 listing: a `packages` cell that names no workspace directory (matched
+against the directory, its basename, or the package name — repos write all three), a `may depend on`
+entry that is not a declared tag, and a tag declared twice. `--no-workspace` skips the first of those.
+
+A parenthetical like `(TYPE only)` is a **note**, not a violation: the tag is taken and the
+annotation reported, because none of the three generated spellings can express "type-only" and a
+fact the tooling silently discards is a fact the tooling has decided is untrue.
+
+### `sync --target turbo|layer-walls|restricted-imports [--write <file>] [--check <file>] [--package <name>]`
+
+| Target | Generated | Written into |
+|---|---|---|
+| `turbo` | `{ tags: { <tag>: { dependencies: { allow: [...] } } } }` | the `boundaries` key |
+| `layer-walls` | `[{ name: <tag>, paths: ['^<pkgname>', '<dir>/'], mayImport: [...] }]` | the `layers` of the `biological-architecture/layer-walls` rule |
+| `restricted-imports` | per package, every package its tag may **not** depend on | the `paths` of that package's `no-restricted-imports` rule |
+
+`restricted-imports` is per package, so `--write packages/db/.oxlintrc.json` infers the package from
+the file's directory; `--package` overrides it.
+
+**Nothing is inferred.** If a tag may depend on `storage` and `storage` may depend on `domain`, that
+does *not* make `domain` reachable — the table is spelled in full or it does not say what it says. A
+computed transitive closure would silently widen an edge no author wrote.
+
+`--write` **splices only the named fragment.** `JSON.parse` → `JSON.stringify` would reformat the
+whole file, which turns a one-key sync into an unreviewable diff and a fight with the repo's
+formatter. The value's byte span is located by scanning and replaced in place, so `$schema`, `tasks`,
+and every other rule come out identical. `--check` exits 1 and prints what is committed beside what
+is generated.
+
+A key that is **not there yet is created** — a `turbo.json` with no `boundaries`, a config that has
+never named `layer-walls`, a package whose `no-restricted-imports` has not been written. Still only
+that fragment: everything already in the file stays where it was, and a rule is created as
+`["error", { … }]`, the severity being the one thing a generator cannot read off the table. A repo
+adopting this starts from its own config, not from a shape hand-copied out of these docs.
+
+The adoption evidence is in [`proofs/022-W4-during-day-sync/`](../../proofs/022-W4-during-day-sync/):
+run read-only over a copy of during.day, `architecture check` found a `may depend on` cell naming a
+package instead of a tag, and `sync --target turbo --check` showed a config with five tags against a
+document with seven — sharing one name, `sdk`, which means different things on the two sides.
+
+### `sync --target agents-md|cursor [--write <path>] [--check <path>]` — the law, in the other tools' vocabularies
+
+Skills and `AGENTS.md` port between agents; hooks, subagent definitions and plan pipelines do not.
+These two targets take the half that ports and stop it going stale by hand.
+
+`agents-md` writes the file every agent on the standard reads and Claude Code does not: **the law's
+rules section** (the section matching `ledger.lawSection`, not the whole file — a copy of the law is
+a second law), **one line per skill** taken from that skill's own frontmatter, and **one row per
+glob-scoped rule** saying which files it binds to. Claude Code reads it through the `@AGENTS.md`
+import at the top of `CLAUDE.md`, so the two cannot disagree.
+
+`cursor` writes one `.cursor/rules/geonosis-<area>.mdc` per `.claude/rules/<area>.md`, translating
+the frontmatter: Cursor's `globs` is ONE comma-separated string rather than a YAML list, and a rule
+scoped to `**` becomes `alwaysApply: true` with no `globs` line at all — Cursor ignores `globs` when
+`alwaysApply` is set, and a line that does nothing beside a line that does is how a config starts
+lying.
+
+```bash
+geonosis-ledger sync --target agents-md --write AGENTS.md
+geonosis-ledger sync --target cursor    --write .cursor/rules
+geonosis-ledger sync --target agents-md --check AGENTS.md      # exit 1 on drift
+```
+
+`--write` names the FILE for `agents-md` and the DIRECTORY for `cursor`. `--check` compares byte for
+byte and names what differs — including a generated file that **is not there at all**, which is the
+drift nobody notices: a rule added upstream and never translated reads exactly like one that was.
+
+Neither target reads the architecture table. They are about the law and the rule files, and
+demanding an edges table before generating an `AGENTS.md` would be a coupling nobody asked for.
+
+This repo runs both on itself, checked in `tooling/cross-tool-sync.test.ts`: a generator with a
+round-trip test and no repo behind it proves the function, not the files.
+
+## Configuration — the `ledger` block of `geonosis.json`
+
+Every key is optional and every default is a **contract**, not a consumer's layout.
+
+```jsonc
+{
+  "ledger": {
+    "plans": "plans",                          // directory
+    "progress": "plans/PROGRESS.md",           // the one file a tick appends to
+    "proofs": "proofs",                        // directory
+    "decisions": "docs/decisions.md",
+    "journal": "docs/journal/fallbacks.md",
+    "handoff": "HANDOFF.md",
+    "architecture": "docs/architecture.md",
+    "law": "CLAUDE.md",                        // what lawLineCount counts and sync projects
+    "lawSection": "^#{2,3} +The laws\\b",       // the section of it AGENTS.md carries
+    "agents": "AGENTS.md",                     // where sync --target agents-md writes
+    "skills": ".claude/skills",                // read for the one-line summaries
+    "rules": ".claude/rules",                  // the glob-scoped rules cursor translates
+    "maxLines": 200,                           // captured proof output, bounded
+    "commitMessageLines": 4,                   // subject + 3
+    "plan": {
+      "statusHeader": "^> \\*\\*Status\\*\\*: *\\S+",
+      "criteriaHeading": "^#{2,3} +Acceptance criteria *$",
+      "criteria": "^- When .+ shall .+",
+      "verificationHeading": "^#{2,3} +Verification\\b"
+    },
+    "runtime": { "include": ["…"], "exclude": ["…"] }
+  }
+}
+```
+
+An unknown key is an **error**, not a shrug: a typo in a gate's config is silence.
+
+### The plan patterns are regexes because a heading name is a repo's vocabulary
+
+during.day writes `## Done criteria` and `## Test plan` and ticks a checkbox; this repo writes
+`## Acceptance criteria` and an EARS sentence. Neither is the contract — *declaring* criteria and
+*declaring* how they are verified is. A repo with its own words sets four regexes:
+
+```jsonc
+"plan": {
+  "statusHeader": "^#{2,3} +Status *$",
+  "criteriaHeading": "^#{2,3} +Done criteria *$",
+  "criteria": "^- \\[[ x]\\] .+",
+  "verificationHeading": "^#{2,3} +Test plan\\b"
+}
+```
+
+### `runtime` — G0, generalised
+
+dielime's G0 gate ("a tick MUST deliver real runtime code") greps a staged diff for
+`(apps|packages)/.+/src/`. That anchor is true of dielime and of nothing else: during.day keeps
+1,727 of its 2,295 source files outside any `src/` directory, so it would refuse every tick that
+repo has ever made. What travels is the **kind** of file, so the default is:
+
+```jsonc
+"runtime": {
+  "include": ["\\.(?:ts|tsx|js|jsx|mjs|cjs|mts|cts|css|scss|sass|less|svg|vue|svelte|astro)$"],
+  "exclude": [
+    "\\.(?:test|spec)\\.",
+    "\\.stories\\.",
+    "\\.d\\.ts$",
+    "(?:^|/)(?:__tests__|__mocks__|__fixtures__|__snapshots__|__perf__)/",
+    "(?:^|/)(?:docs?|tests?|e2e)/",
+    "(?:^|/)\\.[^/]+/"
+  ]
+}
+```
+
+The last exclusion is every dot-directory at once — `.dielime/`, `.github/`, `.claude/` — without
+naming any repo.
+
+On top of these, `tick` excludes **the ledger's own artefacts**: everything under `ledger.plans`,
+`progress`, `proofs`, `journal`, `decisions`, `handoff` and `architecture`. dielime's G0 excluded
+`^\.dielime/`, the directory its ledger lived in; that literal cannot ship, but the fact can, because
+every one of those files is already a key of this config and so the exclusion follows a repo wherever
+it keeps them. (Found by running G0 over this repo's history: a `test:` commit whose whole diff was
+three files under `proofs/` passed, on a `.ts` proof harness.)
+
+A repo that wants dielime's exact strictness keeps its own anchor:
+
+```jsonc
+"runtime": { "include": ["(apps|packages)/.+/src/.+\\.(ts|tsx|js|jsx|css|svg)$"] }
+```
+
+## Licence
+
+Apache-2.0.

package/bin/geonosis-ledger.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+// Committed, so `pnpm install` can link the bin on a fresh clone — before `pnpm build` has
+// produced dist/. A bin that only exists after a build is a bin that is missing when you need it.
+import '../dist/ledger-cli.js'