Skip to content

fix: keep committed library.md aligned with the live tree #2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
IronAdamant wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

fix: keep committed library.md aligned with the live tree #2

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

### Fixed
- CI: install `wikifier[mcp]` only on Python ≥3.10 (`mcp` has no 3.8/3.9 wheels).
- Regenerated committed `library.md` from a full `update-maps` so deleted 4.6.10 leftovers (`mcp/tools/{intel,status,workflow}.py`, `parsers/javascript/_parser.py`, `health.py`, `server_backup.py`) no longer appear in the file tree, Mermaid graph, or reverse-deps.
- `generate_library_md` drops cache keys / reverse-deps whose source is not a file on disk (stale cache cannot resurrect ghosts).
- File-tree captions prefer `*.wiki.md` purpose/role text; health *reasons* are audit stamps and are not copied as descriptions.
- `session_bootstrap`: re-read `cache_backend` after ACS persist so creating an empty SQLite stub does not leave `cache_backend: "none"`. Additive `cache_empty` / `cache_files_indexed` distinguish sqlite-empty from no store.

### Added
- `tests/test_library_map_honesty.py`: fails if committed `library.md` names a path that is not a file on disk.

### Changed
- Agent Protocol **v0.6.1**: 4.6.x additive field notes (readiness tiers, `map_paths`, ACS v1.3 `agent_signal`, `needs_mark_green`, sqlite-empty vs `cache_backend: none`).
- README / protocol language table: deep/ACS (Python, JS/TS) vs regex hint (Rust/Go/C/C++/C#/Java).

## [4.6.13] - 2026-08-27

Expand Down
2 changes: 1 addition & 1 deletion CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co

Wikifier is a **zero-dependency, agent-to-agent codebase wiki**: it gives AI agents a token-efficient, queryable map of a codebase (health matrix, dependency graph, per-file wiki summaries) so they can look things up instead of re-reading full sources. The human layer (`index.html` dashboard) is strictly secondary — a read-only viewer of the same artifacts. It is deliberately NOT a general human documentation tool.

**This repo dogfoods itself.** Wikifier runs on its own source, and you are expected to follow its agent protocol when working here (see below). The authoritative agent contract is `skills/run.md` (Agent Protocol v0.6 — package 4.6.x) — read it before substantive work.
**This repo dogfoods itself.** Wikifier runs on its own source, and you are expected to follow its agent protocol when working here (see below). The authoritative agent contract is `skills/run.md` (Agent Protocol v0.6.1 — package 4.6.x) — read it before substantive work.

**USE WIKIFIER FIRST (non-negotiable in this repo, preferred on any managed target):** At session start call `session_bootstrap` (MCP or `python -m wikifier session-bootstrap`). Prefer Core daily tools (`list_core_tools`): bootstrap, `check_changes`, `prepare_edit`, `suggest_next_actions` (json `actions[]`), `record_change`, `mark_green`. Look up via map/wiki/deps before re-reading full sources. Selective work only (🔴 / actionable 🟡). Never skip `record_change` after edits.

Expand Down
21 changes: 8 additions & 13 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,17 +8,12 @@

Wikifier is an **agent-to-agent** tool: it builds a living map of a project (health matrix, dependency graph, short file summaries) and agents keep that map current as they work. Humans can peek via a small dashboard; the product is the agent loop, not a general docs site or IDE.

Works from small scripts to large monorepos. **Deep import/include maps** (zero-dep regex parsers):

| Language | Extensions | Notes |
|----------|------------|--------|
| Python | `.py` | full ACS/CDIA path |
| JavaScript / TypeScript | `.js` `.ts` `.jsx` `.tsx` | barrels (BREE), dynamic/CDIA |
| Rust | `.rs` | `use` / `mod` / `extern crate` |
| Go | `.go` | `import` / import blocks |
| C / C++ | `.c` `.h` `.cpp` `.cc` `.cxx` `.hpp` `.hh` | `#include` (local + system) |
| C# | `.cs` | `using` namespaces |
| Java | `.java` | `import` / `import static` |
Works from small scripts to large monorepos. Parsers are **zero-dep regex** (not cargo / `go.mod` / classpath / `-I`). Depth is two-tier:

| Depth | Languages | What agents should trust |
|-------|-----------|--------------------------|
| **Deep / ACS** | Python (`.py`); JavaScript / TypeScript (`.js` `.ts` `.jsx` `.tsx` `.mjs` `.cjs` `.mts` `.cts`) | CDIA, BREE barrels, scored resolve, ACS work queue |
| **Regex hint** | Rust (`.rs`); Go (`.go`); C / C++ (`.c` `.h` `.cpp` `.cc` `.cxx` `.hpp` `.hh`); C# (`.cs`); Java (`.java`) | `use` / `import` / `#include` / `using` smokes — not compiler-faithful |

Health/journal still work for any monitored path. Parsers are **pragmatic regex** (not full cargo/`go.mod`/classpath/`-I` resolution). On huge monorepos, split scope deliberately:

Expand Down Expand Up @@ -62,7 +57,7 @@ Always set an explicit root for external trees: `WIKIFIER_PROJECT_ROOT=/abs/path

## Steady state (only touch what needs it)

Full protocol: [`skills/run.md`](skills/run.md) (Agent Protocol v0.6 — package **4.6.x**).
Full protocol: [`skills/run.md`](skills/run.md) (Agent Protocol v0.6.1 — package **4.6.x**).

```bash
wikifier session-bootstrap # one-shot: root, health, attention, actions[]
Expand All @@ -85,7 +80,7 @@ Advanced intel as needed: `get_dependencies`, `get_dependents`, `get_cycles`, ba

## What you get

- **Import analysis** — Python, JS/TS (ESM/CJS, barrels), Rust (`use`/`mod` + best-effort `crate::` paths), Go, C/C++ includes, C# usings; per-edge confidence; barrel expansion for TS/JS
- **Import analysis** — deep/ACS for Python + JS/TS (ESM/CJS, barrels, CDIA); regex-hint maps for Rust/Go/C/C++/C#/Java; per-edge confidence on the deep path
- **Incremental pipeline** — pure-Python `update-maps`: dirty parse → import cache → reverse deps → cycles → `library.md`
- **Warm agent maps (4.6.3–4.6.7)** — zero-dirty + **index-first** candidates (re-list only when fingerprint / map-scoped index / live count disagree); **MapScope** keeps collect, live count, index filter, and prune aligned; **stdlib SQLite**; content-hash dirty
- **Two path lists** — `map_paths.txt` = map package roots; `monitored_paths.txt` = wiki/health watch (**independent** — wiki file lists never collapse the map)
Expand Down
111 changes: 68 additions & 43 deletions file_health.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,16 +1,16 @@
{
"version": 2,
"last_updated": "2026-09-04 06:17:32",
"last_updated": "2026-09-11 06:38:37",
"entries": {
"skills/run.md": {
"status": "🟢 Green",
"last_updated": "2026-08-27 11:15:12",
"reason": "4.6.13 plan WP0–WP7 wiki/protocol aligned",
"wiki_content_hash": "sha256:30f6da4a7b46920c1255c339c4c976c43c3323c6a66f03aed9a5e34cca197e04",
"source_content_hash": "sha256:30f6da4a7b46920c1255c339c4c976c43c3323c6a66f03aed9a5e34cca197e04",
"last_meaningful_edit": "2026-08-27 11:14:42",
"last_wiki_refresh": "2026-08-27 11:15:12",
"freshness_provenance": "record-meaningful-edit:2026-08-27 11:14:42 | 4.6.13: close-the-loop mark-green; relative monitors; mark-green:2026-08-27 11:15:12 (wiki hash captured); wiki=run.md"
"last_updated": "2026-09-11 06:37:25",
"reason": "Protocol v0.6.1 notes and language depth table.",
"wiki_content_hash": "sha256:4660244d3ed7b22c8d8bdb3e9473a0cafb0e3bff71b1fde7ef392e49cccc2abc",
"source_content_hash": "sha256:4660244d3ed7b22c8d8bdb3e9473a0cafb0e3bff71b1fde7ef392e49cccc2abc",
"last_meaningful_edit": "2026-09-11 06:37:17",
"last_wiki_refresh": "2026-09-11 06:37:25",
"freshness_provenance": "record-meaningful-edit:2026-09-11 06:37:17 | Protocol v0.6.1 additive 4.6.x field notes including sqlite-empty vs cache_backend none; language depth table (subid=hon; mark-green:2026-09-11 06:37:25 (wiki hash captured); wiki=run.md"
},
"Findings/Milestones-Overview.md": {
"status": "🟢 Green",
Expand Down Expand Up @@ -57,13 +57,13 @@
},
"README.md": {
"status": "🟢 Green",
"last_updated": "2026-08-27 11:15:12",
"reason": "4.6.13 plan WP0–WP7 wiki/protocol aligned",
"wiki_content_hash": "sha256:ea07d5a76184443393d655eb09084e42d7f6d521f0168fe8e56f043b441327e9",
"source_content_hash": "sha256:ea07d5a76184443393d655eb09084e42d7f6d521f0168fe8e56f043b441327e9",
"last_meaningful_edit": "2026-08-27 11:14:42",
"last_wiki_refresh": "2026-08-27 11:15:12",
"freshness_provenance": "record-meaningful-edit:2026-08-27 11:14:42 | 4.6.13 test count; mark-green:2026-08-27 11:15:12 (wiki hash captured); wiki=README.md"
"last_updated": "2026-09-11 06:37:25",
"reason": "Deep/ACS vs regex-hint language table.",
"wiki_content_hash": "sha256:10dc0533d5f4db138e593d63173d2d016173976274bf0e47e3ef2d38664d08ff",
"source_content_hash": "sha256:10dc0533d5f4db138e593d63173d2d016173976274bf0e47e3ef2d38664d08ff",
"last_meaningful_edit": "2026-09-11 06:37:17",
"last_wiki_refresh": "2026-09-11 06:37:25",
"freshness_provenance": "record-meaningful-edit:2026-09-11 06:37:17 | Language table: deep/ACS vs regex hint; protocol v0.6.1 (subid=honest-map).; mark-green:2026-09-11 06:37:25 (wiki hash captured); wiki=README.md"
},
"wikifier/mcp/server.py": {
"status": "🟢 Green",
Expand Down Expand Up @@ -134,23 +134,23 @@
},
"CHANGELOG.md": {
"status": "🟢 Green",
"last_updated": "2026-08-27 11:15:12",
"reason": "4.6.13 plan WP0–WP7 wiki/protocol aligned",
"wiki_content_hash": "sha256:7a0a54cb4ea5a95815dad3dad5d2e841c74b5b1a47e5cc9b193c96e1a50b7b1c",
"source_content_hash": "sha256:7a0a54cb4ea5a95815dad3dad5d2e841c74b5b1a47e5cc9b193c96e1a50b7b1c",
"last_meaningful_edit": "2026-08-27 11:14:42",
"last_wiki_refresh": "2026-08-27 11:15:12",
"freshness_provenance": "record-meaningful-edit:2026-08-27 11:14:42 | 4.6.13 Keep a Changelog; mark-green:2026-08-27 11:15:12 (wiki hash captured); wiki=CHANGELOG.md"
"last_updated": "2026-09-11 06:37:25",
"reason": "Unreleased honesty notes.",
"wiki_content_hash": "sha256:3a12d8851eaa663ea26b6997143b39b66efb6768dea5965bbae73e104771dbad",
"source_content_hash": "sha256:3a12d8851eaa663ea26b6997143b39b66efb6768dea5965bbae73e104771dbad",
"last_meaningful_edit": "2026-09-11 06:37:17",
"last_wiki_refresh": "2026-09-11 06:37:25",
"freshness_provenance": "record-meaningful-edit:2026-09-11 06:37:17 | Unreleased: library.md honesty, protocol v0.6.1, language table (subid=honest-map).; mark-green:2026-09-11 06:37:25 (wiki hash captured); wiki=CHANGELOG.md"
},
"CLAUDE.md": {
"status": "🟢 Green",
"last_updated": "2026-09-04 06:17:32",
"reason": "live hash synced; case-ghost Claude.md pruned",
"wiki_content_hash": "sha256:aa4eed92d69d7575c1d26beb9cc7852d2596cb771d65cea576374fd425856445",
"source_content_hash": "sha256:aa4eed92d69d7575c1d26beb9cc7852d2596cb771d65cea576374fd425856445",
"last_meaningful_edit": "2026-09-04 06:17:31",
"last_wiki_refresh": "2026-09-04 06:17:32",
"freshness_provenance": "record-meaningful-edit:2026-09-04 06:17:31 | re-baseline live hash after Claude.md case-ghost retirement; mark-green:2026-09-04 06:17:32 (wiki hash captured); wiki=CLAUDE.md"
"last_updated": "2026-09-11 06:37:25",
"reason": "Protocol pointer v0.6.1.",
"wiki_content_hash": "sha256:d2a708614ef48b5d1dd0f7bda001f9fff0b65f30f004513200636c00125bcc0d",
"source_content_hash": "sha256:d2a708614ef48b5d1dd0f7bda001f9fff0b65f30f004513200636c00125bcc0d",
"last_meaningful_edit": "2026-09-11 06:37:17",
"last_wiki_refresh": "2026-09-11 06:37:25",
"freshness_provenance": "record-meaningful-edit:2026-09-11 06:37:17 | Point agent contract at protocol v0.6.1 (subid=honest-map).; mark-green:2026-09-11 06:37:25 (wiki hash captured); wiki=CLAUDE.md"
},
"wikifier/__init__.py": {
"status": "🟢 Green",
Expand Down Expand Up @@ -223,11 +223,13 @@
},
"wikifier/library.py": {
"status": "🟢 Green",
"last_updated": "2026-08-01 11:25:15",
"reason": "gap amendment 4.6.9 closed-when verified (subid=gap-amendment-closure)",
"source_content_hash": "sha256:6312ddc20cd7cd1adef0ec2e5e9818c5030d57ddf1dc49e0384952cf03681ad4",
"last_wiki_refresh": "2026-08-01 11:25:15",
"freshness_provenance": "upsert:🟡 Yellow (non-freshness path); mark-green:2026-08-01 11:25:15 (wiki hash captured)"
"last_updated": "2026-09-11 06:38:32",
"reason": "Wiki captions handle **Role:** as well as ## Purpose.",
"wiki_content_hash": "sha256:89e1fc5b8dbfddb8306f55135392fb5bf5faa5d2e18177285d89f26a649665b8",
"source_content_hash": "sha256:edd02e80508eb135e50681b05307fd2a0e8d269278171f9b2c1d4cf10975a8f6",
"last_meaningful_edit": "2026-09-11 06:38:12",
"last_wiki_refresh": "2026-09-11 06:38:32",
"freshness_provenance": "record-meaningful-edit:2026-09-11 06:38:12 | Match **Role:** wiki captions (colon inside bold) so tree lines are not Role:** leftover (subid=honest-map).; mark-green:2026-09-11 06:38:32 (wiki hash captured); wiki=library.py.wiki.md"
},
"wikifier/parsers/javascript.py": {
"status": "🟢 Green",
Expand Down Expand Up @@ -291,9 +293,13 @@
},
"library.md": {
"status": "🟢 Green",
"last_updated": "2026-06-10 20:20:38 AEST",
"reason": "Verified: endpoint whitelist + Origin/Host 403s + clean shutdown via curl; headless DOM on all 9 projects x 3 modes (exec/static/file): map renders, exec chip + Stop button, no Tailwind, no active errors; 30/30 tests",
"source_content_hash": "sha256:f3f717512ac8c856b79d46d5d47906fdb3f2311025be1bc65186bc3b751bbe2e"
"last_updated": "2026-09-11 06:38:37",
"reason": "Committed map matches live tree after update-maps --full.",
"wiki_content_hash": "sha256:5ced31b3d5598e13d38877627603fcd813d425531c1b3b555c80e1a5211afc03",
"source_content_hash": "sha256:5ced31b3d5598e13d38877627603fcd813d425531c1b3b555c80e1a5211afc03",
"last_meaningful_edit": "2026-09-11 06:38:37",
"last_wiki_refresh": "2026-09-11 06:38:37",
"freshness_provenance": "record-meaningful-edit:2026-09-11 06:38:37 | Regenerated from full update-maps on live tree; 4.6.10 leftovers gone (subid=honest-map).; mark-green:2026-09-11 06:38:37 (wiki hash captured); wiki=library.md"
},
"screenshot/front_page_review.png": {
"status": "🟢 Green",
Expand Down Expand Up @@ -565,12 +571,12 @@
},
"wikifier/agent_loop.py": {
"status": "🟢 Green",
"last_updated": "2026-08-27 11:15:11",
"reason": "4.6.13 plan WP0–WP7 wiki/protocol aligned",
"source_content_hash": "sha256:e08d0f9d3d7ffd57a544277a7ddb7342abd0d216cd4b846f6878b4f1126e7a4a",
"last_meaningful_edit": "2026-08-27 11:14:41",
"last_wiki_refresh": "2026-08-27 11:15:11",
"freshness_provenance": "record-meaningful-edit:2026-08-27 11:14:41 | 4.6.13: emit mark_green action for recorded yellows; mark-green:2026-08-27 11:15:11 (wiki hash captured)"
"last_updated": "2026-09-11 06:37:25",
"reason": "Bootstrap cache_backend refresh; cache_empty / cache_files_indexed additive.",
"source_content_hash": "sha256:feb6a159759552f27af71035557515ca6f367df7e0277df99b769814c27b7893",
"last_meaningful_edit": "2026-09-11 06:37:17",
"last_wiki_refresh": "2026-09-11 06:37:25",
"freshness_provenance": "record-meaningful-edit:2026-09-11 06:37:17 | Refresh cache_backend after ACS persist; add cache_empty and cache_files_indexed so sqlite-empty is not none (subid=hone; mark-green:2026-09-11 06:37:25 (wiki hash captured)"
},
"tests/test_agent_loop.py": {
"status": "🟢 Green",
Expand Down Expand Up @@ -971,6 +977,25 @@
"last_meaningful_edit": "2026-08-27 11:27:44",
"last_wiki_refresh": "2026-08-27 11:27:44",
"freshness_provenance": "record-meaningful-edit:2026-08-27 11:27:44 | 4.6.13: status tools wrap health/cache in call_with_deadline; mark-green:2026-08-27 11:27:44 (wiki hash captured); wiki=status_ops.py.wiki.md"
},
"tests/test_library_map_honesty.py": {
"status": "🟢 Green",
"last_updated": "2026-09-11 06:38:32",
"reason": "Caption **Role:** unit test.",
"source_content_hash": "sha256:c9e8e37d44908971ee3167281d1934186d71f8ed97d73ab9019cb1afec616165",
"last_meaningful_edit": "2026-09-11 06:38:32",
"last_wiki_refresh": "2026-09-11 06:38:32",
"freshness_provenance": "record-meaningful-edit:2026-09-11 06:38:32 | Cover **Role:** wiki caption parsing (subid=honest-map).; mark-green:2026-09-11 06:38:32 (wiki hash captured)"
},
"wikifier/library.py.wiki.md": {
"status": "🟢 Green",
"last_updated": "2026-09-11 06:37:25",
"reason": "Generator wiki current.",
"wiki_content_hash": "sha256:89e1fc5b8dbfddb8306f55135392fb5bf5faa5d2e18177285d89f26a649665b8",
"source_content_hash": "sha256:89e1fc5b8dbfddb8306f55135392fb5bf5faa5d2e18177285d89f26a649665b8",
"last_meaningful_edit": "2026-09-11 06:37:18",
"last_wiki_refresh": "2026-09-11 06:37:25",
"freshness_provenance": "record-meaningful-edit:2026-09-11 06:37:18 | Wiki for library.md generator: live-path filter and wiki captions (subid=honest-map).; mark-green:2026-09-11 06:37:25 (wiki hash captured); wiki=library.py.wiki.md"
}
}
}
Loading