@timiagama/ecr 0.0.1 → 0.1.0

package/examples/docs/0. Orientation/0.0 - System Overview.md

@@ -0,0 +1,34 @@
+# 0.0 - System Overview
+
+A payments platform that ingests merchant settlement files, validates them,
+and processes the resulting payment instructions.
+
+## 0.0#1 - Purpose
+
+This document is the orientation map. It carries no normative rules of its own;
+each domain is governed by its own authority document.
+
+## 0.0#2 - Mental Model
+
+### 0.0#2.1 - The Happy Path
+
+A settlement file arrives, is validated per 3.1, and produces payment
+instructions executed per 4.2.
+
+### 0.0#2.2 - Failure Handling
+
+Every stage runs under the orchestration contract, so retry semantics are
+uniform across the platform — see 8.1#3.
+
+## 0.0#3 - Where To Start
+
+New engineers should read 0.0.1 before anything else. Build and review
+expectations are defined in 0.0.2.
+
+## References
+
+- 0.0.1 - Glossary (dependency - defines the vocabulary used throughout this overview)
+- 0.0.2 - Quality Gates (dependency - the build and review expectations referenced here)
+- 3.1 - Ingestion - Validation Rules (dependency - the validation stage described in this overview)
+- 4.2 - Payment Processing Contract (dependency - the execution stage described in this overview)
+- 8.1 - Workflow Orchestration Contract (authority - governs the runtime behaviour of every stage)

package/examples/docs/0. Orientation/0.0.1 - Glossary.md

@@ -0,0 +1,21 @@
+# 0.0.1 - Glossary
+
+Vocabulary shared across the corpus. Terms defined here are used with this
+meaning everywhere; a document that needs a narrower meaning must say so.
+
+## 0.0.1#1 - Settlement File
+
+A merchant-submitted batch of transactions awaiting reconciliation.
+
+## 0.0.1#2 - Payment Instruction
+
+A single validated, executable transfer derived from a settlement file.
+
+## 0.0.1#3 - Idempotency Key
+
+The value that makes retrying a payment instruction safe. Its derivation is
+defined per 4.2#1.1 and must not be reimplemented elsewhere.
+
+## References
+
+- 4.2 - Payment Processing Contract (contract - defines idempotency key derivation referenced here)

package/examples/docs/0. Orientation/0.0.2 - Quality Gates.md

@@ -0,0 +1,22 @@
+# 0.0.2 – Quality Gates
+
+Build and review expectations. This document uses an en dash in its H1 to
+demonstrate that the separator variant carries no structural meaning.
+
+## 0.0.2#1 - Purpose
+
+To state what "done" means, so that review is a check rather than a negotiation.
+
+## 0.0.2#2 — Test Coverage
+
+Every behavioural change ships with a test in the standing suite. A throwaway
+script is not coverage.
+
+## 0.0.2#3 - Review Order
+
+Implementation and review happen in separate sessions. See 0.0#3 for where this
+sits in onboarding.
+
+## References
+
+- 0.0 - System Overview (dependency - the orientation map that points here)

package/examples/docs/3. Ingestion/3.1 - Ingestion - Validation Rules.md

@@ -0,0 +1,33 @@
+# 3.1 - Ingestion - Validation Rules
+
+Authoritative rules for accepting or rejecting a settlement file. A file that
+fails any rule here never reaches payment processing.
+
+## 3.1#1 - Structural Validation
+
+### 3.1#1.1 - Required Columns
+
+A settlement file must carry merchant identifier, amount, currency and
+transaction reference. Missing columns reject the whole file, not the row.
+
+### 3.1#1.2 - Encoding
+
+Files are UTF-8. A file that fails to decode is rejected without partial
+processing.
+
+## 3.1#2 - Semantic Validation
+
+Amounts must be positive integers in minor units. Currency must be ISO 4217.
+
+## 3.1#3 - Rejection Reporting
+
+This stage is invoked under the orchestration contract, per 8.1.
+
+A rejected file produces one report naming every failed rule. Rejection is not
+retried automatically — retry semantics apply to transient failures only,
+per 8.1#3.
+
+## References
+
+- 0.0.1 - Glossary (dependency - defines settlement file and payment instruction)
+- 8.1 - Workflow Orchestration Contract (constraint - retry semantics that bound this stage)

