@erclx/aitk 2.1.0 → 2.2.0

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "aitk",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/docs/agents/audits.md

@@ -22,15 +22,19 @@ aitk audits list --json
 
 ## What it runs
 
-Twelve verbs, listed by `aitk audits list`. Each runs once in its fullest form, and the aggregate reads that verb's own record rather than imposing a shared envelope on it. Every one of those records already has consumers naming its keys, so a common shape would be a breaking change bought for tidiness.
+Fourteen verbs, listed by `aitk audits list`. Each runs once in its fullest form, and the aggregate reads that verb's own record rather than imposing a shared envelope on it. Every one of those records already has consumers naming its keys, so a common shape would be a breaking change bought for tidiness.
 
-The verbs walk separate trees and share no state, so they run together. Measured on the authoring machine, twelve runs finish in 0.8 seconds of wall clock against 4.4 seconds of processor, which is under every other stage in `bun run check`.
+The verbs walk separate trees and share no state, so they run together. Measured on the authoring machine at twelve verbs, a run finished in 0.8 seconds of wall clock against 4.4 seconds of processor, which is under every other stage in `bun run check`. `aitk deps audit` is the one that changes that reading, since it reaches a network rather than a tree and its latency is the index's rather than this machine's.
+
+Twelve of the fourteen read a tree on this disk. The two added by `state-scoped-risk.md` read committed state rather than an arriving change, which is the gap every review surface here leaves by construction.
 
 Each is invoked as the CLI the caller is running rather than as a global `aitk`. A globally installed binary resolves to the main checkout no matter which worktree is executing, so the aggregate would measure a tree the branch never touched and report a pass over it.
 
 ## What gates and what reports
 
-Three findings fail the run: an unresolved context citation, a banned character, word, or spelling, and a skill folder carrying no `REQUIREMENT.md`. Those are the same three `scripts/core/verify.sh` already fails a push on, and the aggregate adds nothing to the set. Each is a fact with no false-positive class behind it.
+Four findings fail the run: an unresolved context citation, a banned character, word, or spelling, a skill folder carrying no `REQUIREMENT.md`, and a credential-shaped value in the tree the package ships. Each is a fact with no false-positive class behind it.
+
+Three of the four are the ones `scripts/core/verify.sh` already fails a push on. The secret scan is the one entry gating without a stage behind it, added on that same fact-or-judgment test rather than as a side effect of registering a measure, and the architecture record already ranks content leaving the repository above content that stays.
 
 Everything else reports. A heavy bullet, a long entry, a board row nothing resolves, a degradation term in a comment, and an implementation reaching history ahead of its test are judgments a reader settles. A push failing on one of those teaches contributors to route around the stage, which is the split recorded across every audit here and the one this command inherits rather than moves.
 
@@ -53,7 +57,13 @@ The verdict is published as a field as well as an exit code. A reader branching
 
 A per-machine folder that is not on this disk reports as `absent` and moves neither the verdict nor the exit code. Every one of those folders is gitignored, so a fresh clone and every CI run carry none of them, and counting six expected absences as failures pins the verdict at `incomplete` forever. A signal that never changes is one nobody reads after the second time they see it.
 
-The allowance is narrow. It covers a per-machine corpus refusing because its folder is missing, and nothing else. A tracked tree that cannot be found is a broken checkout, and a per-machine verb refusing for any other reason is a broken verb. Both stay `unmeasured`.
+Which refusals count as an absence is declared per audit rather than inferred from the corpus alone. A per-machine corpus counts a missing folder. An upstream corpus counts every reason the advisory verb publishes, since each of the three means there is nothing resolved to measure. The secret scan overrides its tracked default for the three reasons that mean the project publishes nothing at all.
+
+Everything else stays `unmeasured`. That covers a tree git cannot list, which is a broken checkout, and a package declaring no `files` field, where a publish would pack the whole tree and the scan read none of it. Both are a corpus that exists and went unread, so softening either would report a pass over a shipped tree nobody measured.
+
+The override exists because the corpus answers the wrong question for one audit. What earns it is `private: true`, the one declaration that a package is never published, so a project carrying it reports an absent corpus rather than a broken one. Without that the aggregate would report `incomplete` in every such project on every run, which is the permanent signal this section opens by rejecting.
+
+`upstream` is the third corpus value, carried by the advisory check alone. Its count moves when someone publishes rather than when someone edits here, so it is kept out of the retained baseline for the mirror image of the reason gitignored scratch is, and an offline run reports it absent rather than pinning the verdict at `incomplete` on every machine without a network.
 
 Every run states how many corpora it measured against how many it skipped, including a run with no findings at all. A count of what passed reads as a verdict on the whole set unless the run also says what it never reached.
 

package/docs/agents/commands.md

@@ -9,48 +9,50 @@ Full help: `aitk <command> --help`. Behavior notes for the install and sync verb
 
 ## Project-level
 
