bearings 0.2.0 → 0.3.1

package/templates/docs/DOMAIN.md

@@ -0,0 +1,33 @@
+# DOMAIN
+
+Answers: why does this system exist? Populated and kept current by `/refresh-repo-map`. Do not hand-edit outside that workflow.
+
+## Problem and Outcomes
+
+<agent: fill via /refresh-repo-map - the problem this system solves and the outcomes it produces for its users.>
+
+## Actors
+
+<agent: fill via /refresh-repo-map - users, operators, and other systems that act on or through this system.>
+
+## Use Cases
+
+<agent: fill via /refresh-repo-map - the business use cases this system supports.>
+
+## Workflows
+
+<agent: fill via /refresh-repo-map - the end-to-end workflows actors follow to reach an outcome.>
+
+## Ubiquitous Language
+
+<agent: fill via /refresh-repo-map - canonical domain terms and their precise meaning in this system.>
+
+## Domain Rules
+
+<agent: fill via /refresh-repo-map - domain rules and invariants that constrain behavior regardless of implementation.>
+
+## Boundaries and Non-Goals
+
+<agent: fill via /refresh-repo-map - what this system is explicitly not responsible for.>
+
+<!-- repo-map-synced: <agent: fill via /refresh-repo-map> -->

package/templates/docs/adr/0000-template.md

@@ -8,10 +8,22 @@ State whether this decision is proposed, accepted, superseded, or rejected.
 
 Describe the forces, constraints, and facts that make a decision necessary.
 
+## Scope
+
+State exactly which domain or technical concerns this decision applies to.
+
 ## Decision
 
 Record the chosen approach and the scope where it applies.
 
+## Alternatives
+
+List the alternatives considered and why each was rejected.
+
 ## Consequences
 
 List the tradeoffs, follow-up work, and verification impact.
+
+## Supersession
+
+State whether this ADR supersedes or is superseded by another ADR, and cross-link both records.

package/templates/docs/adr/INDEX.md

@@ -0,0 +1,6 @@
+# Architecture Decision Records
+
+An ADR is warranted when a decision constrains future work, has meaningful alternatives or tradeoffs, or is costly to reverse. Recording a decision here requires an approved consequential decision — never invent or record an unapproved entry. Read this index first, then only matching accepted or superseding ADRs; do not scan every ADR.
+
+| ID | Decision | Status | Affected concerns | Supersedes | Detail |
+|---|---|---|---|---|---|

package/templates/docs/deferred/INDEX.md

@@ -1,6 +1,8 @@
 # Deferred Work
 
-| ID | Parked item | Revisit trigger | Detail |
-|---|---|---|---|
+This folder is not a general backlog and does not hold permanently rejected work or ordinary code TODOs. Recording an entry here requires explicit developer approval — an agent may suggest deferral but never records it unapproved.
 
-Add a `DEF-NNN-topic.md` detail doc per entry. Scan this file before planning new features.
+| ID | Postponed item | Reason | Revisit trigger | Detail |
+|---|---|---|---|---|
+
+Add a `DEF-NNN-topic.md` detail doc per entry. Read this index before planning a new capability, then open only matching detail files. Remove a row once its work is shipped or rejected.

package/templates/agents/commands/current-state.md

