fix(ci): improve auto bm note narrative

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

Author: phernandez

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

@@ -1,27 +1,51 @@
 # 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 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.
+
 ## 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,11 @@ 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 product voice is:
 
@@ -127,15 +129,22 @@ 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 +189,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.