-| Command                    | Purpose                                                                                                                                   |
-| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
-| `aitk init [path]`         | Bootstrap a project with selected toolkit domains                                                                                         |
-| `aitk sync [path]`         | Sync all installed domains in a target project                                                                                            |
-| `aitk sync --check`        | Report toolkit drift and the installed version against the newest published (`--json`, `--exit-code`)                                     |
-| `aitk sandbox [cat:cmd]`   | Run sandbox scenarios (interactive or routed), toolkit-only like the tree it reads                                                        |
-| `aitk sandbox reset`       | Reset sandbox to baseline                                                                                                                 |
-| `aitk sandbox clean`       | Wipe the sandbox                                                                                                                          |
-| `aitk sandbox check`       | Score a provisioned sandbox against a scenario expectation (`--json` for the verdict)                                                     |
-| `aitk sandbox coverage`    | Report which scenarios declare expectations (`--json`, `--strict`, `--skills`)                                                            |
-| `aitk indexes regen`       | Regenerate `index.md` files from sibling frontmatter                                                                                      |
-| `aitk docs [topic]`        | Emit toolkit reference docs (`list`, or a topic by name)                                                                                  |
-| `aitk design render`       | Render `.claude/DESIGN.md` tokens to HTML and CSS                                                                                         |
-| `aitk slides render`       | Render a `.claude/SLIDES.md` source into a PowerPoint deck                                                                                |
-| `aitk slides list`         | List the available slide layouts (`--json` for the catalog)                                                                               |
-| `aitk feedback`            | Write toolkit feedback from stdin to `.claude/review/`, or open a GitHub issue with `--github`                                            |
-| `aitk transcripts <url>`   | Fetch a YouTube transcript with metadata frontmatter (needs `yt-dlp`)                                                                     |
-| `aitk tasks archive`       | Move a shipped task off the board, clear its ordering row, and regenerate the index                                                       |
-| `aitk tasks pull-request`  | Record a pull request number on the task a branch closes, by stem or `--plan` (`--json`)                                                  |
-| `aitk tasks outcome`       | Mark outcomes `[x]` on a task by position, repeating `--close` (`--json`)                                                                 |
-| `aitk tasks validate`      | Report board rows whose plan, task file, group, file set, or blocker does not hold (`--json`)                                             |
-| `aitk intake list`         | Report intake folder counts, or one folder's items, keeping what is unread with `--unread` (`--json`)                                     |
-| `aitk intake answer`       | Write selections into one cluster's answer slots, repeating `--set <item>=<answer>` (`--json`)                                            |
-| `aitk teach list`          | Report learning workspaces and the ordinal a new one takes, or what one workspace holds (`--json`)                                        |
-| `aitk teach open`          | Open a workspace at the next ordinal with its mission, resources, and glossary files (`--json`)                                           |
-| `aitk teach resource`      | Record sources and leads in a workspace, repeating `--read` or `--lead` as `<title>=<url>` (`--json`)                                     |
-| `aitk teach glossary`      | Add terms to a workspace glossary alphabetically, repeating `--term <term>=<definition>` (`--json`)                                       |
-| `aitk records validate`    | Report a session record or a standard against the standard governing it, per kind (`--json`)                                              |
-| `aitk records size`        | Report what each record folder holds and how much of it is recent, heaviest first (`--json`)                                              |
-| `aitk records push`        | Commit the nine backed record folders and push them to a private records remote (`--json`)                                                |
-| `aitk records pull`        | Fetch the records remote and write it back, refusing rather than discarding unpushed records (`--json`)                                   |
-| `aitk sessions list`       | Resolve live sessions to the worktree and branch each holds, filtered by `--branch` (`--json`)                                            |
-| `aitk comments scan`       | Measure comment density by language and comment kind, with a trend recomputed from git                                                    |
-| `aitk context audit`       | Report required sections, length, cited paths, reference form, catalog tables, provenance, superseded-decision narration, and index drift |
-| `aitk markdown audit`      | Fail any markdown path on a banned character, word, or spelling, and report the structural checkpoints                                    |
-| `aitk claude skills audit` | Report both skill corpora against the mechanical rules in `standards/skill.md`                                                            |
-| `aitk claude skills drift` | Name the shipped skill bodies rewritten between a given ref and `HEAD`, and the installed version against the newest published (`--json`) |
-| `aitk gov test-order`      | Report where an implementation reached history ahead of the test covering it (`--json`)                                                   |
-| `aitk audits run`          | Run every audit as one set, report per check under one verdict, and compare each count to the recorded baseline (`--json`, `--record`)    |
-| `aitk audits list`         | List every audit the set runs, with the corpus each reads and whether it gates (`--json`)                                                 |
-| `aitk capture [source]`    | Render HTML capture sources to PNG, toolkit-only and absent from an installed package                                                     |
-| `aitk upgrade`             | Reinstall the CLI globally with the package manager the install path names (`--json`)                                                     |
+| Command                    | Purpose                                                                                                                                        |
+| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `aitk init [path]`         | Bootstrap a project with selected toolkit domains                                                                                              |
+| `aitk sync [path]`         | Sync all installed domains in a target project                                                                                                 |
+| `aitk sync --check`        | Report toolkit drift and the installed version against the newest published (`--json`, `--exit-code`)                                          |
+| `aitk sandbox [cat:cmd]`   | Run sandbox scenarios (interactive or routed), toolkit-only like the tree it reads                                                             |
+| `aitk sandbox reset`       | Reset sandbox to baseline                                                                                                                      |
+| `aitk sandbox clean`       | Wipe the sandbox                                                                                                                               |
+| `aitk sandbox check`       | Score a provisioned sandbox against a scenario expectation (`--json` for the verdict)                                                          |
+| `aitk sandbox coverage`    | Report which scenarios declare expectations (`--json`, `--strict`, `--skills`)                                                                 |
+| `aitk indexes regen`       | Regenerate `index.md` files from sibling frontmatter                                                                                           |
+| `aitk docs [topic]`        | Emit toolkit reference docs (`list`, or a topic by name)                                                                                       |
+| `aitk design render`       | Render `.claude/DESIGN.md` tokens to HTML and CSS                                                                                              |
+| `aitk slides render`       | Render a `.claude/SLIDES.md` source into a PowerPoint deck                                                                                     |
+| `aitk slides list`         | List the available slide layouts (`--json` for the catalog)                                                                                    |
+| `aitk feedback`            | Write toolkit feedback from stdin to `.claude/review/`, or open a GitHub issue with `--github`                                                 |
+| `aitk transcripts <url>`   | Fetch a YouTube transcript with metadata frontmatter (needs `yt-dlp`)                                                                          |
+| `aitk tasks archive`       | Move a shipped task off the board, clear its ordering row, and regenerate the index                                                            |
+| `aitk tasks pull-request`  | Record a pull request number on the task a branch closes, by stem or `--plan` (`--json`)                                                       |
+| `aitk tasks outcome`       | Mark outcomes `[x]` on a task by position, repeating `--close` (`--json`)                                                                      |
+| `aitk tasks validate`      | Report board rows whose plan, task file, group, file set, or blocker does not hold (`--json`)                                                  |
+| `aitk intake list`         | Report intake folder counts, or one folder's items, keeping what is unread with `--unread` (`--json`)                                          |
+| `aitk intake answer`       | Write selections into one cluster's answer slots, repeating `--set <item>=<answer>` (`--json`)                                                 |
+| `aitk teach list`          | Report learning workspaces and the ordinal a new one takes, or what one workspace holds (`--json`)                                             |
+| `aitk teach open`          | Open a workspace at the next ordinal with its mission, resources, and glossary files (`--json`)                                                |
+| `aitk teach resource`      | Record sources and leads in a workspace, repeating `--read` or `--lead` as `<title>=<url>` (`--json`)                                          |
+| `aitk teach glossary`      | Add terms to a workspace glossary alphabetically, repeating `--term <term>=<definition>` (`--json`)                                            |
+| `aitk records validate`    | Report a session record or a standard against the standard governing it, per kind (`--json`)                                                   |
+| `aitk records size`        | Report what each record folder holds and how much of it is recent, heaviest first (`--json`)                                                   |
+| `aitk records push`        | Commit the nine backed record folders and push them to a private records remote (`--json`)                                                     |
+| `aitk records pull`        | Fetch the records remote and write it back, refusing rather than discarding unpushed records (`--json`)                                        |
+| `aitk sessions list`       | Resolve live sessions to the worktree and branch each holds, filtered by `--branch` (`--json`)                                                 |
+| `aitk comments scan`       | Measure comment density by language and comment kind, with a trend recomputed from git                                                         |
+| `aitk context audit`       | Report required sections, length, cited paths, reference form, catalog tables, provenance, superseded-decision narration, and index drift      |
+| `aitk markdown audit`      | Fail any markdown path on a banned character, word, or spelling, and report the structural checkpoints                                         |
+| `aitk claude skills audit` | Report both skill corpora against the mechanical rules in `standards/skill.md`                                                                 |
+| `aitk claude skills drift` | Name the shipped skill bodies rewritten between a given ref and `HEAD`, and the installed version against the newest published (`--json`)      |
+| `aitk gov test-order`      | Report where an implementation reached history ahead of the test covering it (`--json`)                                                        |
+| `aitk secrets scan`        | Report credential-shaped values in the tree the package ships, keyed on issued values rather than on words (`--json`)                          |
+| `aitk deps audit`          | Report published advisories against the resolved dependency set, refusing rather than reporting clean when the index is unreachable (`--json`) |
+| `aitk audits run`          | Run every audit as one set, report per check under one verdict, and compare each count to the recorded baseline (`--json`, `--record`)         |
+| `aitk audits list`         | List every audit the set runs, with the corpus each reads and whether it gates (`--json`)                                                      |
+| `aitk capture [source]`    | Render HTML capture sources to PNG, toolkit-only and absent from an installed package                                                          |
+| `aitk upgrade`             | Reinstall the CLI globally with the package manager the install path names (`--json`)                                                          |
 
 ## Domain commands
 
