Init

docs/tool-verification/EXTENSION-hardware-and-kernel.md

@@ -0,0 +1,70 @@
+# Extension: hardware and kernel routes
+
+What this pass covered, what it verified externally, and what it deliberately did not assert. The
+routes here are the skill's reason to exist and its least portable part, so the record is organised
+around one question: **what does each mechanism actually require, and what does it still not see?**
+
+## What was verified externally
+
+| Fact | How it was established | Grade |
+|---|---|---|
+| The trace feature has its own capability leaf, and its bits describe filters and output modes rather than "works / does not work" | read from an operating system kernel's implementation of the same CPUID contract | `inferred` for the bit names, `observed` that the leaf answers on this host |
+| The trace unit is reachable only from privileged code | the control registers and the output region are set from ring 0 in that same implementation | `inferred` |
+| A last-branch-record capability leaf exists, and its depth field is a **mask rather than a count** | the same implementation computes depth from the mask, and published values differ by generation (4, 8, 16, 32) | `inferred` |
+| The architectural performance-monitoring leaf reports version, counter count, bit width and mask length | the same implementation reads those subfields, and treats the leaf as unusable below a minimum mask length | `inferred` |
+| A hypervisor is detectable from a single CPUID bit, and its vendor from a separate leaf | the same implementation | `inferred` |
+| Hardware breakpoints: a small fixed number of debug registers; a watch is 1, 2, 4 or 8 bytes wide (8 only on 64-bit); the address must be aligned to the width; there is **no read-only data breakpoint**; the access field encodes execute, write, or read-write | processor documentation for the register layout; the encoding rules are what the control field admits | `observed` for the count and the field set |
+| A data breakpoint set on a code address never fires | instruction fetch is not a data access, so no access-width and access-type combination can match it | `inferred`, and it is the single most common misunderstanding in this area |
+| Single-machine instruction-level recording exists as a debugger feature, is user-mode only, has a high recording overhead, produces multi-gigabyte files, and cannot record a protected process | the feature's own documentation | `observed` |
+| Local kernel debugging is documented but cannot stop the target | the documented command set excludes the halting commands while permitting memory access | `observed` |
+| Full kernel debugging over a network needs a boot-configuration change on the target and a second machine (or a virtual machine) | the documented setup procedure | `observed` |
+| Every register-level monitoring mechanism needs ring 0, and therefore an administrator and a driver — which may in turn need test signing, and may still be refused where code-integrity enforcement is active | the documented requirements for each | `inferred` |
+
+## What this changed in the skill
+
+Three claims that were circulating as common knowledge turned out to be wrong, and the corrections
+are now in the route text and in the probe's output:
+
+- **There is no single timing packet.** Timing is carried by three different packet kinds, each
+  gated by its own capability bit. A plan that assumes one timing packet will mis-parse a trace.
+- **The branch-record depth is not a constant.** Values of 4, 8, 16 and 32 all exist across
+  generations, and the field is a mask. Anything that hardcodes "16 entries" is wrong for some of the
+  processors it will meet.
+- **"Four breakpoints" does not mean four watchpoints of any size.** The width is restricted, the
+  address must be aligned, no read-only data watch exists, and setting one on a code address does
+  nothing at all.
+
+And one boundary was sharpened enough to change a recommendation: **on this platform there is no
+documented user-mode path to the trace unit.** The in-box support that exists is aimed at crash
+analytics rather than at analysis, and is not documented for this purpose. That is why the probe
+reports the trace route as needing a driver or a record-and-replay debugger rather than as merely
+needing a decoder, and why `references/evidence-summary.md` grades the route `unverified` here rather
+than `inferred`.
+
+## What was deliberately not asserted
+
+Written down rather than guessed, because each of these is exactly the kind of detail that becomes
+authoritative-looking when it is wrong:
+
+- The normative bit layout of every capability field. Where a vendor specification was not reachable,
+  the encodings were taken from an implementation of the same contract and are labelled as such. A
+  reader who needs the normative definition is told to consult the specification for the processor in
+  front of them.
+- Byte-level encodings of the trace packet format. The packet *set* is established; the wire encoding
+  of individual packets is not.
+- Sampling-precision claims, the deprecation status of the older branch-trace mechanism, which
+  virtualisation exits intercept which registers, and the interaction between kernel patch protection
+  and debuggers. For each of these a first-party source was not reachable from this environment, so
+  the documentation names the mechanism without asserting the behaviour.
+- A numeric overhead figure for OS-level event tracing. The documented problem is loss accounting and
+  a single-session constraint, which is what the text states; an overhead percentage would have had
+  to be invented.
+
+## Why this route is probed rather than declared
+
+Every mechanism here is conditional on the host: on a supported processor, on privileges, on signing,
+on whether the analysis machine is itself virtualised. A plan that assumes otherwise fails at the first
+step and gets attributed to the tooling. `scripts/hwprobe.py` exists so that the answer is a
+measurement with three states — available, needs-`<something>`, unavailable — and so that a host
+inside a hypervisor reports that fact rather than silently degrading every route that depends on a
+debug exception.

