willtools-demo/CLAUDE.md

pyrevit-dev — you are wired to a live Revit session

You were launched from a button inside Revit. Revit is running right now, with a model open, and you can read and modify it directly. Use that — do not write Revit code you have not run.

Engine: IronPython 2.7.12. The Revit and pyRevit versions differ between the machines this is developed on (2025.4 / pyRevit 6.5.3 on one, 2024.3 / pyRevit 5.0.1 on the other), so ask rather than assume — rvt.py status answers it — and guard any API name that moved between versions. Two already known: BrowserOrganization.GetFolderFields() does not exist on the older binding, and Dimension.Curve throws on drafting views.

---

1. Talking to the running Revit

python tools/rvt.py status                        # which model is open
python tools/rvt.py exec -c "print(doc.Title)"    # run a line inside Revit
python tools/rvt.py exec somefile.py              # run a file inside Revit
python tools/rvt.py exec somefile.py --tx "名字"   # wrap in a transaction
python tools/rvt.py sel                           # what the user has selected
python tools/rvt.py collect OST_Walls --limit 20
python tools/rvt.py params 123456                 # every parameter of one element

exec returns {ok, stdout, result, error, traceback} — real stack traces, so iterate until it works. Snippets get doc, uidoc, uiapp, view, DB, UI, vibe, and the common Revit types pre-imported. Assign to result (or make the snippet a single expression) to send a value back.

If status cannot connect: Revit is closed, or a modal dialog is open in Revit — handlers run in Revit's API context and cannot fire behind a dialog. Say so rather than guessing.

Every answer is checked against the request that asked for it

Since 2026-09-01 rvt.py stamps every request with an id (in the JSON body, GET routes included — request headers never reach handler code either), startup.py echoes it back, and an answer carrying a different id is refused outright: both ids named, nothing returned. The reason is that pyRevit serves every route through one shared response slot — routes/server/server.py's module-level REQUEST_HNDLR / EVENT_HNDLR, whose single _response/_done pair every connection thread resets, waits on and reads — so a client-side timeout cancels nothing, and the abandoned request's late answer is handed to whoever asks next. Measured that day, twice: one sweep call timed out at 300s, and the doc.Title calls after it came back with the sweep's progress string, which the sweep printed as the document title and an agent read as the model having changed underneath it. The files on disk were right; only the attribution was wrong, and a response from the wrong request is indistinguishable from a valid answer. So a timeout is now an explicit could-not-judge (exit 1, COULD NOT JUDGE, no value) that latches the channel in .bridge-timeout-<port>.json; the next call drains the stale answer out of that slot with a self-identifying probe before it sends anything real, and refuses to send at all if the channel cannot be proven clean. An in-Revit half that echoes no id — which is every session until Revit is restarted after this lands — is warned about on stderr and flagged _unverified in the body rather than refused, because a restart is the only way to load the new half and refusing would take the bridge down for every tool in the meantime; pass --strict (or set WILLTOOLS_BRIDGE_STRICT=1) to refuse instead.

The bridge can now REFUSE, and a refusal is not a fault

Since 2026-09-01 every route — /status included — refuses outright when the open document's title is on bridge.refuse_titles in the job or plant layer. That is the owner's 不要碰我的live written as code. The answer comes back {"ok": false, "refused": true, "doc_title": ..., "pid": ..., "error": "REFUSED: …"} and it means you reached the live session, not the sandbox. Do not retry it, do not work around it, and do not go looking for another way in.

The owner reversed that policy the same day, for the model it protects. A title on bridge.readonly_titles instead is served normally through the bridge — including /exec — but only for reads: the iron rule is 铁律是在 live里面只读不写, and /exec refuses outright when the request carries a transaction or the snippet matches known write-capable Revit API surface, coming back the same refused: true shape as above with a one-line reason naming the title and the rule, never a silent no-op.

Why it can happen when you did nothing wrong: pyRevit walks the routes port up from the configured one past every Revit already holding one, so 48884 is "whichever Revit started first" rather than the session you meant. With two sessions open the sandbox is usually on 48885 — and its doc.Title is identical to the live model's, because the snapshot deliberately keeps the title so the job folder does not move. rvt.py reads WILLTOOLS_BRIDGE_PORT; set it, or let tools/snapshot_cycle.py find the right session for you. The whole mechanism, including how a snapshot proves it is a snapshot, is in docs/snapshot-cycle.md.

Never reload pyRevit. Restart Revit instead.

This is the single most important rule here, and it is not a style preference — it kills Revit outright.

pyRevit's routes request handler is an external event handler owned by the scripting engine that first loaded it. reload_pyrevit() tears that engine down but leaves the handler and the HTTP server pointing at it. The next bridge request after any reload executes against a dead engine and takes Revit down — an unhandled exception on a non-main thread, which Revit cannot catch. Measured on 2026-08-14: 11 clean requests, one reload, the 12th request fatal. It happened twice.

Nothing inside Revit can defend against this — our code never gets to run. So:

• There is no /reload endpoint, and rvt.py reload refuses.
• startup.py appends a line to .bridge-sessions.log on every pyRevit load.
• rvt.py reads that log before every request and hard-refuses if it sees two loads under the same Revit process.

If rvt.py tells you the bridge is unsafe, do not work around it, do not curl the endpoint directly. Ask the user to restart Revit. A restart picks up new buttons exactly as well as a reload does, and a fresh process is safe.

If rvt.py warns that there is no session log while Revit is clearly running, the tripwire itself is broken — say so and do not reload.

---

2. Layout