@@ -1,163 +0,0 @@
----
-description: Generate or refresh docs/CURRENT_STATE.md and, if `docs/diagrams/` exists in this repo, docs/diagrams/c4-component.puml — the source-of-truth source map
----
-
-# /current-state
-
-Refresh `docs/CURRENT_STATE.md` and, if `docs/diagrams/` exists in this repo, `docs/diagrams/c4-component.puml` when component topology changes. Runs after each committed task, or standalone when the source map has drifted.
-
-This command is the **only** writer for `CURRENT_STATE.md` and, if `docs/diagrams/` exists in this repo, `c4-component.puml`. Do not touch either during implementation.
-
-## When to run
-
-- After a task is implemented and committed — typical use, run in the same thread.
-- Standalone, when the source map has drifted and needs catching up without a task in progress.
-- First time, to seed `CURRENT_STATE.md` for an existing codebase or a freshly-skeletoned project.
-
-## Required sections — CURRENT_STATE.md
-
-Exactly these headings, in this order. Empty section: keep the heading with `(none)`. Do not remove.
-
-```markdown
-# CURRENT_STATE
-
-## Purpose
-
-<1–2 sentences, caveman: what codebase does, for whom>
-
-## Stack
-
-<lang ⊕ framework ⊕ key libs; versions only when material>
-
-## Shipped capabilities
-
-<flat list, 1 line each — only end-user functionality working today>
-
-## Source map
-
-<folder/file tree, 1-line purpose per node — tech-lead pointer granularity>
-
-## Design patterns in use
-
-<pattern name → file/dir>
-
-## Public interfaces
-
-<HTTP routes / UI routes / CLI cmds / events / queues>
-
-## Data model digest
-
-<link to docs/diagrams/erd.puml ⊕ 1-line table list>
-
-## Component diagram
-
-<embed of rendered docs/diagrams/rendered/c4-component.svg, if `docs/diagrams/` exists in this repo>
-
-## Known debt / TODOs
-
-<short, current; deleted once addressed>
-```
-
-## Caveman style — whole file
-
-- Bullet fragments. Drop articles (`the`, `a`).
-- Symbols: `→` leads-to · `⊕` and-also · `~` approximately · `Δ` change · `&` and-also.
-- `file:line` over prose: `auth/login.ts:42` ✓ · "line 42 of auth/login.ts" ✗.
-- No hedging (`might`, `could`, `perhaps`) — state or omit.
-- No preamble, no meta, no restating the question.
-- 1 line per entry where possible.
-
-Example:
-
-```
-## Shipped capabilities
-- email/pw signup ⊕ verify
-- JWT auth → 7d refresh
-- profile edit (name, avatar)
-
-## Source map
-- src/auth/ — signup, login, JWT issuance
-  - login.ts:42 → token mint
-  - guards/ — route protection
-- src/users/ — CRUD ⊕ profile
-- src/db/ — Prisma client ⊕ migrations
-```
-
-## Inputs
-
-Gather these in order — the diff is the truth source; task or issue context describes intent:
-
-1. **`docs/CURRENT_STATE.md`** — baseline to preserve.
-2. **If `docs/diagrams/` exists in this repo, `docs/diagrams/c4-component.puml`** — component baseline.
-3. **Task or issue context** — identify from conversation context, linked issue/spec, or `git log -1 --format=%B`. Read named context docs for intended Δ when present.
-4. **Adjacent planning docs** — read only if linked by the task, issue, spec, or commit message.
-5. **`git diff HEAD~1`** — what actually shipped; trust this over intent docs if they diverge.
-
-## Procedure A — generate from scratch (no file exists)
-
-Covers (a) existing codebase adopting the methodology, (b) new project past design/skeleton phase.
-
-1. **Stack** — read manifests: `package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `tsconfig.json`, `vite.config.*`, `next.config.*`, `prisma/schema.prisma`, etc.
-2. **Source map** — walk top-down. Per top-level folder: read `index.*` / `mod.rs` / `__init__.py`, the largest file, any `README.md`. Stop at tech-lead-pointer granularity (deep enough to route a dev to the right file, no deeper). Symbol-level entries only when the symbol _is_ the landmark.
-3. **Public interfaces** — find route registrations (Express/NestJS/FastAPI/Django/etc.), CLI entry points (`bin/`, `cmd/`, `cli.*`), event/queue handlers.
-4. **Data model digest** — read schema + migrations → 1-line table list. Link `docs/diagrams/erd.puml` if it exists; if not, link `prisma/schema.prisma` or equivalent. Do not inline schema.
-5. **Design patterns in use** — recurring shapes by directory naming + import graph (Repository, Service, UseCase, Controller, ...). Pattern → file/dir.
-6. **Shipped capabilities** — user-facing features actually working today. Skip in-flight or planned. If unsure what works, **ask the user**. Do not infer from task files or phase docs.
-7. **Component diagram** — if `docs/diagrams/` exists in this repo and `docs/diagrams/c4-component.puml` does not exist, create a minimal skeleton from the source map's top-level boundaries. Render to SVG via `docker run --rm -v "$PWD:/data" plantuml/plantuml -tsvg docs/diagrams/c4-component.puml`. Embed the rendered SVG path in the section. If `docs/diagrams/` does not exist in this repo, write `(none)` in the section.
-8. **Known debt / TODOs** — grep `TODO|FIXME|HACK|XXX`. Add obvious gaps spotted during the walk.
-9. **Purpose** — 1–2 caveman sentences. If unclear, **ask the user**. Do not guess.
-10. Apply caveman style end-to-end. Re-read once. Cut every word with no signal.
-
-After drafting: surface to user, ask for corrections. The first version is a draft, not the answer.
-
-## Procedure B — update an existing file
-
-Trigger: a task was just committed and `/current-state` is called in the same thread, or standalone drift correction.
-
-1. Read `docs/CURRENT_STATE.md` fully — establish the baseline.
-2. If `docs/diagrams/` exists in this repo, read `docs/diagrams/c4-component.puml` — establish the component baseline.
-3. Identify the completed task or issue from conversation context or `git log -1 --format=%B`. Read named context docs for intended Δ when present.
-4. Run `git diff HEAD~1` — confirm what actually shipped. This is the truth source.
-5. Map change to affected sections — most tasks touch 1–3:
-   - new dep → **Stack**
-   - new user-facing feature working today → **Shipped capabilities**
-   - new/renamed/removed file or folder, or purpose shift → **Source map**
-   - new endpoint/CLI/event → **Public interfaces**
-   - new migration → **Data model digest**
-   - new component or container relation → **Component diagram** if `docs/diagrams/` exists in this repo (edit `c4-component.puml`, re-render)
-   - new pattern adopted ⊕ old pattern retired → **Design patterns in use**
-   - debt resolved → **prune** from Known debt; new debt → add
-   - **Purpose** — touch only if scope actually shifted
-6. **Weigh new entries against the existing baseline.** A freshly-shipped task does not automatically replace older, more important entries. If the file is growing past one screen, prune low-signal entries first.
-7. Apply changes with the **Edit tool only** — surgical replacements. Never regenerate the file. Untouched sections stay byte-identical.
-8. **Prune obsolete entries.** File removed → delete source-map line. Pattern retired → delete entry. Debt resolved → delete item. Stale entries are worse than missing ones.
-9. New entries match surrounding density. Caveman throughout.
-10. If `docs/diagrams/` exists in this repo and `c4-component.puml` changed, re-render: `docker run --rm -v "$PWD:/data" plantuml/plantuml -tsvg docs/diagrams/c4-component.puml`. Update the embed path in the Component diagram section if the rendered filename changed.
-11. Re-read after editing. Cut redundancy the diff introduced.
-
-After updating: surface the diff of `CURRENT_STATE.md` to the user, flag any conflicts, ask for corrections. Once the user approves (or no corrections are needed), commit with a concise docs message such as:
-
-```
-docs: update CURRENT_STATE
-```
-
-Include only project-required trailers. Stage only `docs/CURRENT_STATE.md` and, if `docs/diagrams/` exists in this repo and changed, `docs/diagrams/c4-component.puml` plus its rendered SVG.
-
-## Conflict handling
-
-- **Task file says X, diff shows Y** → trust the diff. Note the divergence to the user.
-- **Manual human edit in `CURRENT_STATE.md` conflicts with new change** → trust the new change but **flag the conflict before overwriting**. The human edit may encode context the agent lacks.
-
-## Anti-bloat rules
-
-- No narrative. No restating code comments.
-- No planned, in-flight, or "next release" features. Only what works today.
-- No duplication of content that lives elsewhere — link instead (`→ prisma/schema.prisma`, `→ docs/diagrams/erd.puml`).
-- File grows with **source-tree structure**, not task count. Growing per-task → wrong content going in; rework the entry until it describes structure, not the task.
-- No business detail — that lives in `docs/features/`. `CURRENT_STATE.md` is a source map, not a feature catalog.
-- No history — `CURRENT_STATE.md` answers "what is"; `CHANGELOG.md` answers "how we got here". They never overlap.
-
-## Out of scope
-
-- Appending to `CHANGELOG.md`.
-- Editing unrelated requirements, prototypes, class diagrams, ERDs, context diagrams, or container diagrams.

package/templates/agents/skills/enforcement-gates/SKILL.md

@@ -1,35 +0,0 @@
----
-description: Use when a local hook, lint, typecheck, test, build, validation, or CI gate fails.
----
-
-# Enforcement Gates
-
-## Purpose
-
-Diagnose failed gates from evidence, fix the underlying issue, and avoid bypassing safety checks.
-
-## Triggers
-
-- A pre-commit, pre-push, CI, lint, typecheck, test, build, validation, or policy gate fails.
-- You are tempted to skip or weaken a check.
-
-## Required Workflow
-
-1. Capture the failing command and first relevant error -> identify the gate, not a symptom.
-2. Fix the smallest underlying cause -> keep the gate intact.
-3. Re-run the failed gate -> confirm it passes.
-4. Run adjacent verification if the fix changes behavior -> prevent regressions.
-
-## Rules
-
-- Do: preserve strict gate settings and cite the command/output in the report.
-- Do not: bypass hooks, lower thresholds, delete tests, or silence errors without a documented reason.
-
-## Verification
-
-- Run `<agent: fill during handoff — standard gate command>` after fixing any gate failure.
-
-## References
-
-- `<agent: fill during handoff — CI config path>` - canonical gate list.
-- `<agent: fill during handoff — local hook config path>` - developer gate list.

package/templates/agents/skills/implementing-task/SKILL.md

@@ -1,36 +0,0 @@
----
-description: Use when implementing planned work from a task, issue, spec, or phase document.
----
-
-# Implementing Task
-
-## Purpose
-
-Execute planned work without drifting from scope, skipping verification, or mixing unrelated changes.
-
-## Triggers
-
-- You are implementing a task/spec/issue with explicit requirements.
-- You are changing code under a feature or phase plan.
-
-## Required Workflow
-
-1. Read the task source and linked durable docs -> identify exact scope and exclusions.
-2. Write or update the smallest failing test first -> confirm the expected RED failure.
-3. Implement the minimal change -> keep unrelated files untouched.
-4. Run the required verification -> record command and outcome.
-5. Update current-state only through `/current-state` when shipped behavior or source map changed.
-
-## Rules
-
-- Do: preserve exact values, paths, and commands from the task source.
-- Do not: pull future-phase work forward or silently expand scope.
-
-## Verification
-
-- Run `<agent: fill during handoff — smallest command that proves a planned task>` before reporting completion.
-
-## References
-
-- `docs/CURRENT_STATE.md` - current source map.
-- `docs/conventions/doc-lifecycle.md` - durable vs planning document lifecycle.

package/templates/agents/skills/installing-dependencies/SKILL.md

@@ -1,36 +0,0 @@
----
-description: Use when adding, removing, or updating dependencies, package-manager metadata, lockfiles, or workspace package links.
----
-
-# Installing Dependencies
-
-## Purpose
-
-Keep dependency changes reproducible, scoped to the correct package, and aligned with the project's package manager.
-
-## Triggers
-
-- Adding, removing, or upgrading an external package.
-- Linking an internal workspace package.
-- Editing package manifests or lockfiles.
-
-## Required Workflow
-
-1. Identify package manager and workspace shape -> `<agent: fill during handoff — package manager and workspace command rules>`.
-2. Identify the owning package/app -> avoid installing at the wrong level.
-3. Run the package manager command -> update manifest and lockfile together.
-4. Run dependency-sensitive verification -> prove install and imports work.
-
-## Rules
-
-- Do: use `<agent: fill during handoff — approved package manager command>` for dependency changes.
-- Do not: edit lockfiles by hand or mix unrelated dependency upgrades.
-
-## Verification
-
-- Run `<agent: fill during handoff — install/build/test command after dependency changes>` when dependency metadata changes.
-
-## References
-
-- `<agent: fill during handoff — package manifest path>` - dependency owner.
-- `<agent: fill during handoff — lockfile path>` - resolved dependency graph.

package/templates/agents/skills/repo-navigation/SKILL.md

@@ -1,34 +0,0 @@
----
-description: Use when exploring the repo, locating code, or deciding which docs and paths to read before making changes.
----
-
-# Repo Navigation
-
-## Purpose
-
-Explore efficiently without crawling irrelevant, archived, generated, or project-specific material.
-
-## Triggers
-
-- You need to understand where code, docs, commands, or ownership rules live.
-- You are about to do broad repository exploration.
-
-## Required Workflow
-
-1. Read `docs/CURRENT_STATE.md` -> use it as the first source map.
-2. Read only the paths relevant to the task -> keep exploration proportional.
-3. If the source map is stale -> report the mismatch and continue from direct evidence.
-
-## Rules
-
-- Do: prefer durable docs, manifests, and entry points before deep file walks.
-- Do not: crawl archived, generated, vendored, or build-output folders unless the task explicitly needs them.
-
-## Verification
-
-- Run `<agent: fill during handoff — smallest command that proves navigation-sensitive changes>` when exploration changes generated docs or routing metadata.
-
-## References
-
-- `docs/CURRENT_STATE.md` - source map and current shipped shape.
-- `docs/conventions/current-state.md` - update policy and staleness rules.

package/templates/agents/skills/secrets-handling/SKILL.md

@@ -1,36 +0,0 @@
----
-description: Use when touching credentials, tokens, keys, secret references, config containing secrets, or secret redaction paths.
----
-
-# Secrets Handling
-
-## Purpose
-
-Prevent secrets from being committed, logged, exposed through APIs, or stored outside the approved secret store.
-
-## Triggers
-
-- Storing, reading, rotating, deleting, or displaying credentials.
-- Editing config, environment files, CI secrets, tokens, keys, or redaction logic.
-- Adding a new integration that needs a secret.
-
-## Required Workflow
-
-1. Identify the secret and owner -> `<agent: fill during handoff — secret store/provider and ownership rule>`.
-2. Store only references in code/config where possible -> keep raw values in the approved store.
-3. Verify redaction boundaries -> responses, logs, errors, docs, and tests must not reveal secret values.
-4. Rotate or revoke exposed values -> treat accidental disclosure as a security incident.
-
-## Rules
-
-- Do: use `<agent: fill during handoff — approved secret reference pattern>` for secret lookup and storage.
-- Do not: commit raw secrets, print them, include them in snapshots, or expose secret references where the project forbids it.
-
-## Verification
-
-- Run `<agent: fill during handoff — secret/config validation command>` when secret handling changes.
-
-## References
-
-- `<agent: fill during handoff — secret management doc/path>` - approved store and redaction contract.
-- `<agent: fill during handoff — config/env schema path>` - allowed secret references.

package/templates/docs/CURRENT_STATE.md

@@ -1,38 +0,0 @@
-# CURRENT_STATE
-
-## Purpose
-
-<agent: fill via /current-state>
-
-## Stack
-
-- <agent: fill via /current-state>
-- <agent: fill via /current-state>
-
-## Shipped capabilities
-
-- <agent: fill via /current-state>
-
-## Source map
-
-- `<agent: fill via /current-state>` - <agent: fill via /current-state>
-
-## Design patterns in use
-
-- <agent: fill via /current-state> -> <agent: fill via /current-state>
-
-## Public interfaces
-
-- <agent: fill via /current-state> -> <agent: fill via /current-state>
-
-## Data model digest
-
-- <agent: fill via /current-state> - <agent: fill via /current-state>
-
-## Component diagram
-
-- <agent: fill via /current-state>
-
-## Known debt / TODOs
-
-- <agent: fill via /current-state>

package/templates/docs/conventions/current-state.md

@@ -1,9 +0,0 @@
-# Current State Policy
-
-## Policy
-
-- Agents read it before broad exploration.
-- If it answers the question, agents should not re-crawl the repo.
-- It should be updated only by an explicit command or maintenance workflow.
-- If stale, agents should report staleness instead of silently rewriting it during unrelated work.
-- Only `/current-state` writes `docs/CURRENT_STATE.md`.

package/templates/docs/conventions/doc-lifecycle.md

@@ -1,16 +0,0 @@
-# Documentation Lifecycle
-
-## Common categories
-
-| Category | Examples | Lifecycle |
-|---|---|---|
-| Durable | architecture, ADRs, glossary, operations, current-state conventions | Long-lived |
-| Planning | roadmap, phases, feature plans, task docs | Archived or removed after shipped |
-| Runbooks | deployment, rollback, manual checks, provider setup | Updated when operations change |
-| Deferred work | parked plans and revisit triggers | Removed when built or rejected |
-
-## Why this matters
-
-- Prevents agents from treating stale plans as shipped behavior.
-- Prevents durable docs from depending on soon-archived docs.
-- Gives agents a clear source of truth for scope disputes.