@feigi/fleet-ctl 3.24.3 → 3.24.4

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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@feigi/fleet-ctl",
3
- "version": "3.24.3",
3
+ "version": "3.24.4",
4
4
  "description": "Agent fleet: run-team controller, merge bot, PR reviewer, and the ticket pipeline they share",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -99,7 +99,7 @@ unrunnable() { printf '%s: %s\n' "$NAME" "$1" >&2; exit 3; }
99
99
 
100
100
  # Named once: every refusal that sends the caller to re-derive names the same
101
101
  # step, so a controller or reviewer reading any of them knows what to run.
102
- derive="run the Recipe derivation step (run-team phase 0, before the first claim — ADR 0015) to derive, prove and write it"
102
+ derive="run the Recipe derivation step (run-team phase 0, before the first claim) to derive, prove and write it"
103
103
 
104
104
  [ $# -eq 2 ] || die "usage: derive-testcmd.sh <repo> <install|test>"
105
105
  repo=$1
@@ -4,16 +4,15 @@
4
4
  # claim that never became" a PR). This is neither Release nor Reap
5
5
  # (CONTEXT.md's Reap is branches and worktrees, not the label) — a third,
6
6
  # merge-triggered step in the claim lifecycle CONTEXT.md does not yet name.
7
- # #170.
8
7
  #
9
- # Single writer, per the #170 ruling: the merge is the only moment the ticket
8
+ # Single writer: the merge is the only moment the ticket
10
9
  # number and the fact of completion are known together, so only a PROVEN merge
11
10
  # triggers this — never reap (branches, not tickets), never a repo automation
12
11
  # (no attribution). The merge bot's branch-delete step, delete-merged-branch.sh,
13
12
  # calls this script as a sibling with --apply, after its own MERGED gate: the
14
13
  # claim has not ended until the merge lands. Direct use is manual repair.
15
14
  #
16
- # #1617: `closingIssuesReferences` reflects `Closes #N` syntax in the PR's own
15
+ # `closingIssuesReferences` reflects `Closes #N` syntax in the PR's own
17
16
  # title/body, but NOT a commit-message-only reference — GitHub's real
18
17
  # merge-time closer honors the latter (confirmed via the issue's own
19
18
  # timeline), this field never does, even after the merge. This script unions
@@ -53,7 +52,7 @@ if ! issues=$(gh pr view "$pr" --json closingIssuesReferences --jq '.closingIssu
53
52
  die "gh pr view $pr failed — cannot read which issues it closes"
54
53
  fi
55
54
 
56
- # #1617: the query above misses a commit-message-only close. Scan every
55
+ # The query above misses a commit-message-only close. Scan every
57
56
  # commit's own headline+body for the same close/fix/resolve keyword forms
58
57
  # GitHub's real closer recognizes, and union the result into `$issues` — the
59
58
  # set of issues this PR is proven to close, so the check below acts on
@@ -63,13 +62,13 @@ if ! commit_text=$(gh pr view "$pr" --json commits --jq '[.commits[] | (.message
63
62
  die "gh pr view $pr failed — cannot scan its commit messages for issue closes"
64
63
  fi
65
64
 
66
- # Same three-outcome discipline as the label scan below (#1543): rc 1 (no
65
+ # Same three-outcome discipline as the label scan below: rc 1 (no
67
66
  # keyword anywhere in any commit) must read as zero commit-closed issues,
68
67
  # never conflated with rc 2+ (the scan itself broke), which must halt loudly
69
68
  # instead of silently behaving like "commits close nothing".
70
69
  # The leading `(^|[^[:alnum:]_])` requires a non-word character (or line
71
- # start) immediately before the keyword, so "bugfix #77" or "prefix #88"
72
- # never read as closing #77/#88 just because "fix" is a substring of a
70
+ # start) immediately before the keyword, so "bugfix #N" or "prefix #N"
71
+ # never reads as closing issue N just because "fix" is a substring of a
73
72
  # larger word — only a real close/fix/resolve keyword counts.
74
73
  if matched=$(printf '%s\n' "$commit_text" | grep -Eio '(^|[^[:alnum:]_])(close[sd]?|fix(e[sd])?|resolve[sd]?)[[:space:]]*#[0-9]+'); then
75
74
  commit_grep_rc=0
@@ -92,9 +91,9 @@ esac
92
91
  # Union both signals through the SAME three-outcome discipline, never a bare
93
92
  # `grep | sort`: command substitution reports only the LAST pipe stage's
94
93
  # exit status, so `sort`'s own rc 0 would otherwise mask a grep 2+ break
95
- # entirely — the exact "commits close nothing" misreading #1543 already
96
- # guards against elsewhere in this file. `awk '{print $0+0}'` strips any
97
- # leading zeros (#121's defect class) before the final sort, so a
94
+ # entirely — the exact "commits close nothing" misreading the label scan
95
+ # below already guards against. `awk '{print $0+0}'` strips any
96
+ # leading zeros before the final sort, so a
98
97
  # commit-message "#007" reaches the JSON payload below as the bare,
99
98
  # valid-JSON integer `7` — and correctly dedupes against a plain `7` named
100
99
  # by the other signal.
@@ -127,7 +126,7 @@ for n in $issues; do
127
126
  fi
128
127
 
129
128
  # grep's OWN scan failing (rc 2+) must not read as "no in-progress label":
130
- # the same defect PR #1519 fixed in reap.sh's grep_probe (#1543). A bare
129
+ # the same defect reap.sh's grep_probe guards against. A bare
131
130
  # `if … grep -qx …; then had=true; else had=false; fi` has room for only two
132
131
  # of grep's three `-q` outcomes — rc 0 matched, rc 1 none did, rc 2+ the
133
132
  # scan itself broke — so a scan that could not look would read here exactly
@@ -1,5 +1,5 @@
1
1
  #!/usr/bin/env node
2
- // The Resolver's one-time bootstrap (#1335, ADR 0003 point 4). Places a copy
2
+ // The Resolver's one-time bootstrap. Places a copy
3
3
  // of `fleet-run` at `~/.fleet/bin/fleet-run` — the one artefact this repo
4
4
  // owns OUTSIDE the plugin, because the Resolver cannot resolve itself and no
5
5
  // per-session mechanism can carry it (nothing survives between harness
@@ -7,7 +7,7 @@
7
7
  // placed copy already matches.
8
8
  //
9
9
  // SOURCE, and the one licensed exception. Every other script's rule is
10
- // "only installed scripts run" (ADR 0003 point 3) — never a source checkout.
10
+ // "only installed scripts run" — never a source checkout.
11
11
  // This script's source is always ITS OWN sibling `fleet-run`, i.e. whatever
12
12
  // directory this file itself is running from. Two shapes exist for that:
13
13
  // - run as an INSTALLED script (this file's own directory IS a registry
@@ -16,9 +16,9 @@
16
16
  // - run DIRECTLY FROM A CHECKOUT (this file's own directory is not any
17
17
  // registered installPath) — the state the world is actually in the
18
18
  // first time this ever runs, since no install anywhere yet carries
19
- // `scripts/fleet-run`. ADR 0003 licenses exactly this once, loudly.
19
+ // `scripts/fleet-run`. This exception is licensed exactly once, loudly.
20
20
  // This file cannot tell those apart by calling git (that would be exactly
21
- // the self-location-derives-a-repo pattern #1335's audit test forbids); it
21
+ // the self-location-derives-a-repo pattern every other script is barred from); it
22
22
  // tells them apart by comparing its own directory's PARENT against the
23
23
  // registries' recorded installPath strings — a plain string compare, no git
24
24
  // involved, so it never anchors a git root to its own location.
@@ -36,7 +36,7 @@ function die(message) {
36
36
  process.exit(2);
37
37
  }
38
38
 
39
- // The Install root, same resolution point as scripts/fleet-run (ADR 0021):
39
+ // The Install root, same resolution point as scripts/fleet-run:
40
40
  // the realpath of `~/.omp/plugins/node_modules/@feigi/fleet-ctl`. Absent or
41
41
  // dangling answers null, which the caller reports as "omp: not installed".
42
42
  function readInstallPath(packagePath) {
@@ -66,7 +66,7 @@ function main() {
66
66
  }
67
67
 
68
68
  const home = os.homedir();
69
- const PLUGIN_KEY = "@feigi/fleet-ctl"; // ADR 0006 name; ADR 0021 — the node_modules package dir.
69
+ const PLUGIN_KEY = "@feigi/fleet-ctl"; // the plugin's package name, and its node_modules package dir.
70
70
  const ompInstall = readInstallPath(path.join(home, ".omp", "plugins", "node_modules", PLUGIN_KEY));
71
71
  // Both sides are realpaths — readInstallPath() already resolved the install,
72
72
  // and this file's own directory exists, so its parent resolves too — so a
@@ -85,7 +85,7 @@ function main() {
85
85
  die(
86
86
  `refusing to place ${target} from ${ownDir}, which is not omp's resolved install root (looked at `
87
87
  + `${ompInstall ? `omp: ${ompInstall}` : "omp: not installed"}) — re-run with --from-checkout to take `
88
- + "ADR 0003's one-time bootstrap exception explicitly",
88
+ + "the one-time bootstrap exception explicitly",
89
89
  );
90
90
  }
91
91
 
@@ -94,7 +94,7 @@ function main() {
94
94
  `${NAME}: BOOTSTRAP EXCEPTION — running from a source checkout (${ownDir}), not omp's resolved `
95
95
  + "install root (looked at "
96
96
  + `${ompInstall ? `omp: ${ompInstall}` : "omp: not installed"}). `
97
- + "ADR 0003 licenses this ONCE, as the Resolver's own bootstrap, because no install anywhere yet carries "
97
+ + "This is licensed ONCE, as the Resolver's own bootstrap, because no install anywhere yet carries "
98
98
  + "scripts/fleet-run for an install-root-driven copy to come from. Every other fleet script must run through "
99
99
  + "the Resolver once it exists.\n",
100
100
  );
@@ -1,14 +1,14 @@
1
1
  #!/usr/bin/env node
2
- // The Provenance check (#1335, ADR 0003 point 4, ADR 0021, CONTEXT.md § Install
2
+ // The Provenance check (CONTEXT.md § Install
3
3
  // "Provenance check"). Names the live Install root — the realpath of omp's
4
4
  // `node_modules/@feigi/fleet-ctl` package entry, the one path every install kind
5
- // places (ADR 0021) — its kind and recorded version, and hashes the placed
5
+ // places — its kind and recorded version, and hashes the placed
6
6
  // Resolver (`~/.fleet/bin/fleet-run`) against the Install root's own copy and
7
7
  // refuses on drift. Writes nothing, mutates no config — every path below is
8
8
  // read-only.
9
9
  //
10
- // The `enabledProviders: ["claude-plugins"]` assertion retired here (ADR
11
- // 0021): omp's #11362 fix (shipped 18.2.1) exempts omp-origin installs from
10
+ // The `enabledProviders: ["claude-plugins"]` assertion retired here: omp
11
+ // 18.2.1 exempts omp-origin installs from
12
12
  // that provider gate, and the native package route never depended on it.
13
13
  // Asserting it refused correct setups.
14
14
  //
@@ -27,7 +27,7 @@ const os = require("node:os");
27
27
  const crypto = require("node:crypto");
28
28
 
29
29
  const NAME = "fleet-provenance";
30
- const PLUGIN_KEY = "@feigi/fleet-ctl"; // ADR 0006 name; ADR 0021 — the node_modules package dir.
30
+ const PLUGIN_KEY = "@feigi/fleet-ctl"; // the plugin's package name, and its node_modules package dir.
31
31
 
32
32
  // Same resolution point as scripts/fleet-run (its header names the shape of
33
33
  // each install kind). Duplicated rather than shared because a module the
@@ -49,7 +49,7 @@ function resolveInstall(home) {
49
49
  }
50
50
 
51
51
  // Version lives in omp's runtime plugin lock, which every install kind writes
52
- // (ADR 0021 point 4) — a link records the manifest's own `package.json`
52
+ // — a link records the manifest's own `package.json`
53
53
  // version (measured on 18.4.8: `0.0.0`, the placeholder), so the number never
54
54
  // identifies a link; `kind:` does. Read tolerantly: any shape problem degrades
55
55
  // to null, it never fails the check, because the version is informational.
@@ -67,7 +67,7 @@ function readLockVersion(home) {
67
67
 
68
68
  // Every regular file under `<root>/scripts`, repo-relative, sorted — a
69
69
  // filesystem walk rather than `git ls-files`: an installed copy need not
70
- // carry a .git at all (a directory-source install can exclude it, ADR 0003),
70
+ // carry a .git at all (a directory-source install can exclude it),
71
71
  // so git is not an instrument this check can rely on being present.
72
72
  function walkFiles(dir, base = dir, out = []) {
73
73
  let entries;
@@ -182,7 +182,7 @@ function main() {
182
182
  }
183
183
 
184
184
  if (kind === "linked-checkout") {
185
- // Not a failure: a link is the dev loop (ADR 0021). It is a NOTICE on
185
+ // Not a failure: a link is the dev loop. It is a NOTICE on
186
186
  // every other install's answer, because a linked root outranks an
187
187
  // installed copy of the same names in omp's own discovery — the check
188
188
  // above certified the LINK, not what a session without the link runs.
package/scripts/fleet-run CHANGED
@@ -1,10 +1,10 @@
1
1
  #!/usr/bin/env node
2
- // The Resolver (#1335, ADR 0003, ADR 0014, ADR 0021, CONTEXT.md § Install
2
+ // The Resolver (CONTEXT.md § Install
3
3
  // "Resolver"). The single door between prose and an installed script: a prose
4
4
  // callsite names a SCRIPT, never a path, and this reads omp's own extension
5
5
  // package layout to find where that script actually lives right now.
6
6
  //
7
- // RESOLUTION POINT (ADR 0021): `~/.omp/plugins/node_modules/@feigi/fleet-ctl`. Every
7
+ // RESOLUTION POINT: `~/.omp/plugins/node_modules/@feigi/fleet-ctl`. Every
8
8
  // omp install kind — marketplace, `omp plugin link`, npm — places an entry
9
9
  // there (a symlink for marketplace/link, a real directory for npm), and it is
10
10
  // the only path common to all three. Its realpath IS the Install root. The
@@ -37,7 +37,7 @@ const os = require("node:os");
37
37
  const { spawnSync } = require("node:child_process");
38
38
 
39
39
  const NAME = "fleet-run";
40
- const PLUGIN_KEY = "@feigi/fleet-ctl"; // ADR 0006 name; ADR 0021 — the node_modules package dir, no longer a qualified registry key.
40
+ const PLUGIN_KEY = "@feigi/fleet-ctl"; // the plugin's package name, and its node_modules package dir, no longer a qualified registry key.
41
41
 
42
42
  function die(message) {
43
43
  process.stderr.write(`${NAME}: ${message}\n`);
@@ -1,5 +1,5 @@
1
1
  {
2
- "_comment": "The allow-list data (#1314, #1347, ADR 0014). One allow-list per artefact kind (agents, skills, commands) for omp's documented keys (`omp://task-agent-discovery.md`, `omp://skills.md`). Enforced by frontmatter-check.mjs: unknown keys are rejected, required keys are enforced, and `forbidden` catches a key that reads as configuration but silently reroutes a member's tier, tree, or dispatch.",
2
+ "_comment": "The allow-list data. One allow-list per artefact kind (agents, skills, commands) for omp's documented keys (`omp://task-agent-discovery.md`, `omp://skills.md`). Enforced by frontmatter-check.mjs: unknown keys are rejected, required keys are enforced, and `forbidden` catches a key that reads as configuration but silently reroutes a member's tier, tree, or dispatch.",
3
3
 
4
4
  "agents": {
5
5
  "required": ["name", "description", "model"],
@@ -11,18 +11,18 @@
11
11
  "thinking-level": "the level rides on model's `@<role>:<level>` suffix — one spelling only",
12
12
  "thinking": "the level rides on model's `@<role>:<level>` suffix — one spelling only",
13
13
  "effort": "retired Claude Code key — silently ignored by omp",
14
- "prewalk": "silent mid-run model hand-off — the tier degradation ADR 0005 forbids",
15
- "advisor": "silent mid-run model hand-off — the tier degradation ADR 0005 forbids",
16
- "isolation": "members never use harness isolation (#1315): omp builds the workspace outside the claimed worktree and patch-applies into the controller's checkout"
14
+ "prewalk": "silent mid-run model hand-off — a tier degradation the fleet forbids",
15
+ "advisor": "silent mid-run model hand-off — a tier degradation the fleet forbids",
16
+ "isolation": "members never use harness isolation: omp builds the workspace outside the claimed worktree and patch-applies into the controller's checkout"
17
17
  },
18
18
  "values": {
19
19
  "model": {
20
20
  "pattern": "^@(slow|task|smol):(minimal|low|medium|high|xhigh|max)$",
21
- "message": "must be a fleet tier route `@slow|@task|@smol` with an explicit `:<level>` suffix (ADR 0014)"
21
+ "message": "must be a fleet tier route `@slow|@task|@smol` with an explicit `:<level>` suffix"
22
22
  },
23
23
  "name": {
24
24
  "pattern": "^fleet-[^:]*$",
25
- "message": "must be fleet--prefixed with no ':' — omp's agent registry is bare-name/unnamespaced, so the prefix is the only collision guard (#1303)"
25
+ "message": "must be fleet--prefixed with no ':' — omp's agent registry is bare-name/unnamespaced, so the prefix is the only collision guard"
26
26
  }
27
27
  }
28
28
  },
@@ -1,10 +1,10 @@
1
1
  #!/bin/sh
2
- # Did the controller's instrument set change under it? (#436)
2
+ # Did the controller's instrument set change under it?
3
3
  #
4
4
  # The controller reads the world through scripts and runbooks that live in the
5
5
  # MAIN checkout, and every member can write to that checkout — except through a
6
- # `write`/`edit`/`ast_edit` that member-write-guard.mjs refuses (ADR 0020); a
7
- # `bash` or `eval` write still lands, the backstop #2210 tracks. Worktree isolation
6
+ # `write`/`edit`/`ast_edit` that member-write-guard.mjs refuses; a
7
+ # `bash` or `eval` write still lands. Worktree isolation
8
8
  # and `./agent-test` port derivation protect members from each other; neither
9
9
  # protects the tree the controller measures from. Measured: a member edited two
10
10
  # files in the main checkout instead of its worktree while the CI monitor was
@@ -42,7 +42,7 @@
42
42
  # already knows can be stale). A list rots on the next commit that adds a
43
43
  # script; a directory does not.
44
44
  #
45
- # NOT THE WHOLE REPO, deliberately: since #1336 the plugin's payload is
45
+ # NOT THE WHOLE REPO, deliberately: the plugin's payload is
46
46
  # nested under `plugin/`, and the repo root also carries `docs/`, `.github/`
47
47
  # and `.out-of-scope/`. `docs/metrics/` is APPENDED BY THE CONTROLLER
48
48
  # MID-RUN, so a whole-repo set would fire the gate on the run's own
@@ -65,7 +65,7 @@
65
65
  # blob untouched; both exit 0 here. A mode change that costs the hash its READ
66
66
  # is caught instead: `chmod 000` on a tracked instrument refuses at exit 2
67
67
  # through `could not hash every tracked file` — as root that never fires,
68
- # since root reads a mode-000 file regardless (instruments.test.mjs skips
68
+ # since root reads a mode-000 file regardless (the suite skips
69
69
  # this case there for the same reason). So the exposure is the bits that
70
70
  # still permit reading, the exec bit above all — and that bit is not how a
71
71
  # fleet probe runs: fleet-run hands `.sh` to `sh` and `.mjs` to `node`, so a
@@ -74,20 +74,19 @@
74
74
  # modes in — digesting `git ls-files -s` alongside the contents, or a per-file
75
75
  # `[ -x "$f" ]` — is a behaviour change to the gate on a channel with no
76
76
  # silently wrong reading to its name, and whether a mode-only edit is worth
77
- # refusing on is a decision rather than a fix, so #1059 names the gap and
78
- # leaves the behaviour alone. instruments.test.mjs pins the accepted pair,
77
+ # refusing on is a decision rather than a fix, so this paragraph names the gap and
78
+ # leaves the behaviour alone. The suite pins the accepted pair,
79
79
  # so closing the gap later goes red there rather than leaving this
80
80
  # paragraph stale.
81
81
  #
82
82
  # REFS ARE DELIBERATELY NOT IN THE DIGEST, and the reason is not that they do
83
- # not matter. The corroborating evidence on #436 is a stray `fix/42-slug` branch
83
+ # not matter. The corroborating evidence is a stray `fix/42-slug` branch
84
84
  # left in the main checkout by something running this repo's own fixtures — a
85
85
  # ref write, which no hash of files can see. But `claim-ticket.sh` creates a
86
86
  # branch per ticket and `reap.sh` deletes them, in the ref store every worktree
87
87
  # shares, so a ref digest changes several times per pass as ORDINARY WORK. Per
88
88
  # gate that is noise, and noise is the one failure this check cannot afford.
89
- # Sweeping for unexpected refs is a drain-cadence question, not a gate one, and
90
- # it is not what #436's acceptance criteria ask for.
89
+ # Sweeping for unexpected refs is a drain-cadence question, not a gate one.
91
90
  #
92
91
  # COST: two `git ls-files` (the state home's own set, which decides whether a
93
92
  # recorded root may be followed at all, and the audited tree's set) and one
@@ -98,19 +97,19 @@
98
97
  set -eu
99
98
 
100
99
  # Directly below `set -eu`, not below a locale pin: this script has none and is
101
- # deliberately off locale-pin-prose.test.mjs's PINNED list. The five siblings
102
- # that DO carry a pin put this line under it instead, because that file's
103
- # PROLOGUE regex admits only comments, blanks and `set -[eux]+` above the pin.
100
+ # deliberately off the suite's list of locale-pinned scripts. The siblings
101
+ # that DO carry a pin put this line under it instead, because the suite admits
102
+ # only comments, blanks and `set -[eux]+` above the pin in those scripts.
104
103
  # Here the only constraint left is the real one: above the first git call.
105
104
  #
106
- # GIT_WORK_TREE is #1337's defect reached through the environment. The
107
- # contract that ticket established is that the audited tree is the WORKING
105
+ # GIT_WORK_TREE is the wrong-tree defect reached through the environment. The
106
+ # contract here is that the audited tree is the WORKING
108
107
  # DIRECTORY's checkout — and `git rev-parse --show-toplevel` answers with the
109
- # ambient work tree instead the moment one is set, `--repo` or not. Measured
110
- # (#1020): standing in a checkout whose instruments have been TAMPERED, with
108
+ # ambient work tree instead the moment one is set, `--repo` or not. Measured:
109
+ # standing in a checkout whose instruments have been TAMPERED, with
111
110
  # `GIT_WORK_TREE` naming a clean twin that carries its own pinned baseline,
112
111
  # this script exits 0 and prints the twin's digest. The gate passes. That is
113
- # the same wrong-tree write `--repo ""` produced before #1350 refused it, one
112
+ # the same wrong-tree write `--repo ""` produced before this script refused it, one
114
113
  # door further out, and a gate that certifies a tree nobody looked at is
115
114
  # worse than no gate.
116
115
  #
@@ -122,12 +121,12 @@ set -eu
122
121
  # pair is one hazard with one remedy, and because "inert today" is a
123
122
  # measurement of the current call set: a digest taken from `git show` or
124
123
  # `cat-file` rather than from disk would reintroduce the half nothing here
125
- # can see. ambient-git-vars-prose.test.mjs pins the line itself, which is
124
+ # can see. The suite pins the line itself, which is
126
125
  # what keeps that half from being quietly dropped.
127
126
  unset GIT_DIR GIT_WORK_TREE
128
127
 
129
128
  NAME=instruments
130
- # `printf '%s'`, never `echo` (#484): `echo` expands backslash escapes in its
129
+ # `printf '%s'`, never `echo`: `echo` expands backslash escapes in its
131
130
  # operand, and the messages below carry paths that git will happily hand us with
132
131
  # a backslash in them.
133
132
  die() { printf '%s: %s\n' "$NAME" "$1" >&2; exit 2; }
@@ -154,9 +153,9 @@ while [ $# -gt 0 ]; do
154
153
  [ $# -ge 2 ] || die "usage: instruments.sh [--pin] [--repo <path>] [--audit <path>]"
155
154
  repo=$2
156
155
  # An empty value falls through the `[ -n "$repo" ]` branch below and
157
- # silently re-derives from cwd — measured (#1350 review): `--repo ""`
156
+ # silently re-derives from cwd — measured: `--repo ""`
158
157
  # pinned the CALLER's cwd repo instead of refusing, exactly the
159
- # wrong-tree-write class this ticket exists to close. Refuse here,
158
+ # wrong-tree-write class this script exists to close. Refuse here,
160
159
  # before that check ever runs.
161
160
  [ -n "$repo" ] || die "--repo requires a non-empty path"
162
161
  shift 2
@@ -171,10 +170,10 @@ done
171
170
  #
172
171
  # `root` — the STATE HOME — is the WORKING DIRECTORY's checkout, never the
173
172
  # checkout this script happens to ship from. Under the install-only dev loop
174
- # (ADR 0003) this file runs out of a plugin cache — on a real install, under
173
+ # this file runs out of a plugin cache — on a real install, under
175
174
  # `~/.omp/plugins/cache/...` — and the OLD own-location contract (`git -C
176
175
  # "$(dirname "$0")" …`) resolved it to whatever git checkout happens to
177
- # CONTAIN that cache path. Measured (#1337), pre-cutover: on a real box that
176
+ # CONTAIN that cache path. Measured, pre-cutover: on a real box that
178
177
  # was the operator's unrelated personal dotfiles checkout, and `--pin` run
179
178
  # that way writes `.fleet/instruments.sha` into it. `--repo <path>` is the
180
179
  # explicit override for the one legitimate case that needs a home other than
@@ -209,7 +208,7 @@ base="$root/.fleet/instruments.sha"
209
208
  # Whether the state home tracks an instrument set OF ITS OWN decides if a
210
209
  # second tree may be named at all — and it is what closes the door a recorded
211
210
  # root would otherwise open: measured, a member who can write `.fleet/`
212
- # (member-write-guard does not stop `bash`, #2210) can keep the honest
211
+ # (member-write-guard does not stop `bash`) can keep the honest
213
212
  # run-start digest on line 1 and move `root=` to a pristine clone of the
214
213
  # workspace whose bytes match it — the old script hashed the tampered tree and
215
214
  # refused; a check that trusted the pointer would certify the clone and pass.
@@ -228,7 +227,8 @@ if [ -n "$audit" ]; then
228
227
  target=$(git -C "$audit" rev-parse --show-toplevel) \
229
228
  || die "$audit is not inside a git checkout — cannot identify the instrument set to pin"
230
229
  elif [ "$pin" = true ] && [ -z "$home" ]; then
231
- # #1058's refusals mirrored on this path: a baseline that EXISTS but cannot
230
+ # The check path's unreadable-baseline refusals, mirrored here: a baseline
231
+ # that EXISTS but cannot
232
232
  # be read names the tree this re-pin is supposed to keep certifying, and
233
233
  # overwriting it blind would discard the pointer with no record that it was
234
234
  # ever there.
@@ -260,21 +260,20 @@ if [ "$pin" != true ]; then
260
260
  # case "no baseline" and prescribing `--pin` would walk a controller from
261
261
  # "the check could not look" to "certified clean" in one step, discarding
262
262
  # evidence it never read — the exact anti-pattern run-team/SKILL.md forbids.
263
- # (#1058)
264
263
  basedir="$(dirname "$base")"
265
264
 
266
265
  # A directory that exists but cannot be searched (missing +x) hides
267
266
  # everything under it from stat(2) — `[ -e "$base" ]` below reads FALSE for
268
267
  # every file underneath, so without this check the run falls through to the
269
268
  # "no baseline" message one level up: the exact mislabel this refusal exists
270
- # to prevent, just moved from the file to its containing directory. (#1058)
269
+ # to prevent, just moved from the file to its containing directory.
271
270
  [ -d "$basedir" ] && [ ! -x "$basedir" ] \
272
271
  && die "$basedir exists but is unreadable — fix its permissions; do NOT --pin over it, --pin overwrites rather than compares"
273
272
 
274
273
  # `-L` catches a dangling symlink: the link entry is present but its target
275
274
  # is gone, so `-e` (which dereferences) reads FALSE and the run would
276
275
  # otherwise fall through to the same "no baseline" message for a baseline
277
- # that is very much present, just broken. (#1058)
276
+ # that is very much present, just broken.
278
277
  { [ -e "$base" ] || [ -L "$base" ]; } && [ ! -r "$base" ] \
279
278
  && die "$base exists but is unreadable — fix its permissions; do NOT --pin over it, --pin overwrites rather than compares"
280
279
  [ -r "$base" ] || die "no baseline at $base — run instruments.sh --pin once at run start"
@@ -345,7 +344,7 @@ git -C "$target" ls-files -z -- $set > "$files" \
345
344
  # run at all leaves the second one hashing empty input and exiting 0, and the
346
345
  # empty-input digest then compares unequal and reads as CHANGED. That is exit 1
347
346
  # — a verdict about the tree — off a failure to look. reap.sh shipped this exact
348
- # bug against `git cherry` (#264) and it deleted branches.
347
+ # bug against `git cherry` and it deleted branches.
349
348
  #
350
349
  # `xargs` exits 123 when `shasum` failed on any file, which is how a tracked
351
350
  # file deleted from the worktree arrives: as exit 2 naming it, not as a digest
@@ -382,7 +381,7 @@ fi
382
381
 
383
382
  # Cold path only, so it costs the ordinary run nothing. The controller has to
384
383
  # report WHAT changed, and neither digest says. `git status` names the
385
- # uncommitted half, which is the shape the near-miss on #436 actually took; a
384
+ # uncommitted half, which is the shape this header's measured near-miss took; a
386
385
  # checked-out branch that moved shows as nothing here and the HEAD line is what
387
386
  # names it. Both are read from the AUDITED tree, which is the one the verdict
388
387
  # is about — not the state home the baseline was found in.
package/scripts/json.sh CHANGED
@@ -30,14 +30,14 @@
30
30
  # reads and has a SYNTAX error aborts before either guard on /bin/sh, bash 3.2
31
31
  # and `bash --posix`, while bash 5.3 reaches the `|| die` with status 2. The
32
32
  # suite does NOT cover that case: measured, a syntax error appended at EOF
33
- # leaves bash 3.2 with every function it had already parsed and json.test.mjs
33
+ # leaves bash 3.2 with every function it had already parsed and the suite
34
34
  # stays green. CI's `shellcheck -x -S warning` over `git ls-files '*.sh'` is
35
35
  # what catches it (SC1072/SC1073).
36
36
  #
37
37
  # `LC_ALL=C` is a per-command prefix on every tool below, never an export. Three
38
38
  # of the callers (verify-sha.sh, prove-merge.sh, claim-ticket.sh) do not pin the
39
39
  # locale, and exporting from a sourced lib would silently re-locale every OTHER
40
- # tool in them. The prefix is a no-op in the five that do pin it (#582), and
40
+ # tool in them. The prefix is a no-op in the five that do pin it, and
41
41
  # closes the same hazard in the three that do not. It matters here because BSD
42
42
  # `tr` exits 1 on a byte that is not valid UTF-8 under a UTF-8 locale, and
43
43
  # `sed` emits nothing at all.
@@ -52,7 +52,7 @@
52
52
  # zero-width word BOUNDARY to GNU sed and a literal `b` to BSD sed, so the rule
53
53
  # would insert `\b` at every word edge on one and mangle every letter `b` on the
54
54
  # other (measured, GNU sed 4.9 and macOS sed). \177 (DEL) is not a C0 byte and
55
- # JSON permits it unescaped, so it is left alone (#146). Every remaining byte
55
+ # JSON permits it unescaped, so it is left alone. Every remaining byte
56
56
  # below \040 has no short form, \013 (VT) included — RFC 8259 lists exactly the
57
57
  # five above and `\v` is not among them; `tr` turns it into a space, and
58
58
  # `jrewritten` is how a caller finds out that happened, since a replaced value
@@ -70,11 +70,11 @@
70
70
  # POSIX leaves this undefined and GNU sed's answer differs — so plain `N;$!ba`
71
71
  # prints nothing at all for a single-line value.
72
72
  #
73
- # EVERY FALLIBLE STAGE'S STATUS IS READ HERE, and that is the #119 fix rather
73
+ # EVERY FALLIBLE STAGE'S STATUS IS READ HERE, and that is a fix rather
74
74
  # than a style choice. A pipeline's status is its LAST stage's, so the
75
75
  # original `printf | sed | tr` reported only `tr` — forcing `sed` to fail left
76
76
  # jstr exiting 0 with an empty value and every caller's `|| die` unfired, while
77
- # forcing `tr` worked (measured on PR #425). POSIX sh has no `pipefail` and no
77
+ # forcing `tr` worked (measured). POSIX sh has no `pipefail` and no
78
78
  # `PIPESTATUS`, so each stage that can fail is captured and its status read.
79
79
  # The consequence, and the rule a later edit is checked against: a pipeline may
80
80
  # still END a function, but only where its LAST stage is the fallible one — `tr`
@@ -89,7 +89,7 @@
89
89
  # indistinguishable one and `$( )` takes it off — `jstr` of `a<LF>` and of `a`
90
90
  # are byte-identical (measured). No live caller can reach it: every argument
91
91
  # reaching jstr today is a script literal or a `$( )`/`awk`/`read` capture that
92
- # has already lost its own trailing newline. #119 leaves it there rather than
92
+ # has already lost its own trailing newline. This file leaves it there rather than
93
93
  # adding a sentinel no caller would exercise. jarr is the exception and is
94
94
  # handled in its own note.
95
95
  #
@@ -104,13 +104,13 @@
104
104
  # sequence starts or continues with — sailed through untouched and landed raw
105
105
  # in the payload: `jq` then silently substitutes U+FFFD on decode (changing
106
106
  # what the caller reads back) and a strict parser (`python3 json.load`)
107
- # refuses the payload outright (#613). `jstr` and `jarr` now run the value
107
+ # refuses the payload outright. `jstr` and `jarr` now run the value
108
108
  # through Python's own UTF-8 decoder with `errors="replace"` first — the same
109
109
  # U+FFFD a lenient consumer already substitutes, made explicit and JSON-legal
110
110
  # at the source instead of implicit and consumer-dependent — and `jrewritten`
111
111
  # reports it as a rewrite like any other replaced byte.
112
112
 
113
- # Python's own UTF-8 decoder with errors="replace" (#613), shared script text
113
+ # Python's own UTF-8 decoder with errors="replace", shared script text
114
114
  # rather than a function: a function called on the right side of a pipe runs
115
115
  # in its own subshell, and a `json_u8=` assigned inside it would not survive
116
116
  # back to the caller — every call site below runs this as
@@ -123,7 +123,7 @@ sys.stdout.buffer.write(sys.stdin.buffer.read().decode("utf-8", "replace").encod
123
123
  # Escape $1 into a JSON string BODY — no surrounding quotes, the caller adds
124
124
  # those. Exit 0 with the escaped value, non-zero if any stage failed.
125
125
  jstr() {
126
- # Empty in, empty out, no fork at all (#120). This is what lets a PATH-wide
126
+ # Empty in, empty out, no fork at all. This is what lets a PATH-wide
127
127
  # sed/tr outage — the failure inflight.sh measures at its own top — leave a
128
128
  # field that legitimately found nothing untouched: that field never calls the
129
129
  # broken tool, so it cannot observe its failure.
@@ -179,7 +179,7 @@ jrewritten() {
179
179
  # short-circuit above existed).
180
180
  json_ascii=$(printf '%s' "$1" | LC_ALL=C tr -d '\200-\377') || return 1
181
181
  [ "$json_ascii" = "$json_orig" ] && { printf false; return 0; }
182
- # jstr also repairs a byte that is not valid UTF-8 (#613) — a second,
182
+ # jstr also repairs a byte that is not valid UTF-8 — a second,
183
183
  # independent replacement alongside the C0 scrub above, so a second,
184
184
  # independent check: this value must decode as strict UTF-8 unchanged, or
185
185
  # jstr rewrote it too.
@@ -194,15 +194,14 @@ jrewritten() {
194
194
  # boundary between two elements by the time a value reaches per-line stdin,
195
195
  # which is why no-undo-audit.sh refuses a conflicting path holding one before it
196
196
  # ever calls this. Escaping a byte this function structurally never receives
197
- # would be dead code standing in for a restructure nobody has needed; #89 owns
198
- # that class.
197
+ # would be dead code standing in for a restructure nobody has needed.
199
198
  #
200
199
  # Empty stdin gives empty stdout at exit 0 — measured as the original
201
200
  # pipeline's behaviour, and the `[ -n ]` guard is what preserves it: without it
202
201
  # the `printf '%s\n'` re-emit below would turn "no elements" into one empty
203
202
  # line and `paste` would answer `""`, inventing an element out of nothing.
204
203
  jarr() {
205
- # Same repair as jstr, same reason (#613), run once over the whole
204
+ # Same repair as jstr, same reason, run once over the whole
206
205
  # (possibly multi-line) input rather than per line: \n is ASCII and never a
207
206
  # byte of a multi-byte UTF-8 sequence, so decoding the joined blob in one
208
207
  # pass cannot manufacture or hide a line boundary.