bearings 0.5.3 → 0.5.5

package/templates/agents/commands/update-bearings-setup.md

@@ -0,0 +1,144 @@
+---
+description: Resolve exact pending bearings update or reconstruction tasks and reconciliations. First-time setup resumes through bearings init.
+---
+
+# /update-bearings-setup
+
+Use the **bearings Commands for This Task** header's exact resume and completion
+commands when supplied. They select the initiating executable. Otherwise use
+`npx bearings`, or the established local bearings invocation.
+
+## 1. Select Pending Update Work
+
+Read `.agents/bearings.json` and the exact setup scope supplied by bearings.
+Require `setupPending.kind` to be `update` or `reconstruction`.
+
+- `init`: stop this command and use `bearings init` to resume first-time setup.
+- No pending setup: report no pending update work and stop.
+- Missing, invalid, or inconsistent journal/scope: report the blocker and use
+  `bearings init` to obtain the current handoff.
+
+Resolve only listed tasks, file `reconciliations`, and
+`migrationReconciliations`. Inspect their current targets and recorded
+artifacts before asking questions. Preserve completed work on resume. Ask one
+necessary question at a time, with a recommendation based on the evidence.
+Checkpoint each fully resolved task through step 5. Reread the journal after
+each checkpoint and process only its remaining tasks.
+
+Skills whose upstream template is unchanged stay untouched, including locally
+customized versions. Preserve `protectedSkills` and all other out-of-scope
+skills even when they have unrelated verify warnings. New ordinary runtime or
+checklist bundle files alone need no setup.
+Do not re-interview the project or adapt every installed skill. A
+`skippedTemplate` is a declined template revision; do not apply it as cleanup.
+
+## 2. Resolve Listed File Reconciliations
+
+Read each record's target and backup, plus baseline and incoming artifacts
+when present. Summarize the differences and get the developer's choice before
+applying backed-up changes. For an ordinary collision or `update-merge`, offer
+merge, keep parts, keep either version, or discard backed-up content. Apply
+the choice directly to that target regardless of owner.
+
+For a `retired` file, ask whether to keep useful content as an untracked target
+or discard it. After an explicit discard choice, a missing retired target can
+be resolved by selecting its path with `--setup-path` during completion.
+Preserve its backup until the CLI accepts the choice. A deliberately discarded
+retired map needs no refresh.
+
+Map edits go through `/refresh-repo-map` in step 4, with the developer's
+resolution as input. If a map reconciliation has no explicit map task, report
+the scope mismatch as blocked rather than edit it or expand the scope.
+
+### Starter Skill Updates (`skill-update`)
+
+Read the live skill, `backup`, and `incomingPath`. Check whether `basePath`
+exists before attempting a baseline diff.
+
+- **Base available:** compare local versus base and incoming versus base.
+  Offer **Take new template**, **Keep local**, **Three-way merge**, or
+  **Freeform**, one skill at a time. Recommend Three-way merge when both diffs
+  contain useful changes.
+- **Base missing:** explain that a historical base is unavailable. Offer only
+  **Take new template**, **Keep local**, or **Freeform**. Never fabricate a base
+  or present a two-way comparison as a three-way merge.
+
+Take new template writes incoming content to the live skill. Keep local leaves
+the live content intact and declines the incoming revision. Three-way merge
+combines both sides while preserving local intent. Freeform writes the agreed
+result; establish whether the developer accepts or declines the incoming
+revision. For Keep local or a Freeform result that declines the incoming
+revision, include that scoped skill-update path in `--keep-local` when
+checkpointing it with `--setup-path`. Omit `--keep-local` for accepted incoming
+templates and merges. The CLI owns `owner`,
+`hash`, `lastTemplateHash`, `skippedTemplate`, and baseline updates.
+
+## 3. Resolve Listed Checklist Migrations
+
+For each migration record, follow the installed `checklist` skill's authored
+schema and validation workflow.
+
+- **`testplan-collision`:** read `target` and the pre-existing checklist in
+  `backup`. Summarize both and ask whether to keep either version or combine
+  them. Write the chosen useful content to `target`.
+- **`invalid-testplan`:** read `backup`, explain each contract problem, and
+  agree with the developer how to preserve its useful authored content in a
+  repaired checklist. Use the exact repair destination printed in the supplied
+  scope. When the record has no `target`, the CLI's `migrationTarget` supplies
+  a deterministic safe `checklists/repairs/<id>.json` path. Read any existing
+  checklist there before writing and obtain the developer's choice to keep
+  either version or combine useful content. Discard content only on an explicit
+  developer choice; do not choose a different destination or edit the journal.
+
+Validate each repaired checklist and run the checklist skill's full-library
+build. Both must pass for that repair to be complete. An unrelated invalid
+checklist is a reported blocker, not permission to rewrite it. Only after useful
+content is preserved in the chosen target and validation/build pass, remove the
+recorded legacy `source` if it still exists. Keep backups and incoming artifacts
+until the completion CLI accepts their outcomes and performs cleanup; preserve
+useful content if a record remains blocked.
+
+## 4. Complete Listed Tailoring and Map Tasks
+
+For `reason: tailor`, or a reconciled seed, index, or starter-skill target,
+fill only its remaining placeholders. Inspect current project evidence and
+preserve existing entries and decisions. Use real commands or explicit
+`not configured`. Keep seed routing thin and skill safety workflows intact.
+For a listed `AGENTS.md`, remove a legacy `## Setup Required` blocking section
+and any obsolete `## Pending bearings Setup` section before checkpointing it.
+
+For `reason: map`, pass only the exact listed map paths to `/refresh-repo-map`
+as an explicit setup target scope, together with any reconciliation choices.
+A missing, added, restored, or accepted changed map can need refresh; a package
+version or unrelated skill change does not. With no map task, skip map refresh.
+With one map task, refresh only that artifact. Create C4 source only when
+`docs/diagrams/c4-component.puml` is explicitly listed. The selected targets
+still require the command's artifact contracts, sync markers, and probes.
+
+## 5. Complete Through the CLI
+
+Check each completed task and reconciliation against the developer's choices.
+Use the header's **Complete** command from the repository and append
+`--setup-path <path...>` with only the fully completed paths. Quote each path
+as a shell argument. For scoped `skill-update` paths whose incoming template
+the developer declined, also append `--keep-local <path...>`. Both flags require
+`--complete-setup`; `--keep-local` must refer only to selected skill updates.
+
+Without a supplied header, use
+`npx bearings init --complete-setup --setup-path <path...>`, with the established
+local bearings invocation when applicable. Omit `--setup-path` only when all
+remaining tasks are ready to complete. After each successful checkpoint, reread
+the journal and continue only its remaining paths. A partial checkpoint is
+progress, not whole-setup completion.
+
+The CLI owns the manifest, reconciliation records, hashes, ownership, template
+lineage, baselines, exposure copies, and artifact cleanup. Never remove
+`setupPending`, delete reconciliation artifacts, or change bookkeeping by hand.
+Neither `bearings verify` nor an agent exit code proves scoped completion.
+
+On validation failure, preserve progress and report **setup pending**, exact
+blocked paths, and the next action. Fix only in-scope content problems; leave
+unrelated warnings and unchanged skills outside this follow-up. Report
+completion only after the completion CLI succeeds and the journal confirms
+no pending setup. Finish with changed paths, developer choices, and validation
+result; stop without first-time setup.