@@ -72,6 +74,8 @@ Each domain exposes a consistent shape where applicable: `list`, `install`, `syn
 | `comments`  | `scan`                                                                                      |
 | `context`   | `audit`                                                                                     |
 | `markdown`  | `audit`                                                                                     |
+| `secrets`   | `scan`                                                                                      |
+| `deps`      | `audit`                                                                                     |
 | `audits`    | `run`, `list`                                                                               |
 
 Common patterns:

package/docs/agents/index.md

@@ -26,6 +26,7 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [Scripting](scripting.md): The runtime catalogs that replace hardcoded names, what each carries, and a headless invocation per domain
 - [Sessions](sessions.md): Resolving live peer sessions to the worktree and branch each holds, the liveness confidence field, the unresolved reasons, and what the read depends on
 - [Skill audit](skills-audit.md): Measuring both skill corpora against standards/skill.md, the checks it reads, the requirement gate that is the only failing one, and the drift verb that names bodies rewritten since a ref
+- [State-scoped risk](state-scoped-risk.md): Reading committed state rather than an arriving change, the shipped-tree corpus the secret scan reads, what it keys on and how a deliberate value is exempted, the advisory check and its network failure mode, and why one gates while the other reports
 - [Tasks](tasks.md): Selecting a shipped task by stem or pull request, recording a number and closing an outcome, the refusal reasons, the board and backlog checks validate runs, and why the board root defaults to the main worktree
 - [Teach](teach.md): Listing learning workspaces and the ordinal a new one takes, opening one with its required files, recording sources and glossary terms, resolving what the next lesson needs before it is written, the refusal reasons, and why every write here runs through a verb
 - [Test order](test-order.md): Reading where an implementation reached history ahead of its test, how a pair is decided, the three verdicts, the coverage the pairing cannot reach, and why the check reports rather than gates

package/docs/agents/scripting.md

@@ -129,8 +129,23 @@ SANDBOX_SCENARIO=sync aitk sandbox infra:tooling
 
 # Read every audit as one record. Exit 2 is a fact, 3 an audit that did not report
 aitk audits run --json
+
+# Read committed state rather than an arriving change. Exit 2 carries findings
+aitk secrets scan --json
+aitk deps audit --json
 ```
 
