AGENTS.md: what @module is for, and no external tools without approval - #1765

`fjs/AGENTS.md` §2 reserves `@module` for a package entry point. Nothing
enforced it, and it drifted twice in a week: onto 102 `types.ts` and proof
files, corrected in #1756, and again on a parallel branch that hit the same
rule and filed it as debt rather than applying it. `tsc` cannot see the
tag's placement, so the rule needs its own gate — the shape main
established for the file-scope-typedef prohibition, in the same job.

Both directions are checked, as two steps. A guard for stray tags alone
would also pass on a tree that had lost the tag from every entry point,
which is the failure the second half catches; the drift so far has been in
the first direction only because nothing was looking in either.

`grep -L` cannot carry the verdict in its exit status. It reports whether
any file *matched*, not whether it listed one, so `xargs grep -L @module`
exits 0 on a clean tree and the obvious spelling of the second guard can
never fail. It pipes into `grep -q .` instead. The first guard's `grep -qv`
has the right semantics as written.

Each guard was proven against the string CI will actually run, extracted
from the generated `ci.yml` rather than read off the generator source, and
each fails on its own violation and no other: `@module` added to a
`types.ts`, added to a `proof.f.mjs`, and removed from an entry point.

The proof asserts both steps are generated, since a guard that silently
stopped being emitted is precisely the failure it exists to prevent — and
those assertions were themselves checked by removing each guard in turn.
The existing typedef guard has no such assertion; left alone rather than
widening this change.

`fjs/ci/todo/node26-job-is-this-repo-only.md` records what this revealed:
`fjs ci` is offered to other projects, but `node26` carries this
repository's own gates — `npm run ci-update` against a script a consumer
will not have, and now three convention checks. Pre-existing and not
introduced here; naming it rather than fixing it inside this change.

`npx tsc` clean, suite 3528/3528, `fjs/ci` proofs 29/29.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01T7vAocRuxfmWJDnujCoMup

The guard failed CI on its own commit. It matched `@module` anywhere in a
`.ts`/`.mjs` file, and `fjs/ci/proof.f.mjs` — added in the same change —
contains the string three times, in the assertions naming these very
steps. So the guard flagged the code that asserts the guard exists.

My verification ran in the wrong order and that is the whole lesson here:
I extracted the emitted commands and exercised them against three
violations, then added the proof assertions, and never re-ran the guards
afterwards. Everything I checked was correct when I checked it. The final
tree was never checked at all.

The pattern now matches the tag where JSDoc puts it — the same anchoring
the file-scope-typedef guard uses — so a line that mentions `@module` in a
string or a `//` comment is not a declaration of it. That distinction is
what the rule was always about; the bare string only happened to work
while nothing in the repository discussed the tag.

Both guards also end in a plain `grep` rather than `grep -q`. The `-q`
form exits on its first match and closes the pipe, so the failing run
printed `grep: write error: Broken pipe` and no indication of which file
was at fault. Without it the log names the offending paths.

Six cases now run against the strings extracted from the regenerated
`ci.yml`, after every edit: the clean tree; a file that only mentions the
tag (must not fire); a real tag on a `types.ts` and on a `proof.f.mjs`
(must fire); an entry point stripped of its tag (must fire); and a failing
run, checked for naming the file. The proof assertions match `grep -rlE`
and `xargs grep -LE`, the parts that tell the two steps apart, so neither
can be satisfied by the other's step — re-checked by removing each guard
in turn.

`npx tsc` clean, suite 3528/3528, `fjs/ci` proofs 29/29.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01T7vAocRuxfmWJDnujCoMup

Reverts the two generated CI steps and their proof assertions. The CI
generator, its proof and `.github/workflows/ci.yml` are byte-identical to
`main` again.

The guards were the argument against themselves. A pattern over source text
cannot tell a JSDoc tag from the same characters in a string or a comment,
so the first flagged `fjs/ci/proof.f.mjs` — the file whose assertions named
the guard — and the second could not have reported a missing tag in any
file that mentioned the tag anywhere. Anchoring the pattern fixed both
instances without fixing the category: the check still only approximated
the question it claimed to answer, and its failures were silent ones.

AGENTS.md gains §6. No external tool is called from our code without
approval first; where a rule needs real analysis the answer is a tool that
parses what it checks, ESLint or Clippy, proposed and approved rather than
a pattern that resembles one. And leaving the check undone beats the
machinery: a rule no available tool can express stays written down and
unenforced, which is honest and cheaper.

That makes the `@module` rule unenforced again — deliberately. It drifted
twice, which argued for a gate, but the gate has to be worth trusting.

Two things left standing, both open to reversal:

`fjs/ci/todo/node26-job-is-this-repo-only.md` stays. It records that
`fjs ci` is offered to other projects while `node26` carries this
repository's own gates — `npm run ci-update` hard-references this tree, and
`Setup.nodeExtra` does not reach the canonical jobs. Pre-existing, and the
Codex P1 on the reverted change was about the same seam.

The file-scope `@typedef` guard is still generated. It is the same shape as
what this reverts, so §6 covers it, but removing it was not asked and is a
separate call.

`npx tsc` clean, suite 3533/3533, `fjs/ci` proofs 30/30.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01T7vAocRuxfmWJDnujCoMup

Review caught the issue describing a tree that no longer exists. It listed
"both halves of the `@module` placement rule" among the repository-only
gates `fjs ci` ships to consumers, and the revert in 1932280 removed them —
so it recorded as shipped a pair of steps the same pull request had already
taken out, and told whoever picks it up that consumers fail on a rule this
branch deliberately leaves unenforced.

