bearings 0.3.0 → 0.3.2

package/README.md

@@ -1,6 +1,8 @@
 # bearings
 
-`bearings` is a small TypeScript CLI that helps you give your agents their bearings: it scaffolds an agent-friendly repository setup, exposes shared skills and commands to supported harnesses, records the generated files in a manifest, and leaves project-specific tailoring to your AI agent via `/setup-repo`.
+`bearings` is a small TypeScript CLI that helps you give your agents their bearings: it scaffolds an agent-friendly repository setup, exposes shared skills and commands to supported harnesses, records every generated file in a manifest, and leaves project-specific tailoring to your AI agent via `/setup-repo`.
+
+Requires Node >= 24.
 
 ## Quick Start
 
@@ -11,9 +13,11 @@ bearings verify
 ```
 
 1. `npx bearings init` writes the generic scaffold and prints the next step.
-2. `/setup-repo` runs inside your AI agent to merge backups, fill placeholders, seed docs, and tailor skills.
+2. `/setup-repo` runs inside your AI agent to review backups, fill placeholders, seed docs, and tailor the setup.
 3. `bearings verify` checks the scaffold for drift, missing files, broken exposures, and unresolved setup warnings.
 
+Re-run `npx bearings init` later to update an initialized repository. There is no separate `update` verb — `init` dispatches on manifest state (ADR-0001).
+
 ## What Gets Generated
 
 ```text
@@ -34,11 +38,6 @@ docs/
     refresh-repo-map.md
     setup-repo.md
   skills/
-    repo-navigation/SKILL.md
-    implementing-task/SKILL.md
-    installing-dependencies/SKILL.md
-    secrets-handling/SKILL.md
-    enforcement-gates/SKILL.md
     commit-convention/SKILL.md
     defer-work/SKILL.md
     resurface-deferred-work/SKILL.md
