feat(context): tag audit sub-check — inventory @FLOW/@ENTRY doc-tags (closes #305) - #307
Merged
Conversation
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
…convention (closes #305) The @WHO/@WHAT/@PART/@entry + @FLOW/@CALLS/@mutates convention is used across the codebase (46/236 .py files carry the header, 21 named flows) but nothing read it back, so the data rotted: two flows (LLM_INVOKE, LLM_TOOL_INVOKE) still name code whose command was dropped in #195. `context --check tags` answers three questions from the tags already in the source, inventing nothing: flow inventory + locations, header coverage (full/partial/none), and the untagged-file list. Pure regex, no LLM, no network, all collections sorted — deterministic. A tag counts only when it opens a comment/docstring line (marker + whitespace + @tag:), so a prose mention like `the `@FLOW: PURE` example` is not mistaken for a declaration — without that anchor, any file documenting the convention (this engine included) registered phantom flows. Caught by dogfooding. Read-only by design: never writes tags back. Auto-tagging and staleness-by-body-hash are out of scope (deciding a tag's value is authorship, which for a no-LLM tool belongs to the human/agent). Reuses BaseEngine for the walk — no new walker. Command count stays 12 (sub-check, not a top-level command). Registry allowlist, docs sync (#278), and command-count gates all green; full suite 19 failures = 19 on main, identical list. Known limitation: markdown/ai formats render the context umbrella empty (pre-existing, all sub-checks) — tracked in #306. json/compact correct. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #305.
Masalah
Konvensi
@WHO/@WHAT/@PART/@ENTRY(file) +@FLOW/@CALLS/@MUTATES(fungsi) dipakai lintas codebase — 46/236 file .py, 21 flow bernama — tapi nol tooling membacanya. Datanya membusuk:LLM_INVOKE/LLM_TOOL_INVOKEmasih menamaiscripts/llm/padahal commandllmdi-drop di #195.Yang ditambahkan
context --check tagsmenjawab tiga pertanyaan dari tag yang sudah ada di kode, tanpa mengarang:@FLOWunik + lokasinyaMurni regex, nol LLM, nol network, semua koleksi ter-sort → deterministik.
Keputusan desain
@TAG:). Ini memisahkan deklarasi nyata dari penyebutan prosa sepertithe `@FLOW: PURE` example— tanpa anchor ini, file mana pun yang mendokumentasikan konvensi (engine ini sendiri!) mendaftarkan flow hantu. Ditemukan lewat dogfooding saat self-scan mengembalikanPUREfantom.BaseEngineuntuk walk — nol walker baru.#(Python) dan//(TS/JS).Verifikasi (dijalankan)
TAG_AUDITmilik file ini), 46 file header, dua orphanLLM_*tersurface dengan lokasi.PUREfantom hilang setelah anchor diperketat.tests/test_tag_audit.py) dengan fixture sintetis (bukan cuma self-scan): full/partial/no header, penolakan prosa, tokenisasi nama flow, determinisme, read-only (mtime tak berubah).context --check tagsexit 0, envelope{s,st,r}benar,compact9.5KB lengkap — pada scan repo penuh munculwith_partial_header: 5(deteksi header parsial bekerja pada data nyata).sync_command_count --checkbersih.main, daftar identik — nol regresi.Batasan diketahui (tracked)
--format markdown+--format aimerender umbrellacontextkosong ("Symbol not found") — pra-eksisting, semua sub-check context, bukan bug fitur ini. Difile sebagai #306.json/compact(agent-facing) benar.Feature-class → design doc
docs/design/0305-tag-audit.mddisertakan.🤖 Generated with Claude Code