The inventory is now the two that are actually generated: `npm run
ci-update` with its drift check, and the file-scope `@typedef` prohibition.
The `@module` attempt is kept as history rather than deleted — it is why
the issue exists — but stated as reverted, with the reason and a pointer to
root `AGENTS.md` §6, which now rules the approach out.

Nothing else in the file assumed the gates: the two options, the question
of whether any outside project runs `fjs ci`, and the README disagreement
all stand as written.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01T7vAocRuxfmWJDnujCoMup

Review checked `fjs/ci/README.md`, which I had not read past its opening.
It names `cov` and `ci-update` as the commands a consuming `package.json`
must provide, shows the typical definitions, and explains that a project
chains its own generators into `ci-update` so the drift check covers them
for free. This repository's `node ./fjs/module.mjs ci && …` spelling is
explained there too: it avoids depending on the package bin before the
package is installed. So the step is an extension point, and listing it as
this repository's private gate was wrong.

That correction cuts the other way from how I argued it. I claimed on the
pull request that `node26` is already unusable for consumers, so a
convention gate added to it changes nothing for them. The opposite holds: a
project that follows the documented setup has a working `node26`, and the
one step outside the contract — the file-scope `@typedef` prohibition — is
then the only thing standing between them and a green build. The reviewer
who called the reverted `@module` gates a real consumer regression was
right, and my rebuttal rested on not having read the contract.

The issue is rescoped to that one step, and retitled, since "ships this
repository's own gates" overstated a job that is mostly portable by design.
The narrowness is the finding rather than a softening of it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01T7vAocRuxfmWJDnujCoMup

todo/README.md asks for a heading that names the action or the thing, not
the full context. "ships one convention consumers never agreed to" carried
the diagnosis in the title; the Problem section already states it, at
length and more accurately.

Kept the `{slug}.` prefix — it is what 151 of the 279 issue files do, and
the neighbours this branch touched are among them.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01T7vAocRuxfmWJDnujCoMup

§2 said the tag belongs only to `module.f.mjs` / `module.mjs`. That is the
rule #1756 enforced across 102 files, and it had the reason backwards.

`deno doc` reads the tag and nothing else. A file whose leading block
carries it gets that prose as `module_doc`; a file without it gets no
`module_doc` at all — the block is dropped, not demoted. Checked against
the Deno the repository pins, for `.mjs` and `.ts` alike, and the tag need
not be in the first block, only in some block. So the tag is what makes a
leading block *be* documentation, and it goes wherever a file has module
documentation to publish: `module.f.mjs`, `types.ts`, `private.ts`. A block
holding only `@import` tags has nothing to attach and wants none. Where the
documentation is never published the tag buys nothing, which is `proof.*`.

98 of the 102 stripped files had real prose, so their module documentation
is currently invisible to `deno doc` — the output
`fjs/website/todo/publish-deno-doc-to-website.md` plans to publish. §2 says
so plainly rather than describing a tree that does not exist, and points at
the restore.

`fjs/todo/module-tag-restore.md` (P3) carries the inventory, split by the
three decisions it actually contains: 89 `types.ts` with prose, mechanical;
11 proof files where the rule says leave them but that is worth confirming;
and two files that are neither — `browser.mjs` has real prose and reads
like the first group, `testlib.f.mjs` held only `@import` tags and wants no
tag at all.

`todo/jsdoc-verification.md` (P4) asks how any of this could be checked.
Three passes over one tag with no signal at any point is the argument for
looking; §6 ruling out text patterns is why the answer has to parse, and
"not worth it, leave it to review" is a legitimate outcome to record.

Documentation only. `npx tsc` clean, suite 3533/3533.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01T7vAocRuxfmWJDnujCoMup

…d claim

Three review findings, all against text I wrote in the previous commit.

§1.2 still showed a `proof.f.mjs` leading block carrying `@module`, while the
§2 I had just rewritten said a proof's documentation is never published so
the tag has nothing to attach to. Same file, opposite instructions for the
same shape. The example loses the tag and says why.

The restore issue omitted `private.ts`. All 16 have prose and none carry the
tag — stripped by #1750 rather than #1756, so they were not in the 102 I
counted, but it is the same reading and the same fix, and §2 names
`private.ts` explicitly. As written the issue could have been completed in
full while leaving 16 files violating the rule it exists to satisfy, and its
last task says to delete §2's non-compliance note.

And the publication rationale was overstated. The website issue plans
`deno doc --html **/module.f.mjs`, a glob excluding every `types.ts` and
`private.ts`, so restoring the tag alone puts nothing on the website. The
tag is necessary, not sufficient: it decides whether `deno doc` *can* see a
file's module documentation, and what the build is pointed at is a separate
question. Both §2 and the issue say that now, and widening the glob is named
as the other half.

Also added: a task to correct `todo/migrate-typescript-to-mjs.md`, which
restates the old rule verbatim under "Module header and import ordering"
rather than linking §2, so it did not move when §2 did.

Documentation only. `npx tsc` clean, suite 3533/3533.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01T7vAocRuxfmWJDnujCoMup

Codex P2 on b7d8e2d: fjs/todo/module-tag-restore.md told the website
issue to widen its deno doc glob to types.ts and private.ts alike. Doing
that would put all 16 private.ts modules and their exported _ types on
the public API site, which is what separate-private-types.md exists to
prevent: those types are outside the public declaration closure, and its
Stage 2 drops their generated declarations from the package.

Restoring the tag in private.ts still stands - the prose is reachable by
deno doc for a contributor either way - so the split is about audience,
not about the tag. AGENTS.md section 2 said documentation to publish,
which conflated the two; it now says documentation a reader is meant to
get from deno doc, and names which reader per file kind.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01T7vAocRuxfmWJDnujCoMup