Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
bump: patch
---

### Changed

- Pointer records no longer carry an as-of date or recheck trigger; stored values keep theirs.
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
bump: patch
---

### Changed

- Pointer records no longer carry an as-of date or recheck trigger; stored values keep theirs.
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
bump: patch
---

### Changed

- Pointer records no longer carry an as-of date or recheck trigger; stored values keep theirs.
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
bump: patch
---

### Changed

- Pointer records no longer carry an as-of date or recheck trigger; stored values keep theirs.
7 changes: 7 additions & 0 deletions .changes/testing/docs-drop-pointer-stamps-batch6-d790d70d.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
bump: patch
---

### Changed

- Pointer records no longer carry an as-of date or recheck trigger; stored values keep theirs.
2 changes: 1 addition & 1 deletion plugins/code-tidying/agents/comment-reviewer.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ skills:
tools: "Read, Grep, Glob, Bash, Edit"
model: sonnet
effort: medium
maxTurns: 80 # fields: https://code.claude.com/docs/en/sub-agents#supported-frontmatter-fields (as of 2026-11-02; recheck when that table renames or drops skills, effort or maxTurns)
maxTurns: 80 # fields: https://code.claude.com/docs/en/sub-agents#supported-frontmatter-fields
---
You are the comment reviewer: a fresh reader of code you did not write, dispatched by
`/code-tidying:remove-comments` to triage one scope's comments. The skill reaches you through your
Expand Down
12 changes: 4 additions & 8 deletions plugins/code-tidying/skills/audit-dead-code/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -117,13 +117,11 @@ Bounded by design. Evidence catalogue: [context/adjudication.md](context/adjudic
5. Fan out to fresh-context subagents in batches when the set is large; if spawn depth is
exhausted, say so and adjudicate inline at the same cap rather than silently shrinking the set
(the depth-limit pointer record is in
[context/adjudication.md, Bounding the pass](context/adjudication.md#bounding-the-pass); relay
as of 2026-10-11, recheck when that record's pointer moves out of that section).
[context/adjudication.md, Bounding the pass](context/adjudication.md#bounding-the-pass)).
6. **Optional LSP assist**, never required and never a lane: when Claude Code's `LSP` tool is
available, `findReferences` on one candidate is one more evidence source. Read what it returns
in [LSP tool behavior](https://code.claude.com/docs/en/tools-reference#lsp-tool-behavior)
before reading a count as dead (as of 2026-11-03; recheck when that section changes what
`findReferences` returns). Done when every emitted candidate has a `dead`, `uncertain` or
before reading a count as dead. Done when every emitted candidate has a `dead`, `uncertain` or
`alive` verdict with evidence, or the cap stopped the batch and the report says so.

## Hard rules
Expand All @@ -141,8 +139,7 @@ Bounded by design. Evidence catalogue: [context/adjudication.md](context/adjudic
counted as a finding. A fourth verdict landing there is the alarm, not the answer.
- **Exit codes are never run health.** Run health comes from the detector's output, never its
exit code. The documented codes: [vulture](https://github.com/jendrikseipp/vulture#exit-codes),
[knip](https://knip.dev/reference/cli#--no-exit-code). As of 2026-11-03; recheck when one of
those sections changes its exit codes.
[knip](https://knip.dev/reference/cli#--no-exit-code)..
- **Presence is proven by invocation**, never by a locator hit (measured: `command -v
rust-analyzer` succeeds while invocation fails).
- **knip evaluates repo-controlled config through jiti.** Disclose it on every run that loads one.
Expand Down Expand Up @@ -213,8 +210,7 @@ verdicts live in the report and in a comment at the declaration, and the same ca
Say so rather than emitting a directive. The probe behind the Go half is in
[context/adjudication.md](context/adjudication.md#suppression-formats) "Suppression formats"; `//lint:ignore` belongs
to staticcheck, per
[Ignoring problems with linter directives](https://staticcheck.dev/docs/configuration/#ignoring-problems-with-linter-directives)
(as of 2026-11-03; recheck when that section names gopls among the tools that read it).
[Ignoring problems with linter directives](https://staticcheck.dev/docs/configuration/#ignoring-problems-with-linter-directives).

`dead` and `uncertain` verdicts are session-scoped: an un-suppressed `uncertain` returns next run.
A committed vulture whitelist raises `F821` under a consumer's ruff config; say so when you emit
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -29,8 +29,7 @@ strings), then the config files, then the framework-registration patterns for th
language. Stop at the first piece of real evidence.

The optional `LSP` assist is one more source, never a substitute. What `findReferences` returns:
[LSP tool behavior](https://code.claude.com/docs/en/tools-reference#lsp-tool-behavior),
as of 2026-11-03; recheck when that section changes what `findReferences` returns.
[LSP tool behavior](https://code.claude.com/docs/en/tools-reference#lsp-tool-behavior).

## Verdict rules

Expand Down Expand Up @@ -59,8 +58,6 @@ parser recognized, and it is a bug report about the detector, not a finding abou
and adjudicate inline at the same cap. Silently shrinking the set is the failure mode to avoid.
Pointer for the depth limit and what a subagent at it can spawn:
[Let subagents spawn their own subagents](https://code.claude.com/docs/en/sub-agents#let-subagents-spawn-their-own-subagents).
As of: 2026-10-11. Recheck trigger: that section changes the depth default or what a subagent
at the limit can spawn.

## Suppression formats

Expand All @@ -76,17 +73,15 @@ The skill writes nothing. It emits ready-to-paste text and the human decides.
```

Where knip reads its config and what `ignore` takes:
[ignore](https://knip.dev/reference/configuration#ignore), as of 2026-11-03; recheck when that
section changes what an `ignore` entry takes.
[ignore](https://knip.dev/reference/configuration#ignore).

**vulture**, a whitelist entry carrying the adjudication as its comment:

```python
format_legacy_row # adjudicated alive: dispatched by name from handlers.py
```

How vulture reads a whitelist: [Whitelists](https://github.com/jendrikseipp/vulture#whitelists),
as of 2026-11-03; recheck when that section changes how a whitelist is passed.
How vulture reads a whitelist: [Whitelists](https://github.com/jendrikseipp/vulture#whitelists).

**A committed vulture whitelist raises `F821` (undefined name) under a consumer's ruff config.**
Say so whenever you emit one; the consumer either excludes the file in `ruff.toml` or keeps the
Expand Down
10 changes: 3 additions & 7 deletions plugins/code-tidying/skills/audit-dead-code/context/lanes.md
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,6 @@ non-source paths are not in the coverage total.
healthy, so stdout genuinely cannot establish run health here.
- **Exit codes:** the lane never reads knip's exit code; run health comes from stderr, as above.
Pointer: [knip CLI `--no-exit-code`](https://knip.dev/reference/cli#--no-exit-code).
As of: 2026-11-10. Recheck trigger: that section gives findings and errors different codes.
- **Config evaluation is disclosed, not denied.** knip loads a repository-controlled
`knip.config.{ts,js,mjs,cjs}` through `jiti`; a planted side effect in one **fired**. Every run
that loads a config module says so in the report. The same experiment in Python did not fire:
Expand Down Expand Up @@ -101,8 +100,7 @@ non-source paths are not in the coverage total.
is degraded. Conflating them would let one stray `.toml` in scope suppress the whole Python lane.
knip's `ERROR:` stderr rule does **not** generalize here.
- **Exit codes:** health comes from the shape of stderr, never from the code. Pointer:
[vulture exit codes](https://github.com/jendrikseipp/vulture#exit-codes). As of: 2026-11-10.
Recheck trigger: that section adds a code that separates an input error from a crash.
[vulture exit codes](https://github.com/jendrikseipp/vulture#exit-codes).
- **Pipeline safety:** vulture's output is written to a temp file and read back in full, never
piped into a truncating reader; a stdout closed early fails the run (measured, versions per the
record above).
Expand Down Expand Up @@ -219,8 +217,7 @@ non-source paths are not in the coverage total.
dead. Precision of this shape is unmeasured beyond the fixture contract (a workflow reference
saves the script it names; a script named nowhere is the one candidate).
- **`-H -o` attribute each match to its file**, and the lane relies on BSD grep taking both flags.
Pointer: [FreeBSD grep(1)](https://man.freebsd.org/cgi/man.cgi?query=grep&sektion=1). As of:
2026-11-10. Recheck trigger: the lane fails on a BSD or macOS userland, or the man page drops
Pointer: [FreeBSD grep(1)](https://man.freebsd.org/cgi/man.cgi?query=grep&sektion=1). Recheck trigger: the lane fails on a BSD or macOS userland, or the man page drops
either flag.

## Why Rust, a .NET build lane, and an LSP scanning lane are absent
Expand All @@ -236,8 +233,7 @@ non-source paths are not in the coverage total.
- **An LSP scanning lane**: a lane is a detector the scan script runs in one batch. Claude Code's
`LSP` tool is used only as an optional per-candidate assist inside the already-bounded
adjudication. Pointer:
[LSP tool behavior](https://code.claude.com/docs/en/tools-reference#lsp-tool-behavior). As of:
2026-11-10. Recheck trigger: that section lets a script or a batch call reach the tool.
[LSP tool behavior](https://code.claude.com/docs/en/tools-reference#lsp-tool-behavior).
- **`DiagnosticTag.Unnecessary`**: wrong scope everywhere (file-local/private only), push-only
delivery, and Claude Code's diagnostics normalizer strips `tags` entirely.
- **pyright as a Python detector**: measured, it misses `dead_fn`, `DeadClass`, and `dead_method`.
Expand Down
23 changes: 7 additions & 16 deletions plugins/code-tidying/skills/batch-simplify/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,15 +15,13 @@ discovery, filtering, grouping, ordering, verification, and report around it. On
runs per group, never both. `docs` mode keeps the simplifier agent, since `simplify` has no
factual-staleness pass, and records `State: skipped (docs mode)`. Repo mode never invokes
`simplify` ([context/repo-mode.md](context/repo-mode.md) gives the reasons). Pointer for how an invoked skill's body stays in context:
[Skill content lifecycle](https://code.claude.com/docs/en/skills#skill-content-lifecycle). As of:
2026-11-10. Recheck trigger: that section changes when an invoked skill's body leaves context.
[Skill content lifecycle](https://code.claude.com/docs/en/skills#skill-content-lifecycle).

**Identity check.** The name is in the skill listing; the description is advisory. A description
that reads as a different surface is a likely user or project shadow: skip with a warning and
spawn the agent. A name listed with no description is invoked with the warning "identity
confirmed by name alone". Pointer for when the listing drops a description:
[Skill descriptions are cut short](https://code.claude.com/docs/en/skills#skill-descriptions-are-cut-short).
As of: 2026-10-11. Recheck trigger: that section changes when a description is dropped.

**Mutation.** Groups the step runs over go one at a time, never in a parallel wave. Before each
invocation, fingerprint the tracked files outside that group; any change there right after it is
Expand All @@ -33,10 +31,8 @@ invocation, fingerprint the tracked files outside that group; any change there r
session`, invocation refused (the reason, never retried), or identity mismatch; those three name the axis
line: settings or environment, plan, platform or provider, host surface; and the enable path,
read live from [Bundled skills](https://code.claude.com/docs/en/skills#bundled-skills).
As of: 2026-10-11. Recheck trigger: that section changes the settings that turn a bundled skill
off. The matching row is in
[context/bundled-simplify.md](context/bundled-simplify.md#decision-records)
(relay as of 2026-10-11; recheck when that table is renamed or moved). When `simplify` runs but
The matching row is in
[context/bundled-simplify.md](context/bundled-simplify.md#decision-records). When `simplify` runs but
says it ran a weaker procedure, the state is resolved but degraded, and the report relays its disclosure instead of
calling the group fully simplified.

Expand All @@ -63,8 +59,7 @@ invocation:

Treat a failure (not a repository, git unavailable) as an unknown value and carry on. Keep these as
separate body Bash calls rather than pre-compute lines. How the harness runs a skill's injected
commands: [How injected commands run](https://code.claude.com/docs/en/skills#how-injected-commands-run),
as of 2026-11-03; recheck when that section changes how injected commands run.
commands: [How injected commands run](https://code.claude.com/docs/en/skills#how-injected-commands-run).

## Variables

Expand All @@ -87,7 +82,7 @@ For any batch run (Phases 1-8), copy `templates/checklist.md` into your project'

Supported formats: `24h`, `48h`, `72h`, `7d`, `2d`, `1w`. Default: `48h`.

**Normalize before use:** convert to long units before passing the window to `git log --since` (the option's entry is under [Commit Limiting](https://git-scm.com/docs/git-log#_commit_limiting), as of 2026-11-03; recheck when that entry documents the short `h`, `d` and `w` forms):
**Normalize before use:** convert to long units before passing the window to `git log --since` (the option's entry is under [Commit Limiting](https://git-scm.com/docs/git-log#_commit_limiting); recheck when that entry documents the short `h`, `d` and `w` forms):

- `<N>h` → `<N> hours` (e.g., `48h` → `48 hours`)
- `<N>d` → `<N> days` (e.g., `7d` → `7 days`)
Expand Down Expand Up @@ -229,8 +224,6 @@ Track one entry per group, each with:
When the task tools (`TaskCreate`, `TaskUpdate`) are present in this session, create each entry with `TaskCreate`. When they are not, write the entries as a per-group list in the run's copied checklist (or inline, when it has no working-notes copy) and tick them there; never fail or stop the run for want of the tools. Decide by whether the tools are present, not by the model: which sessions get them is upstream's call and changes by release.

- **Pointer**: when deciding whether this session should have the task tools, fetch [tools-reference: Task tool availability](https://code.claude.com/docs/en/tools-reference#task-tool-availability) live.
- **As of**: 2026-10-10
- **Recheck trigger**: that section changes the default model set or the opt-ins that enable the tools.

### Phase 6: Run simplification waves

Expand Down Expand Up @@ -298,8 +291,7 @@ conflated whenever the request is "run simplify":

- **`simplify` (bundled skill)**: a single-target cleanup pass that edits the code it reviews.
What it reviews and which targets it takes are in the pointer records in
[context/bundled-simplify.md](context/bundled-simplify.md#decision-records)
(relay as of 2026-10-11; recheck when that table is renamed or moved).
[context/bundled-simplify.md](context/bundled-simplify.md#decision-records).
- **This skill (marketplace plugin).** Sweeps a time window, a branch, or the whole repository in
waves, grouped by ecosystem in dependency order, with a checklist, a deferred-items contract,
and a docs mode for factual staleness.
Expand All @@ -315,8 +307,7 @@ one sweep would mix their diffs.
**Availability is never assumed.** This section states what to do when a bundled surface
resolves, never that it is present. The pointer records, including what can turn a bundled skill
off, live in
[context/bundled-simplify.md](context/bundled-simplify.md#decision-records)
(relay as of 2026-10-11; recheck when that table is renamed or moved).
[context/bundled-simplify.md](context/bundled-simplify.md#decision-records).

## Next

Expand Down
Original file line number Diff line number Diff line change
@@ -1,22 +1,19 @@
# The bundled `simplify` skill: pointer records

Detail behind the boundary section in
[SKILL.md](../SKILL.md#boundary-the-bundled-simplify-skill) (relay as of 2026-10-11; recheck when
that section is renamed or moved). Each row states the decision this skill takes about the bundled
surface, the upstream section to read for the current behavior, the date it was checked, and the
event that makes it worth checking again. The sibling `tidy` skill keeps its own record against
[SKILL.md](../SKILL.md#boundary-the-bundled-simplify-skill). Each row states the decision this skill takes about the bundled
surface, and the upstream section to read for the current behavior. The sibling `tidy` skill keeps its own record against
the same surface in
[../../tidy/reference/bundled-simplify.md](../../tidy/reference/bundled-simplify.md#decision-records)
(relay as of 2026-10-11; recheck when that table is renamed or moved).
[../../tidy/reference/bundled-simplify.md](../../tidy/reference/bundled-simplify.md#decision-records).

## Decision records

| Decision | Pointer | As of | Recheck trigger |
|---|---|---|---|
| Treat `simplify` as a bundled skill invoked by its own name, never through an alias | The `/simplify` row in [All commands](https://code.claude.com/docs/en/commands#all-commands) | 2026-10-11 | The row gains an alias or stops being labeled Skill |
| Treat every `simplify` run as a mutating pass, so the Native step's mutation gate applies | The same row | 2026-10-11 | The row documents a report-only mode or a flag that turns applying off |
| Give it one group's file list per run, never a time window or a whole repository. One target may already span many files, so the registry row's trigger, "a multi-file argument form", is half fired; what still separates the two skills is the time window, the repository mode, and ecosystem grouping | The same row, for the targets it takes | 2026-10-11 | The row gains a time-window argument, a repository mode, or ecosystem grouping |
| Check presence every run; a session where it does not resolve is an ordinary session | [Bundled skills](https://code.claude.com/docs/en/skills#bundled-skills), for what turns bundled skills off | 2026-10-11 | That section changes the settings that turn a bundled skill off |
| Decision | Pointer |
|---|---|
| Treat `simplify` as a bundled skill invoked by its own name, never through an alias | The `/simplify` row in [All commands](https://code.claude.com/docs/en/commands#all-commands) |
| Treat every `simplify` run as a mutating pass, so the Native step's mutation gate applies | The same row |
| Give it one group's file list per run, never a time window or a whole repository. One target may already span many files, so the registry row's trigger, "a multi-file argument form", is half fired; what still separates the two skills is the time window, the repository mode, and ecosystem grouping | The same row, for the targets it takes |
| Check presence every run; a session where it does not resolve is an ordinary session | [Bundled skills](https://code.claude.com/docs/en/skills#bundled-skills), for what turns bundled skills off |

## Why the verdict is complementary

Expand Down
Loading
Loading