2026-07-26  FRAME       README.md, CLAUDE.md, docs/adr/*        → 00-frame.md written
2026-07-26  INVENTORY   evidence ranking below

2026-07-26  P1 struct   entry_points/cli/app.py, dispatch.py      → 27 CLI commands, 18 wire commands
2026-07-26  P1 struct   alembic/versions/0001,0002                → 7 tables + 1 FTS5 virtual table
2026-07-26  P1 struct   documents/domain/{schema,entities,vo}     → Document aggregate, Schema, DocId, RelatedRef
2026-07-26  P1 struct   documents/infra/{profiles,default_schema} → core + 5 profiles, 12 types
2026-07-26  P2/P3       documents/application/services/*          → DocumentService, MaintenanceService call chains
2026-07-26  P2/P3       tags/application, indexing/*, agents/*    → per-module behaviour + ordering
2026-07-26  P2/P3       platform/{persistence,filesystem,transport}, entry_points/daemon
2026-07-26  P4/P5       all of the above                          → BR-001..BR-072 drafted
2026-07-26  READ        tests/** (28 files)                       → cross-check of P4; encoded intent
2026-07-26  SKIPPED     tach.toml, scripts/check_contract_sync.py → out of scope per 00-frame.md
2026-07-26  SKIPPED     assets/, docs/PUBLISHING.md, .github/     → out of scope per 00-frame.md
2026-07-26  SKIPPED     platform/persistence/alembic/env.py       → migration machinery, no business rule

PROBE-1  clone->reindex->add    store1  → CONFIRMED id collision (GAP-003)
PROBE-2  get/query after PROBE-1 store1 → CONFIRMED first doc invisible to all read paths
PROBE-3  check --strict on 2 new docs   → exit 1 from `orphan` alone (GAP-006)
PROBE-4  context w/ resolved neighbour  → CONFIRMED inactive filter bypassed via graph (GAP-004)
PROBE-5  context --limit 3, 3x out-deg 2 → returned 9 docs (GAP-005)
PROBE-6  delete --force w/ incoming ref  → CONFIRMED dangling ref written to canonical file (GAP-007)
PROBE-7  update a doc holding dangling ref → CONFIRMED accepted, ref re-persisted (GAP-007)
PROBE-8  decision --related issue        → CONFIRMED permanent `layering` warning (GAP-008)
PROBE-9  delete then add                 → id NOT reused (counter monotonic) — no gap

2026-07-26  PROBE-10  6x concurrent --no-daemon add   → all returned adr-0002 (GAP-009)
2026-07-26  PROBE-11  same race WITH the daemon        → adr-0002..0007, unique — scopes GAP-009
2026-07-26  PROBE-12  schema validate on a typo'd transition target → {"valid":true} (GAP-010)
2026-07-26  PROBE-13  agent install --agent <typo>     → [], exit 0, no files (GAP-024)
2026-07-26  PROBE-14  context on unrelated query       → returns a doc, score 0.0328 (GAP-017)
2026-07-26  PROBE-15  all five profiles merged         → 15 types, no prefix collision — NO gap
2026-07-26  PROBE-16  delete then add                  → id not reused — NO gap

2026-07-26  MODEL   01-actors.yaml     → 8 actors (2 of them absent-but-implied: ACT-007, ACT-008)
2026-07-26  MODEL   02-flows/          → 5 flows, 41 hotspots, 3 off-system step clusters
2026-07-26  MODEL   04-glossary.yaml   → 13 terms, 10 with recorded conflicts
2026-07-26  FORMAL  03-rules.yaml      → 45 rules (EARS), 3 decision tables, 5 marked `disputed`

SELF-1  GAP-013 was hedged ("advanced and committed... or not"). Re-read repositories.py:55 —
        next_number only *flushes*, so the counter rolls back with the transaction while the
        already-written file survives. Rewritten as a concrete third duplicate-id path.
SELF-2  GAP-012 was severity:material but meets my own blocking rubric ("touches data loss").
        Raised to blocking; register re-sorted.
SELF-3  BR-034 has four conditions and no decision table — violates quality gate §9.
        Table added (verified against runner.py:36-48).
SELF-4  Q/BR/GAP cross-references were inconsistent after renumbering. Reconciled by script;
        verified no dangling or undefined ids in either direction.

[x] Every actor appears in >=1 flow                     8/8
[x] Every flow has unwanted-behaviour rules per failure point
                                    BR-001..003, 010..012, 018, 043, 061, 064, 070, 071
[x] Every rule has an evidence pointer and a status     45/45 (verified by script)
[x] Every rule with >2 conditions has a decision table  BR-003, BR-005, BR-034
[x] Smell scan clean                                    0 hits across 45 statements
[x] Every glossary term has exactly one definition      13 terms; 10 conflicts recorded as gaps
[x] Every hotspot resolved into a rule/gap/assumption   41/41
[x] Coverage log lists what was not examined            below
[x] Adversarial pass run and findings addressed         4 found, 4 fixed

FIX  GAP-003  reindex restores the id counter; + IdGenerator skips indexed ids;
              + create refuses to overwrite a file already holding the id   → resolved
FIX  GAP-013  same change; a crash mid-write can no longer be overwritten silently → resolved
FIX  GAP-009  next_number is one atomic upsert (was read-modify-write in Python);
              busy_timeout set explicitly                                    → resolved
FIX  GAP-005  --limit is a hard ceiling; --expand N reserves neighbour slots,
              unused ones backfilled; expansion breadth-first across seeds    → resolved
NEW  --id-style on `docir init`, defaulting to `random` (BR-073, BR-074)
DOC  packaged agent guide corrected: `docir reindex --all` does not exist     → GAP-040

GAP-040  the shipped agent guide told agents to run a flag that does not exist; nothing
         validates the template against the CLI. Typo fixed, guard still missing.
GAP-041  the counter restore reads an all-digit random id (0.36% of them) as sequential.
         Latent: no symptom while the type stays `random`.
GAP-042  random ids are ~3x longer and ride in every skeleton and every edge; the token
         cost of the new default is unmeasured (see GAP-001).

FIX  GAP-041  counter restore now keyed on the schema's declared id_style, with a
              suffix-length guard for ids left behind by a style switch      → resolved

FIX  GAP-006  CheckIssue carries a severity derived from its kind; --strict gates on
              errors only; --strict-all preserves fail-on-anything            → resolved
              NOTE: the existing test asserted the old behaviour as intent, so the tests
              could never have caught this — only running the tool did.

FIX  GAP-012  `docir check --fix` re-issues duplicate ids (oldest keeps it) and drops
              dead edges; malformed/unknown-type returned as needing a human  → resolved
              GAP-007 becomes recoverable but is still not prevented — stays open.
NEW  found while testing: `_as_list` accepted only `list`, but `dataclasses.asdict`
     preserves tuple fields, so the table renderer showed "nothing to repair" while
     --json printed the fix. Caught only because the human path was exercised
     separately from the JSON one. Both are now asserted in the same test.

FIX  GAP-001  benchmarks/ — 20-doc corpus, 12 judged tasks, recall/precision/MRR +
              payload size per strategy, run against both embedders        → resolved
NEW  GAP-043  the measurement's own headline: the DEFAULT embedder is lexical, not
              semantic, so `context` ~= `search` unless the `embeddings` extra is on.
              README:42 claims "retrieval by meaning" for a config most users lack.

FIX  GAP-043  docs-honesty pass: README table, command table, agent guide and CLAUDE.md
              now say which configuration each retrieval claim describes. No code
              change — the code was right, the copy was not.               → resolved
              OPEN QUESTION deferred: should fastembed be the default? Left undecided;
              it is a dependency-weight call, not a correctness one.

FIX  GAP-043  fastembed is now a hard dependency and the default; the hashing embedder
              becomes the DOCIR_EMBEDDER=deterministic fallback. README states the
              measured cost (~64 MB model, ~240 MB deps) instead of a caveat. → resolved
NEW  GAP-044  found while implementing that flip: nothing recorded which model produced
              a vector, and mismatched widths RAISE. The switch would have broken every
              existing store on first `docir context`. model_id is now written and
              honoured; foreign vectors fall out of ranking and are recomputed. → resolved

CHECK  uv.lock in sync with the new required dependency, committed  → clean
CHECK  CI workflow                                                  → passes, but see below
NEW    GAP-045: the default embedder path was excluded from every gate (ty, coverage,
       no tests) while CI installed 240 MB and ran none of it. The exclusions were
       correct when the adapter was opt-in and became a hole when it became the
       default; nothing re-checks an exclusion when its premise changes. → resolved
       Lifting the ty exclusion surfaced a real diagnostic on the first run.

FIX  GAP-036  `docir import` adopts existing markdown and preserves the number the
              filename implies, so historical cross-references survive adoption.
              Verified on docir's own ADR corpus.                          → resolved
              Two of my own test expectations were wrong, not the code: a title of
              "2026 is the year..." must NOT be de-numbered (only a number followed
              by punctuation is a label), and asdict returns tuples, not lists.

FIX  import now reports skipped files. Found by pointing it at `analysis/`: 12 files in,
     7 imported, 5 dropped with no mention — including 05-gaps.yaml and 06-questions.yaml.
     My own test had asserted non-markdown was *ignored*, never that it was *reported*.

FIX  GAP-004  one `_is_visible` predicate now serves both `context` paths; the ranked
     GAP-019  loop and graph expansion can no longer filter differently. Expansion also
              follows incoming supersedes/contradicts, successors first.       → resolved
              Maintainer answered Q-005 "hidden" (not "returned but flagged") and Q-017
              "yes, follow it backwards".

GAP-046  the benchmark cannot see either fix. Both change retrieval semantics; every
         number was byte-identical either side (recall@5 0.96 fastembed / 0.88
         deterministic). corpus.yaml has no supersedes edge and no inactive document,
         so the two behaviours `context` most depends on are unmeasurable. The corpus
         was deliberately NOT edited: re-basing it would break comparability with every
         figure recorded before today, and that is the maintainer's call.
NEW      benchmarks/run.py printed `embedder: deterministic (default)` from
         os.environ.get(..., "deterministic (default)") — a label, not the resolved
         object. The default flipped to fastembed in ADR-0011 and this line did not,
         so every run since has reported a configuration it did not measure. It was
         reporting "deterministic" while scoring 0.96, the recorded fastembed figure.
         `Container` now carries the built embedder and the harness prints its model_id.

FIX  GAP-046  corpus re-based to 23 docs / 14 tasks: a supersedes-linked decision pair
              plus a resolved issue. Loader learned typed edges and `status_path`.
              The harness now moves under these fixes.                     → resolved
              Measured by reverting each fix against the new corpus:
              context recall@5 0.93 -> 0.96 (fastembed), 0.89 -> 0.93 (deterministic).

FIX  GAP-008  layering check reads a dependency allowlist (`depends_on`, `refines`)
              instead of exempting supersedes/contradicts. `relates_to` — every bare
              id — no longer violates. PROBE-8 replayed: `[]` where it reported a
              permanent violation; `:depends_on` on the same edge still flags. → resolved
              Q-006 implemented on its recorded assumption, not on an answer.

FIX  GAP-040  test_agent_guide_matches_cli.py resolves every `docir ...` in the
              packaged guide against the Typer command tree. 29 invocations.
              Attribution: three defects injected (unknown flag, unknown
              subcommand, unknown top-level command), each caught.      → resolved
REWORD        the guide said "One `docir import`-style bulk pass" — a backticked
              command that deliberately does not exist. Prose, not an exemption:
              an agent runs a backticked command whatever the sentence says.

every pair after it. It reported a healthy-looking 28 invocations and did not contain the one
line the test exists to catch; the injected `reindex --all` passed. Second: after fixing
that, an unknown word fell back to the parent group, so `docir schema dump` validated
against `docir schema`.

Both were found the same way — by injecting the bug the test claims to catch and watching it
pass. A test written against a real corpus that happens to be clean cannot distinguish
"nothing is wrong" from "nothing is checked".

The guard-the-guard has the same disease in miniature: it first asserted `len(INVOCATIONS)
>= 20`, which both defects satisfied. A count cannot say *which* line went missing. It now
names six invocations that must be found, each reachable from a different part of the
document — fenced block, inline span, table cell, indented sub-list.

This is the fourth appearance of the family recorded here (GAP-006, GAP-045, GAP-008, now
GAP-040), and the sharpest: the other three were tests that asserted existing behaviour was
intended. This one asserted nothing at all while appearing to assert a great deal.

## Follow-up — forced delete compensates for what it breaks (2026-07-28)

**The fix invalidated five tests, and that is the interesting part.** Each used `delete
--force` as a cheap way to *manufacture* a dangling edge before asserting something about
`check` or `check --fix`. That route is now closed, so they build the state the way it
actually occurs: remove the target's file as a merge from a branch that deleted it would,
then reindex.

`test_check_detects_dangling_reference` in `test_merge_safety.py` is the one worth naming.
Its comment already claimed to simulate "a cross-branch delete after a merge" — but it used
the CLI shortcut, so the merge-safety test was not exercising a merge. The comment described
the intent and the code did something easier; nothing flagged the divergence because the
assertion still passed. A convenience path used as a fixture had quietly become the thing
under test.

GAP-007 moves from *recoverable* to *prevented*. `check --fix` stays as the recovery path
for edges broken outside the CLI — which, after this, is the only way left to break one.

## DELTA PASS — 2026-07-29, v0.7.0 (39 commits since the original run at 560aea5)

Scope: the surface *added or changed* since v0.2.1, not a re-derivation. The existing
register was appended to, never rewritten (SKILL.md §1.6). 37 of 46 recorded gaps had been
resolved; the question was what the fixing itself introduced.

### Probes

Three of seven probes found nothing. Recorded so the coverage is not overstated: the
stale/archived interaction, `check --fix`'s handling of the new finding kinds, and
cross-style id adoption are all correct.

### What the delta pass was for

**Two of the four findings were introduced by the fixes themselves**, which is the argument
for running one at all:

- GAP-048 (self-merge corrupts the registry) came from the GAP-028 merge, four commits
  earlier. Its tests asked "does merging two tags work?" and never "what if they are the
  same tag?". It shipped in 0.7.0 and manufactured precisely the `unknown-tag` state that
  the GAP-016 work had taught `check` to detect — one fix creating the condition another
  fix had just learned to report.
- GAP-050 came from the GAP-023 fix, which reasoned about writes and did not ask whether
  reads have the same question. GAP-049 came from the GAP-026 fix.

**A feature added to close a gap is new surface, and its degenerate cases are unexamined by
construction** — the tests written alongside it are shaped by the gap it was closing.

GAP-047 is different: it predates the original run and that run missed it. `init` is the one
command that builds its own home rather than using the resolved settings, so it fell outside
a review that traced `Settings.resolve`. Worth remembering that "every command does X" is a
claim to verify per command, not per resolver.

### Coverage — what this pass did NOT examine

Unchanged since v0.2.1 and not re-read: the daemon transport and lifecycle, the embedding
scheduler, `lint --deep`, the agents module beyond the template, and Alembic. The nine
cosmetic gaps left open from the original run were not re-examined either; they were
assessed for priority on 2026-07-29 (see the entries) but not re-derived from code.

## Note on paths (2026-07-30)

This document was `analysis/99-log.md` until the discovery bundle was folded into docir's own store. The `analysis/...` paths in the text above describe where the run wrote its output at the time; those files are documents in this store now — see `docs/README.md` for the map. The gap issues that cite this log link to it as a typed edge.