@erclx/aitk 3.47.0 → 3.47.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/claude/.claude-plugin/plugin.json +1 -1
- package/docs/agents/commands.md +56 -56
- package/docs/agents/index.md +1 -1
- package/docs/agents/superseded.md +35 -7
- package/package.json +1 -1
- package/src/commands/gov.ts +64 -9
- package/src/gov/superseded.ts +223 -15
package/docs/agents/commands.md
CHANGED
|
@@ -9,62 +9,62 @@ Full help: `aitk <command> --help`. Behavior notes for the install and sync verb
|
|
|
9
9
|
|
|
10
10
|
## Project-level
|
|
11
11
|
|
|
12
|
-
| Command | Purpose
|
|
13
|
-
| -------------------------- |
|
|
14
|
-
| `aitk init [path]` | Bootstrap a project with selected toolkit domains
|
|
15
|
-
| `aitk sync [path]` | Sync all installed domains in a target project
|
|
16
|
-
| `aitk sync --check` | Report toolkit drift and the installed version against the newest published (`--json`, `--exit-code`)
|
|
17
|
-
| `aitk sandbox [cat:cmd]` | Run sandbox scenarios (interactive or routed), toolkit-only like the tree it reads
|
|
18
|
-
| `aitk sandbox reset` | Reset sandbox to baseline
|
|
19
|
-
| `aitk sandbox clean` | Wipe the sandbox
|
|
20
|
-
| `aitk sandbox check` | Score a provisioned sandbox against a scenario expectation (`--json` for the verdict)
|
|
21
|
-
| `aitk sandbox coverage` | Report which scenarios declare expectations (`--json`, `--strict`, `--skills`)
|
|
22
|
-
| `aitk indexes regen` | Regenerate `index.md` files from sibling frontmatter
|
|
23
|
-
| `aitk docs [topic]` | Emit toolkit reference docs (`list`, or a topic by name)
|
|
24
|
-
| `aitk design render` | Render `.claude/DESIGN.md` tokens to HTML and CSS
|
|
25
|
-
| `aitk slides render` | Render a `.claude/SLIDES.md` source into a PowerPoint deck
|
|
26
|
-
| `aitk slides list` | List the available slide layouts (`--json` for the catalog)
|
|
27
|
-
| `aitk feedback` | Write toolkit feedback from stdin to `.claude/review/feedback/`, or open a GitHub issue with `--github`
|
|
28
|
-
| `aitk transcripts <url>` | Fetch a YouTube transcript with metadata frontmatter (needs `yt-dlp`)
|
|
29
|
-
| `aitk tasks archive` | Move a shipped task off the board, clear its ordering row, and regenerate the index
|
|
30
|
-
| `aitk tasks pull-request` | Record a pull request number on the task a branch closes, by stem or `--plan` (`--json`)
|
|
31
|
-
| `aitk tasks outcome` | Mark outcomes `[x]` on a task by position, repeating `--close` (`--json`)
|
|
32
|
-
| `aitk tasks validate` | Report board rows whose plan, task file, group, file set, or blocker does not hold (`--json`)
|
|
33
|
-
| `aitk intake list` | Report intake folder counts, or one folder's items, keeping what is unread with `--unread` (`--json`)
|
|
34
|
-
| `aitk intake answer` | Write selections into one cluster's answer slots, repeating `--set <item>=<answer>` (`--json`)
|
|
35
|
-
| `aitk teach list` | Report learning workspaces and the ordinal a new one takes, or what one workspace holds (`--json`)
|
|
36
|
-
| `aitk teach open` | Open a workspace at the next ordinal with its mission, resources, and glossary files (`--json`)
|
|
37
|
-
| `aitk teach resource` | Record sources and leads in a workspace, repeating `--read` or `--lead` as `<title>=<url>` (`--json`)
|
|
38
|
-
| `aitk teach glossary` | Add terms to a workspace glossary alphabetically, repeating `--term <term>=<definition>` (`--json`)
|
|
39
|
-
| `aitk records validate` | Report a session record or a standard against the standard governing it, per kind (`--json`)
|
|
40
|
-
| `aitk records migrate` | Rewrite the records a validate finding names a recoverable transform for (`--write`, `--json`)
|
|
41
|
-
| `aitk records size` | Report what each record folder holds and how much of it is recent, heaviest first (`--json`)
|
|
42
|
-
| `aitk records push` | Commit the nine backed record folders and push them to a private records remote (`--json`)
|
|
43
|
-
| `aitk records pull` | Fetch the records remote and write it back, refusing rather than discarding unpushed records (`--json`)
|
|
44
|
-
| `aitk sessions list` | Resolve live sessions to the worktree and branch each holds, filtered by `--branch` (`--json`)
|
|
45
|
-
| `aitk worktrees list` | Report which worktrees are reclaimable, keyed on the pull request having merged, with every refusal and the removal route named (`--json`)
|
|
46
|
-
| `aitk comments scan` | Measure comment density by language and comment kind, with a trend recomputed from git
|
|
47
|
-
| `aitk context audit` | Report required sections, length, cited paths, reference form, catalog tables, provenance, superseded-decision narration, and index drift
|
|
48
|
-
| `aitk markdown audit` | Fail any markdown path on a banned character, word, or spelling, and report the structural checkpoints
|
|
49
|
-
| `aitk claude skills audit` | Report both skill corpora against the mechanical rules in `standards/skill.md`
|
|
50
|
-
| `aitk standards audit` | Report the corpus against the `## Success criterion` gate, failing only on a standard new to the branch (`--json`, `--arrivals-only`)
|
|
51
|
-
| `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`)
|
|
52
|
-
| `aitk claude skills reach` | Report the bodies in either skill corpus citing a toolkit path no target project receives, exiting 2 on an unqualified one
|
|
53
|
-
| `aitk claude skills rank` | Score either skill corpus's descriptions against a case corpus by TF-IDF cosine similarity, reporting rank-one and top-three (`--cases <path>`)
|
|
54
|
-
| `aitk claude routing` | Report per `CLAUDE.md` section how many bullets name a path and how many of those a path-scoped rule already covers (`--json`)
|
|
55
|
-
| `aitk gov test-order` | Report where an implementation reached history ahead of the test covering it (`--json`)
|
|
56
|
-
| `aitk gov superseded` | Report where the tree still asserts a value a changed convention no longer produces, keyed on the value (`--json`)
|
|
57
|
-
| `aitk gov restated` | Report every instruction the always-loaded file or a rule shares with the seed, a shipped skill body, or another rule, classed and with its anchors named (`--json`)
|
|
58
|
-
| `aitk secrets scan` | Report credential-shaped values in the tree the package ships, keyed on issued values rather than on words (`--json`)
|
|
59
|
-
| `aitk deps audit` | Report published advisories against the resolved dependency set, refusing rather than reporting clean when the index is unreachable (`--json`)
|
|
60
|
-
| `aitk labels audit` | Report the labels a changed set earns from the pull request label map and the paths no row reaches (`--json`)
|
|
61
|
-
| `aitk census [path]` | Report tracked file count, a breakdown by extension, and a line total that skips whatever reads as binary (`--json`)
|
|
62
|
-
| `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`)
|
|
63
|
-
| `aitk audits list` | List every audit the set runs, with the corpus each reads and whether it gates (`--json`)
|
|
64
|
-
| `aitk inventory [subject]` | Walk every route a project declares and group its elements by the property each computes, as a listing rather than a gate (`--json`)
|
|
65
|
-
| `aitk capture [source]` | Render HTML capture sources to PNG, toolkit-only and absent from an installed package
|
|
66
|
-
| `aitk serve [dir]` | Serve a directory on the loopback interface and print the link that opens it, running until interrupted (`--port`, `--entry`, `--json`)
|
|
67
|
-
| `aitk upgrade` | Reinstall the CLI globally with the package manager the install path names (`--json`)
|
|
12
|
+
| Command | Purpose |
|
|
13
|
+
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
14
|
+
| `aitk init [path]` | Bootstrap a project with selected toolkit domains |
|
|
15
|
+
| `aitk sync [path]` | Sync all installed domains in a target project |
|
|
16
|
+
| `aitk sync --check` | Report toolkit drift and the installed version against the newest published (`--json`, `--exit-code`) |
|
|
17
|
+
| `aitk sandbox [cat:cmd]` | Run sandbox scenarios (interactive or routed), toolkit-only like the tree it reads |
|
|
18
|
+
| `aitk sandbox reset` | Reset sandbox to baseline |
|
|
19
|
+
| `aitk sandbox clean` | Wipe the sandbox |
|
|
20
|
+
| `aitk sandbox check` | Score a provisioned sandbox against a scenario expectation (`--json` for the verdict) |
|
|
21
|
+
| `aitk sandbox coverage` | Report which scenarios declare expectations (`--json`, `--strict`, `--skills`) |
|
|
22
|
+
| `aitk indexes regen` | Regenerate `index.md` files from sibling frontmatter |
|
|
23
|
+
| `aitk docs [topic]` | Emit toolkit reference docs (`list`, or a topic by name) |
|
|
24
|
+
| `aitk design render` | Render `.claude/DESIGN.md` tokens to HTML and CSS |
|
|
25
|
+
| `aitk slides render` | Render a `.claude/SLIDES.md` source into a PowerPoint deck |
|
|
26
|
+
| `aitk slides list` | List the available slide layouts (`--json` for the catalog) |
|
|
27
|
+
| `aitk feedback` | Write toolkit feedback from stdin to `.claude/review/feedback/`, or open a GitHub issue with `--github` |
|
|
28
|
+
| `aitk transcripts <url>` | Fetch a YouTube transcript with metadata frontmatter (needs `yt-dlp`) |
|
|
29
|
+
| `aitk tasks archive` | Move a shipped task off the board, clear its ordering row, and regenerate the index |
|
|
30
|
+
| `aitk tasks pull-request` | Record a pull request number on the task a branch closes, by stem or `--plan` (`--json`) |
|
|
31
|
+
| `aitk tasks outcome` | Mark outcomes `[x]` on a task by position, repeating `--close` (`--json`) |
|
|
32
|
+
| `aitk tasks validate` | Report board rows whose plan, task file, group, file set, or blocker does not hold (`--json`) |
|
|
33
|
+
| `aitk intake list` | Report intake folder counts, or one folder's items, keeping what is unread with `--unread` (`--json`) |
|
|
34
|
+
| `aitk intake answer` | Write selections into one cluster's answer slots, repeating `--set <item>=<answer>` (`--json`) |
|
|
35
|
+
| `aitk teach list` | Report learning workspaces and the ordinal a new one takes, or what one workspace holds (`--json`) |
|
|
36
|
+
| `aitk teach open` | Open a workspace at the next ordinal with its mission, resources, and glossary files (`--json`) |
|
|
37
|
+
| `aitk teach resource` | Record sources and leads in a workspace, repeating `--read` or `--lead` as `<title>=<url>` (`--json`) |
|
|
38
|
+
| `aitk teach glossary` | Add terms to a workspace glossary alphabetically, repeating `--term <term>=<definition>` (`--json`) |
|
|
39
|
+
| `aitk records validate` | Report a session record or a standard against the standard governing it, per kind (`--json`) |
|
|
40
|
+
| `aitk records migrate` | Rewrite the records a validate finding names a recoverable transform for (`--write`, `--json`) |
|
|
41
|
+
| `aitk records size` | Report what each record folder holds and how much of it is recent, heaviest first (`--json`) |
|
|
42
|
+
| `aitk records push` | Commit the nine backed record folders and push them to a private records remote (`--json`) |
|
|
43
|
+
| `aitk records pull` | Fetch the records remote and write it back, refusing rather than discarding unpushed records (`--json`) |
|
|
44
|
+
| `aitk sessions list` | Resolve live sessions to the worktree and branch each holds, filtered by `--branch` (`--json`) |
|
|
45
|
+
| `aitk worktrees list` | Report which worktrees are reclaimable, keyed on the pull request having merged, with every refusal and the removal route named (`--json`) |
|
|
46
|
+
| `aitk comments scan` | Measure comment density by language and comment kind, with a trend recomputed from git |
|
|
47
|
+
| `aitk context audit` | Report required sections, length, cited paths, reference form, catalog tables, provenance, superseded-decision narration, and index drift |
|
|
48
|
+
| `aitk markdown audit` | Fail any markdown path on a banned character, word, or spelling, and report the structural checkpoints |
|
|
49
|
+
| `aitk claude skills audit` | Report both skill corpora against the mechanical rules in `standards/skill.md` |
|
|
50
|
+
| `aitk standards audit` | Report the corpus against the `## Success criterion` gate, failing only on a standard new to the branch (`--json`, `--arrivals-only`) |
|
|
51
|
+
| `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`) |
|
|
52
|
+
| `aitk claude skills reach` | Report the bodies in either skill corpus citing a toolkit path no target project receives, exiting 2 on an unqualified one |
|
|
53
|
+
| `aitk claude skills rank` | Score either skill corpus's descriptions against a case corpus by TF-IDF cosine similarity, reporting rank-one and top-three (`--cases <path>`) |
|
|
54
|
+
| `aitk claude routing` | Report per `CLAUDE.md` section how many bullets name a path and how many of those a path-scoped rule already covers (`--json`) |
|
|
55
|
+
| `aitk gov test-order` | Report where an implementation reached history ahead of the test covering it (`--json`) |
|
|
56
|
+
| `aitk gov superseded` | Report where the tree still asserts a value a changed convention no longer produces, keyed on the value and on the family stem behind a templated citation (`--json`) |
|
|
57
|
+
| `aitk gov restated` | Report every instruction the always-loaded file or a rule shares with the seed, a shipped skill body, or another rule, classed and with its anchors named (`--json`) |
|
|
58
|
+
| `aitk secrets scan` | Report credential-shaped values in the tree the package ships, keyed on issued values rather than on words (`--json`) |
|
|
59
|
+
| `aitk deps audit` | Report published advisories against the resolved dependency set, refusing rather than reporting clean when the index is unreachable (`--json`) |
|
|
60
|
+
| `aitk labels audit` | Report the labels a changed set earns from the pull request label map and the paths no row reaches (`--json`) |
|
|
61
|
+
| `aitk census [path]` | Report tracked file count, a breakdown by extension, and a line total that skips whatever reads as binary (`--json`) |
|
|
62
|
+
| `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`) |
|
|
63
|
+
| `aitk audits list` | List every audit the set runs, with the corpus each reads and whether it gates (`--json`) |
|
|
64
|
+
| `aitk inventory [subject]` | Walk every route a project declares and group its elements by the property each computes, as a listing rather than a gate (`--json`) |
|
|
65
|
+
| `aitk capture [source]` | Render HTML capture sources to PNG, toolkit-only and absent from an installed package |
|
|
66
|
+
| `aitk serve [dir]` | Serve a directory on the loopback interface and print the link that opens it, running until interrupted (`--port`, `--entry`, `--json`) |
|
|
67
|
+
| `aitk upgrade` | Reinstall the CLI globally with the package manager the install path names (`--json`) |
|
|
68
68
|
|
|
69
69
|
`aitk serve` ships and drives no browser, which is what separates it from the two that do. A generated page loses its stylesheet and its script to an editor preview and to a `file://` open, so the link is the delivery rather than a convenience, and every generated surface here reaches a reader through one. It binds `127.0.0.1` and never a wildcard, because what it is pointed at is routinely a gitignored record tree. It sends `cache-control: no-store`, since a preview exists to be edited and reloaded and a cached stylesheet reads as a fix that did not work.
|
|
70
70
|
|
package/docs/agents/index.md
CHANGED
|
@@ -35,7 +35,7 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
|
|
|
35
35
|
- [Citation reach](skills-reach.md): Reporting the skill bodies that cite a path no target project receives, which corpus the verb reads, the ownership key that decides what counts, the one-word qualifier that marks a citation as decided, and why the verb reports instead of gating
|
|
36
36
|
- [Standard success criteria](standards-audit.md): Reading the corpus against the Success criterion gate, why the check scopes to arrival rather than the whole corpus, and the exit codes it sets
|
|
37
37
|
- [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
|
|
38
|
-
- [Superseded values](superseded.md): Reading where the tree still asserts a value a changed convention no longer produces, why the sweep keys on the value rather than the file, the exemption marker, the blind
|
|
38
|
+
- [Superseded values](superseded.md): Reading where the tree still asserts a value a changed convention no longer produces, why the sweep keys on the value rather than the file, the family stem behind a templated citation, the exemption marker, the blind spots it cannot reach, and why it reports rather than gates
|
|
39
39
|
- [Targets](targets.md): The projects this toolkit installed into, the record the install writes against the sweep that backs it, what bounds each answer, and the cross-target pull request read
|
|
40
40
|
- [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
|
|
41
41
|
- [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
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: Superseded values
|
|
3
|
-
description: Reading where the tree still asserts a value a changed convention no longer produces, why the sweep keys on the value rather than the file, the exemption marker, the blind
|
|
3
|
+
description: Reading where the tree still asserts a value a changed convention no longer produces, why the sweep keys on the value rather than the file, the family stem behind a templated citation, the exemption marker, the blind spots it cannot reach, and why it reports rather than gates
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Superseded values
|
|
@@ -30,11 +30,31 @@ The slug transform is what proved it. Dropping the type segment left four fixtur
|
|
|
30
30
|
|
|
31
31
|
The whole corpus git lists: tracked files plus untracked ones git does not ignore. The untracked half keeps a file added on this branch in scope rather than one push later.
|
|
32
32
|
|
|
33
|
-
Matching is a literal substring,
|
|
33
|
+
Matching is a literal substring, for the value and for the family stem below it alike, so either one carrying regular-expression characters means what it says. Every occurrence on a line reports under its own column, since a line carrying the value twice is two edits, and a column both kinds reach reports once as the literal one.
|
|
34
34
|
|
|
35
35
|
Binary files are skipped on a NUL byte rather than on an extension list, and so is any listed path that will not open. Both are counted. A run states the files it opened against the files git listed, because a count of what passed reads as a verdict on the repository unless it also says how much it left out.
|
|
36
36
|
|
|
37
|
-
Pass an empty replacement to retire a value outright, as in `aitk gov superseded feature-feat- ""`. Findings report the same way
|
|
37
|
+
Pass an empty replacement to retire a value outright, as in `aitk gov superseded feature-feat- ""`. Findings report the same way, none is annotated, since a line cannot carry a replacement that does not exist, and no templated form is read, since there is no second value for a stem to diverge from.
|
|
38
|
+
|
|
39
|
+
## The templated citation
|
|
40
|
+
|
|
41
|
+
A citation naming a family as a pattern carries neither value. `aitk-*` and `internal-<X>` are the two forms this corpus writes, and a literal comparison matches neither, so a rename running the verb once per name reports clean while the family citations stay stale. Two of those on `#1250` had inverted, stating the old prefix as a guard, which left a rule instructing the next session to flag the correct naming as a mismatch.
|
|
42
|
+
|
|
43
|
+
Beside the literal comparison the run matches a family stem, derived from the segment the two values actually differ on, with everything they share carried ahead of it. `toolkit-operator` to `aitk-operator` derives `toolkit`, and `aitk-cli` to `aitk-shell` derives `aitk-cli` rather than `aitk`, which is what keeps a rename of one folder off every sibling in its family.
|
|
44
|
+
|
|
45
|
+
Three forms report, decided by the character after the stem and its separator:
|
|
46
|
+
|
|
47
|
+
| Form | Shape | What it names |
|
|
48
|
+
| ------------- | ------------ | ---------------------------------- |
|
|
49
|
+
| `glob` | `<stem>-*` | the family written as a pattern |
|
|
50
|
+
| `placeholder` | `<stem>-<X>` | the family with a stand-in segment |
|
|
51
|
+
| `prefix` | `<stem>-` | the family written bare |
|
|
52
|
+
|
|
53
|
+
The stem has to start a name. A letter, a digit, an underscore, or a separator directly before it means the stem sits mid-name, which is what a temp-directory prefix such as `aitk-check-toolkit-` looks like, and a path separator or a backtick before it means a citation, which is what `claude/skills/toolkit-*` looks like.
|
|
54
|
+
|
|
55
|
+
A hit under any of the three counts as a finding and moves the exit code. A stale templated citation is as real as a literal one, and reporting it outside the count would recreate the silence being fixed one report shape further along.
|
|
56
|
+
|
|
57
|
+
Every hit in a markdown file carries the nearest heading above it. A line reads differently under the section holding it, and `Use the aitk-* prefix on an internal skill` is a prohibition under `## Must not` and an instruction anywhere else. A reviewer reading that line without its heading made exactly that misreading against this tree.
|
|
38
58
|
|
|
39
59
|
## The exemption marker
|
|
40
60
|
|
|
@@ -42,15 +62,23 @@ A declaration disagreeing with a convention for a stated reason carries `aitk-al
|
|
|
42
62
|
|
|
43
63
|
Only a marker naming a reason counts. A bare token is a line that meant to say something and did not, and honoring it would let a typo mute a finding. This is the `aitk-allow-secret` shape, and both read the same placement rule through one helper.
|
|
44
64
|
|
|
45
|
-
## The blind
|
|
65
|
+
## The blind spots
|
|
66
|
+
|
|
67
|
+
The sweep sees the value, its stem, and nothing else. A prose reference that went stale without carrying either is invisible here, which is not hypothetical: alongside the mechanical instances, one declaration had gone stale by citing the wrong standard for the transform, and it matches no string this sweep could have been given.
|
|
68
|
+
|
|
69
|
+
The second is a family written in a form the three shapes do not read: a bracket style other than `<>`, a glob with no separator ahead of it, or the family described in words. Adding a form is a change to the classifier rather than a name a caller can pass, since a list of names cannot reach this class by construction, which is the whole finding behind the stem.
|
|
70
|
+
|
|
71
|
+
A value sweep closes most of the first class and no part of either one. The help text and the frame name both on every run, so a clean report is not read as a clean tree.
|
|
72
|
+
|
|
73
|
+
## The false-positive rate
|
|
46
74
|
|
|
47
|
-
|
|
75
|
+
Over-reporting is the design here as it is for the literal half, and the corpus bounds it. Sweeping `toolkit-operator` to `aitk-operator` over this tree named one templated hit outside the change's own fixtures, a passage recording the retired `toolkit-` prefix as history, which reads correctly in place.
|
|
48
76
|
|
|
49
|
-
A
|
|
77
|
+
A version reporting a page of hits teaches the next rename to skip the verb, which is worse than the blind spot being fixed. Read a report against that rate rather than against zero.
|
|
50
78
|
|
|
51
79
|
## Exit codes
|
|
52
80
|
|
|
53
|
-
Exit codes are `0` when nothing asserts the superseded value, `1` for a refusal, and `2` for at least one finding. It refuses an empty superseded value, which would match every line rather than a convention, a superseded value equal to its replacement, which means no convention changed, and a tree git cannot list, since an empty list passes each of its zero files. An empty replacement is not among them, because retiring a value is an ordinary reason to run this.
|
|
81
|
+
Exit codes are `0` when nothing asserts the superseded value or its family, `1` for a refusal, and `2` for at least one finding of either kind. It refuses an empty superseded value, which would match every line rather than a convention, a superseded value equal to its replacement, which means no convention changed, and a tree git cannot list, since an empty list passes each of its zero files. An empty replacement is not among them, because retiring a value is an ordinary reason to run this.
|
|
54
82
|
|
|
55
83
|
Nothing wires this into `bun run check` or into a hook. A value sweep over-reports by construction, and gating a measure carrying a known false-positive class is what teaches contributors to route around the stage. `aitk gov test-order` is the sibling precedent.
|
|
56
84
|
|
package/package.json
CHANGED
package/src/commands/gov.ts
CHANGED
|
@@ -306,18 +306,31 @@ export function register(program: Command): void {
|
|
|
306
306
|
`\`${SUPERSEDED_MARKER}: <reason>\` marker on its own line or the one above.`,
|
|
307
307
|
'',
|
|
308
308
|
'Pass an empty replacement to retire a value outright. Findings report',
|
|
309
|
-
'the same way
|
|
310
|
-
'replacement that does not exist
|
|
309
|
+
'the same way, none is annotated, since a line cannot carry a',
|
|
310
|
+
'replacement that does not exist, and no templated form is read, since',
|
|
311
|
+
'there is no second value for a stem to diverge from.',
|
|
311
312
|
'',
|
|
312
|
-
'
|
|
313
|
+
'Templated forms, matched on the segment the two values differ on:',
|
|
314
|
+
' glob <stem>-* , the family written as a pattern',
|
|
315
|
+
' placeholder <stem>-<X> , the family written with a stand-in segment',
|
|
316
|
+
' prefix <stem>- , the family written bare',
|
|
317
|
+
'',
|
|
318
|
+
'A hit under one of them counts as a finding, since a stale templated',
|
|
319
|
+
'citation is as real as a literal one. Each carries the nearest heading',
|
|
320
|
+
'above it in a markdown file, because a line reading as a prohibition',
|
|
321
|
+
'under one section reads as an instruction under another.',
|
|
322
|
+
'',
|
|
323
|
+
'Blind spots:',
|
|
313
324
|
' a prose reference that went stale without carrying the value, such as',
|
|
314
325
|
' a declaration citing the wrong standard for the transform, matches',
|
|
315
326
|
' nothing here and is reached by reading rather than by this sweep',
|
|
327
|
+
' a family named in any other form, such as a bracket style other than',
|
|
328
|
+
' <>, a trailing glob with no separator, or a description in words',
|
|
316
329
|
'',
|
|
317
330
|
'Exit codes:',
|
|
318
|
-
' 0 nothing in the corpus asserts the superseded value',
|
|
331
|
+
' 0 nothing in the corpus asserts the superseded value or its family',
|
|
319
332
|
' 1 refused, with the reason on stderr or in the JSON record',
|
|
320
|
-
' 2 at least one declaration
|
|
333
|
+
' 2 at least one declaration asserts either',
|
|
321
334
|
'',
|
|
322
335
|
'Examples:',
|
|
323
336
|
' aitk gov superseded feature-feat- feature-',
|
|
@@ -520,7 +533,37 @@ function describeHit(hit: SupersededHit): string {
|
|
|
520
533
|
const note = hit.carriesReplacement
|
|
521
534
|
? ' (the replacement is on this line)'
|
|
522
535
|
: ''
|
|
523
|
-
|
|
536
|
+
const section = hit.heading === undefined ? '' : ` under ${hit.heading}`
|
|
537
|
+
return `[${hit.match}] ${hit.file}:${hit.line}:${hit.column}${section}${note}: ${hit.preview}`
|
|
538
|
+
}
|
|
539
|
+
|
|
540
|
+
/**
|
|
541
|
+
* Named separately from the literal hits rather than counted in with them. A
|
|
542
|
+
* templated hit is a wider match on a shorter string, so a reader weighing one
|
|
543
|
+
* is weighing a different question, and the section is where the forms it still
|
|
544
|
+
* cannot read are stated.
|
|
545
|
+
*/
|
|
546
|
+
function reportTemplated(
|
|
547
|
+
report: Extract<SupersededReport, { kind: 'measured' }>,
|
|
548
|
+
): void {
|
|
549
|
+
const templated = report.findings.filter((hit) => hit.match !== 'literal')
|
|
550
|
+
|
|
551
|
+
logStep('Templated')
|
|
552
|
+
if (report.stems === undefined) {
|
|
553
|
+
logInfo(
|
|
554
|
+
'no stem derives from these two values, so no templated citation was read',
|
|
555
|
+
)
|
|
556
|
+
} else if (templated.length === 0) {
|
|
557
|
+
logInfo(
|
|
558
|
+
`nothing names the family as ${report.stems.superseded}-*, ${report.stems.superseded}-<X>, or ${report.stems.superseded}- bare`,
|
|
559
|
+
)
|
|
560
|
+
} else {
|
|
561
|
+
for (const hit of templated) logWarn(describeHit(hit))
|
|
562
|
+
}
|
|
563
|
+
|
|
564
|
+
logInfo(
|
|
565
|
+
'not read: a family named in any other form, such as a bracket style other than <>, a trailing glob with no separator, or a description in words',
|
|
566
|
+
)
|
|
524
567
|
}
|
|
525
568
|
|
|
526
569
|
function reportSuperseded(
|
|
@@ -531,14 +574,26 @@ function reportSuperseded(
|
|
|
531
574
|
|
|
532
575
|
logStep('Sweep')
|
|
533
576
|
logInfo(`${report.superseded} → ${report.replacement} in ${root}`)
|
|
577
|
+
logInfo(
|
|
578
|
+
report.stems === undefined
|
|
579
|
+
? 'no family stem, so the sweep is the literal value alone'
|
|
580
|
+
: `family stem ${report.stems.superseded} → ${report.stems.replacement}`,
|
|
581
|
+
)
|
|
534
582
|
|
|
535
|
-
|
|
536
|
-
|
|
583
|
+
const literal = report.findings.filter((hit) => hit.match === 'literal')
|
|
584
|
+
|
|
585
|
+
// Named for the kind rather than for a verdict. `Clean` over the literal half
|
|
586
|
+
// alone would read as a clean tree on a run whose templated half is the one
|
|
587
|
+
// carrying every finding.
|
|
588
|
+
logStep('Literal')
|
|
589
|
+
if (literal.length === 0) {
|
|
537
590
|
logInfo('nothing in the corpus asserts the superseded value')
|
|
538
591
|
} else {
|
|
539
|
-
for (const finding of
|
|
592
|
+
for (const finding of literal) logWarn(describeHit(finding))
|
|
540
593
|
}
|
|
541
594
|
|
|
595
|
+
reportTemplated(report)
|
|
596
|
+
|
|
542
597
|
// Named rather than counted. A muted line is a judgment someone recorded,
|
|
543
598
|
// and a reader weighing this report has to be able to reach the reason.
|
|
544
599
|
logStep('Exempt')
|
package/src/gov/superseded.ts
CHANGED
|
@@ -15,11 +15,33 @@ import { listRepositoryFiles } from '@/git-files'
|
|
|
15
15
|
*/
|
|
16
16
|
export const SUPERSEDED_MARKER = 'aitk-allow-superseded'
|
|
17
17
|
|
|
18
|
+
/**
|
|
19
|
+
* What matched at one column.
|
|
20
|
+
*
|
|
21
|
+
* `literal` is the superseded value itself. The other three are the stem
|
|
22
|
+
* followed by a glob, by an angle-bracket placeholder, or by nothing that
|
|
23
|
+
* continues a name, which are the three forms this corpus writes a family in.
|
|
24
|
+
* A literal comparison reaches none of them, which is why a rename running the
|
|
25
|
+
* verb once per name reported clean over seven stale citations.
|
|
26
|
+
*/
|
|
27
|
+
export type SupersededMatch = 'literal' | 'glob' | 'placeholder' | 'prefix'
|
|
28
|
+
|
|
18
29
|
export interface SupersededHit {
|
|
19
30
|
readonly file: string
|
|
20
31
|
/** One-based, matching the `file:line` form a reader clicks. */
|
|
21
32
|
readonly line: number
|
|
22
33
|
readonly column: number
|
|
34
|
+
readonly match: SupersededMatch
|
|
35
|
+
/**
|
|
36
|
+
* The nearest heading above the hit in a markdown file, absent elsewhere and
|
|
37
|
+
* above the first heading.
|
|
38
|
+
*
|
|
39
|
+
* A line reads differently under the section holding it. `Use the aitk-*
|
|
40
|
+
* prefix on an internal skill` is a prohibition under `## Must not` and an
|
|
41
|
+
* instruction anywhere else, and a reviewer reading the line alone made
|
|
42
|
+
* exactly that misreading against this tree.
|
|
43
|
+
*/
|
|
44
|
+
readonly heading: string | undefined
|
|
23
45
|
/**
|
|
24
46
|
* Whether the replacement sits on the same line, outside the superseded
|
|
25
47
|
* occurrences themselves.
|
|
@@ -45,11 +67,22 @@ export interface SupersededOptions {
|
|
|
45
67
|
readonly replacement: string
|
|
46
68
|
}
|
|
47
69
|
|
|
70
|
+
/**
|
|
71
|
+
* The segment pair a templated citation is matched on, reported so a run states
|
|
72
|
+
* the net it cast rather than only what the net caught.
|
|
73
|
+
*/
|
|
74
|
+
export interface SupersededStems {
|
|
75
|
+
readonly superseded: string
|
|
76
|
+
readonly replacement: string
|
|
77
|
+
}
|
|
78
|
+
|
|
48
79
|
export type SupersededReport =
|
|
49
80
|
| {
|
|
50
81
|
readonly kind: 'measured'
|
|
51
82
|
readonly superseded: string
|
|
52
83
|
readonly replacement: string
|
|
84
|
+
/** Absent when the two values yield no bounded stem to match on. */
|
|
85
|
+
readonly stems: SupersededStems | undefined
|
|
53
86
|
/** Everything git listed, so the report states its own bound. */
|
|
54
87
|
readonly listed: number
|
|
55
88
|
/** Files opened, which is what the verdict actually covers. */
|
|
@@ -68,22 +101,181 @@ export type SupersededReport =
|
|
|
68
101
|
*/
|
|
69
102
|
const PREVIEW_LIMIT = 200
|
|
70
103
|
|
|
104
|
+
/** The separator a family name is built from across this corpus. */
|
|
105
|
+
const SEGMENT_SEPARATOR = '-'
|
|
106
|
+
|
|
107
|
+
/**
|
|
108
|
+
* A character that continues a name, so `aitk-` inside `aitk-cli` is read as
|
|
109
|
+
* one name rather than as the family prefix written bare.
|
|
110
|
+
*/
|
|
111
|
+
const NAME_CHARACTER = /[A-Za-z0-9]/
|
|
112
|
+
|
|
71
113
|
/**
|
|
72
|
-
*
|
|
73
|
-
*
|
|
74
|
-
*
|
|
114
|
+
* A character that puts the stem mid-name when it sits directly before it, so
|
|
115
|
+
* a stem is only read where a name starts.
|
|
116
|
+
*
|
|
117
|
+
* The separator is here and not in `NAME_CHARACTER` because it decides one side
|
|
118
|
+
* only. `aitk-check-toolkit-` is a temp-directory prefix and matched the stem
|
|
119
|
+
* `toolkit` on four fixtures before this, where `claude/skills/toolkit-*` is a
|
|
120
|
+
* path and has to keep matching.
|
|
121
|
+
*/
|
|
122
|
+
const SEGMENT_CONTINUATION = /[A-Za-z0-9_-]/
|
|
123
|
+
|
|
124
|
+
const HEADING = /^#{1,6}\s+\S/
|
|
125
|
+
|
|
126
|
+
/**
|
|
127
|
+
* A fence opening or closing a code block, tracked so a shell comment inside
|
|
128
|
+
* one is not read as the section a hit below it sits under. A `# Install` line
|
|
129
|
+
* in a bash block is the ordinary shape of that.
|
|
130
|
+
*/
|
|
131
|
+
const FENCE = /^\s*(?:```|~~~)/
|
|
132
|
+
|
|
133
|
+
/**
|
|
134
|
+
* The segment the two values differ on, carried with everything they share
|
|
135
|
+
* ahead of it.
|
|
136
|
+
*
|
|
137
|
+
* The shared prefix alone is what this exists against. `aitk-cli` and
|
|
138
|
+
* `aitk-feedback-file` share `aitk`, so a stem cut there matches every sibling
|
|
139
|
+
* and reports the whole family on a rename of one folder. Including the
|
|
140
|
+
* differing segment bounds the net to what actually changed, which leaves
|
|
141
|
+
* `aitk-cli` to `aitk-shell` matching neither sibling and `toolkit-operator` to
|
|
142
|
+
* `aitk-operator` matching the family prefix that did move.
|
|
143
|
+
*
|
|
144
|
+
* An empty replacement yields nothing. Retiring a value outright leaves no
|
|
145
|
+
* second value to diverge from, so every stem would run to the first segment
|
|
146
|
+
* and match the family the retirement never touched.
|
|
147
|
+
*/
|
|
148
|
+
export function deriveStems(
|
|
149
|
+
options: SupersededOptions,
|
|
150
|
+
): SupersededStems | undefined {
|
|
151
|
+
if (options.replacement === '') return undefined
|
|
152
|
+
|
|
153
|
+
const supersededSegments = options.superseded.split(SEGMENT_SEPARATOR)
|
|
154
|
+
const replacementSegments = options.replacement.split(SEGMENT_SEPARATOR)
|
|
155
|
+
|
|
156
|
+
let index = 0
|
|
157
|
+
while (
|
|
158
|
+
index < supersededSegments.length &&
|
|
159
|
+
index < replacementSegments.length &&
|
|
160
|
+
supersededSegments[index] === replacementSegments[index]
|
|
161
|
+
) {
|
|
162
|
+
index += 1
|
|
163
|
+
}
|
|
164
|
+
|
|
165
|
+
const superseded = trimSeparators(
|
|
166
|
+
supersededSegments.slice(0, index + 1).join(SEGMENT_SEPARATOR),
|
|
167
|
+
)
|
|
168
|
+
const replacement = trimSeparators(
|
|
169
|
+
replacementSegments.slice(0, index + 1).join(SEGMENT_SEPARATOR),
|
|
170
|
+
)
|
|
171
|
+
|
|
172
|
+
if (superseded === '' || replacement === '') return undefined
|
|
173
|
+
if (superseded === replacement) return undefined
|
|
174
|
+
|
|
175
|
+
return { superseded, replacement }
|
|
176
|
+
}
|
|
177
|
+
|
|
178
|
+
function trimSeparators(value: string): string {
|
|
179
|
+
let end = value.length
|
|
180
|
+
while (end > 0 && value[end - 1] === SEGMENT_SEPARATOR) end -= 1
|
|
181
|
+
return value.slice(0, end)
|
|
182
|
+
}
|
|
183
|
+
|
|
184
|
+
/**
|
|
185
|
+
* Which templated form sits at `column`, or nothing when the stem there
|
|
186
|
+
* continues into an ordinary name.
|
|
187
|
+
*
|
|
188
|
+
* The character after `<stem>-` decides all three, so one scan reads every
|
|
189
|
+
* form. A name character means a sibling spelled out, which the literal
|
|
190
|
+
* comparison already answers for or correctly ignores.
|
|
191
|
+
*/
|
|
192
|
+
function classifyStem(
|
|
193
|
+
line: string,
|
|
194
|
+
column: number,
|
|
195
|
+
stem: string,
|
|
196
|
+
): SupersededMatch | undefined {
|
|
197
|
+
const before = column === 0 ? '' : line[column - 1]
|
|
198
|
+
if (before !== '' && SEGMENT_CONTINUATION.test(before)) return undefined
|
|
199
|
+
|
|
200
|
+
const after = line[column + stem.length + 1] ?? ''
|
|
201
|
+
if (after === '*') return 'glob'
|
|
202
|
+
if (after === '<') return 'placeholder'
|
|
203
|
+
if (after !== '' && NAME_CHARACTER.test(after)) return undefined
|
|
204
|
+
return 'prefix'
|
|
205
|
+
}
|
|
206
|
+
|
|
207
|
+
/**
|
|
208
|
+
* Whether the value replacing whatever matched appears on the line somewhere
|
|
209
|
+
* other than inside the matched occurrences, which is what makes the flag mean
|
|
210
|
+
* anything when one value contains the other.
|
|
75
211
|
*
|
|
76
212
|
* An empty replacement carries nothing, so it answers false rather than the
|
|
77
213
|
* true every line returns from a containment test against the empty string.
|
|
78
214
|
* Retiring a value outright is what passes one, and reporting every finding as
|
|
79
215
|
* carrying its replacement there says the opposite of what happened.
|
|
216
|
+
*
|
|
217
|
+
* A templated hit reads the stem pair instead, since the line repairing
|
|
218
|
+
* `toolkit-*` carries `aitk-*` and never the full name either value spells.
|
|
80
219
|
*/
|
|
81
|
-
function carriesReplacement(
|
|
82
|
-
|
|
83
|
-
|
|
220
|
+
function carriesReplacement(
|
|
221
|
+
line: string,
|
|
222
|
+
options: SupersededOptions,
|
|
223
|
+
stems: SupersededStems | undefined,
|
|
224
|
+
match: SupersededMatch,
|
|
225
|
+
): boolean {
|
|
226
|
+
if (match === 'literal') {
|
|
227
|
+
if (options.replacement === '') return false
|
|
228
|
+
return line.split(options.superseded).join('').includes(options.replacement)
|
|
229
|
+
}
|
|
230
|
+
|
|
231
|
+
if (stems === undefined) return false
|
|
232
|
+
const matched = `${stems.superseded}${SEGMENT_SEPARATOR}`
|
|
233
|
+
return line
|
|
234
|
+
.split(matched)
|
|
235
|
+
.join('')
|
|
236
|
+
.includes(`${stems.replacement}${SEGMENT_SEPARATOR}`)
|
|
84
237
|
}
|
|
85
238
|
|
|
86
|
-
/**
|
|
239
|
+
/**
|
|
240
|
+
* Every column in one line carrying the superseded value or its family stem,
|
|
241
|
+
* ordered left to right.
|
|
242
|
+
*
|
|
243
|
+
* A stem occurrence sharing a column with a literal one is dropped. The stem is
|
|
244
|
+
* a prefix of the value it derives from whenever only the last segment moved,
|
|
245
|
+
* so the same text would otherwise report twice under two kinds.
|
|
246
|
+
*/
|
|
247
|
+
function matchLine(
|
|
248
|
+
line: string,
|
|
249
|
+
options: SupersededOptions,
|
|
250
|
+
stems: SupersededStems | undefined,
|
|
251
|
+
): { column: number; match: SupersededMatch }[] {
|
|
252
|
+
const matches: { column: number; match: SupersededMatch }[] = []
|
|
253
|
+
|
|
254
|
+
let column = line.indexOf(options.superseded)
|
|
255
|
+
while (column !== -1) {
|
|
256
|
+
matches.push({ column, match: 'literal' })
|
|
257
|
+
column = line.indexOf(options.superseded, column + 1)
|
|
258
|
+
}
|
|
259
|
+
|
|
260
|
+
if (stems !== undefined) {
|
|
261
|
+
const pattern = `${stems.superseded}${SEGMENT_SEPARATOR}`
|
|
262
|
+
let at = line.indexOf(pattern)
|
|
263
|
+
while (at !== -1) {
|
|
264
|
+
const form = classifyStem(line, at, stems.superseded)
|
|
265
|
+
if (form !== undefined && !matches.some((hit) => hit.column === at)) {
|
|
266
|
+
matches.push({ column: at, match: form })
|
|
267
|
+
}
|
|
268
|
+
at = line.indexOf(pattern, at + 1)
|
|
269
|
+
}
|
|
270
|
+
}
|
|
271
|
+
|
|
272
|
+
return matches.sort((first, second) => first.column - second.column)
|
|
273
|
+
}
|
|
274
|
+
|
|
275
|
+
/**
|
|
276
|
+
* Every occurrence of `superseded` or of its family stem in one file's text,
|
|
277
|
+
* exemptions separated.
|
|
278
|
+
*/
|
|
87
279
|
export function sweepText(
|
|
88
280
|
file: string,
|
|
89
281
|
text: string,
|
|
@@ -92,10 +284,19 @@ export function sweepText(
|
|
|
92
284
|
const lines = text.split('\n')
|
|
93
285
|
const findings: SupersededHit[] = []
|
|
94
286
|
const exempt: SupersededHit[] = []
|
|
287
|
+
const stems = deriveStems(options)
|
|
288
|
+
const sectioned = file.endsWith('.md')
|
|
289
|
+
let heading: string | undefined
|
|
290
|
+
let fenced = false
|
|
95
291
|
|
|
96
292
|
for (const [index, line] of lines.entries()) {
|
|
97
|
-
|
|
98
|
-
|
|
293
|
+
if (sectioned) {
|
|
294
|
+
if (FENCE.test(line)) fenced = !fenced
|
|
295
|
+
else if (!fenced && HEADING.test(line)) heading = line.trim()
|
|
296
|
+
}
|
|
297
|
+
|
|
298
|
+
const matches = matchLine(line, options, stems)
|
|
299
|
+
if (matches.length === 0) continue
|
|
99
300
|
|
|
100
301
|
const muted = isMarked(lines, index, SUPERSEDED_MARKER)
|
|
101
302
|
const bucket = muted ? exempt : findings
|
|
@@ -104,17 +305,17 @@ export function sweepText(
|
|
|
104
305
|
trimmed.length > PREVIEW_LIMIT
|
|
105
306
|
? `${trimmed.slice(0, PREVIEW_LIMIT)}…`
|
|
106
307
|
: trimmed
|
|
107
|
-
const alsoReplacement = carriesReplacement(line, options)
|
|
108
308
|
|
|
109
|
-
|
|
309
|
+
for (const { column, match } of matches) {
|
|
110
310
|
bucket.push({
|
|
111
311
|
file,
|
|
112
312
|
line: index + 1,
|
|
113
313
|
column: column + 1,
|
|
114
|
-
|
|
314
|
+
match,
|
|
315
|
+
heading,
|
|
316
|
+
carriesReplacement: carriesReplacement(line, options, stems, match),
|
|
115
317
|
preview,
|
|
116
318
|
})
|
|
117
|
-
column = line.indexOf(options.superseded, column + 1)
|
|
118
319
|
}
|
|
119
320
|
}
|
|
120
321
|
|
|
@@ -135,9 +336,15 @@ export function sweepText(
|
|
|
135
336
|
* what was listed, opened, and skipped are what keep it from reading as a
|
|
136
337
|
* verdict over the whole tree.
|
|
137
338
|
*
|
|
339
|
+
* Beside the literal comparison it matches the family stem the two values
|
|
340
|
+
* differ on, so a citation writing the family as a pattern enters the report.
|
|
341
|
+
* The trade is false positives, bounded at one across a sixteen-folder rename,
|
|
342
|
+
* which is why this reports rather than gates.
|
|
343
|
+
*
|
|
138
344
|
* What it cannot see is a prose reference that went stale without carrying the
|
|
139
|
-
* value, such as a declaration citing the wrong standard for the transform
|
|
140
|
-
*
|
|
345
|
+
* value, such as a declaration citing the wrong standard for the transform, and
|
|
346
|
+
* a family written in a form neither the value nor the three stem shapes reach.
|
|
347
|
+
* A value sweep closes most of this class and no part of either one.
|
|
141
348
|
*/
|
|
142
349
|
export async function readSuperseded(
|
|
143
350
|
root: string,
|
|
@@ -198,6 +405,7 @@ export async function readSuperseded(
|
|
|
198
405
|
kind: 'measured',
|
|
199
406
|
superseded: options.superseded,
|
|
200
407
|
replacement: options.replacement,
|
|
408
|
+
stems: deriveStems(options),
|
|
201
409
|
listed: listed.length,
|
|
202
410
|
files,
|
|
203
411
|
skipped,
|