docs/tool-verification/EXTENSION-tool-verification.md

@@ -0,0 +1,93 @@
+# Extension: tool verification
+
+How the toolchain claims in this skill were established, and which of them remain documentation only.
+
+## Method
+
+For each tool or mechanism the skill depends on, three questions were asked in this order:
+
+1. **Is it present on the host that did the work?** A path lookup and a version call, recorded in
+   `TOOL-VERDICTS.md`. Absence is a finding, not a failure.
+2. **Is what the skill says about it true?** Wherever possible from the tool's own documentation or
+   the platform's own specification — not from a recollection, and not from a secondary summary.
+3. **Has the route been run?** If not, the claim is `inferred` or `unverified` and the missing step is
+   named. `references/evidence-summary.md` carries the grade.
+
+The order matters. A tool that is present but whose behaviour is described from memory is worse than
+an absent tool, because the description reads as verified.
+
+## What is `observed` and can be re-run
+
+These rest on commands whose output exists, and every one of them needs only Python plus a file on
+disk — no third-party sample, no debugger, no network:
+
+- the reader parsing real platform images and generated fixtures, and reproducing the declared checksum
+  on unmodified images;
+- RVA-to-file-offset translation in both directions, including the virtual-only tail that has no bytes
+  on disk;
+- import, export, resource, TLS, debug and relocation parsing against fixtures that declare their own
+  expected values;
+- the patch pipeline end to end: a read-only input, a new output, a recomputed checksum, every patched
+  byte re-read from the written file, and the input's hash unchanged;
+- the patcher's refusals, each exercised deliberately: an ambiguous pattern, a mismatch against
+  expected bytes, and a length that cannot be established;
+- pattern location with its hit counts and verdicts, including the zero-match and multi-match cases;
+- fixture generation, deterministic in bytes and parsing back through the reader;
+- the host probe's three-state route table and its raw CPUID reporting;
+- the identity scanner on this repository.
+
+## What is `inferred` and why
+
+A mechanism described from its documentation, with the tool absent from the development host.
+Debugging workflows, injection and hooking, dump repair, managed tooling, installer extraction,
+kernel debugging and driver loading are all in this category. For each, the reference states the
+mechanism and its requirements, and the evidence summary names what would raise the grade: a run.
+
+This is the honest position, and it is deliberate rather than accidental: the alternative is to write
+procedures that have never been executed in the register of ones that have.
+
+## What is `unverified` and why
+
+Two kinds of thing sit here, and they are different problems.
+
+**Hardware-bound routes.** The trace unit and the branch-record registers are reachable only from
+privileged code, and the host used for this work runs under a hypervisor. The probe reports what the
+processor advertises and what the platform permits; the route itself was not exercised. A reader with
+a bare-metal host and a driver can move this row, and the documentation says so rather than implying
+the route is unavailable in principle.
+
+**Details whose normative source was unreachable.** Where a vendor or platform specification could not
+be opened from this environment, the detail is either omitted or labelled. The list is in
+`TOOL-VERDICTS.md` under "what is deliberately not asserted", and it exists so that a later pass
+knows exactly which gaps to close rather than re-discovering them.
+
+## Corrections this pass made
+
+Facts that were checked and turned out to contradict the widely repeated version. Each one is now
+stated in its corrected form where the skill needs it, because a reader acting on the common version
+builds the wrong plan:
+
+- a strong name is identity, not an anti-tamper mechanism, and is not validated at load on current
+  runtimes;
+- a precompiled managed image is not thereby locked — methods can still be replaced at run time,
+  while a natively compiled deployment is the one that removes the readable layer;
+- a dialogs-suppressing switch on a disassembler's command line is not the switch that runs a script;
+- an undocumented build-fingerprint block in a PE header has no normative source, and a parser for it
+  must say so;
+- the largest minidump configuration can carry more than a nominal "full" one, and a flag commonly
+  read as "everything" is documented as unsupported for user-mode dumps;
+- a page-guard breakpoint fires once, and treating it as a watchpoint loses every access after the
+  first;
+- a copy-on-write image page is still reported as an image, so distinguishing it needs the working-set
+  information;
+- an administrative installation of a package removes its digital signature;
+- a certificate in the image is a statement about the digest, which is why editing the file while
+  preserving the digest does not happen;
+- there is no single timing packet in the trace format, and the branch-record depth is a per-generation
+  capability rather than a constant.
+
+## The rule this pass produced
+
+**A tool's absence is a finding, and a tool's behaviour described from memory is a defect.** The first
+is cheap to record; the second propagates as a fact. Everything in this directory exists so a reader
+can tell which of the two they are looking at.

