@dsalazardev/ai-hub-cli 0.0.0-stage → 0.1.0

package/skills/shared/decision-records/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: decision-records
+description: "Use when a hard-to-reverse choice (database, framework, vendor, auth model) must be frozen as an immutable numbered ADR — the context that forced it, the options weighed, the decision, consequences both ways — or superseded without erasing history. NOT a meeting recap (that is meeting-notes), NOT standing project principles (that is constitution)."
+tags: [decision-records, adr, architecture-decisions, rationale, decision-log, madr, knowledge-ops]
+recommends: [meeting-notes, constitution, sop-builder, knowledge-ops, codebase-onboarding, plan, specify]
+origin: ai-hub
+---
+
+# Decision Records — Freeze the Why Before It Evaporates
+
+*A consequential choice got made. Capture it as one short, immutable, numbered ADR: the context that forced it, the real options weighed, the decision, and what it costs you both ways. Six months from now this file is the only thing standing between you and re-litigating the whole thing.*
+
+You own the **durable single-decision artifact** — an Architecture/Any Decision Record (ADR). Not a meeting recap, not a runbook, not a spec. One bounded choice, recorded so the reasoning survives the people who made it.
+
+## The one test: is this even ADR-worthy?
+
+Write an ADR **iff** the choice is *costly to reverse* **OR** *future-you will ask "why did we do it this way"*. Everything else is noise — an ADR for a trivial reversible tweak is just paperwork, and ADRs lose all their value the moment they become forced ceremony (this is the consistent message from Fowler and the AWS Architecture Blog).
+
+| Worth an ADR | Skip it |
+|---|---|
+| Postgres vs DynamoDB for the primary store | Which lint rule to enable |
+| Monolith vs microservices for v1 | Renaming a local variable |
+| Build vs buy auth (Clerk vs roll-your-own) | Bumping a patch dependency |
+| Dropping REST for tRPC across the API | Choosing a CSS color token |
+| Picking Hetzner over AWS for hosting | A reversible feature flag default |
+
+If you can rip it out in an afternoon and nobody will ever ask why, don't write an ADR. Decide, move on.
+
+## Decide home + naming once
+
+Pick a storage convention *before* the first record, and never spawn a competing second log. Default to the project's existing convention if one exists.
+
+| Naming school | Looks like | Use when |
+|---|---|---|
+| Numeric-prefix (adr-tools / MADR) | `0007-choose-postgres.md` | You need stable IDs to cross-reference for supersession — **the default** |
+| Imperative verb-noun | `choose-database.md` | Tiny log, no supersession expected, humans browse by topic |
+
+Prefer **numeric-prefix**: `NNNN-title-with-dashes.md`. Stable IDs are what make "Superseded by ADR-0012" mean something.
+
+**Where to store** (first match wins):
+1. The project's existing convention — never invent a parallel log.
+2. A code repo with no convention: `docs/adr/` (also seen as `doc/adr/`).
+3. A harness workspace: `02-DOCS/wiki/decisions/`, indexed in `02-DOCS/wiki/index.md` (the Knowledge map; root `CLAUDE.md` keeps only a short pointer).
+
+```text
+Bad:  decision-final-v2-REAL.md          # no ID, no order, will rot
+Bad:  notes/adr/db.md                     # buried, not in the log
+Good: docs/adr/0007-choose-postgres.md    # stable ID, sorts, cross-referencable
+```
+
+Seed the **index** the moment you create the first ADR — a README row or `0000-index.md` listing id, title, status, date. An ADR that isn't in the index is an orphan nobody will find.
+
+## The record spine
+
+Map every ADR to the **MADR 4.0.0 template** (released 2024-09-17 — the current version). MADR ships full and minimal variants; use minimal until a section earns its place.
+
+Required spine, in order: **Title → Status → Date → Context and Problem Statement → Decision Drivers → Considered Options → Decision Outcome → Consequences**. The MADR-optional sections (Confirmation, Pros and Cons of the Options, More Information) you add only when they pull weight.
+
+Minimal skeleton — this is enough for most decisions. When the ADR lives in a harness
+workspace (`02-DOCS/wiki/decisions/`), it is part of an OKF v0.1 bundle, so it opens with YAML
+frontmatter carrying a non-empty `type: decision` (plus the OKF-recommended `title`/`tags`/
+`timestamp`). The body keeps the human-readable `- Status:`/`- Date:` lines verbatim — they are
+the decision's domain record and `scripts/verify.sh` reads them, so the frontmatter is purely
+additive. Cross-references use standard markdown links, never wikilinks. (In a plain code repo
+under `docs/adr/`, the frontmatter is optional — OKF conformance only governs the wiki bundle.)
+
+```markdown
+---
+type: decision
+title: "Choose Postgres over DynamoDB for the primary store"
+tags: [adr, database, billing]
+timestamp: 2026-06-02T00:00:00Z
+---
+
+# 7. Choose Postgres over DynamoDB for the primary store
+
+- Status: accepted
+- Date: 2026-06-02
+- Deciders: @alice, @bob
+
+## Context and Problem Statement
+
+We need a primary datastore for the billing service. Relational
+invoicing data, ~2k writes/min, team of 3 with deep SQL experience,
+EU data-residency required. Which store do we adopt?
+
+## Decision Drivers
+
+- Strong relational integrity for invoices (foreign keys, transactions)
+- Team SQL fluency; near-zero NoSQL operational experience
+- EU residency + self-host option (constitution §data-residency)
+
+## Considered Options
+
+- Postgres (managed, EU region)
+- DynamoDB
+- MongoDB Atlas
+
+## Decision Outcome
+
+Chosen: **Postgres**, because it matches the relational shape of the
+data and the team's existing fluency, with the lowest operational risk.
+
+## Consequences
+
+- Good: ACID transactions, mature tooling, team productive day one.
+- Bad: we own connection-pool and vertical-scaling concerns earlier.
+- Follow-up: provision read replica before launch (ADR-0009 tracks scaling).
+```
+
+Keep it to **1–2 pages, readable in 5–10 minutes**. If a record sprawls, you're probably bundling two decisions — split them. The full annotated MADR full+minimal templates and a worked example live in [`references/templates.md`](references/templates.md).
+
+## Write context that forces the decision
+
+The context section must make the decision feel *inevitable*. State the problem and the constraints — **not the solution**.
+
+- **State the problem, not the answer.** "We need to pick a store" not "We should use Postgres." The verdict belongs in Decision Outcome.
+- **Quantify.** "~2k writes/min", "team of 3", "EU residency", "p99 < 100ms". Numbers are what let future readers judge if your constraints still hold.
+- **Cite the driver.** If a constitution principle or a spec/plan fork forced this, link it. An ADR is often downstream of [`constitution`](../constitution/SKILL.md) and cites it as a driver.
+
+```markdown
+Bad context:  "We decided to use Postgres because it's reliable."
+              (conclusion smuggled in, no constraints, unfalsifiable)
+
+Good context: "Billing needs relational integrity for invoices,
+              ~2k writes/min, a 3-person team with SQL but no NoSQL
+              ops experience, and EU data residency (constitution
+              §data-residency). Which primary store do we adopt?"
+```
+
+## Options must be real and comparable
+
+The rejected options are the *asset* — they're the proof you thought, and they stop the next person re-proposing them.
+
+- **List ≥2 genuine options.** A single foregone "option" is theatre. If there was really only one path, you don't need an ADR.
+- **Score each against the *same* drivers.** Apples to apples, or the comparison is meaningless.
+- **Record why each loser lost.** That sentence is worth more than the winner's praise.
+
+```markdown
+| Option    | Relational integrity | Team fluency | EU self-host | Op. risk |
+|-----------|----------------------|--------------|--------------|----------|
+| Postgres  | native               | high         | yes          | low      |
+| DynamoDB  | app-enforced         | none         | no (AWS)     | high     |
+| Mongo     | partial              | medium       | yes          | medium   |
+```
+
+## Consequences, both directions
+
+A one-sided ADR is marketing, and marketing erodes the trust that makes the log worth reading. Record:
+
+- **What improves** — the upside you bought.
+- **What degrades** — the price you paid, honestly.
+- **New work / risk it creates** — what you now own that you didn't before.
+- **Follow-ups** — concrete tasks, ideally linked to a tracker or a future ADR.
+
+If you can't name a single downside, you haven't finished thinking. Every real choice has a cost.
+
+## Status lifecycle + immutability
+
+An accepted or rejected ADR is **immutable**. You never edit the decision — you write a *new* ADR that supersedes it and flip the old one's status. This is the whole point: history stays intact.
+
+| Status | Meaning | Next |
+|---|---|---|
+| `proposed` | drafted, under review | → accepted or rejected |
+| `accepted` | adopted, in force | → deprecated or superseded |
+| `rejected` | considered and declined | terminal (kept for the record) |
+| `deprecated` | no longer relevant, not replaced | terminal |
+| `superseded by ADR-NNNN` | replaced by a newer decision | terminal, back-linked |
+
+The supersession ritual (never skip a step):
+
+1. Write the new ADR (e.g. `0012-adopt-trpc.md`), status `accepted`, with a "Supersedes ADR-0004" note in its context.
+2. Edit **only the status line** of the old ADR (`0004`) to `superseded by ADR-0012`. Leave its decision and rationale untouched.
+3. Back-link both ways so a reader landing on either finds the other.
+
+Never delete an ADR and never rewrite its decision — a wrong-in-hindsight ADR is still true history. A worked supersession pair is in [`references/templates.md`](references/templates.md).
+
+## Maintain the log
+
+A decision log is only useful if it stays navigable.
+
+- **Index every ADR at creation.** One row: `| 0007 | Choose Postgres | accepted | 2026-06-02 |`. No orphans.
+- **Keep supersession links live** in both directions.
+- **Review cadence.** Periodically sweep `accepted` ADRs — anything reality has overtaken gets a superseding record, not a silent edit.
+- **Index the log from the entry point** — `02-DOCS/wiki/index.md` — so onboarding finds it. The broader wiki and onboarding doc belong to [`knowledge-ops`](../knowledge-ops/SKILL.md) and [`codebase-onboarding`](../codebase-onboarding/SKILL.md); this skill owns only the ADRs the wiki links to. The meeting that spawned a decision routes to [`meeting-notes`](../meeting-notes/SKILL.md); the repeatable how-to it implies routes to [`sop-builder`](../sop-builder/SKILL.md).
+
+## Anti-patterns
+
+| Anti-pattern | Why it's wrong | Do instead |
+|---|---|---|
+| Editing an accepted ADR's decision in place | Destroys history; future readers can't see the path | Supersede with a new ADR, flip old status |
+| Single foregone "option" | No real comparison; theatre, not a record | List ≥2 genuine options or skip the ADR |
+| No consequences (or only upside) | One-sided ADR is marketing; erodes trust | Record gains, costs, new work, follow-ups |
+| Novella-length ADR | Nobody reads 8 pages; signal drowns | 1–2 pages; split bundled decisions |
+| ADR for a trivial reversible choice | Forced paperwork; kills the practice | Apply the one test first |
+| Re-deciding what the constitution settled | Duplicates the standing ruleset, causes drift | Cite the constitution as a driver instead |
+| Orphan ADR not in the index | Invisible; nobody finds it | Add the index row at creation |
+| Context that states the answer | Decision smuggled in, unfalsifiable | Problem + constraints only; verdict in Outcome |
+
+## Verify
+
+Lint a produced ADR (or a whole decisions dir) with `scripts/verify.sh <path>`: it checks for a recognized status, a date, the required sections, ≥2 options, and a valid filename — read-only, no network. It expects the skeletons above.