package/examples/docs/4. Payments/4.10 - Settlement.md

@@ -0,0 +1,22 @@
+# 4.10 — Settlement
+
+Reconciliation of executed payment instructions against merchant expectations.
+This document's DocID shares a prefix with 4.1 in text but is a distinct
+document; identifier matching is by segment, not by string prefix.
+
+## 4.10#1 - Reconciliation Window
+
+Settlement runs daily. An instruction executed after the cut-off settles in the
+next window.
+
+## 4.10#2 - Discrepancies
+
+Settlement runs as an orchestrated stage; see 8.1 for invocation and retry.
+
+A discrepancy halts settlement for that merchant only. Orchestration-level
+retry does not apply — see 8.1#3.2.
+
+## References
+
+- 4.2 - Payment Processing Contract (dependency - the upstream stage that produces settled instructions)
+- 8.1 - Workflow Orchestration Contract (constraint - bounds the retry behaviour excluded here)

package/examples/docs/4. Payments/4.2 - Payment Processing Contract.md

@@ -0,0 +1,33 @@
+# 4.2 - Payment Processing Contract
+
+The contract every payment executor must satisfy. This document defines
+obligations, not implementation.
+
+## 4.2#1 - Idempotency
+
+### 4.2#1.1 - Key Derivation
+
+The idempotency key is the SHA-256 of merchant identifier, transaction
+reference and amount in minor units, joined by U+001F. This derivation is
+normative; see 0.0.1#3 for the term itself.
+
+### 4.2#1.2 - Replay
+
+A repeated instruction carrying a known key returns the original result and
+performs no new transfer.
+
+## 4.2#2 - Ordering
+
+Instructions within a settlement file are independent and may execute in any
+order. Cross-file ordering is not guaranteed.
+
+## 4.2#3 - Settlement Handoff
+
+Completed instructions are handed to settlement per 4.10.
+
+## References
+
+- 0.0.1 - Glossary (dependency - defines the idempotency key term this contract derives)
+- 3.1 - Ingestion - Validation Rules (authority - only validated instructions reach this contract)
+- 4.10 - Settlement (dependency - the downstream stage this contract hands off to)
+- 8.1 - Workflow Orchestration Contract (authority - governs execution and retry of this contract)

package/examples/docs/8. Orchestration/8.1 - Workflow Orchestration Contract.md

@@ -0,0 +1,38 @@
+# 8.1 - Workflow Orchestration Contract
+
+Governs how every stage in the platform runs: invocation, failure
+classification and retry. This document is an authority for the runtime
+behaviour of the stages it governs; it does not define what those stages do.
+
+## 8.1#1 - Stage Invocation
+
+A stage is invoked with a single immutable input and returns a single result.
+Stages do not share mutable state.
+
+## 8.1#2 - Failure Classification
+
+### 8.1#2.1 - Transient Failures
+
+Network timeouts, lock contention and rate limiting. Eligible for retry.
+
+### 8.1#2.2 - Permanent Failures
+
+Validation rejections and contract violations. Never retried; see 3.1#3.
+
+## 8.1#3 - Retry Semantics
+
+### 8.1#3.1 - Backoff
+
+Exponential with full jitter, base 200ms, ceiling 30s.
+
+### 8.1#3.2 - Bounds
+
+At most five attempts. A stage that exhausts its attempts fails permanently and
+is reported, not re-queued. The concrete policy is defined per 8.1.3, and the
+exhausted invocation is routed per 8.10.
+
+## References
+
+- 3.1 - Ingestion - Validation Rules (dependency - the rejection behaviour classified as permanent here)
+- 8.1.3 - Retry Policy (contract - the concrete policy values this contract delegates to)
+- 8.10 - Dead Letter Queue (dependency - where exhausted invocations are routed)