@@ -51,9 +50,11 @@ docs/
   skills/*
 ```
 
+Every file carries an `owner` in the manifest. `bearings`-owned files (`CLAUDE.md`, the ADR template, commands, skills) are package-maintained — the incoming template is their canonical update source. `agent`-owned files (`AGENTS.md`, the three maps, the two indexes) are yours; bearings never overwrites them without an explicit per-file decision.
+
 `/setup-repo` creates `docs/diagrams/c4-component.puml` (via `/refresh-repo-map`) once the repo is tailored; it is not part of the generated scaffold or the manifest.
 
-Existing scaffold targets are backed up as `<path>.bkp` before replacement. Re-running `init` skips unchanged managed files.
+Existing files that collide with a scaffold target are backed up as `<path>.bkp` before replacement, and the backup is recorded as a pending reconciliation for `/setup-repo` to resolve.
 
 ## The Model
 
@@ -72,24 +73,59 @@ user task
 
 ### `bearings init`
 
-Scaffold the agent-friendly setup in the current repository.
+State-aware entry point. With no manifest it scaffolds; with a manifest it runs an interactive update; with a corrupt manifest it enters reconstruction.
 
 | Flag | Meaning |
 |---|---|
 | `--harness <name...>` | Expose to `claude` and/or `opencode`. Defaults to detected harness dirs, or both in a fresh repo. |
 | `--copy` | Copy exposures instead of symlinking them. `verify` checks copy drift. |
-| `-y`, `--yes` | Accept defaults and do not prompt. |
+| `-y`, `--yes` | Accept defaults and do not prompt. Fresh init only. |
+
+**Fresh init** — scans the repo, resolves harness/exposure, aborts on unmanaged adapter collisions before writing anything, generates the scaffold, exposes `.agents/{commands,skills}/*` per harness, writes the v2 manifest, and hands off to `/setup-repo`.
+
+**Update** — interactive only (requires a TTY; `--yes` has no effect). It refuses to downgrade the recorded bearings version and refuses to start while a prior update's `/setup-repo` handoff is still pending. Each managed file is classified against its manifest baseline:
+
+| Situation | What happens |
+|---|---|
+| Content matches baseline | Kept silently |
+| Template changed, file unchanged locally | Replaced |
+| File changed locally **and** in the template | Conflict — you choose **Replace**, **Merge** (back up your content for `/setup-repo`), or **Skip** (decline this revision; it won't re-prompt) |
+| File no longer shipped, unchanged locally | Removed |
+| File no longer shipped, changed locally | You choose **Remove** or **Keep and untrack** |
+| New scaffold path already occupied | Conflict, resolved the same way |
+
+Adapter changes (harness added/removed, symlink↔copy switch) are planned alongside. The full plan is shown and confirmed before any mutation, then applied as a single transaction — the manifest is written last, and any failure restores the exact prior state. A run that changes nothing reports `already up to date`.
+
+**Reconstruction** — when the manifest is missing fields, hash-broken, or otherwise invalid, harness and exposure config is detected from the adapters on disk, confirmed with you, and a fresh v2 manifest is rebuilt.
 
 ### `bearings verify`
 
-Check the manifest and harness exposures for mechanical breakage. Exit code `0` means no failures; exit code `1` means one or more failures.
+Check the manifest and harness exposures for mechanical breakage. Exit code `0` means no failures; exit code `1` means one or more failures. Warnings never affect the exit code.
 
 | Code | Severity | Condition |
 |---|---|---|
 | `no-manifest` | fail | `.agents/bearings.json` missing |
+| `invalid-manifest` | fail | manifest fails structural validation |
 | `missing-file` | fail | manifest entry path doesn't exist |
 | `missing-exposure` | fail | a child of `.agents/skills` or `.agents/commands` absent from a configured harness dir |
 | `broken-symlink` | fail | harness entry is a symlink whose target doesn't resolve |
 | `copy-drift` | fail | copy mode: harness file content differs from `.agents` source content |
+| `setup-pending` | warn | an update finished but `/setup-repo` hasn't run yet |
 | `unfilled-placeholder` | warn | a bearings-generated file still contains `<agent:` |
 | `unreviewed-backup` | warn | manifest `backup` path still exists on disk |
+| `pending-reconciliation` | warn | a recorded backup from a collision or Merge is still unresolved |
+
+## Development
+
+```sh
+npm test     # rebuilds dist/ via pretest, then runs the full Vitest suite
+npm run build
+```
+
+- `docs/ARCHITECTURE.md` — components, dependency direction, build shape.
+- `docs/CODEBASE_MAP.md` — capability-to-source routing with `path#symbol` anchors.
+- `docs/DOMAIN.md` — terminology, workflows, and domain rules.
+- `docs/adr/INDEX.md` — consequential decisions.
+- `docs/qa/RELEASE_QA.md` — manual pre-release tiers, staged by `node scripts/qa.ts setup`.
+
+This repo is maintained by bearings itself; see `AGENTS.md` for the dogfooding ownership rules before editing any managed file.

package/dist/{chunk-GUIHDRBB.js → chunk-VRWQ3OWC.js}

@@ -7,11 +7,6 @@ function templatesDir() {
   return join(dirname(fileURLToPath(import.meta.url)), "..", "templates");
 }
 var SKILLS = [
-  "repo-navigation",
-  "implementing-task",
-  "installing-dependencies",
-  "secrets-handling",
-  "enforcement-gates",
   "commit-convention",
   "defer-work",
   "resurface-deferred-work",
@@ -31,7 +26,7 @@ var SCAFFOLD = [
   ...SKILLS.map((skill) => ({
     template: `agents/skills/${skill}/SKILL.md`,
     target: `.agents/skills/${skill}/SKILL.md`,
-    owner: skill === "installing-dependencies" || skill === "secrets-handling" ? "agent" : "bearings"
+    owner: "bearings"
   }))
 ];
 
@@ -638,7 +633,7 @@ async function runFreshInit(repoDir, flags, version) {
 async function runInit(repoDir, flags, version) {
   const state = await inspectManifest(repoDir);
   if (state.kind === "absent") return runFreshInit(repoDir, flags, version);
-  const { runUpdate } = await import("./update-GAIUBEGX.js");
+  const { runUpdate } = await import("./update-5F7TZEUH.js");
   return runUpdate(repoDir, flags, version, state);
 }
 

package/dist/cli.js

@@ -5,7 +5,7 @@ import {
   runInit,
   sha256,
   validateHarnesses
-} from "./chunk-GUIHDRBB.js";
+} from "./chunk-VRWQ3OWC.js";
 
 // src/cli.ts
 import { Command } from "commander";

package/dist/{update-GAIUBEGX.js → update-5F7TZEUH.js}

@@ -10,7 +10,7 @@ import {
   sha256,
   templatesDir,
   validateHarnesses
-} from "./chunk-GUIHDRBB.js";
+} from "./chunk-VRWQ3OWC.js";
 
 // src/semver.ts
 function parseSemver(value) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bearings",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Give your AI agents their bearings — scaffold an agent-friendly setup in any repository.",
   "type": "module",
   "engines": {

package/templates/agents/commands/setup-repo.md

@@ -47,9 +47,9 @@ When `.agents/bearings.json` is manifest v2 and has `setupPending`:
 4. Fill only the `AGENTS.md` project-purpose and primary-stack placeholders.
    Keep `AGENTS.md` a thin router — do not add a skill table, invariants
    section, or always-on rules block.
-5. Tailor only the agent-owned starter skills (`installing-dependencies`,
-   `secrets-handling`) to this project. Create a new project-specific skill
-   only when native skill discovery has no adequate existing match.
+5. Create a project-specific skill only when native skill discovery has no
+   adequate existing match. Every starter skill is bearings-owned — leave
+   them untouched.
 6. Run the `/refresh-repo-map` workflow to initialize `docs/DOMAIN.md`,
    `docs/ARCHITECTURE.md`, `docs/CODEBASE_MAP.md`, and
    `docs/diagrams/c4-component.puml`.
@@ -69,10 +69,9 @@ When `.agents/bearings.json` is manifest v2 and has `setupPending`:
   of a Backup File is the developer's call.
 - Do not edit `.agents/bearings.json` except where this workflow requires
   it.
-- Do not change bearings-owned starter commands or skills; tailor only the
-  agent-owned starter skills. The one exception: a reconciliation that records
-  an explicit Merge decision permits applying that Backup File's changes
-  directly to its bearings-owned target.
+- Do not change bearings-owned starter commands or skills. The one exception:
+  a reconciliation that records an explicit Merge decision permits applying
+  that Backup File's changes directly to its bearings-owned target.
 - Do not add a skill registry row to `AGENTS.md` — native skill discovery
   replaces it.
 - Do not invent domain or technical constraints — every stated constraint

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

@@ -1,36 +0,0 @@
----
-name: enforcement-gates
-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,45 +0,0 @@
----
-name: implementing-task
-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 the entire `docs/CODEBASE_MAP.md` -> identify
-   exact scope, exclusions, and owning `path#symbol` anchors.
-2. Load `docs/DOMAIN.md`, `docs/ARCHITECTURE.md`, `docs/adr/INDEX.md`, or
-   `docs/deferred/INDEX.md` only when the task's trigger matches.
-3. Write or update the smallest failing test first -> confirm the expected RED failure.
-4. Implement the minimal change -> keep unrelated files untouched.
-5. Run the required verification -> record command and outcome.
-6. Run `/refresh-repo-map` only after this task's changes are committed and
-   they meaningfully alter shipped behavior, structure, or source routing, or
-   after detected staleness -> never patch the owned maps directly.
-
-## Rules
-
-- Do: preserve exact values, paths, and commands from the task source.
-- Do not: pull future-phase work forward or silently expand scope.
-- Do not: edit `docs/DOMAIN.md`, `docs/ARCHITECTURE.md`,
-  `docs/CODEBASE_MAP.md`, or `docs/diagrams/c4-component.puml` directly;
-  route every change through `/refresh-repo-map`.
-
-## Verification
-
-- Run `<agent: fill during handoff — smallest command that proves a planned task>` before reporting completion.
-
-## References
-
-- `docs/CODEBASE_MAP.md` - current capability/concern-to-source map.
-- `docs/DOMAIN.md`, `docs/ARCHITECTURE.md`, `docs/adr/INDEX.md`, `docs/deferred/INDEX.md` - trigger-matched context.

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

@@ -1,42 +0,0 @@
----
-name: installing-dependencies
-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.
-5. If the change is architecture-significant (a new runtime dependency, a
-   replaced core dependency, or a changed dependency role) -> route it to
-   `docs/ARCHITECTURE.md` through `/refresh-repo-map` once committed; do not
-   edit that map directly.
-
-## 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.
-- `docs/ARCHITECTURE.md` - significant-dependency routing target via `/refresh-repo-map`.

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

@@ -1,53 +0,0 @@
----
-name: repo-navigation
-description: Use when exploring the repo, locating code, or deciding which docs and paths to read before making changes.
----
-
-# Repo Navigation
-
-## Purpose
-
-Route straight to owning source using the codebase map, and load domain,
-architecture, decision, or deferred-work context only when the task actually
-needs it.
-
-## 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 the entire `docs/CODEBASE_MAP.md` before any source work -> use its
-   `path#symbol` anchors as the routing model.
-2. Load `docs/DOMAIN.md` only when the task turns on behavior, requirements,
-   workflows, terminology, scope, or domain rules.
-3. Load `docs/ARCHITECTURE.md` only when the task turns on components,
-   dependency direction, integrations, state ownership, significant
-   dependencies, or environment/build shape.
-4. Load `docs/adr/INDEX.md` and only matching ADRs when a consequential
-   decision constrains the task.
-5. Load `docs/deferred/INDEX.md` and only matching details when planning a
-   new capability.
-6. If any loaded map is stale -> report the mismatch and continue from direct
-   evidence.
-
-## Rules
-
-- Do: prefer the codebase map, other 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.
-- Do not: load a map whose trigger does not match the current task.
-
-## Verification
-
-- Run `<agent: fill during handoff — smallest command that proves navigation-sensitive changes>` when exploration changes generated docs or routing metadata.
-
-## References
-
-- `docs/CODEBASE_MAP.md` - current capability/concern-to-source map.
-- `docs/DOMAIN.md` - business language and workflows.
-- `docs/ARCHITECTURE.md` - stable technical shape and environment.
-- `docs/adr/INDEX.md` - consequential decision registry.
-- `docs/deferred/INDEX.md` - approved postponed-work registry.

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

@@ -1,37 +0,0 @@
----
-name: secrets-handling
-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.