docs/tool-verification/FINDINGS.md

@@ -0,0 +1,165 @@
+# Findings
+
+Defects that this repository's own tools, gates and fixtures found **in each other**, during the pass
+that built it. Each entry states the symptom, the root cause, how it surfaced, and the check that now
+catches it.
+
+These are recorded because the interesting part is not the fix. It is that every one of these produced
+output that looked correct: a table of plausible flag names, a resource count that was merely large, a
+length guard that never fired. That is the failure shape this whole repository is organised against.
+
+## Parser defects
+
+**F1. The DLL-characteristics table was shifted by six bits, and produced a confident wrong answer.**
+
+*Symptom:* parsing a stock system binary reported `no_seh, no_bind, wdm_driver, 32bit_dll`. Those
+flags on a modern executable are implausible — a user-mode program with no exception handling, marked
+as a kernel driver and as 32-bit, on a 64-bit host.
+
+*Root cause:* the constant table was written from recall rather than from the specification, and every
+entry was displaced: what the code called `no_seh` was the high-entropy-VA bit, and so on through the
+whole table. The output was well-formed, self-consistent, and wrong.
+
+*How it surfaced:* by parsing a **real** image whose expected flags are known, rather than by testing
+against the parser's own fixtures. A fixture built from the same wrong table would have agreed with it.
+
+*Fix and check:* the values were taken from the published format specification and the table now
+records where it came from. The regression is a test asserting the exact flag **names** for a real
+binary's header, not merely that a list is non-empty.
+
+**F2. The section-alignment field was treated as a set of independent bits.**
+
+*Symptom:* a code section reported two alignment flags at once.
+
+*Root cause:* the alignment of a section is bits [23:20] of the characteristics field — an **index**,
+not a set of bits — and the specification states the values are valid only for object files. Testing
+them one bit at a time turns the execute and read bits into two imaginary alignment flags.
+
+*How it surfaced:* the same real-image run, on a section whose characteristics value is a plain
+execute|read pair.
+
+*Fix and check:* alignment is decoded with a mask and the table carries the note about its scope. A
+unit test asserts that a section with execute|read reports exactly those two flags and no alignment.
+
+**F3. Resource counts are 16-bit fields read as 32-bit, which inflated one resource into 478.**
+
+*Symptom:* a fixture with exactly one resource entry reported 478 entries.
+
+*Root cause:* the resource directory's two count fields are 16 bits each. Reading either as a 32-bit
+value swallows the first two bytes of the following entry and the walk then chases table bytes as if
+they were entries.
+
+*How it surfaced:* only after the fixture generator was written. Real system images hid it — their
+counts and neighbouring bytes happen to combine into values that do not explode — while a fixture with
+exactly one entry could not.
+
+*Fix and check:* both counts are read as 16-bit. The fixture declares its expected entry count and a
+test asserts the walk returns exactly that.
+
+## Patcher defects
+
+**F4. The ambiguity guard was defeated by its own default.**
+
+*Symptom:* a pattern matching dozens of sites was silently patched at the first one.
+
+*Root cause:* the command-line path always wrote an explicit hit index into the request, and its
+default value was `0`. The guard exists to refuse a multi-site match unless a site is *chosen*, and a
+default of zero counted as a choice.
+
+*How it surfaced:* by testing the guard deliberately with a pattern that is obviously common (an
+indirect call sequence) instead of with a pattern known to be unique.
+
+*Fix and check:* the index is carried only when it was actually supplied, and the refusal now lists the
+sites it found. A test calls the guard with the common pattern and asserts the refusal.
+
+**F5. The equal-length check compared a value with itself, so it never fired.**
+
+*Symptom:* the length guard existed, was documented, and could not fail.
+
+*Root cause:* the "original" bytes were sliced to the length of the replacement, so the two lengths
+were equal by construction. Worse, the script cannot in general know the length of a site without
+disassembling it — which means the honest answer is not "equal" but "not established".
+
+*How it surfaced:* by trying to make the guard fire. A guard that cannot fail is not a guard.
+
+*Fix and check:* length is only judged when a reference exists (the expected bytes, or an explicit
+declared length), and the three states — equal, changed, unproven — are printed distinctly. A test
+asserts that a request with no reference prints the unproven marker, and that a declared length that
+disagrees with the replacement is refused. The first version also printed the unproven case as a
+length change, because a missing value is falsy; that is now a three-state marker.
+
+## Fixture defects
+
+**F6. `SizeOfHeaders` was computed without the section table.**
+
+*Symptom:* every section's payload sat at a different file offset than the one the header declared.
+
+*Root cause:* the header size calculation covered the DOS header, the PE signature, the file header
+and the optional header, and omitted the section table — 40 bytes per section. The declared value was
+therefore smaller than the real header block, and everything after it was misplaced.
+
+*How it surfaced:* an assertion in the generator comparing the planted byte sequence at its declared
+file offset with the bytes actually written there. Without that assertion the file would have been
+written, would have parsed, and would have been wrong.
+
+*Fix and check:* the section table is included in the calculation, with an assertion that the aligned
+size is at least the computed size. The generator asserts every structural claim it makes.
+
+**F7. Two structures were placed at estimated offsets, and overlapped.**
+
+*Symptom:* the debug directory was written into the region the import table occupied.
+
+*Root cause:* the first version of the generator gave the import table, the debug directory and the TLS
+directory each a hand-picked offset. Two of those choices collided.
+
+*How it surfaced:* while computing where the import table actually ended, which is not something one
+does while *writing* estimated offsets.
+
+*Fix and check:* the payload is laid out with a single cursor that allocates each structure in turn and
+refuses to overflow the buffer. An overlap is now impossible by construction rather than by care.
+
+**F8. The debug-directory structure had the wrong field count, and a file offset was filled with an RVA.**
+
+*Symptom:* the generator failed to build, then — once it built — the record could not be located.
+
+*Root cause:* the structure has eight fields, not seven, and its last field is a **file offset** while
+the field before it is an RVA. Two different address spaces inside one 28-byte structure.
+
+*Fix and check:* both fields are written correctly and the reader resolves the PDB path from the file
+offset, which is a round-trip the test asserts.
+
+## Probe defects
+
+**F9. A pseudo-handle was passed as a 32-bit integer, and the probe looked like a policy denial.**
+
+*Symptom:* the privilege probe reported that opening the process token failed with error 6
+(`ERROR_INVALID_HANDLE`) on an elevated session.
+
+*Root cause:* the pseudo-handle for the current process is `(HANDLE)-1`. Without an explicit pointer
+return type the binding layer narrows it, the call receives the wrong value, and the failure looks
+exactly like a machine where the operation is not permitted.
+
+*How it surfaced:* by disbelieving the result. "Elevated session cannot query its own token" is not a
+plausible measurement.
+
+*Fix and check:* the call signature declares its types, and a test asserts the probe reports elevation
+on this host rather than an error.
+
+**F10. Long values were truncated by the printer.**
+
+*Symptom:* a raw capability value printed as `0x000`, losing its significant digits.
+
+*Root cause:* a fixed column width applied to a value string. The data was correct; the report was not.
+
+*Fix and check:* long values wrap onto continuation lines instead of being cut. A test asserts a long
+value survives into the output intact.
+
+## What this list is for
+
+Ten defects, all in code written during this pass, all of which produced output that looked right. The
+pattern is consistent enough to state as a rule:
+
+**A check that cannot fail is not a check, and a table written from recall is a table that is wrong in
+one place you will not notice.** Both are why this repository prefers a value taken from a
+specification with its source named, an assertion over an estimate, and a fixture that can disagree
+with the tool reading it.