package/templates/agents/skills/checklist/SKILL.md

@@ -35,6 +35,13 @@ authored instructions; the static previewer owns execution state.
 
 ## Content Policy
 
+- **Show** every operator-facing field (`title`, `summary`, `intro`,
+  `callout`, `conventions`, section `intro`, `instruction`, `expectedResult`,
+  `warning`, `failureGuidance`, link `label`). The field is the action,
+  command, path, identifier, or observable. Lead with that object. Shortest
+  scannable structure: line, bullets, `codeBlocks`, exact value. Prose fields
+  render HTML (`<code>`, `<strong>`). Titles, chrome, and `codeBlocks` stay
+  plain text. ASD-STE100 Simplified Technical English for a reader with ADHD.
 - Organize sections in execution order and keep each checklist item to one
   primary action or verification. Use `info` sections for concise context that
   the operator does not mark as executed.
@@ -64,6 +71,7 @@ authored instructions; the static previewer owns execution state.
 ## Completion
 
 Finish only when exactly one authored checklist file exists for this request,
-its mechanics and outcomes trace to evidence, its validator prints `OK`, the
-full library build succeeds, and the static previewer opens or its absolute path
-is reported after an opening failure.
+its mechanics and outcomes trace to evidence, every operator-facing field
+leads with an action, command, path, identifier, or observable, its validator
+prints `OK`, the full library build succeeds, and the static previewer opens
+or its absolute path is reported after an opening failure.