+The two state-scoped verbs both exit 2 on findings and mean different things by
+it. A credential in the shipped tree is a fact and fails `aitk audits run`, while
+a published advisory is a judgment that reports and moves no verdict. Neither
+reads a diff, so a consumer already running a review surface gets no overlap.
+
+Both refuse rather than report clean when they have no corpus, and the refusal
+reason is the field to branch on. A project publishing nothing refuses the secret
+scan with `no-manifest`, and one whose dependencies are not installed refuses the
+advisory check with `no-lockfile`. The aggregate reads those as an absent corpus
+rather than a broken run, so neither pins its verdict at `incomplete`.
+
 `aitk tooling sync` is the one verb above whose flag is mandatory headlessly. It
 overwrites every golden config a stack ships, which reaches the CI workflow, the
 git hooks, the end-to-end harness, and the shell scripts under `scripts/`, so a

package/docs/agents/state-scoped-risk.md

@@ -0,0 +1,105 @@
+---
+title: State-scoped risk
+description: Reading committed state rather than an arriving change, the shipped-tree corpus the secret scan reads, what it keys on and how a deliberate value is exempted, the advisory check and its network failure mode, and why one gates while the other reports
+---
+
+# State-scoped risk
+
+Every review surface a session can reach is scoped to a change. `claude-review` reads the branch diff, `claude-pr-review` reads a pull request, and `code-review` takes a diff, a branch, or a path. A risk that arrived before the range under review is invisible to all three by construction, which is what these two commands answer.
+
+| Question                                                 | Command             |
+| -------------------------------------------------------- | ------------------- |
+| Does a credential sit in the tree this repository ships? | `aitk secrets scan` |
+| Does a resolved dependency carry a published advisory?   | `aitk deps audit`   |
+
+Neither reads a range. That boundary is deliberate: change-scoped correctness review already exists, and a state-scoped bug scan would be a different product competing with it. Both register in `aitk audits run`, so a reader who runs the aggregate gets them without knowing they exist.
+
+## Secrets in the shipped tree
+
+```bash
+aitk secrets scan
+aitk secrets scan --json
+aitk secrets scan ../my-app
+```
+
+The corpus is the package's own `files` field rather than a list the check keeps. That field is the single statement of which trees leave this repository, so a second list beside it would answer the same question and drift. It also carries the negations the publish already makes, which is what puts the sandbox tree, the eval tree, and every test file out of scope by the rule that keeps them out of the tarball rather than by an exclusion this check invented.
+
+The plugin reaches a target by a different route, loading live from `claude/` rather than from a tarball. That folder is a `files` entry too, and its `standards` and `snippets` symlinks resolve into trees the field lists in their own right, so both routes land inside the same corpus.
+
+Three root files are read whether or not the field names them, being `package.json`, the readme, and the license, since npm packs those on every publish. A negation still removes one, because a field that excludes a file outranks the default that included it.
+
+### What the corpus leaves out
+
+The corpus answers what the package publishes, which is narrower than what the repository holds. Measured against this repository on 2026-08-21, the scan read 544 files and left 593 of the 1139 git lists unread. Those include everything under `.claude/`, `wiki/`, and `internal/`, the workflow definitions under `.github/`, and the trees the publish negations remove, being `scripts/sandbox/`, `scripts/eval/`, `src/capture/`, and every test file.
+
+A public repository makes that gap readable by anyone, so a clean run means no credential in the published tree rather than none in the repository. The run states the number on every pass, including a clean one, so the bound travels with the verdict. Widening the corpus to every tracked file is a separate decision, since the row this implements puts the shipped tree first on the record's rule that content leaving the repository gates harder than content that stays.
+
+### What it keys on
+
+Every pattern matches an issued value and none of them matches a word. A scan keyed on `password`, `secret`, or `token` fires on the environment reads, the workflow inputs, and the prose that name those things, and this repository ships all three. Keying on values instead is what makes the exclusion set empty: measured across the shipped tree on 2026-08-21, 544 files produced zero findings with nothing exempted.
+
+The set covers issuer-stamped shapes, being AWS access key ids, GitHub tokens in both forms, Google API keys, Slack tokens and webhooks, Stripe live keys, Anthropic and OpenAI keys, npm tokens, and private key block headers. What it does not reach is a credential no issuer stamps recognizably, which no exclusion policy would have helped with either.
+
+A reported value is redacted to its two ends. Those are what a reader needs to find it in the file and to tell one match from another, and the middle is the part no report should carry.
+
+### Exempting a deliberate value
+
+A line carrying a credential-shaped value on purpose takes an inline marker, either on the line itself or on the line directly above it:
+
+```bash
+# aitk-allow-secret: documented sample from the vendor's own reference
+AWS_KEY="<the sample value>"
+```
+
+Only a marker naming a reason counts. A bare token reads as a line that meant to say something and did not, which is the rule `stub: true` already applies to a seed field set to anything but `true`, and honoring it would let a typo mute a finding.
+
+The exemption travels with the line rather than sitting in a path list away from it, so a reader meeting a muted match finds the reason on the spot. A path allow-list was weighed and declined: the noise it would target is word-keyed and spread past the fixture trees, so it would hide part of the noise and none of the risk.
+
+### Exit codes and gating
+
+Exit codes are `0` when the shipped tree carries no credential-shaped value, `1` for a refusal, and `2` for at least one value found.
+
+This is the one entry in `aitk audits run` that gates without a `verify.sh` stage behind it. A credential in the published tree is a fact rather than a judgment, which is the test the catalog asks any gating addition to pass, and the architecture record already ranks content leaving the repository above content that stays.
+
+A refusal is never a clean tree. Five reasons produce one, and each exits `1`, because zero findings over zero files reads in the report exactly like zero findings over the whole shipped tree.
+
+| Reason             | What it means                                                | In the aggregate |
+| ------------------ | ------------------------------------------------------------ | ---------------- |
+| `no-manifest`      | No `package.json`, so nothing is published from this tree    | absent           |
+| `no-publish`       | The manifest declares `private`, so it publishes nothing     | absent           |
+| `no-shipped-files` | The `files` field matched nothing git lists                  | absent           |
+| `no-files-field`   | A publish would pack the whole tree, and none of it was read | unmeasured       |
+| `no-git`           | git could not list the tree, so the corpus is unknown        | unmeasured       |
+
+The split turns on whether a corpus exists. The first three mean this project publishes nothing, which is where most targets installing this CLI sit, so reporting them as unmeasured would pin the aggregate at `incomplete` there forever.
+
+The last two mean a corpus exists and went unread, so neither is softened. `private` is what separates them, since a manifest with no `files` field publishes everything rather than nothing and the field alone cannot tell those apart. Declaring `private: true` is the way a project that never publishes says so.
+
+## Advisories against the resolved dependencies
+
+```bash
+aitk deps audit
+aitk deps audit --json
+```
+
+The check shells the runtime's own advisory command rather than carrying an index. A vendored advisory database is a second corpus to keep current, and what this is worth is the report rather than the data.
+
+It refuses for three reasons, and each is an absence rather than a break: no `package.json`, no lockfile beside it, and no record back from the lookup. The lockfile is checked here rather than left to the underlying command, because a project whose dependencies were never resolved needs an install and not a retry, and one message naming the network would send half the readers at the wrong cause.
+
+That buys the one failure mode no other audit here carries. The command reaches a network, so an unreachable index has to be told from a tree with nothing against it. The exit code cannot separate them, since the underlying command exits non-zero both on advisories found and on a lookup that failed, so the record on stdout is what decides: output that parses is a measurement, and output that does not is a refusal under `no-record`.
+
+Exit codes are `0` when nothing is published against the resolved set, `1` for a refusal, and `2` for at least one advisory.
+
+### Why it reports rather than gates
+
+A published advisory is a fact about the index and a judgment about this tree, since the upgrade closing it may not exist yet. A push failing on one would teach a contributor to route around the stage while nothing about the dependency has changed, which is the split every other reporting measure here rests on.
+
+The corpus is recorded as `upstream`, a third value beside `tracked` and `per-machine`. Its count moves when someone publishes rather than when someone edits here, so a retained baseline would report growth against a tree nobody touched, and the aggregate keeps it out of the record for the mirror image of the reason it keeps gitignored scratch out.
+
+The same value decides what an offline run reports. An index this machine could not reach is an ordinary absence rather than a broken checkout, so it lands as `absent` and moves no verdict. Reading it as unmeasured would pin the aggregate at `incomplete` on every machine without a network, which is a signal nobody reads after the second time they see it.
+
+## Reading either from a skill
+
+An exit code says nothing about a call made from a session, since a shell profile may wrap the binary in a function taking its status from a later command. Read the `--json` record instead.
+
+The secret scan publishes `findings`, `files`, `skipped`, and `listed`, where `listed` is everything git reports so a consumer can state the bound alongside the verdict. The advisory check publishes `advisories` and a `severities` object. A refusal from either publishes `reason` and `message` and no measurement keys at all, which is what separates it from a clean run.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/aitk",
   "type": "module",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/src/audits/baseline.ts