docs/tool-verification/README.md

@@ -0,0 +1,56 @@
+# Tool Verification
+
+**This directory is not part of the installed skill.** It is the evidence record for measurement
+passes: what was actually run, on what, against which independent method, and what the target could
+not exercise. It exists so the coverage claims in the skill can be checked against runs instead of
+being trusted.
+
+**When to read it:** when a claim's strength decides whether you rely on it, or when you are
+extending the skill and want to know whether a route has ever been exercised.
+
+## What is in here
+
+| File | What it holds |
+|---|---|
+| `FINDINGS.md` | defects that this repository's own tools, gates and fixtures found in each other — each with its root cause and the check that now catches it |
+| `TOOL-VERDICTS.md` | per-tool verdicts: present or absent on the development host, what was verified about it from a primary source, and what remains documentation-only |
+| `REPO-DECISIONS.md` | the design decisions behind the layout, the strength vocabulary, and the gates, with the reason each was chosen |
+| `EXTENSION-*.md` | one file per research pass: what the pass covered, what it verified externally, and what it deliberately did not assert |
+
+## How to read a record here
+
+Three things make a row usable, and a row missing any of them should be treated as a note rather than
+as evidence:
+
+1. **The command.** Not "the reader was tested" — the exact invocation, so anyone can re-run it.
+2. **The output that matters.** The decisive line, not a log dump.
+3. **The independent method.** A second way of arriving at the same answer. A parser agreeing with
+   itself is not a check; a parser agreeing with the value the file declares, or with an independent
+   tool, is.
+
+## The rules this directory obeys
+
+- **A claim carries its grade.** `observed` (a command and its output exist), `inferred` (reasoned
+  from an observation), `unverified` (assumed, or reported elsewhere and never reproduced here).
+- **A limit cites the measurement that set it.** A limit without a constraint behind it is a
+  preference.
+- **Missing coverage is `unknown`, never absence.** "The tool was not found" and "the tool does not
+  exist" are different statements; the first names the search.
+- **A measurement that disagrees with a recorded conclusion re-opens it.** The conclusion is not
+  quietly edited; the change is described.
+- **Nothing here names a target.** Binaries used for measurement are either built by this repository
+  or are platform images that exist on any Windows installation; no third-party sample is required to
+  reproduce a row, and none is committed.
+
+## The relationship to `tests/`
+
+They are different artifacts and neither substitutes for the other.
+
+- `tests/` asserts what the **scripts** do. It runs on a bare checkout, offline, in seconds, and it is
+  what CI gates on.
+- `docs/tool-verification/` records what a **route** did against a real artifact, including the routes
+  that cannot run in CI because they need a debugger, a driver, a second machine or hardware support.
+
+A green test suite means the parsers and planners behave as documented. It says nothing about whether
+a hardware route works on your machine, which is why `scripts/hwprobe.py` exists and why the hardware
+rows in `references/evidence-summary.md` are graded `inferred` or `unverified` with what is missing.