package/examples/docs/8. Orchestration/8.1.3 - Retry Policy.md

@@ -0,0 +1,17 @@
+# 8.1.3 - Retry Policy
+
+Concrete retry values. This document's DocID extends 8.1, and its sections are
+addressed as 8.1.3#N — distinct from 8.1's own sections, which are 8.1#N.
+
+## 8.1.3#1 - Bounds
+
+Maximum five attempts per stage invocation, as required per 8.1#3.2.
+
+## 8.1.3#2 - Backoff Parameters
+
+Base 200ms, ceiling 30s, full jitter. Values are configuration, not contract;
+changing them does not change 8.1.
+
+## References
+
+- 8.1 - Workflow Orchestration Contract (authority - defines the retry semantics these values implement)

package/examples/docs/8. Orchestration/8.10 - Dead Letter Queue.md

@@ -0,0 +1,20 @@
+# 8.10 - Dead Letter Queue
+
+Where permanently failed stage invocations go. Its DocID begins with the same
+characters as 8.1 but is a different document: identifiers compare by segment,
+never by string prefix.
+
+## 8.10#1 - Entry Conditions
+
+A stage invocation enters the queue when it fails permanently, or when it
+exhausts its retry attempts as bounded per 8.1#3.2.
+
+## 8.10#2 - Replay
+
+Replay is manual and produces a fresh idempotency key only when the original
+instruction has been superseded — see 4.2#1.
+
+## References
+
+- 4.2 - Payment Processing Contract (dependency - idempotency behaviour on replay)
+- 8.1 - Workflow Orchestration Contract (authority - defines the failure classification that routes here)

package/examples/docs/README.md

@@ -0,0 +1,7 @@
+# Example Corpus
+
+A small ECR-compliant corpus used as a worked example and as the fixture for
+this repository's navigation-recipe tests.
+
+This file is a meta-document: it carries no DocID and sits outside the reference
+graph. `ecr lint` excludes it by default.

package/package.json

@@ -1,18 +1,76 @@
 {
   "name": "@timiagama/ecr",
-  "version": "0.0.1",
-  "description": "Placeholder. Explicit Constraint Referencing (ECR): a Markdown convention and linter that turns cross-references in architecture documents into a graph agents can navigate with grep. The first release is 0.1.0.",
-  "license": "Apache-2.0",
-  "author": "Timi Agama",
+  "version": "0.1.0",
+  "description": "Explicit Constraint Referencing (ECR): a Markdown convention that helps reduce coding-agent errors by turning cross-references in architecture docs into a graph that agents can navigate with grep. Agents gain IDE-like \"Go to Definition\" and \"Find all references\" across large document corpora, reducing missed constraints and context-window bloat.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "ecr": "./dist/bin.js"
+  },
+  "files": [
+    "dist",
+    "src",
+    "spec",
+    "protocol",
+    "examples",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "keywords": [
+    "markdown",
+    "documentation",
+    "architecture",
+    "coding-agent",
+    "ai-agent",
+    "llm",
+    "context-engineering",
+    "constraint",
+    "linter",
+    "ecr"
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/timiagama/ecr.git"
   },
   "homepage": "https://github.com/timiagama/ecr#readme",
+  "bugs": {
+    "url": "https://github.com/timiagama/ecr/issues"
+  },
+  "author": "Timi Agama",
+  "license": "Apache-2.0",
   "publishConfig": {
     "access": "public"
   },
-  "files": [
-    "README.md"
-  ]
+  "scripts": {
+    "build": "npm run clean && npm run generate:protocol && tsc",
+    "generate:protocol": "node scripts/generate-navigation-protocol.mjs",
+    "test": "vitest run",
+    "lint": "eslint src/ tests/",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.eslint.json",
+    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+    "prepublishOnly": "npm run verify",
+    "verify": "npm run typecheck && npm run lint && npm test && npm run build && node dist/bin.js lint spec/v2 && node dist/bin.js lint docs/engineering && node dist/bin.js lint --example"
+  },
+  "dependencies": {
+    "decode-named-character-reference": "^1.3.0",
+    "micromark-util-decode-numeric-character-reference": "^2.0.2",
+    "remark-parse": "^11.0.0",
+    "unified": "^11.0.5"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.2",
+    "@types/node": "^22.10.0",
+    "@vscode/ripgrep": "^1.18.0",
+    "eslint": "^9.39.2",
+    "eslint-plugin-jsdoc": "^62.5.5",
+    "eslint-plugin-tsdoc": "^0.5.0",
+    "typescript": "~6.0.3",
+    "typescript-eslint": "^8.55.0",
+    "vitest": "^4.0.18"
+  }
 }

