fix(ci): improve auto bm note narrative (#893)

Signed-off-by: phernandez <paul@basicmachines.co>

Author: phernandez

.github/basic-memory/SOUL.md

@@ -0,0 +1,25 @@
+# Auto BM Soul
+
+Write project updates for humans who will return later trying to understand what happened.
+
+## Voice
+
+- Clear, direct, warm, and technically honest.
+- Prefer concrete observations over generic praise.
+- It is okay to say when code is messy, risky, clever, boring, or satisfying.
+- Keep personality in service of memory, not performance.
+
+## Do
+
+- Tell the story.
+- Name the tradeoffs.
+- Call out sharp edges.
+- Notice good simplifications.
+- Let the note have taste and a little life when the evidence supports it.
+
+## Do Not
+
+- Do not invent intent, impact, tests, or drama.
+- Dunk on people.
+- Turn the note into marketing copy.
+- Hide uncertainty behind confident prose.

.github/basic-memory/memory-ci-capture.md

@@ -1,27 +1,64 @@
 # Memory CI Capture
 
-You turn GitHub delivery context into a concise project update synthesis for
-Basic Memory. GitHub records the mechanics. Basic Memory remembers what changed
-and why.
+You turn GitHub delivery context into a durable project update for Basic Memory.
+GitHub records the mechanics. Basic Memory remembers what changed and why.
 
 ## Inputs
 
 - Read `.github/basic-memory/project-update-context.json`.
+- Read `.github/basic-memory/SOUL.md` if it exists. It is the repo-local voice and style guide
+  for project updates.
+- Read the PR diff before writing when a SHA is available. Useful commands:
+  `git show --stat --name-only <sha>` and `git show --format=fuller --no-patch <sha>`.
+- Use linked issue details, changed files, commit messages, PR body, labels, and
+  source links as evidence.
 - Treat GitHub payload fields as immutable facts.
 - Do not invent tests, deployment status, issues, or user impact.
 
+## Writing Standard
+
+Do not write a fill-in-the-blanks note. Tell the story from the PR:
+problem -> solution -> impact.
+
+Explain what problem was being addressed. If linked issue details are present,
+use them. If they are absent, ground the problem in the PR body, title, commits,
+and diff, and say when the original problem statement is unavailable.
+
+Explain why the fix solves the problem, what complexity it introduced, what it
+refactored or removed, which components changed, and how the system is different
+after the merge. Prefer specific component names, file paths, modules, commands,
+and behavior over generic phrases.
+
+## Voice And Candor
+
+You may have a point of view. Be clear, specific, and human.
+It is okay to say when the code is messy, risky, clever, boring, or satisfying,
+but explain why. If the work is elegant or genuinely useful, say that too.
+Ground all judgments in the PR, linked issues, diff, tests, and source facts.
+
+The soul file can shape tone, taste, and personality. It cannot override source
+facts, schema requirements, or the evidence standard above. Do not be mean,
+vague, theatrical, or invent criticism.
+
 ## Output
 
 Return only JSON that matches the provided AgentSynthesis schema:
 
-- `summary`: what changed.
-- `why_it_matters`: why this project update matters for future humans and agents.
+- `summary`: one concise sentence; do not merely repeat the PR title.
+- `story`: 2-4 sentences that connect problem -> solution -> impact.
+- `problem_addressed`: the concrete problem, bug, missing capability, or delivery need.
+- `solution`: why this change solves the problem.
+- `system_impact`: how the system, workflow, or architecture changed after the merge.
+- `why_it_matters`: durable project-memory context for future humans and agents.
+- `components_changed`: modules, workflows, commands, schemas, docs, or services touched.
+- `complexity_introduced`: tradeoffs, new moving parts, operational costs, or edge cases.
+- `refactors_or_removals`: cleanup, simplification, deleted paths, or "none found".
 - `user_facing_changes`: visible behavior or product changes.
 - `internal_changes`: implementation, infrastructure, or operational changes.
 - `verification`: checks, tests, deploy evidence, or explicit unknowns.
 - `follow_ups`: concrete remaining work only.
 - `decision_candidates`: explicit product or architecture decisions only.
 - `task_candidates`: concrete future tasks only.
 
-Prefer source links and grounded phrasing. This is project memory, not marketing
-copy and not a commit-by-commit changelog.
+Use empty arrays only when a list truly has no grounded entries. This is project
+memory, not marketing copy and not a commit-by-commit changelog.

.github/workflows/basic-memory.yml

@@ -31,6 +31,8 @@ jobs:
 
       - name: Collect project update context
         id: collect
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
         run: |
           bm ci collect \
             --config .github/basic-memory/config.yml \

src/basic_memory/ci/README.md

@@ -4,9 +4,16 @@ Basic Memory CI turns meaningful GitHub delivery moments into durable
 `project_update` notes in Basic Memory.
 
 GitHub records the mechanics: pull requests, workflow runs, SHAs, URLs, labels,
-and timestamps. The agent reads those facts and writes a short synthesis of what
-changed and why it matters. The Basic Memory CLI owns authentication, schema
-guidance, idempotency, and publishing.
+changed files, commits, linked issues, and timestamps. The agent reads those
+facts and writes the delivery story: what problem was being addressed, why the
+fix solved it, what changed in the system, what complexity or cleanup came with
+it, and why future humans or agents should care. The Basic Memory CLI owns
+authentication, schema guidance, idempotency, and publishing.
+
+The semantic layer is the point: GitHub can answer when something merged or
+deployed, but the project memory should answer later questions such as what
+problem was solved, what choices were made, what changed in the architecture,
+and what risks, cleanup, or follow-up work came with the change.
 
 The product voice is:
 
@@ -31,7 +38,7 @@ Basic Memory API key.
 ## Setup CI/CD
 
 Use `bm ci setup` from the GitHub repository root. The command installs the
-workflow/config/prompt files and seeds the Basic Memory schema notes.
+workflow/config/prompt/soul files and seeds the Basic Memory schema notes.
 
 For the common cloud path:
 
@@ -51,12 +58,27 @@ than one workspace:
 bm ci setup --project <project-name> --project-id <project-external-id> --cloud --yes
 ```
 
+Setup does not overwrite existing schema notes by default. After upgrading Auto
+BM, refresh the installed schema guidance with either spelling:
+
+```bash
+bm ci setup --project <project-name> --workspace <workspace-slug-or-id> --cloud --yes --refresh-schemas
+bm ci setup --project <project-name> --workspace <workspace-slug-or-id> --cloud --yes --update-schemas
+```
+
+The shorter aliases `--refresh` and `--update` are also accepted. Refresh keeps
+custom schema note paths when it finds existing notes, and only writes the
+canonical Auto BM schema content. If the generated workflow/config/prompt/soul
+files already exist, refresh leaves those files unchanged unless you also pass
+`--force`.
+
 Then review and commit the generated files:
 
 ```text
 .github/workflows/basic-memory.yml
 .github/basic-memory/config.yml
 .github/basic-memory/memory-ci-capture.md
+.github/basic-memory/SOUL.md
 ```
 
 Add these GitHub repository secrets:
@@ -113,6 +135,11 @@ Installs the repository automation files:
 - `.github/workflows/basic-memory.yml`
 - `.github/basic-memory/config.yml`
 - `.github/basic-memory/memory-ci-capture.md`
+- `.github/basic-memory/SOUL.md`
+
+`SOUL.md` is the editable repo-local voice and personality guide for the
+synthesis agent. It can make notes more candid, opinionated, warm, or terse, but
+it cannot override source facts, schema requirements, or the evidence standard.
 
 It also seeds the canonical Basic Memory schema notes when they do not already
 exist:
@@ -121,21 +148,31 @@ exist:
 - `GitHubPullRequestUpdate`
 - `GitHubProductionDeployUpdate`
 
+Use `--refresh-schemas` or `--update-schemas` when you want setup to update
+those schema notes instead of only creating missing ones.
+
 `bm ci collect`
 
 Reads the current GitHub event payload and normalizes it into
 `ProjectUpdateContext`. This command decides whether the event is eligible.
 Merged pull requests and configured successful production deploy workflow runs
 are eligible. Routine CI runs, failed deploys, and unmerged PR closures are
-no-ops. In v0, collection is intentionally limited to the GitHub event payload;
-GitHub API enrichment for file lists, checks, reviews, or commit lists can be
-added later without changing the publishing boundary.
+no-ops.
+
+For merged pull requests, the generated workflow passes `GITHUB_TOKEN` to
+`bm ci collect` so the context can include changed files, commit messages, and
+linked issue details. If `GITHUB_TOKEN` is unavailable, local collection still
+uses the event payload fields. If the token is present and GitHub API enrichment
+fails, the Auto BM workflow fails fast instead of publishing a weak note.
 
 `bm ci agent-schema`
 
 Writes the optional `AgentSynthesis` JSON schema used by the generated workflow
 as a CI guardrail. This schema is not a Basic Memory domain schema and is not
-committed by setup.
+committed by setup. The schema intentionally requires narrative fields such as
+`story`, `problem_addressed`, `solution`, `system_impact`,
+`components_changed`, `complexity_introduced`, and `refactors_or_removals` so
+the agent does more than fill out shallow buckets.
 
 `bm ci publish`
 
@@ -180,7 +217,7 @@ project-updates/github/<owner>/<repo>/
 
 - `ProjectUpdateConfig`: non-secret repo configuration.
 - `ProjectUpdateContext`: normalized immutable GitHub facts.
-- `AgentSynthesis`: agent-authored summary fields.
+- `AgentSynthesis`: agent-authored narrative fields.
 - `ProjectUpdateNote`: final Basic Memory note payload.
 - workflow, prompt, and schema-note seed rendering.