package/templates/agents/skills/checklist/previewer/index.html

@@ -8,30 +8,64 @@
   <link rel="stylesheet" href="./viewer.css">
 </head>
 <body>
+  <a class="skip-link" href="#content">Skip to current checklist</a>
   <header class="masthead">
     <div class="masthead-inner">
-      <p class="eyebrow">Bearings / local checklist library</p>
+      <p class="eyebrow">Bearings / operator console</p>
       <h1 id="title">Choose a checklist</h1>
       <p id="summary" class="summary">Browse the checklists generated from this repository.</p>
     </div>
   </header>
   <div class="toolbar">
     <div class="toolbar-inner">
-      <label class="picker-label" for="checklist-picker">Checklist</label>
-      <select id="checklist-picker"><option value="">Loading...</option></select>
+      <div class="picker">
+        <label class="toolbar-label" for="checklist-picker">Checklist</label>
+        <select id="checklist-picker"><option value="">Loading...</option></select>
+      </div>
+      <div class="task-pointer">
+        <span class="toolbar-label">Next unresolved</span>
+        <a id="current-task-link" href="#content">Choose a checklist</a>
+        <span id="next-task-copy" class="next-task">Next: —</span>
+      </div>
       <div class="progress" aria-live="polite">
-        <span id="progress-copy">0 / 0 resolved</span>
-        <span class="progress-track" aria-hidden="true"><span id="progress-fill"></span></span>
+        <div class="progress-heading">
+          <strong id="progress-copy">0 / 0 complete</strong>
+          <span class="progress-outcomes">
+            <span class="outcome outcome-failed"><b id="failed-count">0</b> failed</span>
+            <span class="outcome outcome-blocked"><b id="blocked-count">0</b> blocked</span>
+            <span class="outcome outcome-na"><b id="na-count">0</b> N/A</span>
+          </span>
+        </div>
+        <progress id="progress-track" class="progress-track" aria-label="Checklist completion" max="1" value="0"></progress>
       </div>
-      <button id="export-progress" type="button">Export</button>
-      <button id="import-progress" type="button">Import</button>
-      <input id="import-file" type="file" accept="application/json,.json" hidden>
-      <button id="reset-progress" type="button">Reset</button>
+      <details id="action-menu" class="action-menu">
+        <summary>Actions</summary>
+        <div class="action-panel">
+          <button id="export-progress" type="button">Export progress</button>
+          <button id="import-progress" type="button">Import progress</button>
+          <input id="import-file" type="file" accept="application/json,.json" hidden>
+          <button id="reset-progress" class="danger-button" type="button">Reset progress</button>
+          <p id="action-status" class="action-status" role="status" aria-live="polite" hidden></p>
+        </div>
+      </details>
     </div>
+    <p class="shortcut-legend" aria-label="Keyboard shortcuts">
+      <span><kbd>j</kbd>/<kbd>k</kbd> actions</span>
+      <span><kbd>[</kbd>/<kbd>]</kbd> sections</span>
+      <span><kbd>y</kbd> copy / choose</span>
+      <span><kbd>x</kbd> complete</span>
+      <span><kbd>f</kbd> failed</span>
+      <span><kbd>b</kbd> blocked</span>
+      <span><kbd>-</kbd> N/A</span>
+      <span><kbd>u</kbd> not started</span>
+      <span><kbd>R</kbd> reset</span>
+      <span><kbd>Enter</kbd> details</span>
+      <span><kbd>Esc</kbd> return</span>
+    </p>
   </div>
   <p id="storage-warning" class="storage-warning" role="status" hidden></p>
   <p id="status" class="status" role="status" aria-live="polite"></p>
-  <main id="content"></main>
+  <main id="content" tabindex="-1"></main>
   <script src="./data.generated.js"></script>
   <script src="./viewer.js"></script>
 </body>