Repository navigation
kb init: adapt seeds of any page type and report spend in the PR body - #256
Merged
Merged
Conversation
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
Stage 1 of kb init (design kb-init v3): bootstrap a repository's knowledge base from its docs and seed pages, as one human-merged PR. - init_budget: hard per-stage ceiling by reservation. A generator call reserves threshold + one worst-case request (claude's --max-budget-usd only stops the next request); models without a price are refused before any call. Judge calls are accounted at a fixed cost. - init_support: InitRuntime (never KbRuntime, so never kb.db), the per-stage InitRecord, the upstream pin (bare mirror; the pin defaults to the mirror's HEAD, i.e. the upstream default branch, never an assumed main; safe export; PinnedObserver), model calls through the budget, claim/evidence and outside-knowledge path checks, the CI knowledge validators on the result, and InitPublisher (one deterministic commit on an exact base, pushed to a branch that must not exist, PR via the owner's gh; or a local dry run). Writes need ALLOW_PUSH=1, ALLOW_POST=1 and KB_INIT_GIT_AUTHOR (checked before any model call); private upstreams are always dry runs. INIT_PATHS allows knowledge/repos/_index.md, the shared list a new repository joins. - init_stages: run_stage + validate_change (the only check_changeset(bootstrap=True) caller). Skeleton: map call (entry page, architecture page, routes, general links), doc-invariant rules, adapted seed pages. Every rule is D5-filtered, evidenced and checked at the pin, then PLACED on a running tree before judging (a page that fills up sends the rule to a sibling page), so the advisory judge sees each rule where it is written; fail verdicts are stripped. Existing pages are only appended to; routes start from owners read deterministically from existing sub-directory entry pages (code paths they name that exist at the pin); findings on existing pages go to the PR checklist; a failed push is recorded as blocked. suggest_seeds ranks candidates without a model call. - InitConfig gains generator_call_usd and harness_overhead_bytes; build_doc_corpus takes optional globs (doc_files). - knowledge.init step, kb-init playbook, `kb init REPO --stage S [--dry-run] [--pin SHA]` and `kb init REPO --suggest-seeds`, dispatched before any ledger is opened. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
L1 reads any line starting with "## <Word>" as a rule ID (lifecycle.RULE_HEADING / ANY_RULE_HEADING), so a model-written "## Overview" or "## SERV-1 — x" in architecture.md or the entry page intro could collide with real rule IDs or masquerade as a rule. Every non-rule page the skeleton writes now goes through neutral_headings: an ATX heading outside code becomes a bold paragraph, any other line that starts with "#" is escaped, and such a line inside a fence is indented by one space. No line starts with "#", so the rule regexes (all anchored at column 0) can never match. The entry page's list heading is bold too. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Stage 2 of kb init (design v3 §7.1-7.2): route every code module. - init_stages: the skeleton's flow becomes a _Stage base shared by every stage (pin, record, rule screening and placement, the deterministic checks as _conclude, the publication); _Skeleton keeps only its own steps. New: the stage chain. Each earlier stage must be merged (record published and gh pr view MERGED, so main holds it), or, for a dry run of this stage, dry-run: its snapshot is overlaid on main as the base and handed to the knowledge validators with this stage's change. A stage with nothing to change is recorded "empty", not blocked. Later stages keep the earlier stages' pin unless --pin says otherwise. - init_modules: scan_modules_at_depth at the pin (language from the adapter's repo.language; none or unknown -> no scan, checklist). A module an owner partly reaches is absorbed: its prefix is appended to that owner's scope_prefixes. Every other module gets one bounded generator call (file names, signatures, leading docstrings, never bodies) and a map card: a prose page (type architecture) in an existing components/<group>/ (index append-only) or a new group with its own _index.md and route owner, linked upward. Sections are bold labels: the knowledge format reads any "## <Word>" heading as a rule ID. The route table is only appended to (routes_append_only). Budget or card cap -> the cards written so far still make a PR; the rest is listed. - InitRecord.coverage: the stage's coverage report, rendered as a before/after table in the PR body. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Stage 3 of kb init (design v3 §7.3, §9 PR 3). - UpstreamPin.first_parent_changes: the PR window, read offline from the mirror: the files each of the last pr_window_count first-parent commits up to the pin changed, no older than pr_window_max_age_days before the PIN's commit time (a function of the pin, never of the clock). - init_deepen: modules by churn in the window, highest first. A module no route reaches, or whose owner already bears rules (the page itself, or a page in the same directory, has an active rule), is skipped. Every other module gets one generator call that reads its code at the pin (numbered, byte-bounded) and proposes rules with line-ranged evidence, which must lie inside the module. They go through the shared screening (D5, pinned evidence and claims, placement, advisory judge) and are appended to the owner's rule page, or rules.md beside it; existing rules are never edited. Stops at coverage_target (rule-bearing PR-weighted), when the budget runs out, or at the end of the list. The record reports routed and rule-bearing coverage before/after and the hot paths still without rules. - The shadow flip in the same PR: flip_to_shadow edits exactly the enabled / mode lines of the adapter's knowledge_lifecycle block (inserting enabled under the header if missing); comments and every other line are kept. _check_flip accepts only that manifest, check_flip_to_shadow, and parse_lifecycle on the head (on, shadow, same knowledge dir). A manifest without the block blocks before any model call. - init_modules.scan_modules is now a module function both stages use. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The last kb init stage (design v3 §11). After the deepen PR merged (a dry run chains on the dry-run snapshots), it compares what the advisory judge said about every rule init wrote with what the owner merged, and proposes adapters/<adapter>/kb-calibration/cases/*.json plus knowledge_lifecycle.calibration_set: kb-calibration as its own PR. - Stage records now keep the judged rule text and its pinned evidence in each verdict, so rules the judge stripped or the owner deleted can be turned into cases. - Labels follow the design table: kept pass/unsure/unjudged -> good (source owner); stripped fail -> bad (source judge); deleted or rewritten pass -> bad with override; deleted or rewritten unsure/unjudged -> bad (source owner). A rewritten rule's case holds the text the judge saw. - Cases are self-contained in the load_cases shape: the page without the rule as base, the judged text re-applied through apply_operations as head, evidence re-read from the pinned mirror. A case that does not pass L1 on its own is left out and noted. Case IDs carry the stage: an ID one stage's judge stripped can be reassigned by a later stage. - Deterministic mutations of good rules (broken path claim, shifted evidence range, negated invariant, a sibling module's evidence) balance the set and top owner-sourced bad cases up to five (a broken path must really be absent at the pin, a moved range must show different text); with fewer than five bad cases from the owner or from mutations the stage is blocked, since the judge's own fails cannot calibrate it; so it is with no good case at all (kb calibrate never passes without one). - The manifest edit is one line (set_calibration_set), checked with check_lifecycle_flip(allowed=CALIBRATION_KEYS) and parse_lifecycle; existing cases are never overwritten. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
tzhouam
force-pushed
the
kb/init-harvest
branch
from
September 30, 2026 15:37
c9c7100 to
a260acd
Compare
Found by the first afd-plugin pilot (skeleton, dry run): - The adapter's repos/ seed was a type: guide page; the skeleton only adapted type: rule pages, so it was skipped with no trace, which the design forbids (a seed is never skipped silently). Any content page a seed names is now adapted (indexes are navigation, not content). A seed naming no content page goes on the checklist, a page that transfers no rule goes in the notes, and a budget stop lists that seed and every one after it as unfinished. - The PR body said "Model spend (accounted): $0.00" while the record held $7.42: spent_usd was written in the stage's finally block, after the body was rendered. It is now written before rendering. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
tzhouam
force-pushed
the
kb/init-pilot-fixes
branch
from
September 30, 2026 15:37
66d3231 to
81b8a48
Compare
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
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.
Summary
Two defects found by the first real kb init pilot (afd-plugin, skeleton stage, dry run):
repos/vllm-omni/rebase/upstream-api-drift.mdis atype: guidepage; the skeleton only adaptedtype: rulepages, so the seed produced nothing and left no trace (design §4: never carried over silently). Now any content page a seed names is adapted (_index.mdexcluded); a seed naming no content page goes on the checklist, a page that transfers no rule goes in the notes, and a budget stop lists that seed and every later one as unfinished.spent_usdwas written in the stage'sfinally, after the body was rendered. It is now written before rendering.Pilot result (afd-plugin skeleton, dry run, before this fix)
12 doc-invariant rules generated; advisory judge: 5 pass, 6 unsure, 1 fail stripped (AFD-I6: claimed
closesafe "in any state" while the docs require stopping work first)._routes.yamlcreated with 6 owners seeded deterministically from existing component pages. Spend $7.42. A first attempt blocked on a JSON reply with raw newlines in a string — fixed separately in #255.Tests
6 new tests in
test_kb_init_skeleton.py(guide seed adapted, directory seed skips its index, index-only seed reported, no-transfer seed reported in notes + body, budget stop lists every remaining seed, body spend equals the record). Commit gate approved; local CI mirror green.Stacked on #254 (kb/init-harvest).
🤖 Generated with Claude Code