package/skills/shared/decision-records/evals/README.md

@@ -0,0 +1,3 @@
+# Evals — decision-records
+
+These cases are routing prompts plus one capability rubric; there is no automated runner here. To evaluate, read `cases.yaml` and judge by hand (or with an LLM grader): for each `should_trigger` prompt, confirm a router would reach for `decision-records`; for each `should_not_trigger`, confirm it routes to the named sibling instead and not here. For the `capability` case, have the model produce the ADR end to end and check it against every bullet in `must_include` — a numbered/dated file, problem-framed context, ≥2 compared options, an explicit decision, two-directional consequences, an index row, and correct supersession if a prior decision is replaced. A produced ADR file can additionally be linted mechanically with `../scripts/verify.sh <path-to-adr.md | decisions-dir>`, which checks status, date, required sections, ≥2 options, and filename convention.

package/skills/shared/decision-records/evals/cases.yaml

@@ -0,0 +1,43 @@
+skill: decision-records
+
+should_trigger:
+  - prompt: "We just picked Postgres over DynamoDB — write it up so we don't argue about it again."
+    why: "Classic ADR: a consequential, hard-to-reverse store choice that needs its rationale and alternatives frozen."
+  - prompt: "Freeze the rationale for choosing Remix instead of Next before everyone forgets why we did it."
+    why: Non-obvious phrasing ("freeze the rationale", "before everyone forgets") for the durable why-capture this skill owns.
+  - prompt: "We're dropping REST for tRPC; record the change but keep the old decision in history."
+    why: Supersession path — new ADR plus immutable old one, the core lifecycle this skill enforces.
+  - prompt: "Documenta por qué elegimos Hetzner y qué alternativas descartamos, con sus pros y contras."
+    why: Spanish phrasing asking for decision + rejected options with pros/cons — exactly the ADR structure.
+  - prompt: "Every new hire re-asks why we use a monorepo; capture the decision once with the trade-offs."
+    why: Onboarding re-litigation of a settled choice; the cure is a single durable record, not a wiki page.
+  - prompt: "Registra la decisió d'usar Clerk en comptes de muntar auth nosaltres, amb les opcions que vam valorar."
+    why: Catalan build-vs-buy auth decision with weighed options — a bounded, costly-to-reverse choice.
+
+should_not_trigger:
+  - prompt: "Summarize today's architecture call and list the action items with owners and due dates."
+    route_to: meeting-notes
+    why: A point-in-time session recap with tasks/owners, not a durable single-decision artifact.
+  - prompt: "Write a step-by-step procedure for how we cut a release."
+    route_to: sop-builder
+    why: A repeatable how-to-every-time process, not a one-time why-we-chose-X record.
+  - prompt: "Define our project-wide coding standards and the canonical stack everyone must use."
+    route_to: constitution
+    why: Standing non-negotiable principles run once and amended, not one bounded decision.
+  - prompt: "Write the implementation plan for the new billing feature."
+    route_to: plan
+    why: Describes how to build the thing, not the decision behind a fork.
+  - prompt: "Draft the feature spec for the new export tool with user stories."
+    route_to: specify
+    why: Defines what to build, not the rationale for a settled architectural choice.
+
+capability:
+  - scenario: "Choosing between Stripe and Lemon Squeezy for billing. Team of 2, EU customers, need invoicing and EU VAT handling. Produce the decision record and wire it into the log."
+    must_include:
+      - A numbered, dated ADR file (e.g. docs/adr/0003-choose-billing-provider.md) with a recognized status (proposed/accepted/...).
+      - Context stated as problem + constraints (team of 2, EU customers, invoicing, VAT), not the answer.
+      - At least 2 real options (Stripe, Lemon Squeezy) scored against the same drivers with pros/cons.
+      - An explicit Decision Outcome naming the chosen option and the dominant driver.
+      - Consequences in both directions — gains plus costs/risks/follow-ups, not only upside.
+      - An index/log row added for the new ADR (id, title, status, date).
+      - If a prior billing decision is being replaced, correct supersession (new ADR + old status flipped to "superseded by", back-linked) rather than an in-place edit.