docs/tool-verification/REPO-DECISIONS.md

@@ -0,0 +1,145 @@
+# Repository Decisions
+
+Why the repository is shaped the way it is. Each entry records the alternative that was considered
+and the reason it lost, because a decision with no recorded alternative gets re-litigated by every
+future contributor.
+
+**When to read it:** before proposing a structural change, and when an existing rule looks arbitrary.
+
+## Layout
+
+**Decision: a skills repository with the skill under `skills/<name>/`, and everything else as
+maintenance tooling.**
+
+The alternative was a flat repository where the skill is the root. It loses on one specific point: the
+gates, the tests and the evidence record are *about* the skill rather than part of it, and installing
+the skill should not install them. The `skills/<name>/SKILL.md` layout is also what the installer
+resolves, so the structure and the install mechanism are the same fact stated once.
+
+**Decision: an agent preset is not involved, and no runtime is required.**
+
+The skill is documents plus scripts. A background process, a server, or a plugin would each add a
+failure mode that cannot be checked by reading a file, and none of them is needed to answer the
+questions this skill answers.
+
+## The strength vocabulary
+
+**Decision: three grades — `observed`, `inferred`, `unverified` — applied to every factual claim.**
+
+The alternative was ordinary prose, which reads as uniformly confident. The observed failure is not
+that a reader disbelieves a claim; it is that a reader cannot tell a measured result from a plausible
+one, and therefore builds a plan on top of an assumption.
+
+Three grades rather than two, because the interesting middle case is real: a mechanism verified from
+its documentation, exercised by nobody here. Calling that "unverified" hides that the mechanism is
+known; calling it "verified" is a lie.
+
+**Decision: missing coverage is recorded as `unknown`, never as absence.**
+
+A search that returned nothing is evidence about the search. "The tool is not installed" and "the tool
+does not exist" lead to different actions, and collapsing them is the most repeated data error in this
+kind of record.
+
+**Decision: a claim is only as strong as the weakest link in its chain.**
+
+Stated separately because it is violated by composition rather than by any single sentence: a row that
+joins a verified mechanism to an unexercised route reads as one verified claim unless the joining is
+called out.
+
+## The entry point
+
+**Decision: `SKILL.md` stays near 300 lines, and the inventory lives in `references/routing.md`.**
+
+The alternative was one large entry point. It loses because the entry point loads in full on every
+activation: a lookup table that is read once per task is a poor use of that budget, while a
+symptom-to-file mapping must stay one hop and therefore belongs there.
+
+**Decision: the symptom index is mirrored into `routing.md`, with a gate comparing the two.**
+
+Splitting a table is how two tables start disagreeing. A mirror plus a check gives a reader all three
+tables in one load and makes drift a build failure rather than a slow decay.
+
+**Decision: the entry point is a procedure with gates, not background reading.**
+
+Because the observed failure mode is a reader agreeing with the material and then reasoning from
+first principles anyway. Gates are actions with pass criteria precisely so that "I understand the
+idea" cannot be mistaken for having done it.
+
+## The scripts
+
+**Decision: standard library only, Python 3.9+, no third-party imports.**
+
+A parser used to build a toolchain must be readable and must run on a bare install, including in a
+locked-down analysis VM. A dependency is a thing that can fail to install at the moment the analysis
+is happening. Where a third-party tool is the right instrument, the script reports its absence
+instead of substituting a weaker method.
+
+**Decision: every structure offset is computed, never estimated.**
+
+Two structures in the fixture generator overlapped because each had a hand-picked offset. A single
+allocating cursor makes the overlap impossible rather than merely absent.
+
+**Decision: a numeric table carries its source.**
+
+A constant table written from recall was wrong in every entry and produced plausible output. Tables
+taken from a specification name the specification; tables that read an undocumented structure say so.
+
+**Decision: an unproven property is reported as unproven, not as satisfied.**
+
+The length guard is the case that produced this rule: it compared a value with itself and could never
+fail. A property the tool cannot establish — the length of a site without disassembling it — is now a
+third state rather than a silent pass.
+
+**Decision: fixtures are generated, not committed.**
+
+A committed sample is a licensing and provenance problem, and a downloaded one makes the suite depend
+on the network and on a target that changes. A generated fixture is deterministic, carries the awkward
+cases deliberately, and is code rather than an artifact.
+
+## The gates
+
+**Decision: six structural gates at the repository root, and CI runs all of them.**
+
+Consistency has a natural counter-pressure — a broken path fails loudly. Bloat and drift do not, which
+is why there is a budget gate and a routing gate rather than only link checking. Every gate exists
+because a specific class of change went unnoticed without it.
+
+**Decision: the leak scanner owns its rules, and the repository gate delegates to it.**
+
+One place to argue with an exemption list. A second implementation would diverge, and the diverging
+one would be the one that ran.
+
+**Decision: the claim that a document makes about a command is machine-checked against that script's
+own argument table.**
+
+A flag that no longer exists is drift no path check can see: the file resolves, the line number is
+right, and the command fails at the moment someone follows the page instead of the tool.
+
+## The hardware layer
+
+**Decision: the hardware routes are probed per host and degraded honestly, rather than declared
+supported.**
+
+This is the skill's differentiator and its least portable part. A CPU reporting the feature says
+nothing about whether a capture path is reachable, and a hypervisor present on the analysis host
+changes what a debugger and a hardware breakpoint can do. A plan that assumes otherwise fails at the
+first step and gets attributed to the tooling. The probe exists so the answer is a measurement.
+
+**Decision: bits whose meanings are not verified are printed raw.**
+
+Reading a capability out of a recollection is how a wrong plan becomes an authoritative-looking one.
+There is no loss in printing the register values and letting the reader consult the processor
+specification for the family in front of them.
+
+## Publishing
+
+**Decision: the desensitization rules state what must be removed *and* what must stay.**
+
+A one-sided rule trains people to redact tool names and format names, which destroys the reusable part
+of the material while removing none of the target's identity. A scanner that flags those gets switched
+off, and then the real findings go with it.
+
+**Decision: an entry-point document is treated as a prompt surface.**
+
+A README, a case note, a screenshot filename — these carry target identity as easily as body text, and
+they are the part most often forgotten because they were written before the material was.