package/protocol/navigation-protocol.md

@@ -0,0 +1,223 @@
+# ECR Navigation Protocol for Coding Agents
+
+You are grounding an implementation task against a documentation corpus written
+with **Explicit Constraint Referencing (ECR)**. **Do not load the corpus
+wholesale.** Every architectural document carries a stable numeric identity (a
+*DocID*), every sub-heading carries a *SectionID*, and every document declares its
+external references, each with a type. That structure lets you walk to exactly
+the sections a task depends on, and stop.
+
+Read this once when a task starts, then navigate on demand. Keep the corpus out
+of your context except the sections you are actively using.
+
+## 1 - What the structure gives you
+
+**DocID.** The number in a document's H1:
+
+```
+# 4.2 - Payment Processing Contract
+```
+
+- DocIDs are globally unique and stable. The DocID **is** the document's
+  identity — not its title, not its path.
+- Many corpora also start each filename with its DocID and group documents
+  into folders by first segment (`4. Payments/4.2 - Payment Processing
+  Contract.md`). Where yours does, you can jump to a directory from the number
+  alone — but ECR does not require it, so when the path and the H1 disagree,
+  the H1 is authoritative.
+- DocIDs may be any depth, and one DocID may be a prefix of another. `8.1` and
+  `8.1.3` may both be documents, and `8.10` is a third, unrelated to either.
+  **Compare identifiers by segment, never by string prefix.**
+
+**SectionID.** A DocID, then `#`, then a dot-separated section path:
+
+```
+## 8.1#3 - Retry Semantics
+### 8.1#3.1 - Backoff
+```
+
+`8.1#3.1` is document `8.1`, section 3, sub-section 1. The `#` is what makes the
+identifier unambiguous: everything before it is the document, everything after
+it is the path within that document. A heading at depth *d* carries *d − 1*
+section-path segments.
+
+**SectionID stability.** SectionIDs are identities, not sequence numbers. They need
+not be contiguous or appear in numeric order, so do not renumber existing sections
+merely to remove gaps or reflect document order. Existing SectionIDs remain stable
+when unrelated sections are inserted or reordered. Nested SectionIDs encode their
+parent path, however: moving a subsection under a different parent, or promoting it
+to another heading level, changes its identity and requires affected references to
+be updated. Prefer a top-level SectionID for a consumer reference when it expresses
+the required constraint precisely enough; use a subsection address when the narrower
+rule is what the consumer actually depends on.
+
+**References.** Every ECR document carries a `## References` section
+declaring its typed, document-level references. Read it before acting on the
+document. References entries cite documents, never sections.
+
+**Inline references.** `see X` and `per X` point into another document, either
+at a whole document (`see 8.1`) or at a precise section (`per 8.1#3.2`). They
+may be capitalised at the start of a sentence, so match `[Ss]ee` and `[Pp]er`.
+
+**Meta-documents.** Repository-level instruction and orientation files such as
+`README`, `CLAUDE.md`, `AGENTS.md`, contributing guides and changelogs may sit
+outside the reference graph and therefore carry no DocID. Do not assume every
+Markdown file in or near a corpus is an ECR document.
+
+## 2 - How to find things
+
+Patterns are ripgrep. Escape the dots in an identifier. If `rg` is not
+installed, GNU grep takes the same patterns: use `grep -rnE` for `rg --no-ignore -n`,
+`grep -rlE` for `rg --no-ignore -l`, and `grep -rnP` for `rg --no-ignore -P -n`.
+
+`--no-ignore` makes ripgrep also search files listed in `.gitignore`, `.ignore`
+and `.rgignore`, which the CLI validates. Without it, a valid document can be
+invisible to your search.
+
+These searches do not follow symbolic links or junctions inside the corpus, and
+the `ecr` CLI does not validate what is behind them. A corpus directory named on
+the command line is followed even when it is itself a link, by the searches and
+the CLI alike.
+
+**Open the document for a DocID.**
+
+```bash
+rg --no-ignore -l "^# 8\.1[^0-9.#]" docs      # the H1 for 8.1, not 8.10 or 8.1.3
+```
+
+**Resolve a SectionID** — jump straight to the heading:
+
+```bash
+rg --no-ignore -n "^#+ 8\.1#3\.1([^0-9]|$)" docs
+```
+
+**Read a document's declared references (forward edges):**
+
+```bash
+rg -n -A 40 "^## References" "docs/8. Orchestration/8.1 - Workflow Orchestration Contract.md"
+```
+
+**Find who relies on a document, or on one specific section (reverse edges).**
+Nothing precomputes this — grep the citations. Run this *before editing a
+section* to see exactly who leans on that spot.
+
+| Question | Pattern |
+|---|---|
+| Who references document `8.1`? | `rg --no-ignore -n "(\b\|_)([Ss]ee\|[Pp]er) 8\.1(\.[^0-9A-Za-z.#]\|\.$\|[^0-9A-Za-z.#]\|$)" docs` |
+| Who references any section of `8.1`? | `rg --no-ignore -n "(\b\|_)([Ss]ee\|[Pp]er) 8\.1#" docs` |
+| Who references section `8.1#3` or below? | `rg --no-ignore -n "(\b\|_)([Ss]ee\|[Pp]er) 8\.1#3([^0-9A-Za-z#]\|$)" docs` |
+| Either the document or any section? | `rg --no-ignore -n "(\b\|_)([Ss]ee\|[Pp]er) 8\.1(#[0-9.]*\|\.[^0-9A-Za-z.#]\|\.$\|[^0-9A-Za-z.#]\|$)" docs` |
+| Every section-precise reference in the corpus | `rg --no-ignore -n "(\b\|_)([Ss]ee\|[Pp]er) [0-9.]+#" docs` |
+| References-section entries citing `8.1` | `rg --no-ignore -n "^\s*([-*+]|[0-9]+[.)])\s*\[?8\.1[^0-9.#]" docs` |
+
+These patterns bound a citation explicitly, because `\b` alone fails at both
+ends. It cannot terminate a dotted identifier: `.` and `#` are both non-word
+characters, so `8\.1\b` matches inside `8.1.3`, `8.1#3` and `8.1.3#1`. And `_`
+is a word character, so `\b` finds nothing before the keyword in `_see 8.1_`,
+which is ordinary Markdown emphasis. So the keyword follows `(\b|_)` — a word
+boundary or an underscore — and the identifier is followed by anything but an
+ASCII letter or digit. After a bare DocID, `#` is refused too, and so is `.`
+unless it ends a sentence (the `\.[^0-9A-Za-z.#]` / `\.$` alternatives), so that
+`see 8.1.` matches while `see 8.1.3` does not.
+
+Where ripgrep is built with PCRE2, `-P` allows the clearer form:
+
+```bash
+rg --no-ignore -P -n "(?<![0-9A-Za-z])([Ss]ee|[Pp]er) 8\.1(?![0-9A-Za-z#])(?!\.[0-9A-Za-z.#])" docs
+```
+
+**Find everything a document governs.** This is the high-value query that
+similarity search cannot answer — a generic contract governing many specific
+documents that don't resemble it textually:
+
+```bash
+rg --no-ignore -ln "^\s*([-*+]|[0-9]+[.)])\s*\[?8\.1[^0-9.#].*\(authority" docs
+```
+
+Swap `authority` for `constraint` / `contract` / `dependency` to pull the other
+edge types.
+
+**Map the whole corpus, one line per document:**
+
+```bash
+rg --no-ignore -n "^# [0-9]" docs
+```
+
+**Find the document owning a concept by name** — the fallback when you have no
+ID to follow:
+
+```bash
+rg --no-ignore -li "idempotency key" docs
+```
+
+## 3 - What each reference obligates you to do
+
+A References entry reads `{DocID} - {Title} ({direction} - {explanation})`. The
+edge points **from this document to the cited one**. The middle column is what
+ECR defines; the right-hand column is how to act on it, which ECR does not
+define:
+
+| Direction | Meaning (ECR) | Agent action (recommended) |
+|---|---|---|
+| **authority** | the cited document governs this one | Read it first. Treat it as the governing source. Flag apparent conflicts. |
+| **constraint** | the cited document restricts this one | Check your change does not violate it. |
+| **contract** | the cited document defines obligations or interfaces | Conform exactly — schemas, field names, typed outputs. |
+| **dependency** | this document consumes the cited one | Read it to use it correctly. |
+
+The `{explanation}` says *why* the edge exists. Use it to judge whether an edge
+is relevant to your current change before you open the target.
+
+**Precedence.** ECR does not define one. It records that a document governs
+another; it does not say what to do when two governing documents disagree,
+because resolving that requires reading what the constraints mean, which is
+outside what ECR claims. Authority is therefore domain-scoped rather than a
+ranking: each authority document governs its own domain and none outranks
+another.
+
+So when two authorities appear to conflict, surface it rather than picking a
+winner. If the corpus declares its own precedence hierarchy, it does so in a map
+document of its own — follow that. If it does not, say so and ask.
+
+## 4 - Grounding protocol
+
+For any implementation task:
+
+1. **Orient.** Identify the DocID(s) the task touches.
+2. **Open the primary document** by its DocID.
+3. **Read its `## References` before writing code.** Open every `authority` and
+   `constraint` it cites; treat `contract` entries as obligations to satisfy;
+   read `dependency` entries you will consume. Use the `{explanation}` to skip
+   edges irrelevant to your change.
+4. **Follow inline `see`/`per` to the exact SectionID named** — open that one
+   section, not the whole document.
+5. **Before finishing, reverse-check at section granularity.** Grep backlinks to
+   the section you changed using the reverse-lookup patterns above. This is the step that surfaces the documents
+   relying on what you changed — the ones your target never mentions, and the
+   ones a change can silently break, because nothing in the file you are
+   reading points at them.
+6. **Load only what you need.** Pull sections, not the corpus. A few extra reads
+   of the right slice beat one read of everything.
+7. **On ambiguity, defer** to the domain authority rather than guessing.
+
+## 5 - Gotchas
+
+- **Match numbers, not dashes.** Separators appear as hyphen `-`, en dash `–`
+  and em dash `—`, sometimes mixed within one line. Never anchor a pattern on a
+  dash.
+- **Never match an identifier by string prefix.** `8.1` is not a prefix of
+  `8.10` in identifier terms, and `8.1.3` is a different document from section
+  `8.1#3`. Use the lookup patterns in this protocol rather than improvising.
+- **`see` and `per` may be capitalised.** A pattern matching only lowercase
+  silently under-reports backlinks, which is the one failure this protocol
+  exists to prevent.
+- **A bare number in prose is not an edge.** Only `see`/`per` inline references
+  and `## References` entries are load-bearing. But opening a document is cheap —
+  when unsure, look.
+- **Every reference is found, but not every hit is a reference.** In a corpus
+  that passes the linter, these patterns find every reference it recognises.
+  They can also match text it does not: `per 60**s**` reads as `per 60s`, which
+  is prose, yet the pattern for `60` matches it. Read the line before treating
+  a hit as an edge.
+- **Corpora drift.** A document may deviate from the convention. If a recipe
+  returns nothing, loosen it — drop the anchor, search by title text — before
+  concluding the target does not exist.