refactor: act on the structure/naming review

Addresses the high-level review's findings — internal legibility, not behavior
(review mode output is unchanged):

- rename scripts/cb_engine.py -> scripts/engine_adapter.py (+ test file): it is
  a thin CLI adapter over the separate CodeBoarding engine, not the engine; the
  old name implied analysis logic lived here. Docstring now says so up front.
- dedupe the incremental-or-full path: review 'head' and sync 'analyze' shared
  ~90% logic (try incremental, fall back to full on the same two exceptions);
  both now call one _incremental_or_full helper, so a fallback fix lands once.
- move baseline parsing into the adapter: new 'baseline-info' subcommand emits
  commit_hash= only when present and SHA-shaped, replacing the sync_seed step's
  inline python heredoc + grep with one tested code path.
- add a 'force_full' input (sync mode) that rebuilds the baseline from scratch,
  and RETIRE refresh-baseline.yml: it was a 198-line hand-rolled copy of the
  action's own pipeline. Its 'fresh full rebuild' is now codeboarding-sync.yml's
  workflow_dispatch + force_full, running the tested action instead of a clone.
- structure legibility: a top-of-file phase map (guard / shared setup /
  analysis-with-key / drop-key + output) naming the shared analysis.json
  baseline as the binding between the two modes; review-only inputs now carry a
  'Review mode:' prefix so the Marketplace-rendered view matches the README.
- refresh AGENT.md (was review-only) to describe both modes; document force_full.

93 tests pass (both module orders); actionlint, shellcheck, black clean.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: brovatten

.github/workflows/codeboarding-sync.yml

@@ -1,8 +1,11 @@
-# Dogfood sync mode: sync THIS repo's committed architecture baseline
-# (analysis.json + docs) on every push to main, keeping the
-# baseline the PR review workflow diffs against current. This supersedes the
-# manual refresh-baseline.yml for routine freshness; that workflow stays as a
-# manual escape hatch for an on-demand, from-scratch baseline rebuild.
+# Dogfood sync mode: keep THIS repo's committed architecture baseline
+# (.codeboarding/analysis.json + rendered docs) current on every push to main,
+# so the PR review workflow always diffs against an up-to-date baseline.
+#
+# This is the ONLY baseline writer for this repo. The manual "rebuild from
+# scratch" path (previously a separate refresh-baseline.yml) is now the
+# workflow_dispatch + force_full input below, which runs the same tested action
+# instead of a hand-rolled copy of its pipeline.
 
 name: CodeBoarding sync
 
@@ -12,22 +15,27 @@ on:
     # Don't re-trigger on the files this workflow itself commits. Deliberately
     # NOT '.codeboarding/**': that would also swallow pushes that only edit the
     # user-authored .codeboarding/.codeboardingignore, which changes analysis
-    # scope and should regenerate the docs.
+    # scope and should regenerate the baseline.
     paths-ignore:
       - '.codeboarding/*.md'
       - '.codeboarding/analysis.json'
       - '.codeboarding/codeboarding_version.json'
       - '.codeboarding/health/**'
       - 'docs/development/architecture.md'
   workflow_dispatch:
+    inputs:
+      force_full:
+        description: 'Ignore the committed baseline and rebuild it from scratch (full analysis).'
+        type: boolean
+        required: false
+        default: false
 
 permissions:
-  contents: write   # commit the generated docs to the branch
+  contents: write   # commit the generated baseline + docs to main
 
 concurrency:
-  # Shared with refresh-baseline.yml: both commit .codeboarding/analysis.json
-  # to main and must never run concurrently (refresh-baseline's plain `git
-  # push` hard-fails on non-fast-forward).
+  # Serialize this workflow against itself: a push landing while a manual
+  # dispatch is mid-run must not produce two concurrent commits to main.
   group: codeboarding-baseline-writers
   cancel-in-progress: false
 
@@ -44,4 +52,5 @@ jobs:
       - uses: ./
         with:
           mode: sync
+          force_full: ${{ inputs.force_full || false }}
           llm_api_key: ${{ secrets.OPENROUTER_API_KEY }}

.github/workflows/refresh-baseline.yml

@@ -1,11 +1,19 @@
 # AGENT.md — CodeBoarding-action
 
-This repo is a GitHub Action that gives pull requests a visual system-design
-review: it analyzes the PR with the CodeBoarding engine and posts a diagram of
-the added, modified, and removed components as a PR comment. The engine
-(`CodeBoarding/CodeBoarding`) is pinned to a release in `action.yml`; engine
-changes reach users only when that pin is bumped *and* a new action release
-ships.
+This repo is a GitHub Action with two modes, selected by the `mode` input:
+
+- **`mode: review`** (default): analyzes a PR with the CodeBoarding engine and
+  posts a Mermaid diagram of the added, modified, and removed components as a PR
+  comment (runs on `pull_request` / `issue_comment`).
+- **`mode: sync`**: on push to a branch, regenerates the architecture and commits
+  the versioned baseline (`.codeboarding/analysis.json` + rendered markdown) back
+  to the branch, so review mode always diffs against a current baseline.
+
+The action is a thin orchestration wrapper, not the analysis engine: the engine
+(`CodeBoarding/CodeBoarding`) is a separate repo checked out at runtime and
+pinned to a release in `action.yml`. `scripts/engine_adapter.py` is the CLI
+adapter into it (no analysis logic lives there). Engine changes reach users only
+when that pin is bumped *and* a new action release ships.
 
 ## Releases
 

AGENT.md

@@ -252,6 +252,7 @@ Be aware that `contents: write` is repo-wide — GitHub does not scope it to a b
 | `target_branch` | sync | `${{ github.ref_name }}` | Branch the generated docs are pushed to. |
 | `write_architecture_md` | sync | `true` | Also write `docs/development/architecture.md`: all rendered pages concatenated, `overview.md` first. |
 | `commit_message` | sync | `chore(codeboarding): sync architecture baseline [skip ci]` | Commit message for the generated docs. |
+| `force_full` | sync | `false` | Ignore any committed baseline and run a full analysis from scratch. Use to rebuild a stale or corrupt baseline (e.g. from a `workflow_dispatch`). |
 
 ## Outputs