docs/tool-verification/TOOL-VERDICTS.md

@@ -0,0 +1,110 @@
+# Tool Verdicts
+
+What was verified about each tool this skill depends on or recommends, **and what is only
+documentation**. Two different questions live here and they are kept apart: "is the tool present on
+the machine that did this work" and "is what the skill says about the tool true".
+
+A tool being absent from the development host is not a defect in the skill. It is the reason a
+route's grade is `inferred` rather than `observed`, and it is recorded so a reader knows which rows
+are plan-shaped and which are run-shaped.
+
+## Local inventory
+
+Measured on the development host with a path lookup and a version call. Windows 11 build 26100,
+Python 3.14.
+
+| Tool | On the host | Used for |
+|---|---|---|
+| Python 3.14 | present | every script |
+| `git` | present | repository work |
+| `gcc`, `objdump`, `strings`, `gdb` (MinGW) | present | building small C helpers, section and symbol dumps |
+| `go` | present | reading a Go binary's symbols and code |
+| `dotnet` | present | managed assemblies |
+| `java`, `javac` | present | tools distributed as archives |
+| `node`, `npm` | present | the `skills` CLI, and scriptable tooling |
+| `frida` | present | runtime instrumentation |
+| `wpr`, `logman`, `tracerpt`, `bcdedit` | present | OS-level event tracing and boot configuration |
+| `nasm` | present | assembling small stubs |
+| `curl`, `tar` | present | fetching and unpacking archives |
+| A disassembler (IDA, Ghidra, Binary Ninja, Cutter) | **absent** | reading code; several are GUI-only |
+| `x64dbg`, `WinDbg`, `cdb` | **absent** | interactive and command-line debugging |
+| `dumpbin`, `link`/`editbin`, `signtool` (MSVC) | **absent** | header inspection and signing |
+| `ildasm`, `ilasm`, `corflags` | **absent** | CIL disassembly and assembly |
+| A packer/protector identifier | **absent** | shell and protector recognition |
+| `procdump` | **absent** | process dumping |
+| `tshark` | **absent** | capture reading |
+| `cargo`, `rustc` | **absent** | building Rust tooling |
+| `cl`, `msbuild` | **absent** | building from the MSVC toolchain |
+
+The scripts treat absence as a report, not a failure: `scripts/hwprobe.py --tools` prints what is
+present and names what is not, and `EXEREV_TOOLS` lets a toolchain that lives outside `PATH` be found.
+
+## What is verified about each mechanism
+
+Three columns: what the skill says, how strongly it is supported, and what would raise it.
+
+| Mechanism | Support | What would raise it |
+|---|---|---|
+| PE structure, flag values, directory semantics, checksum | `observed` against the published format specification, and confirmed by the reader reproducing the declared checksum on real images | nothing further needed for the fields in use |
+| Import, export, resource, TLS, debug and relocation parsing | `observed` against fixtures that declare their own expected values, plus plausible results on platform images | a second, independent parser agreeing on a larger corpus |
+| Byte patching, checksum recomputation, patch verification | `observed` by running the pipeline end to end on a copy and re-reading the written bytes | nothing further for the described behaviour |
+| Pattern location and cross-build comparison | `observed` on generated fixtures, including the ambiguous and zero-match cases | a real multi-version pair to exercise migration |
+| Managed-assembly structure and tooling | `inferred` from the platform's own published format documentation and the tools' own documentation | a managed sample and a run |
+| Installer and package formats | `inferred` from each project's own documentation | extraction performed on a sample of each container type |
+| Debugger breakpoint families and their costs | `inferred` from the debugger's own documentation | a debugger installed, and a session recorded |
+| Injection and hooking mechanics | `inferred` from the platform API documentation | a run, on a sample, with a control |
+| Runtime gate verdict by paired observation | `observed` end to end on a real gated feature of a patched snapshot target: the code section was located by content match, the six patched bytes were read back live from the mapped code before any verdict was trusted, the shared decision function was entered exactly once, returned the true-object pointer, and the refusal display routine was never entered | a second target whose gate shape differs, to exercise the other two verdict states against reality |
+| Dump semantics and repair | `inferred` from the platform's dump documentation | a dump repaired and loaded |
+| Hardware breakpoints | `inferred` from the architecture as documented; the **count** of debug registers is the only architectural fact stated | a debugger, and a session on a host whose probe reports the route available |
+| Instruction tracing capability and decoding | `unverified` here: the CPU reports the feature and no capture was taken | a capture path, then a decoder, then an address-to-symbol pass |
+| OS event tracing | `inferred`; the tools are present and no session was recorded | a recorded trace of a known operation |
+| Kernel debugging and driver loading | `inferred` from platform documentation | a second machine, or a boot configuration change, plus a driver to load |
+| Hypervisor-assisted observation | `unverified`; documented as a route with its requirement chain | a driver, signing, and a host that is not already nested |
+
+## Facts worth stating because common belief differs
+
+Each of these was checked against a primary source, and each contradicts a thing that is widely
+repeated. They are recorded here because a reader acting on the common version will build the wrong
+plan.
+
+- **A strong name is not anti-tamper.** It provides identity, and on current runtimes the signature is
+  not validated at load time. Work planned around defeating it is planned against a mechanism that is
+  not doing the work.
+- **A managed assembly can be compiled to something with no readable intermediate code.** A
+  ready-to-run image can still have its methods replaced by the runtime's compiler, so "precompiled"
+  does not mean locked; a native-compiled deployment is the one that genuinely removes the readable
+  layer.
+- **`-A` on a disassembler's command line is not "run this script".** It suppresses dialogs; the script
+  is a separate switch, and the two are documented as being used together.
+- **The Rich Header is not in the format specification.** The published document does not describe it
+  at all, so a parser for it is reading an undocumented structure and must say so rather than implying
+  a normative source.
+- **A full dump is not always the most complete dump.** The largest minidump configuration can carry
+  more than a nominal "full" one, and one of the flags commonly believed to mean "everything" is
+  documented as not supported for user-mode dumps.
+- **A protected process cannot be recorded by the record-and-replay debugger**, and its replay is
+  read-only. A recording is evidence about the run that was recorded, not about the binary.
+- **A page-guard breakpoint fires once.** It is an alarm that the page was touched, not a watchpoint,
+  and treating it as one loses every access after the first.
+- **A copy-on-write image page is still reported as an image**, not as private memory. Distinguishing
+  it needs the working-set information rather than the region query.
+- **An administrative installation of a package removes its digital signature.** The extraction route
+  and the signing state are not independent.
+- **A certificate in the image is a statement about the image digest**, which is why editing the file
+  while preserving the digest is not a thing that happens.
+
+## What is deliberately not asserted
+
+These came up during the research and were left out of the documentation rather than stated from
+partial evidence:
+
+- The exact byte ranges excluded from an Authenticode digest. The page that would have said so was not
+  reachable; the consequence of editing is documented, the exclusion list is not.
+- The deterministic-build behaviour of the linker's timestamp field. Candidate specification pages
+  were not reachable, so build identity is described through the file hash and product version, with
+  the format's own caveat about the timestamp.
+- Byte values of any standard cryptographic substitution table. The standard is named and the reader
+  is told to compare against it rather than against a recollection.
+- Information classes for the undocumented memory-query call. The family is named and the reader is
+  pointed at the target's own call sites.
+- The detailed control layout of the debug registers. Only the architectural count is stated.