pyrevit-dev/
├── CLAUDE.md                     ← you are here
├── INSTALL.md                    deploying to another machine / Revit version
├── tools/rvt.py                  client for the live bridge
├── tools/package.py              builds dist/willtools-<ver>-<date>.zip
├── tools/sweep.py                check every WP assembly in the open model
├── tools/snapshot_cycle.py       make a timestamped detached copy, cycle a
│                                 Revit onto it, run a batch, close it
├── docs/snapshot-cycle.md        …and why the detach is not done in-session
├── docs/revit-api-cheatsheet.md  working Revit 2025 patterns — read when stuck
├── docs/interference.md          why the clash check is shaped the way it is
├── docs/lift-check.md            the handling check, and what it will not answer
├── docs/handoff.md               open engineering questions, the last sweep,
│                                 what to pick up first
├── knowledge/catalogue.yaml      published hardware ratings (ships with the tool)
├── panellift/                    PCI Ch.8 handling checks — CPython, own suite
│   ├── src/panellift/cli.py      `python -m panellift job.json -o report.html`
│   └── src/panellift/layout.py   where the inserts should go instead
└── WillTools.extension/
    ├── startup.py                registers the bridge (no UI)
    ├── lib/vibe/
    │   ├── helpers.py            q() p() set_p() tx() ft() mm() selected() ...
    │   ├── compat.py             text_type / string_types — py2+py3 shim
    │   ├── designspec.py         evidence scrape, spec schema, spec io
    │   ├── aiextract.py          the AI reader — NOT the extractor any more
    │   ├── knowledge.py          knowledge.yaml → defaults, family rules
    │   ├── configdump.py         all five layers flattened into one file
    │   ├── configmodel.py        what may be edited, its provenance, the splice
    │   ├── liftexport.py         assembly → panellift job file, and runs it
    │   ├── ticketqc.py           reads tickets, the comparison checks
    │   ├── ticketchecks.py       the checks that need arithmetic
    │   └── ticketqc_run.py       the shared engine behind TicketQC and
    │                             ReinforcingQC (a `mode` parameter apart)
    └── WillTools.tab/             the ribbon — "Folder names are the UI"
        │                          below is the whole of how it is built
        ├── Tools.panel/           Modeling.pulldown/ — ReinforceSuggest,
        │                          ReinforcingQC, TicketQC — plus
        │                          SnapshotClose as the one remaining large
        │                          icon (reorganised 2026-09-05; this panel
        │                          used to hold all four as large icons)
        ├── Setup.panel/           Config.pulldown/ — one large button with a
        │                          dropdown arrow: ProjectConfig,
        │                          ExtractDesign, SelfCheck, JobRecon,
        │                          Takeoff
        ├── Design.panel/          DesignHub.pulldown/ — PanelLiftCheck and
        │                          PanelAnalysis (both finished, both grouped
        │                          here on the owner's own instruction), then
        │                          BeamAnalysis, ConnectionAnalysis,
        │                          GravityLoadChase and LateralExtract, all
        │                          four unfinished and titled "(WIP)"
        └── Lab.panel/             GodMod — the button that launched you.

aiextract no longer extracts anything. Design Extract was rewritten to read the scrape in-process with ticketqc's regex/geometry parser — its own header says "no AI call, no subprocess, nothing that leaves this process" — and it imports designspec, ticketqc, knowledge and specsave, not this. The module is kept, and its only live callers are find_claude(): Self Check probes with it to say whether the CLI is on this machine, and the GOD_MOD button uses it to find the CLI it launches. The prompt, the claude -p spawn and the cross-check are all still there and nothing calls them. Spec files written before the rewrite can still carry source.extractor: 'opus' (or the older 'claude-code'); the mechanical reader stamps 'regex'. Nothing branches on which of the three it finds — the field is displayed, in Design Extract's own spec table, and never acted on — so anything touching it has to tolerate all three. Do not describe this module as the extractor.

panellift is not importable from Revit and that is deliberate. It is CPython — dataclasses, typing syntax — and the extension is IronPython 2.7. The two talk through a JSON job file, so the engineering can be tested without a licence, a model, or Windows. vibe.liftexport is the whole Revit side of that boundary: it measures the piece, writes the job, shells out to CPython, and reads the summary back. Anything about mechanics belongs on the far side of that line; anything about this model belongs on this side.

Most of vibe does not touch Revit at module scope either — only at the top of individual functions that need a live doc (knowledge.load(), liftexport.export(), and anything that reaches for vibe.designspec / vibe.ticketqc, which import the Revit API directly). That leaves real logic testable with no model and no licence, the same way panellift is. WillTools.extension/tests/ is 34 files covering about thirty of the vibe modules — ticketpage, knowledge, the host-side half of ticketchecks, the configmodel / configform / configpage set, the reinforce* and takeoff* sets, the part of liftexport.py below export(), and more — run straight on host CPython:

cd WillTools.extension && python -m pytest
python -m pytest                    # from the repo root: this suite + panellift

Run it; do not quote a count from here. The count in this paragraph has been wrong every time anybody has checked it — the suite grows daily, and on 2026-08-31 the root total moved twice in one afternoon while several agents were working. For scale only, and only that: it was roughly 1,800 under WillTools.extension and roughly 2,100 from the repo root that day. The root run also sweeps _scratch/, which is gitignored agent working space, so its total moves for reasons that have nothing to do with the tool.

One test fails on a configured machine and it is the test that is wrong. tests/test_reinforceoffline.py::test_no_index_and_no_jobs_root_says_all_three_ways_to_give_one calls resolve_index(None, None, None) expecting the "no jobs root" refusal, but resolve_index falls back to the ambient WILLTOOLS_JOBS, so on any machine that actually has the tool set up it gets the "which model?" refusal instead. It passes under env -u WILLTOOLS_JOBS. Nothing in the tool is broken; the test needs to clear the variable. Measured 2026-08-31, not yet fixed — so a green suite here is everything passing except that one, and one failure is not automatically your change.

WillTools.extension/tests/conftest.py is how: it loads a module by path instead of import vibe.whatever, because vibe/__init__.py pulls in the Revit API the moment it runs. Read the docstring there before adding a test for a new module — it explains exactly which shape of code this can and cannot reach, and ticketqc.py / ticketchecks.py are the standing example of code that cannot: they import Autodesk.Revit.DB at module scope, not just inside a function, so freeing them needs more than moving an import.

Ticket-QC data lives beside the model, not here: <model folder>/_ticketqc/{evidence,specs,log}/ + knowledge.yaml.

Knowledge is read in five layers, each overriding the one before:

knowledge.DEFAULTS	what the code assumes — in this repo
knowledge/catalogue.yaml	published hardware ratings — in this repo, identifies nobody
%APPDATA%\WillTools\knowledge.yaml	what this plant always does — naming conventions, casting-bed rails
<model folder>/_ticketqc/knowledge.yaml	what this job does — parameter names, tolerances, per-job overrides
the project config file	what the engineer set, wherever they put it — opt-in, and it wins

Only the first two are in the repository, and that is the point: between them the other three are a full description of one office's template. Set WILLTOOLS_KNOWLEDGE to put the plant layer on a share. knowledge.sources(doc) lists the layers; Self Check prints them.

Where the layers get their facts from: knowledge/library/. It is a drop folder for source PDFs — manuals, manufacturer catalogues, datasheets — plus a ledger with one row per document, keyed by content hash, recording what was extracted from it and which file and key path each fact landed in. The folder is gitignored as a folder (not merely by *.pdf), because the ledger and the extraction notes quote their sources verbatim and scrub.py cannot read a PDF; like knowledge/plant/ it is the other repository's territory, and scrub.py --private is what reads it. Idle capacity drains it by knowledge/library/RUNBOOK.md — inventory, extract with a page cite and a confidence mark on every fact, land, verify, report. The landing step is the point and it is the one that gets skipped: a 929-page manual was once mined into ten notes and a 25-fact audit of which almost nothing became YAML, and the owner ruled on it — "提取出来以后没有写入。今天不要再犯这个错误". A document read but not landed is a debt, not progress, and the ledger says so in the status column. python tools/library.py lists the folder against the ledger.

Extraction notes are clues, never sources — a number lands only off the page itself. Measured 2026-08-31: a cheap-model extraction pass over one document drop carried a 42% page-error rate on independently sampled pages — inverted inequalities, misidentified parts, specs blurred into vagueness — and the landing pass then caught three more errors the audit itself had missed, including a one-row table shift and a column read under the wrong heading. Three stages, none may collapse into another:

1. Extract with a page cite on every fact (cheap model is fine — speed is what it buys).
2. Audit independently — a different agent samples pages against the note. A sub checking its own family's work reported zero errors on the same material where the independent auditor found the 42%; self-audit is not audit.
3. Land off the page — any NUMBER moving from a note into a YAML layer is re-read against the rendered source page by the landing agent, cited # SOURCE: <doc> p.N, verified <date>. A number that cannot be confirmed lands as null with the reason and an open question — never as the note's value, never as a plausible reconstruction.

Then run python tools/knowledgelint.py. Landing is not finished until it passes. pyRevit's YAML reader is strict — one mapping key stated twice raises Duplicate key and it returns nothing — and a layer that fails to load looks exactly like a layer that agrees with the defaults. Measured 2026-09-01: one nested duplicate in a plant file discarded that whole 255KB layer inside Revit, every parameter role came back None, the sweep enumerated 0 assemblies, and every report rendered normally. The lint strict-parses every layer on this machine and exits 1 on any that will not load; knowledge.config_problems() and Self Check now say so too, but only after the file has already been written.

Where a table carries its own internal identity (a recommended value derived from two measured columns, a series that must be monotonic), assert the identity across the whole table at landing — it is the cheapest error detector there is, and it is what turned "one value off by one" into "the whole block is shifted a row".

knowledge.load() reads the job file twice, and that is not a bug. The job layer holds job.plant, which names which plant folder the plant layer is read from — but the plant layer merges before the job layer, so by the time the name is in the merged tree the plant file has already been read from the wrong path. The dependency runs backwards through the merge order and no reordering fixes it. So plant_id() reads the job file (and the config file above it, which can override the same key) once on its own, before anything merges, purely to answer "which plant" — then the ordinary five-layer merge runs. Do not collapse this into one pass. Deleting the pre-pass makes the tool read the machine-wide plant file while the job file plainly says which plant it is for, and every report still looks completely normal. _plant_layer_stale is the tripwire for exactly that, comparing the plant the file was chosen by against the plant the merged tree ends up naming. Same discipline as _config_missing: a named plant whose file is absent sets _plant_missing and never falls back to the machine-wide file.

The last layer is what the Project Config button writes. A model has one only once somebody has pressed that button, and the file goes wherever they choose — so a one-line pointer at <model>/_ticketqc/active-config.txt records where it is. It is deliberately last: it is the layer a human edited most recently and by hand.

Two rules around it, both learned the hard way in other tools:

• A pointer to a file that is gone must never fall back quietly. The run would use a configuration nobody chose and look completely normal. load() marks it _config_missing and knowledge.config_problems(doc, know) turns that into a sentence a button can refuse on.
• The file opens with decisions: — every setting that is the engineer's to make, gathered from wherever it is really read and put above everything else, each under its own comment. Where the reports go, whether they open, the prestress loss, the transfer length, and the per-stage rigging mode. knowledge._merge_decisions maps every one of them back on load. A file where editing the obvious place does nothing is a trap, so that mapping has to exist in both directions or the section is decoration.

Write for both Pythons. pyRevit picks the engine and this extension ships to machines whose engine we do not control, so on top of the IronPython 2.7 rules below: no unicode / basestring (use vibe.compat), and guard any Revit API name that moved between versions. python tools/package.py and INSTALL.md cover the rest.

Folder names are the UI: Foo.tab / Bar.panel / Baz.pushbutton / script.py, plus Bar.panel / Thing.pulldown / Baz.pushbutton for a pulldown. Copy GodMod.pushbutton as a structural template (not its contents).

*.stack also exists and this tab used two of them until 2026-08-30. Both are gone: a stack is up to three small buttons in one panel slot, and the owner wanted the set-up commands off the panel entirely rather than shrunk on it. Prefer a .pulldown — one large icon plus an arrow, unlimited rows, and the rows are free to carry readable titles because a row is text beside a 16px icon rather than a ribbon slot.

Which name renders, and from where — this is not uniform and guessing it wastes a Revit restart:

tab	the folder name. uimaker._produce_ui_tab calls create_ribbon_tab(tab.name); a title: in a tab bundle is ignored.
panel	the folder name, same reason (create_ribbon_panel(panel.name)). Rename the folder to rename the panel — spaces are fine, pyRevit ships panels with them.
stack	nothing renders. The folder name is only what the panel's layout: refers to it by.
pulldown	bundle.yaml's title: — unlike a stack, a pulldown container really does read one. genericcomps.GenericUIComponent._read_bundle_metadata sets _ui_title from it and uimaker._produce_ui_pulldown passes that to create_pulldown_button. With no title: it falls back to the folder name.
button	bundle.yaml's title:, and nothing else. __title__ in the script is the fallback pyRevit reads only if not self.meta, i.e. only for a button with no bundle.yaml at all — keep it in step anyway, or the old name comes back the day a bundle file is trimmed.

Order is layout: in the container's own bundle.yaml, a list of child folder names (minus their .panel / .stack / .pushbutton suffix), read by genericcomps.GenericUIContainer.parse_layout_metadata. The old _layout file is gone in pyRevit 5.0.1 — do not write one, nothing reads it. Two things about that list are worth knowing before it bites:

• A child not listed is not created. Not misordered — absent. Add a button, add it to the layout, or it silently never appears.
• "---" inserts a separator and ">>>" a slideout (everything after it hides behind the arrow at the panel's bottom-right). Both must be quoted — a bare > starts a folded block scalar and the panel fails to parse — and neither may be the last entry, because __iter__ only honours a marker whose index is below the last one.

A .pulldown needs its own icon.png or it renders blank. A pulldown is a component like any other — genericcomps resolves an icon.png for it, and _produce_ui_pulldown hands that to create_pulldown_button. When there isn't one, ribbon._create_button_group catches the icon error and only mlogger.debugs it, so you get an empty ribbon slot and no message anywhere. python tools/make_icons.py draws both of the tab's pulldown icons; run it and read its output, because it prints "skipped, no such component" for a path that has moved rather than failing.

Unfinished tools never sit on a panel with finished ones. Standing owner instruction, 2026-08-30. Design.panel is where they go — a panel of its own whose single button is the DesignHub pulldown, so nothing half-built is on screen until somebody opens it; the (WIP) suffix on the title is what names them once they do. (Until 2026-08-30 this was the slideout on Lab.panel. Same rule, better door: a slideout arrow is easy to miss and shares its panel with a working button, which is the thing the rule is against.) DesignHub also holds two FINISHED rows today, PanelLiftCheck and PanelAnalysis — the owner grouped them here on 2026-09-05 because he wants the analysis tools together, not because either stopped working; see that pulldown's own bundle comment.

A button that is finished but not wanted on screen used to move to WillTools.extension/parked/, outside every *.tab. That folder is gone as of 2026-08-30 — JobRecon and Takeoff, its only residents, came back onto the ribbon inside Config.pulldown. A pulldown row costs no panel space, so there is now somewhere on the ribbon to put a button nobody wants underfoot, and parking has no job left. Do not recreate parked/ without asking; if a button really must leave the ribbon, taking it out of the parent's layout: already stops it being built.

Titles are short and two lines: a large ribbon button is as wide as its widest line, which is how "Reinforcing Suggestion" came to dwarf everything next to it. title: "Ticket\nQC" — double quotes, because YAML only honours \n inside them. Keep each line under ~9 characters. Rows inside a pulldown are the opposite case — text beside a 16px icon, in a dropdown that grows to fit its longest row — so those stay single-line and may say what they mean (Project Config, Design Extract). A \n in a pulldown row has nowhere to go.

No button carries hover text. The owner asked for it twice, so it is now a test, not a convention: bundle.yaml gets no tooltip: and no author:, and script.py gets no module docstring at all. Document a button in # comments under the coding cookie instead — pyRevit cannot render those, and nothing is lost. tests/test_button_tooltips.py fails and names the button if any of the three comes back. The trap it exists for: pyRevit reads the docstring only if not self.meta (no bundle.yaml), so a docstring can sit harmless for months and become hover text the day a bundle file is trimmed or a button ships without one.

pyRevit still appends Bundle Name:\n<Name> (pushbutton) to every tooltip in uimaker._make_button_tooltip, with no setting to suppress it. Those two lines are the floor; do not try to beat them by editing the pyRevit install.

Editing an existing script.py needs no reload — pyRevit re-reads it on every click, so most iteration costs nothing. Adding or renaming a button needs a Revit restart (see the rule above — not a pyRevit reload).

---

3. Hard rules

Dry-run and self-test before the owner touches it. Owner, 2026-09-02: "以后写完代码先测试，做dry-run，能修的bug修完以后再让我来测试." Finishing a change is not "the code is written" -- it is "I ran it, on a real input, saw no garbage, and fixed every bug I could before handing it over." For a tool that reads the live model, that means: export a real assembly to a deck through the bridge (read-only), run the offline solver on it (panellift), read the output, and fix what breaks -- BEFORE asking the owner to press the button. His time is the last check, not the first. A handoff that says "try it" without a clean dry-run behind it wastes the one reviewer who cannot be replaced. This sits beside "report outcomes faithfully": a dry-run that still errors is reported as such, not smoothed over.

A green host suite is not a live dry-run, and a clean merge is not one either. Added 2026-09-03, after Panel Analysis reached the owner broken twice in a day. The form passed all 127 panelanalysis host tests and pre-filled nothing live: it read mark and f'c only through plant knowledge roles, and on that job the plant mapped those roles to nothing, so every field came up blank, the header said "unnamed panel", and the project / client / date fields the owner expected did not exist at all. Host tests check the schema; they cannot see that a form reads no real value from a real model. So anything that READS A MODEL or renders a FORM is dry-run through the live bridge, read-only, with the actual values it recovered confirmed present, before it is handed over -- the button press is the owner's last check, never the first. The same holds for code that arrives by MERGE from the other machine: a merge that applied cleanly is UNVERIFIED, not validated. The \xe2 crash and the blank form both shipped in merged front-end code and both first failed when the owner ran them -- run every gate AND a live dry-run on merged code exactly as on your own. A WPF button gets a bridge smoke-import before it reaches the owner. The host cannot import System.Windows at all, so a wrong WPF namespace is invisible to every host gate -- 2026-09-03, StretchDirection imported from System.Windows.Media (it lives in System.Windows.Controls) and the button died at import the first time the owner clicked it, the day after the rule above was written. The bridge runs IronPython INSIDE Revit, so the check is cheap: exec the button's from System.Windows... import block through it (python tools/wpf_smoke.py <script.py>) and require zero import errors. Owner, the same day: "写的东西测试过了再给我，别老让我报错." A button handed over without that run is a button the owner is testing for you.

A failure class that is invisible on the host earns a guard test. The Panel Analysis crash on 2026-09-03 was a non-ASCII byte in an IronPython 2.7 file with no # -*- coding: utf-8 -*- cookie: a hard SyntaxError inside Revit, and completely silent on host CPython 3, which defaults to UTF-8. A bug that only bites in the engine we cannot run here, and passes every host check, recurs unless a host test reproduces its shape. tests/test_coding_cookie.py now walks every extension .py and fails on a non-ASCII byte with no cookie, the way test_button_tooltips.py guards hover text. When a class of failure is invisible on the host but real in Revit, add the guard rather than trusting the next person to remember.

Reading a model must be GENERIC -- geometry and built-ins first, a mapped role only as an accelerator. Owner, 2026-09-03: "很多的预填充应该是通用的代码，避免 换一个活儿就得重来." A pre-fill or scrape keyed to one job's parameter names is rework waiting for the next job. Dimensions and weight come from GEOMETRY (bounding box, solid volume) -- job-independent, the floor. Names come from Revit BUILT-INS (Mark; ProjectInformation's Project Name / Client Name). Strengths and the like, when the plant role is unmapped, fall back to case-insensitive parameter-NAME PATTERN matching (f'c: "f'c" / "fc" / "28 day"; release: "fci" / "release"; unit weight: "density" / "pcf"), never one job's literal name. The plant knowledge role is the accelerator where it exists, never the only path. This is "no client/job information in the repo" seen from the code side, and the same law as the five knowledge layers: switching to another job must pre-fill out of the box with no edit.

Delegation is EXPLORE (me) -> WRITE (DSV4F, to a settled spec) -> REVIEW (me), and the tooling is what makes it safe. DSV4F's code quality is not the risk -- on 2026-09-03 its tools/rvt.py work was correct and passed review plus 16 new tests; every DSV4F failure that day was INFRASTRUCTURE, and each has a standing fix. (a) The dsh headless CLI times out and the dsh sandbox denies pytest's tmp_path, so GATES RUN OUTSIDE the sandbox: I run pytest / scrub on my side, DSV4F only writes. (b) A dsh sub that stalls or hits an approval prompt does not report back, so a dispatched dsh sub is WATCHED with tools/dsh_watch.py <session-id> in the background -- its exit is the wake signal, instead of the owner having to tell me it stopped. And do NOT fork for execution work: a fork inherits the conversation and on 2026-09-03 continued in reply-to-the-owner mode with zero tool calls instead of doing the job. For "go build / change X", spawn a FRESH agent with an imperative, self-contained brief -- the JUDGEMENT about what to build is still mine; the reading that informs it goes to a Sonnet sub-agent, not to me and not to DSV4F (PROJECT.md §3.9). And SPLIT the settled spec before it reaches DSV4F (owner, 2026-09-03: "确认了边界的活儿，拆细了再让 DS 干"): one bounded piece per task -- a function, a section, one file's change -- each sized to finish inside a SINGLE reply. A whole-feature spec handed to DSV4F in one turn truncates at max-tokens (the PanelAnalysis write stopped after the easy schema edits, stopReason: length), which reads as "it skipped the hard parts" when it simply ran out of output. Exploration never goes to DSV4F -- but it does not stay with the expensive coordinator either: it goes to a Sonnet sub-agent (owner, 2026-09-05: "探索你带着sub sonnet…DSV4F别做探索。DSV4F就干点儿体力活儿"). DSV4F gets labour only: extraction, mining, translation, bounded pre-split writes. PROJECT.md §3.9 carries the incident, the cmd -p Command Code route when the DeepSeek platform balance is empty, and the systemd-run --user rule for any worker that outlives a turn.

IronPython 2.7 syntax for everything under WillTools.extension/ and every exec snippet:

• No f-strings. Use '{0}'.format(x).
• print('a:', x) prints a tuple ('a:', 5). Build one string instead.
• No pathlib, dataclasses, typing syntax, or walrus.
• Only tools/rvt.py runs on host CPython 3.11 — modern syntax is fine there.

Any change to the model needs a Transaction. Reading never does.

from vibe import tx
with tx('Name the user will see in Undo'):
    ...

No nested plain Transaction (use SubTransaction / TransactionGroup).

Internal units are decimal FEET. Always — areas in square feet, angles in radians. Convert at the boundary with vibe.ft(mm) / vibe.mm(feet). Use UnitTypeId.*; DisplayUnitType was removed in Revit 2022+.

ElementId in 2024+: .IntegerValue is deprecated for .Value. Read it defensively (try IntegerValue / except .Value) as the existing code does.

Don't block Revit's UI thread. No sleeps or polling loops inside handlers.

"Could not judge" and "judged, found nothing" are different answers, and nothing here may collapse them. This is the discipline the whole tool is built on, and it shows up in three places that each look like a local detail:

• A knowledge lookup that cannot resolve returns None, never False. knowledge.same_face() returns None when either token is an abbreviation it does not know — because "I cannot read that" and "those are different faces" are opposite answers, and False would assert the second. rebar_stock() carries basis = None for "nothing knows a stock length" alongside 'by_size' and 'generic', and stocked is a separate None again. rebar_fy() returns basis = None and fy = None when no grade is defensible — A615 names no strength, so its default_fy_ksi is deliberately null. Each of them also returns a why sentence: standing down without saying why is the same failure one step later. Follow this for any new lookup.
• An unrecognised state word renders red, never grey. ticketpage.state_color() matches GREEN / YELLOW / GREY states by name and everything else falls through to red. That fallthrough is load-bearing, not a default: it is what makes it safe to add a state like MUTED at all, because a typo in a state word becomes loud instead of quietly grey. Grey is reachable only through a word the table knows — a declared mute. Do not "tidy" the fallthrough into grey or into an exception.
• A check that returns nothing owes an explanation. See §5 below; this is the same rule, and it is the one a newcomer trips first.

Never run an unfiltered collector, and never guess at an API enum. This crashed Revit on 2026-08-18 — a single exploratory snippet that walked the whole document with FilteredElementCollector(doc).WhereElementIsNotElementType(), touched .Symbol on every result, and set Options.DetailLevel from a value reached by __import__('Autodesk').Revit.DB.... Revit died with no exception and no journal entry, because a bad value handed to a native API is not a Python error. So:

• Always scope a collector — OfClass, OfCategory, a view id, or just asm.GetMemberIds(). This model has ~377 assemblies and six figures of elements.
• Import enums by name (from Autodesk.Revit.DB import ViewDetailLevel). If the import fails you get a traceback; if a bogus object reaches the native layer you get a dead Revit.
• One narrow question per exec. Geometry extraction goes in its own request, never bundled with a model-wide scan.

A contradiction hit mid-refactor is the owner's to settle, not yours. A restructure on 2026-08-31 (private repo pyrevit-knowledge, commit 767281e, "总表三层化、厂层收割落库") walked into lifters.capacity_lb in a plant's knowledge.yaml and found an override the owner had entered by hand — P76 = 16,000 lb, the correct ALP with-tension-bar rating — disagreeing with knowledge/catalogue.yaml's published 7,690 lb for the same part. The restructure emitted the key EMPTY and wrote a new comment reading "Direct override, checked BEFORE the catalogue. One-offs only," phrased as though the key had always been blank. lifter_capacity() checks that override before the catalogue, so every export after that quietly fell back to 7,690. Five real panels (WP242, WP283, WP318, WP322, WP326) each carried a FAIL / PLUMB finding — 8,660 lb each of a 34,638 lb piece against a 7,690 lb tension limit, 113% — before the owner asked on 2026-09-01 where 7,690 came from, and answering that took a git-history dig across two repositories. The sibling key in the same block, lifters.min_edge_distance_in: 9, survived the identical restructure untouched, which is what makes the dropped key a mistake and not a policy. Deleting the losing side of a contradiction, silently preferring the "published" value, and writing a comment that makes the surviving value look uncontested are all the same move: each retires the question instead of asking it. When a refactor meets a contradiction, stop and surface it to him instead.

No client or job information in the repo. Ever.

Not in code, not in comments, not in docstrings, not in a commit message, not in an example. When you need to refer to one, write the placeholder rather than deleting the sentence:

a client / owner	sample_client
a job / project / model	sample_job

Product codes are not client information and stay as they are: design numbers (PNL1.0), piece marks (PNL101), hardware part numbers (ANCHOR_FACE_4T) are naming conventions, not identities.

python tools/scrub.py checks the working tree and the whole git history against .scrub-terms (gitignored, so the list of names is not itself the leak) plus structural patterns — model filenames, absolute user paths, email addresses. It runs as a pre-commit hook and inside tools/package.py.

The working-tree scan covers untracked files too. A scratch script nobody has added is exactly where a model path gets pasted, and it is one git add -A from being in the commit. --worktree is the audit and a hit anywhere fails; --staged is what the hook runs, where only staged files block and untracked hits are printed as a warning — a gate that blocks work unrelated to the commit is a gate that gets passed with --no-verify.

But every scan above honours .gitignore, so none of them has ever opened QNA/. Nor knowledge/plant/, knowledge/job/ or _scratch/. That is the largest body of prose in the checkout and the only part of it whose job is to quote source material verbatim, so a name is not merely possible there, it is certain. --private is the mode that looks at it, and it is an inventory, not a gate: it always exits 0 and the hook never runs it. It asks a different question, because "does this contain a name" is answered yes by design — it asks whether a name is sitting in a shape that travels: inside a fenced block, a proposed key: value, a quoted literal, a path, or glued into a longer identifier (<name>_EMBED_P76), which is the shape a reader skims past. Those are aggregated by the distinct string and listed, worst first; a name in a sentence, or in a value in a plant file, is the file doing its job and comes back as a number only. Read a row as "has this exact string already been pasted into a tracked file" and check it with git grep. It exits 0 because it has no verdict of its own: every string it prints carries a term or a structural pattern, so a copy into a tracked file is already a --worktree failure. What it finds is the raw material a leak gets made out of, weeks earlier — and a check that failed on that would fail every run, which is a check somebody wraps in || true.

Editing a file does not remove a name from the commit that introduced it, and git push sends commits, not the checkout. Before anything is pushed the history can still be rewritten; afterwards it cannot.

The open model is the user's real work. Before anything that deletes, renames in bulk, purges, or touches a saved model: prototype read-only, show counts and a sample, and get an explicit go-ahead. Never use --tx to "just try" a mutation on a model you have not checked with the user.

---

4. Idioms

from vibe import q, p, set_p, tx, selected, ft, mm, out, table

Instead of	Write
FilteredElementCollector(doc).OfCategory(BuiltInCategory.OST_Walls).WhereElementIsNotElementType().ToElements()	q('OST_Walls')
StorageType branching	p(el, 'Comments')
manual Transaction start/commit/rollback	with tx('name'):
uidoc.Selection.GetElementIds() + GetElement	selected()

Signatures: WillTools.extension/lib/vibe/helpers.py. API patterns: docs/revit-api-cheatsheet.md.

Before touching anything that measures geometry, read docs/interference.md. Two working-looking versions of the clash check reported no interference anywhere because a cylinder's edges are circles whose end points coincide; a third was two thirds false positives because a bent bar's bounding box is mostly the hole in the middle.

Inside a button script, use pyRevit forms rather than raw WPF: forms.alert, forms.SelectFromList.show, forms.ask_for_string, forms.select_levels, and script.get_output() for print_md / print_table / linkify.

---

5. Building a new tool for the user

1. Prototype with rvt.py exec against the live model until it is correct.
2. Write it into WillTools.extension/WillTools.tab/<Panel>.panel/<Name>.pushbutton/ as script.py + bundle.yaml (+ optional 96×96 icon.png).
3. Add <Name> to its parent container's bundle.yaml layout: list — the panel's, or the pulldown's if it is a row inside one. A child that is not listed is not created — the button will simply not be there, and nothing anywhere will say why.
4. A tool that is not finished goes behind the Design.panel pulldown with (WIP) in its title, never onto a panel beside the working tools.
5. Ask the user to restart Revit (never "pyRevit → Reload"), then try it.

Do not declare a tool finished before step 1 has actually run clean.

Adding a check to Ticket QC — a new check owes a skip probe

This is the rule most likely to bite you, because adding a check is the first thing anyone does in ticketchecks.py and the failure is silent at write time and loud on the page.

Write the check, add it to CHECKS, and it runs. But a check returns a list of Findings, and an empty return is ambiguous — it can mean ran and found nothing wrong or never ran, for want of data. run_all cannot tell, so it does not guess:

what happened	what run_all logs	what checklist_states shows
returned findings	RAN	the verdict
raised	FAILED	NOT RUN, plus a CHECK-ERROR warning naming the check
empty, probe returns a reason	SKIPPED	NOT RUN, with that reason
empty, probe returns None	RAN	OK — ran, found nothing
empty, no probe registered	RAN-EMPTY	NOT RUN, "no probe declared"

So a check with no probe that ever legitimately finds nothing renders as a red NOT RUN row for a piece that is fine. That is deliberate — silence that looks like "fine" is the exact defect the checklist exists to surface — but it means a new check with no probe is a defect you have just shipped, not a check that works.

And a checklist row may name more than one check. It is answered only when every one of them spoke; any quiet half makes the whole row NOT RUN and the note carries each quiet half's own reason. Under-claiming is the safe direction, because a green row is a claim — a row that asks two questions and prints OK because the half that could still fail it was never asked is exactly the silent pass the table exists to prevent.

Register one beside the check:

@_register_skip_probe('check_your_thing')
def _probe_your_thing(t, intent, know, spec):
    if not t.get('the_input_it_needs'):
        return 'no <input> on this piece -- <what> could not be judged'
    return None          # None means: it ran, and found nothing. Never ''.

The probe's return is the reason, and it is printed. None is the "everything was there, it just found nothing" answer — do not return an empty string for that, and do not write a probe that can never return a reason.

This is now test-enforced rather than a count somebody has to keep re-auditing: tests/test_ticketchecks_host.py::test_every_registered_check_has_a_skip_probe walks CHECKS and fails, naming names, the day a new check ships without a probe registered for it in _SKIP_PROBES — the same failure the 2026-08-31 backlog of seven bare CHECKS entries used to sit as silently. Run the test rather than trusting a number here; a count copied into this paragraph is exactly the kind of fact this file has gone stale on before.

Tests must not write into the working directory

vibe.batchrun.make_worker takes an io for exactly this reason. A test that actually calls the worker must pass io=RecorderIO(); the sibling tests all do, and the one that did not created a file literally named s — twice, once at the repo root and once under WillTools.extension/ — which reached a commit (68adc27) before anyone noticed and had to be deleted in 9504c05. Anything that only inspects the worker's code object can pass the real one, because nothing runs.

This is a convention with nothing enforcing it. There is no fixture and no guard; pytest will happily let a test write anywhere. Use tmp_path or a recorder, and be aware that the next stray file is one git add -A from the history — which is the same reason tools/scrub.py --worktree scans untracked files. A guard would be better than this paragraph; that is a separate job and nobody has asked for it yet.

---

6. When stuck

• rvt.py params <id> beats guessing a parameter name. It and /collect send their arguments as a JSON body, not a query string, because pyRevit 5.0.1's routes Request exposes no parsed query string under any name. Confirmed live 2026-09-01 on Revit 2024.3 / pyRevit 5.0.1: both endpoints return ok: true over the JSON body. Getting that confirmation took two tries, and the lesson is worth more than the fix: status returning ok is not proof of a fresh engine. A second Revit can hold the bridge port while serving code older than the file on disk, and the right model open plus a session-log line dated today both look exactly like a restart. Compare System.Diagnostics.Process.GetCurrentProcess().StartTime (through /exec) against startup.py's mtime before believing new code is loaded.
• Two things rvt.py can now say about an answer, and neither is a fault to work around. "REFUSING this answer - it belongs to a different request" is the shared-response-slot desync of §1 caught in the act; the channel is latched and the next call drains it, so retry rather than reaching for curl. "this answer could not be attributed" means the in-Revit half is older than the client and echoes no id — a Revit restart (never a reload) is what fixes it, and until then any answer taken shortly after a timeout is unattributed, which is exactly how a sweep's progress string once got printed as a document title.
• rvt.py exec -c "print([m for m in dir(el) if 'Type' in m])" — reflection on the live object beats searching docs.
• pyRevit's library is readable source at %APPDATA%\pyRevit-Master\pyrevitlib\pyrevit\ — grep it.
• https://www.revitapidocs.com/2025/ · https://pyrevitlabs.notion.site/

---

7. Search the transcripts before you ask the owner

PROJECT.md §3.8 is the rule; this is how to run it. Before you put a question to him, search what he has already said. He has answered far more than any document records, and asking twice gets you a second ruling that does not match the first.

The transcripts are ~/.claude/projects/<project-slug>/*.jsonl on the machine the conversation happened on. The owner's machine's transcripts travel in the private KNOWLEDGE repo under sessions/ (the Discord agent's host has them at ~/projects/KNOWLEDGE/sessions/**/*.jsonl), so a search on a different machine must include that tree or it is not a search of what he said (2026-09-05: two issues asked him questions answered there days before). Locally they are ~/.claude/projects/<project-slug>/*.jsonl — newline-delimited JSON, one record per line, no enclosing array, so read them line by line and never json.load() the file. His messages are the records with type == "user"; message.content is either a plain string or a list of blocks, where the text lives in the blocks with type == "text". Skip what is not his: a type: "user" record can also carry a tool result, and the long "This session is being continued…" blocks are a summary written by an agent, not by him — quote one as his words and you have invented a ruling.

The encoding trap. The files are UTF-8 and Windows stdout is cp1252, so printing a Chinese message raises UnicodeEncodeError and the search looks like it crashed rather than like it found something. PYTHONIOENCODING=utf-8 is the fix, and it belongs on every one of these commands:

PYTHONIOENCODING=utf-8 python -c "
import json,glob,os,sys
q=sys.argv[1]
for f in glob.glob(os.path.expanduser('~/.claude/projects/*/*.jsonl')):
    for n,l in enumerate(open(f,encoding='utf-8'),1):
        if q not in l: continue
        r=json.loads(l)
        if r.get('type')!='user': continue
        c=r['message']['content']
        if not isinstance(c,str): c=' '.join(p.get('text','') for p in c if isinstance(p,dict))
        if q in c: print(os.path.basename(f)[:8],n,r.get('timestamp',''),c[:300],'\n')
" "7.5sqrt"

That exact command is what found the ruling the rule was written for. It reads all 65 MB in 0.2 seconds, so run it three or four times with different terms rather than once — and search Chinese as well as English, because he writes in both and often mixes them inside one sentence. Search the value (7.5), the concept (应力极限), the part number, the parameter name. Prefer a git log -S / git grep pass too: a ruling that already landed is usually quoted in the comment beside the value.

Two ways to get this wrong, and the second is the expensive one:

• A hit is not automatically the answer. Check the timestamp and read the surrounding lines. Two rulings months apart may be about different questions — one about what the number is, one about where the setting lives — and neither retracts the other. §3.8 has the case.
• No hit is not proof he never said it. These are one machine's history, unindexed and bilingual, and the word you searched is very often not the word he used. Report "I searched X, Y, Z — nothing", listing the terms, and never "he has never ruled on this". Then ask him. Asking is not the failure; asking first is.