@@ -53,6 +53,8 @@ export type Delta =
   | { readonly id: string; readonly kind: 'unrecorded' }
   /** Gitignored scratch, whose counts are one machine's and answer nobody else. */
   | { readonly id: string; readonly kind: 'per-machine' }
+  /** A network index, whose count moves when someone publishes rather than edits. */
+  | { readonly id: string; readonly kind: 'upstream' }
   /** The audit did not report, so there is nothing to compare. */
   | { readonly id: string; readonly kind: 'unmeasured' }
 
@@ -62,7 +64,9 @@ export type Delta =
  * Only a tracked corpus is retained. A gitignored record folder holds one
  * machine's session scratch, so committing its counts writes a floor no other
  * clone can reproduce, and every contributor would read a regression against a
- * number that describes somebody else's disk.
+ * number that describes somebody else's disk. An upstream count is left out
+ * for the mirror-image reason: it moves when an advisory is published, so a
+ * recorded floor would report growth against a tree nobody touched.
  *
  * An audit that did not report is left out rather than written as zero. Zeros
  * there record a clean corpus nobody measured, and the next run reads its real
@@ -95,6 +99,9 @@ export function compareBaseline(
   results: readonly AuditResult[],
 ): Delta[] {
   return results.map((result) => {
+    if (result.corpus === 'upstream') {
+      return { id: result.id, kind: 'upstream' as const }
+    }
     if (!result.tracked) return { id: result.id, kind: 'per-machine' as const }
     if (result.counts === undefined) {
       return { id: result.id, kind: 'unmeasured' as const }

package/src/audits/catalog.ts

@@ -1,4 +1,6 @@
+import type { AuditRefusal } from '@/deps/audit'
 import type { ValidateRefusal as RecordRefusal } from '@/records/validate'
+import type { ScanRefusal } from '@/secrets/scan'
 import type { ValidateRefusal as BoardRefusal } from '@/tasks/validate'
 
 /**
@@ -16,6 +18,17 @@ export type Corpus =
   | 'tracked'
   /** Gitignored session scratch, so the numbers are one machine's alone. */
   | 'per-machine'
+  /**
+   * Read from an index off this machine, so the count moves when someone
+   * publishes rather than when someone edits here.
+   *
+   * Its own member rather than either of the two above. A baseline would
+   * record growth nobody caused, which is what keeps it out of the retained
+   * set alongside per-machine scratch, and an index this run could not reach
+   * is an ordinary absence rather than the broken checkout a missing tracked
+   * tree would be.
+   */
+  | 'upstream'
 
 export type AuditStatus =
   /** The audit reported and every count it produced is zero. */
@@ -47,6 +60,17 @@ export interface AuditSpec {
    */
   readonly gatingExits: readonly number[]
   readonly corpus: Corpus
+  /**
+   * Refusal reasons that mean this audit has no corpus here rather than that
+   * it broke, overriding what the corpus alone would allow.
+   *
+   * Present only where the corpus answers wrongly. A tracked corpus normally
+   * allows nothing, since a tree that ships to targets and cannot be found is
+   * a broken checkout, and the secret scan is the exception: a project that
+   * publishes nothing has no shipped tree to read, which is an ordinary state
+   * rather than a defect.
+   */
+  readonly absentReasons?: readonly string[]
   /**
    * Pulls the counts worth retaining out of this verb's record.
    *
@@ -62,7 +86,10 @@ export interface AuditResult {
   readonly id: string
   readonly label: string
   readonly status: AuditStatus
+  /** Retained by the baseline, which is `tracked` alone. */
   readonly tracked: boolean
+  /** Why it is or is not retained, which `tracked` alone cannot say. */
+  readonly corpus: Corpus
   readonly exitCode: number
   readonly counts?: Record<string, number>
   /** Why the audit did not report, present only on `unmeasured`. */
@@ -271,6 +298,26 @@ function boardCounts(record: unknown): Record<string, number> | undefined {
   })
 }
 
+/**
+ * Reads the advisory verb's per-severity object rather than a total.
+ *
+ * A single count folds a critical advisory into a low one, and the response to
+ * the two differs. The keys are read off the record rather than listed here,
+ * so a severity the index adds is carried instead of silently dropped.
+ */
+function advisoryCounts(record: unknown): Record<string, number> | undefined {
+  const severities = asObject(asObject(record)?.severities)
+  if (severities === undefined) return undefined
+
+  const counts: Record<string, number> = {}
+  for (const [severity, value] of Object.entries(severities)) {
+    if (typeof value !== 'number') return undefined
+    counts[`advisories-${severity}`] = value
+  }
+
+  return counts
+}
+
 function findingsOnly(record: unknown): Record<string, number> | undefined {
   const root = asObject(record)
   if (root === undefined) return undefined
@@ -318,10 +365,12 @@ const RECORD_KINDS: readonly (readonly [string, Corpus])[] = [
 /**
  * Every audit the aggregate runs.
  *
- * `context`, `markdown`, and `skills` are the three that gate, which is exactly
- * the set `scripts/core/verify.sh` already fails a push on. Adding a fourth
- * here widens what fails a push without anyone deciding to, and the split this
- * repository records gates a fact and reports a judgment.
+ * `context`, `markdown`, and `skills` gate because `scripts/core/verify.sh`
+ * already fails a push on each. `secrets` is the one entry that gates without
+ * a stage behind it, added deliberately rather than as a side effect, since a
+ * credential in the published tree is a fact and the split this repository
+ * records gates a fact and reports a judgment. Weigh any further addition
+ * against that test rather than against the count.
  *
  * Each verb runs once in its fullest form. Running the gating half separately
  * would walk the same tree twice for a number the full record already carries.
@@ -386,6 +435,46 @@ export const AUDITS: readonly AuditSpec[] = [
     corpus: 'tracked',
     counts: testOrderCounts,
   },
+  {
+    id: 'secrets',
+    label: 'Shipped tree secrets',
+    argv: ['secrets', 'scan', '--json'],
+    // The fourth gate, and the first added since the note above was written.
+    // A credential-shaped value sitting in the tree this repository publishes
+    // is a fact rather than a judgment, which is the test that note asks any
+    // addition to pass. It is decided here and stated in the context entry
+    // rather than arriving as a side effect of registering a measure.
+    gatingExits: [EXIT_FINDINGS],
+    corpus: 'tracked',
+    // The three reasons that mean this tree publishes nothing, which is where
+    // most targets installing this CLI sit. Without the allowance the
+    // aggregate reports `incomplete` on every run in every such project and
+    // never changes, which is the permanent signal the per-machine allowance
+    // exists against.
+    //
+    // Two reasons are deliberately left out, and both are a corpus that exists
+    // and went unread. `no-git` is a broken checkout, and `no-files-field` is a
+    // publish that would pack the whole tree, so calling either an absence
+    // would report a pass over a shipped tree nobody measured.
+    absentReasons: [
+      'no-manifest',
+      'no-publish',
+      'no-shipped-files',
+    ] satisfies ScanRefusal[],
+    counts: findingsOnly,
+  },
+  {
+    id: 'deps',
+    label: 'Dependency advisories',
+    argv: ['deps', 'audit', '--json'],
+    // Reports rather than gates, on the same split. A published advisory is a
+    // fact about the index and a judgment about this tree, since the upgrade
+    // may not exist yet, and a push failing on one teaches a contributor to
+    // route around the stage while nothing about the dependency has changed.
+    gatingExits: [],
+    corpus: 'upstream',
+    counts: advisoryCounts,
+  },
 ]
 
 export function auditFor(id: string): AuditSpec | undefined {
@@ -432,6 +521,25 @@ const ABSENT_REASONS: readonly (RecordRefusal | BoardRefusal)[] = [
   'no-board',
 ]
 
+/**
+ * Every reason the advisory verb refuses for, all of which are an absence.
+ *
+ * An index it could not reach, a project that is not JavaScript, and one whose
+ * dependencies were never resolved are three states in which there is nothing
+ * to measure rather than something broken. The verb has no fourth reason, so
+ * this is its whole union rather than a chosen subset, and typing it that way
+ * fails the build if a later reason arrives without this decision being made.
+ *
+ * Typed against that module's own union for the reason the record reasons are:
+ * a literal here would go on matching nothing after a rename and turn every
+ * offline run back into an unmeasured audit.
+ */
+const ADVISORY_ABSENT_REASONS: readonly AuditRefusal[] = [
+  'no-record',
+  'no-lockfile',
+  'no-manifest',
+]
+
 /**
  * Whether a refusal is a folder this machine never created rather than a break.
  *
@@ -443,15 +551,25 @@ const ABSENT_REASONS: readonly (RecordRefusal | BoardRefusal)[] = [
  * A tracked corpus gets no such allowance. That tree ships to targets, so a
  * checkout that cannot find it is broken, and reading the absence as ordinary
  * would report a pass over a corpus nobody measured.
+ *
+ * An upstream corpus takes the allowance for a different reason. Its index is
+ * off this machine, so an offline run reaches nothing through no fault of the
+ * tree, and pinning the verdict at incomplete every time the network is down
+ * is the same signal-nobody-reads failure the per-machine case already names.
  */
+function absentReasonsFor(spec: AuditSpec): readonly string[] {
+  if (spec.absentReasons !== undefined) return spec.absentReasons
+  if (spec.corpus === 'per-machine') return ABSENT_REASONS
+  if (spec.corpus === 'upstream') return ADVISORY_ABSENT_REASONS
+  return []
+}
+
 function isExpectedAbsence(spec: AuditSpec, record: unknown): boolean {
-  if (spec.corpus !== 'per-machine') return false
+  const allowed = absentReasonsFor(spec)
+  if (allowed.length === 0) return false
 
   const reason = asObject(record)?.reason
-  return (
-    typeof reason === 'string' &&
-    (ABSENT_REASONS as readonly string[]).includes(reason)
-  )
+  return typeof reason === 'string' && allowed.includes(reason)
 }
 
 /**
@@ -471,6 +589,7 @@ export function classify(
     id: spec.id,
     label: spec.label,
     tracked: isTracked(spec),
+    corpus: spec.corpus,
     exitCode,
   }
 

package/src/audits/run.ts

@@ -85,6 +85,7 @@ export async function runAudits(
           label: spec.label,
           status: 'unmeasured' as const,
           tracked: spec.corpus === 'tracked',
+          corpus: spec.corpus,
           exitCode: 1,
           reason: `could not be started: ${error instanceof Error ? error.message : String(error)}`,
         }

package/src/cli.ts

@@ -26,6 +26,8 @@ import { register as markdown } from '@/commands/markdown'
 import { register as records } from '@/commands/records'
 import { register as sessions } from '@/commands/sessions'
 import { register as audits } from '@/commands/audits'
+import { register as secrets } from '@/commands/secrets'
+import { register as deps } from '@/commands/deps'
 import { register as upgrade } from '@/commands/upgrade'
 import { readInstalled, UNKNOWN_LABEL } from '@/version/installed'
 import { palette } from '@/ui'
@@ -63,6 +65,8 @@ function showHelp(): void {
     `${GREY}│${NC}    markdown [cmd]     ${GREY}# Report markdown against the attribute standards (audit)${NC}`,
     `${GREY}│${NC}    records [cmd]      ${GREY}# Session records under .claude/ (validate, size, push, pull)${NC}`,
     `${GREY}│${NC}    sessions [cmd]     ${GREY}# Resolve live sessions to worktree and branch (list)${NC}`,
+    `${GREY}│${NC}    secrets [cmd]      ${GREY}# Read the shipped tree for credential-shaped values (scan)${NC}`,
+    `${GREY}│${NC}    deps [cmd]         ${GREY}# Read the resolved dependency set for advisories (audit)${NC}`,
     `${GREY}│${NC}    audits [cmd]       ${GREY}# Run every health check as one set (run, list)${NC}`,
     `${GREY}│${NC}    upgrade            ${GREY}# Reinstall the CLI globally with the manager that installed it${NC}`,
     `${GREY}│${NC}`,
@@ -104,6 +108,8 @@ function showHelp(): void {
     `${GREY}│${NC}    aitk records size --json`,
     `${GREY}│${NC}    aitk records push --json`,
     `${GREY}│${NC}    aitk sessions list --json`,
+    `${GREY}│${NC}    aitk secrets scan --json`,
+    `${GREY}│${NC}    aitk deps audit --json`,
     `${GREY}│${NC}    aitk audits run --json`,
     `${GREY}│${NC}    aitk upgrade --json`,
     `${GREY}└${NC}`,
@@ -148,6 +154,8 @@ context(program)
 markdown(program)
 records(program)
 sessions(program)
+secrets(program)
+deps(program)
 audits(program)
 upgrade(program)