package/skills/shared/decision-records/references/templates.md

@@ -0,0 +1,252 @@
+# ADR templates, conventions & worked examples
+
+Templates track **MADR 4.0.0** (released 2024-09-17, the current version — see https://adr.github.io/madr/). Use the **minimal** template until a section earns its place; reach for the **full** template only when the decision is genuinely contested or far-reaching.
+
+## Naming & index convention
+
+Filenames: `NNNN-title-with-dashes.md` where `NNNN` is a zero-padded sequential id (`0001`, `0002`, …). Stable ids are what make supersession back-links durable.
+
+Store under one log only — `docs/adr/` (code repo) or `02-DOCS/wiki/decisions/` (harness workspace). Maintain an index as `docs/adr/README.md` or `0000-index.md`:
+
+When the log lives in `02-DOCS/wiki/decisions/`, each ADR is a document in an OKF v0.1 bundle, so it opens with YAML frontmatter carrying a non-empty `type: decision` (plus the OKF-recommended `title`/`tags`/`timestamp`). The MADR body — `- Status:`, `- Date:`, the sections — is kept exactly as below; the frontmatter is additive and `verify.sh` keeps reading the body lines. The index file (`0000-index.md` / `README.md`) is the OKF reserved directory listing and carries **no frontmatter**. All cross-references are standard markdown links, never wikilinks. In a plain `docs/adr/` code repo the frontmatter is optional — OKF conformance governs only the wiki bundle. The OKF frontmatter block to prepend (shown once; the templates below omit it for brevity):
+
+```yaml
+---
+type: decision
+title: "<short decision title>"
+tags: [adr]
+timestamp: YYYY-MM-DDTHH:MM:SSZ
+---
+```
+
+```markdown
+# Decision Log
+
+| ID   | Title                                  | Status                 | Date       |
+|------|----------------------------------------|------------------------|------------|
+| 0004 | Adopt REST for the public API          | superseded by ADR-0012 | 2025-11-03 |
+| 0007 | Choose Postgres over DynamoDB          | accepted               | 2026-06-02 |
+| 0012 | Adopt tRPC for internal API            | accepted               | 2026-06-30 |
+```
+
+Every new ADR gets a row here at creation time. No orphans.
+
+## Minimal template (MADR 4.0.0)
+
+```markdown
+# NNNN. <short decision title, imperative>
+
+- Status: proposed | accepted | rejected | deprecated | superseded by ADR-NNNN
+- Date: YYYY-MM-DD
+- Deciders: <names / handles>
+
+## Context and Problem Statement
+
+<2–4 sentences. The problem and the constraints that force a choice.
+State the problem, not the answer. Quantify. Cite any driver (constitution
+section, spec/plan fork) that imposed this.>
+
+## Considered Options
+
+- <option 1>
+- <option 2>
+- <option 3>
+
+## Decision Outcome
+
+Chosen: **<option>**, because <the one-line justification tying back to
+the dominant driver>.
+
+## Consequences
+
+- Good: <what improves>
+- Bad: <what degrades / what you now own>
+- Follow-up: <concrete next work, linked to a tracker or future ADR>
+```
+
+## Full template (MADR 4.0.0, annotated)
+
+Add the optional sections — Decision Drivers, per-option Pros and Cons, Confirmation, More Information — when the decision is contested enough to need them.
+
+```markdown
+# NNNN. <short decision title>
+
+- Status: proposed
+- Date: YYYY-MM-DD
+- Deciders: <names>
+
+## Context and Problem Statement
+
+<The forces at play. Problem + constraints, quantified. End with the
+question being decided.>
+
+## Decision Drivers <!-- optional, but usually worth it -->
+
+- <driver 1, e.g. "EU data residency (constitution §data-residency)">
+- <driver 2, e.g. "team SQL fluency, no NoSQL ops experience">
+- <driver 3, e.g. "p99 < 100ms at 2k writes/min">
+
+## Considered Options
+
+- <option 1>
+- <option 2>
+- <option 3>
+
+## Decision Outcome
+
+Chosen: **<option>**, because <justification scored against the drivers>.
+
+### Confirmation <!-- optional -->
+
+<How we'll confirm the decision is implemented as intended — a review,
+a test, an architecture-fitness check.>
+
+## Pros and Cons of the Options <!-- optional -->
+
+### <option 1>
+
+- Good, because <…>
+- Bad, because <…>
+
+### <option 2>
+
+- Good, because <…>
+- Bad, because <…>
+
+## Consequences
+
+- Good: <upside bought>
+- Bad: <price paid / new ownership>
+- Risk: <what could go wrong>
+- Follow-up: <linked tasks>
+
+## More Information <!-- optional -->
+
+<Links, benchmarks, the meeting that spawned this, related ADRs.>
+```
+
+## Worked example — `0007-choose-postgres.md`
+
+Shown with the OKF frontmatter it carries when stored in `02-DOCS/wiki/decisions/`:
+
+```markdown
+---
+type: decision
+title: "Choose Postgres over DynamoDB for the primary store"
+tags: [adr, database, billing]
+timestamp: 2026-06-02T00:00:00Z
+---
+
+# 7. Choose Postgres over DynamoDB for the primary store
+
+- Status: accepted
+- Date: 2026-06-02
+- Deciders: @alice, @bob
+
+## Context and Problem Statement
+
+The billing service needs a primary datastore. Data is strongly
+relational (invoices, line items, customers with foreign keys),
+write volume ~2k/min, the team is 3 engineers with deep SQL and no
+NoSQL operational experience, and EU data residency is mandatory
+(constitution §data-residency). Which store do we adopt?
+
+## Decision Drivers
+
+- Relational integrity: transactional, foreign-key-enforced invoicing
+- Team fluency: SQL high, NoSQL ops ~zero
+- EU residency + self-host option
+- Operational risk for a 3-person team
+
+## Considered Options
+
+- Postgres (managed, EU region)
+- DynamoDB
+- MongoDB Atlas
+
+## Decision Outcome
+
+Chosen: **Postgres (managed, EU region)**, because it natively matches
+the relational shape of the data and the team's existing fluency, at the
+lowest operational risk for a small team.
+
+## Pros and Cons of the Options
+
+### Postgres
+- Good, because native ACID transactions and foreign keys fit invoicing.
+- Good, because the whole team is productive day one.
+- Bad, because we own connection-pooling and vertical-scaling sooner.
+
+### DynamoDB
+- Good, because effectively infinite write scaling, hands-off ops.
+- Bad, because relational integrity is app-enforced — error-prone for billing.
+- Bad, because no team experience and no EU self-host path (AWS-coupled).
+
+### MongoDB Atlas
+- Good, because flexible schema and EU regions available.
+- Bad, because multi-document transactions are awkward for invoicing.
+- Bad, because partial team fluency, medium operational risk.
+
+## Consequences
+
+- Good: ACID guarantees for invoices; mature tooling; team productive immediately.
+- Bad: we own connection-pool tuning and will hit vertical-scaling limits earlier.
+- Risk: a single-writer bottleneck at much higher volume.
+- Follow-up: provision a read replica before launch — tracked in ADR-0009.
+```
+
+## Worked example — supersession pair
+
+A prior decision is reversed. **Never edit the old decision** — write a new ADR and flip the old status.
+
+Old ADR, status line changed (and *only* the status line):
+
+```markdown
+# 4. Adopt REST for the public API
+
+- Status: superseded by ADR-0012
+- Date: 2025-11-03
+- Deciders: @alice
+
+## Context and Problem Statement
+
+We needed a wire format for the public API in v1. (…original context,
+options, decision and consequences left fully intact…)
+```
+
+New ADR that supersedes it:
+
+```markdown
+# 12. Adopt tRPC for the internal API
+
+- Status: accepted
+- Date: 2026-06-30
+- Deciders: @alice, @carol
+- Supersedes: ADR-0004
+
+## Context and Problem Statement
+
+ADR-0004 chose REST when clients were external and untyped. Clients are
+now exclusively our own TypeScript apps; the manual request/response typing
+that REST forced is a recurring source of drift and bugs. Reconsider the
+internal API transport.
+
+## Considered Options
+
+- Keep REST (status quo, ADR-0004)
+- tRPC (end-to-end TypeScript types)
+- GraphQL
+
+## Decision Outcome
+
+Chosen: **tRPC**, because every client is TypeScript and end-to-end type
+inference removes the drift class entirely, with no schema-layer overhead.
+
+## Consequences
+
+- Good: compile-time-safe client/server contract; no codegen step.
+- Bad: couples clients to a TypeScript server; no longer language-agnostic.
+- Follow-up: deprecate REST routes over two releases; update ADR-0004 status.
+```
+
+Then back-link: ADR-0004 → `superseded by ADR-0012`, ADR-0012 → `Supersedes: ADR-0004`. Both are reachable from the index.

package/skills/shared/decision-records/scripts/verify.sh

@@ -0,0 +1,105 @@
+#!/usr/bin/env bash
+# verify.sh — lint Architecture Decision Records (ADRs).
+# Read-only, no network. Usage: verify.sh <path-to-adr.md | decisions-dir>
+# Checks per ADR: recognized status, a date, required sections, >=2 options,
+# and a valid filename. Exits non-zero on the first failing ADR with a
+# specific message. Exits 0 on a clean target and on an empty/absent dir.
+
+set -u
+
+STATUS_RE='[Ss]tatus[^A-Za-z]*(proposed|accepted|rejected|deprecated|superseded)'
+DATE_RE='[0-9]{4}-[0-9]{2}-[0-9]{2}'
+
+fail() { echo "FAIL: $1" >&2; exit 1; }
+
+# Lint a single ADR file. Echoes nothing on success.
+lint_adr() {
+  local f="$1"
+  local base; base="$(basename "$f")"
+
+  # Filename: numeric-prefix NNNN-*.md, OR any *.md with a non-empty H1 title.
+  if ! printf '%s' "$base" | grep -Eq '^[0-9]{4}-.+\.md$'; then
+    if ! grep -Eq '^#[[:space:]]+[^[:space:]]' "$f"; then
+      fail "$f: filename is not NNNN-title.md and the file has no non-empty '# Title' heading"
+    fi
+  fi
+
+  grep -Eiq "$STATUS_RE" "$f" \
+    || fail "$f: no recognized Status (expected one of proposed|accepted|rejected|deprecated|superseded)"
+
+  grep -Eq "$DATE_RE" "$f" \
+    || fail "$f: no date found (expected a YYYY-MM-DD date)"
+
+  grep -Eiq '^#+[[:space:]]+Context' "$f" \
+    || fail "$f: missing a 'Context' section"
+
+  grep -Eiq '^#+[[:space:]]+(Considered )?Options' "$f" \
+    || fail "$f: missing a 'Considered Options' section"
+
+  grep -Eiq '^#+[[:space:]]+Decision( Outcome)?' "$f" \
+    || fail "$f: missing a 'Decision' / 'Decision Outcome' section"
+
+  grep -Eiq '^#+[[:space:]]+Consequences' "$f" \
+    || fail "$f: missing a 'Consequences' section"
+
+  # Count option bullets inside the Considered Options section.
+  local opts
+  opts="$(awk '
+    /^#+[[:space:]]+(Considered )?Options/ { inopt=1; next }
+    /^#+[[:space:]]/ { if (inopt) inopt=0 }
+    inopt && /^[[:space:]]*[-*][[:space:]]+[^[:space:]]/ { n++ }
+    END { print n+0 }
+  ' "$f")"
+  if [ "$opts" -lt 2 ]; then
+    fail "$f: lists $opts option bullet(s) under Considered Options; need >=2 real options"
+  fi
+}
+
+main() {
+  if [ "$#" -lt 1 ]; then
+    echo "usage: verify.sh <path-to-adr.md | decisions-dir>" >&2
+    exit 2
+  fi
+
+  local target="$1"
+
+  if [ -f "$target" ]; then
+    lint_adr "$target"
+    echo "OK: $target"
+    exit 0
+  fi
+
+  if [ -d "$target" ]; then
+    local count=0 index="" f base
+    # Locate an index file, if any, for orphan warnings.
+    for cand in "$target/README.md" "$target/0000-index.md" "$target/index.md"; do
+      [ -f "$cand" ] && index="$cand" && break
+    done
+
+    while IFS= read -r f; do
+      base="$(basename "$f")"
+      # Skip the index itself.
+      [ -n "$index" ] && [ "$f" = "$index" ] && continue
+      case "$base" in README.md|index.md|0000-index.md) continue ;; esac
+      count=$((count + 1))
+      lint_adr "$f"
+      # Orphan warning: numeric ADR id not referenced in the index.
+      if [ -n "$index" ] && printf '%s' "$base" | grep -Eq '^[0-9]{4}-'; then
+        local id="${base%%-*}"
+        grep -Fq "$id" "$index" \
+          || echo "WARN: $f (ADR $id) is not referenced in $index" >&2
+      fi
+    done < <(find "$target" -maxdepth 1 -type f -name '*.md' | sort)
+
+    if [ "$count" -eq 0 ]; then
+      echo "OK: no ADRs found under $target (nothing to check)"
+    else
+      echo "OK: $count ADR(s) under $target passed"
+    fi
+    exit 0
+  fi
+
+  fail "target not found: $target"
+}
+
+main "$@"