@rasensio/aidlc-content 1.73.1 → 1.75.0

package/docs/knowledge-graph.md

@@ -150,3 +150,27 @@ deliberate:
 
 The same shape guards the coverage cache in `src/traceability/cache.ts`, which is where the pattern
 came from.
+
+## When a source file breaks
+
+A merge that leaves conflict markers in `modules.yaml`, or a hand edit that makes one document
+unparseable, takes that document out of the index. That part is right: the YAML is the source of
+truth, and keeping the old rows would be serving stale facts again. What was wrong is that nobody
+was told. The parser named the file in a warning that nothing printed, and when no entity was left
+the `# Codebase Knowledge` block simply disappeared from `CLAUDE.md` — a shrinking diff in a
+generated file, the exact shape of thing six instances had already filed as noise.
+
+So `aidlc update` and `aidlc init` now print `knowledge graph: <file>: …` for every broken source,
+and say so when the block is left out. Three choices behind that:
+
+- **The warning is read from the files on every run**, not only on the run that rebuilt the index.
+  Whichever command opens the index first after a merge does the rebuild; if that was `aidlc gate`,
+  the warning used to be gone before `aidlc update` ever saw it. That costs one extra parse on those
+  two commands — 70–160 ms here — and nothing anywhere else.
+- **A document the index cannot store is skipped and named, not thrown.** A `description:` holding a
+  map used to fail the whole rebuild with "cannot be bound to SQLite parameter 4", which names
+  neither the file nor the field. The rule is what the index actually refuses, measured against it,
+  rather than the stricter rules `aidlc knowledge add` enforces — applying those on read would drop
+  facts that index fine today.
+- **`compact` is the exception.** It rewrites the YAML from what it read, so skipping a document there
+  would delete it from the source of truth rather than from a cache. It still reads everything.

package/docs/roadmap.md

@@ -481,8 +481,12 @@ the two differ.
   not-asked, yes, and an explicit no are three different answers, and collapsing any two of them
   makes a re-run of `init` delete somebody's configuration.
 - `packages/cli/src/doctor/migrations/roadmap-sync-gh-missing.ts` — the report-tier check. It
-  spawns nothing at all: the primary checkout comes from `ctx.gitCommonDir`, already resolved, not
-  from `primaryCheckout()`, which shells out to `git rev-parse`.
+  spawns nothing at all: the primary checkout comes from `ctx.primaryProjectRoot`, resolved once by
+  doctor, not from `primaryCheckout()`, which shells out to `git rev-parse`. It used to derive the
+  directory itself from the git common dir, which gave the repository's top — and for a project
+  below the top, a config with no `roadmap.sync`, so the check stayed silent. Every roadmap read and
+  write resolves the primary checkout's copy of the *project*, not of the repository, for the same
+  reason.
 - `packages/content/resources` — a portable version of the item-authoring skill, loadable into any
   agent, so a contributor with no checkout can write an item and commit it to `inbox/`.
 - `packages/cli/src/operational` — the `roadmap-done` completion action. Its history is instructive:

package/docs/state-and-concurrency.md

@@ -65,7 +65,16 @@ inside it before starting the agent session.
 ## Where the code lives
 
 - `packages/cli/src/concurrency` — the claim store, staleness logic, and worktree helpers.
-  `claim-store.ts` is the single place a claim is written or read.
+  `claim-store.ts` is the single place a claim is written or read. `common-dir.ts`
+  `primaryProjectRoot` is the one answer to "the primary checkout's copy of this project", which
+  the roadmap, the `aidlc start` concurrency check, autopilot and doctor all use. It is the
+  repository's top *joined with the project's path inside it*, because a project can sit below the
+  top — a monorepo package. Its predecessor returned the top alone, and for such a project the
+  concurrency check told a second session in the same checkout it had "nothing to collide on",
+  while the roadmap read a `.aidlc/` that did not exist. It was deleted rather than kept beside the
+  new one: a helper answering the wrong question is how one mistake reached five callers.
+  `aidlc start --worktree` in a nested project still writes to the new worktree's top; that is
+  item-20261009-worktree-start-in-nested-project.
 - `packages/cli/src/state` — instance folders, `phase-<name>.yaml`, and the append-only
   `transitions.log`.
 - `packages/cli/src/commands/claim.ts` — the `claim` and `release` commands, which also write the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rasensio/aidlc-content",
-  "version": "1.73.1",
+  "version": "1.75.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",