Skip to content

#1263 Retire the deferred-lint mechanism and adopt toolbelt.errors in agents - #1279

Merged
williamthorsen merged 9 commits into
mainfrom
1263
Aug 10, 2026
Merged

#1263 Retire the deferred-lint mechanism and adopt toolbelt.errors in agents#1279
williamthorsen merged 9 commits into
mainfrom
1263

Conversation

@williamthorsen

@williamthorsen williamthorsen commented Aug 10, 2026

Copy link
Copy Markdown
Owner

What

Fixes all outstanding lint issues and removes the cap that downgraded the severity of associated rules during strict-lint runs. Error reporting in the agents package is improved to include the underlying cause. Directory and file names with special dollar-sign sequences are now handled safely during deployment.

Why

Ten rules sat at warn in agents, where they blocked no gate and went unfixed long enough that one of them had been flagging a live defect the whole time. agents held the repository's last deferral, so clearing it is the difference between a mechanism sitting there for the next package to reach for and no mechanism at all. Errors thrown across the package discarded the failures they wrapped, leaving diagnostics that named a symptom without its cause.

Details

🎉 Features

  • Every site that folds a caught failure into a new error attaches it as cause. Nine compose through chainError; two that deliberately discard the caught message take a bare cause, and assertFilledAnchorsResolve keeps its own composition, which places the cause on its own line after a multi-clause explanation.

🐛 Bug fixes

  • rewriteTemplateVariables passes replacer functions to replaceAll, so a harness home directory or identifier containing $$, $&, $`, or $' is inserted literally instead of expanding against the match it was meant to replace.

♻️ Refactoring

  • describeError from @williamthorsen/toolbelt.errors/candidate replaces the inline error instanceof Error ? error.message : String(error) at every site in agents, and the two locally defined copies in content-validation.ts and guidance-hooks.ts are gone. bin/codeassembly.js keeps its inline form so its top-level imports stay resolvable without an install, which is what lets it report a missing build.
  • Twenty warnings across eight unicorn rules are cleared with no rule suppressed inline. The three no-incorrect-template-string-interpolation reports were false positives over CodeAssembly's own {token} syntax, so each site moves the token out of the template literal rather than silencing the rule.
  • Five best-effort .catch(() => {}) cleanups in kb-edit/commit-supersede.ts collapse into an unlinkQuietly helper that carries the rationale for swallowing once instead of five times.
  • packages/agents/.config/ is deleted, along with the eslint.config.ts rule block and the tsconfig.json include that reached it. The root's advisory ceilings apply by cascade.
  • The remaining .js import specifiers in .ts source are rewritten to .ts, across agents and the root scripts/ suite.

🧪 Tests

  • A guard at the repository root enumerates packages/* and fails when one declares a deferred-rule list or sets maxSeverity in its own strict-lint.config.ts. It checks both halves because either alone restores the mechanism, and it covers a package added later without anyone remembering to add it.
  • Every production site that gains a cause gains an assertion on it: path-rewriter, branch-helpers, read-preferences, recall, and rulebook-deploy.
  • The template-variable suite round-trips $&, $$, and $' through both substitution parameters, so a revert to string replacement fails on either.

📦 Dependencies

  • @williamthorsen/toolbelt.errors 0.2.0, the same adoption kb made for its own loader errors.

Closes #1263

An error the CLI raises while wrapping a caught failure now carries that failure as its cause, so a stack trace reaches the original error rather than stopping at the diagnostic that replaced it.

Wrapped messages join the underlying failure with a colon, replacing the em-dash two of them used.
…eError

An `Error` carrying no message now reports as its class name rather than as an empty string, so a diagnostic built from one names something.

The bin wrapper keeps its own copy: its top-level imports must stay resolvable without an install, so it can still report a missing build.
… variables

Installing content for a harness whose home directory or identifier contains `$&`, ``$` ``, `$'`, or `$1` now writes that value verbatim. Those sequences were previously read as replacement patterns and expanded into the template variable they were replacing.
agents has no remaining violation of the ten rules its lint deferral held at warning level.
No package holds a lint deferral, so every rule the shared preset sets to error now fails a gate rather than passing as a warning.

A repo-root test fails when a package reintroduces one, either as a rule list or as a strict-lint promotion cap.
Every relative import in agents and the root scripts names the `.ts` file it resolves to, rather than the `.js` file the build emits from it.
The KB config-health warning builds its detail through the shared describer, so an `Error` with an empty message names its class there as it does everywhere else in agents.
`replaceAll` with a string search value expands `$$`, `$&`, ``$` ``, and `$'`, and inserts `$1` verbatim because a string search captures nothing. The template-variable expander's note now names that set, and its test carries `$$` alongside `$&` and `$'`.
The guard sits at `.config/__tests__/`, beside `strict-lint.config.ts` and the other tool configs, rather than under a `.config/eslint/` directory that holds no configuration.
@williamthorsen williamthorsen added refactoring Improvement to code without change in functionality scope:agents labels Aug 10, 2026
@github-actions

Copy link
Copy Markdown

Dependency audit

Production dependency audit passed.

@williamthorsen williamthorsen self-assigned this Aug 10, 2026
@williamthorsen
williamthorsen marked this pull request as ready for review August 10, 2026 16:36
@williamthorsen
williamthorsen merged commit 02f7f7c into main Aug 10, 2026
3 checks passed
@williamthorsen
williamthorsen deleted the 1263 branch August 10, 2026 16:43
williamthorsen added a commit that referenced this pull request Aug 13, 2026
…e-v0.3.0 codeassembly-v0.9.0 factory-v0.2.6 codeassembly-mcp-v0.2.5

codeassembly-v0.9.0
- #1288 feat: State mutability and name the lede reader at the artifact type lists (#1303)
- #1285 fix: Require plain bullets for checklists on both update-jira-ticket paths (#1302)
- deps: Upgrade all deps to latest version
- #1290 tooling: Upgrade eslint-config-typescript to 10 and complete manifest metadata (#1301)
- #1294 feat: Specify artifact mutability and its sanctioned exceptions (#1297)
- #1293 fix: Present and classify discretionary findings as actionable (#1295)
- #1289 tooling: Remove shelled nmr calls from package manifests (#1291)
- #1280 feat: Add a refresh path that edits an existing AGENTS.md instead of redrafting it (#1287)
- #1055 feat: Replace the lede doctrine with corpus-derived guidance and retire the changelog-writer (#1286)
- deps: Upgrade all deps to latest version
- #1264 refactor: Consolidate error-message extraction on toolbelt.errors' describeError (#1284)
- #1263 refactor: Retire the deferred-lint mechanism and adopt toolbelt.errors in agents (#1279)
- #1262 refactor: Hoist unreadable for-of expressions and promote the lint rule to an error (#1276)
- #1267 fix: Extend the no-hard-wrapping instruction to every GitHub composer (#1275)
- #1177 fix: Rewrite links, tokens, and template variables in a Markdown file support entry (#1273)
- #1176 feat: Add a ticketing-preferences hook to the skills that split and create tickets (#1268)
- #1252 fix: Keep a skill's own sections out of injected guidance (#1266)
- #1260 refactor: Fix lint and retire rule deferrals (#1265)
- #1247 feat: Add a personal tooling-preferences rulebook (#1257)
- #1251 feat: Let a rulebook declare that a guidance hook is how it is reached (#1259)
- #1246 feat: Guard home-domain writes and record their provenance (#1254)
- #1175 feat: Link new tickets to their blockers and parents (#1249)

factory-v0.2.6
- deps: Upgrade all deps to latest version
- #1290 tooling: Upgrade eslint-config-typescript to 10 and complete manifest metadata (#1301)
- deps: Upgrade all deps to latest version
- deps: Upgrade all deps to latest version
- #1264 refactor: Consolidate error-message extraction on toolbelt.errors' describeError (#1284)

kb-v0.6.0
- deps: Upgrade all deps to latest version
- #1290 tooling: Upgrade eslint-config-typescript to 10 and complete manifest metadata (#1301)
- #1289 tooling: Remove shelled nmr calls from package manifests (#1291)
- #1264 refactor: Consolidate error-message extraction on toolbelt.errors' describeError (#1284)
- #1261 feat: Attach causes to kb's loader errors and retire its lint deferral (#1272)
- #1260 refactor: Fix lint and retire rule deferrals (#1265)

codeassembly-lifecycle-v0.4.0
- #1290 tooling: Upgrade eslint-config-typescript to 10 and complete manifest metadata (#1301)
- #1289 tooling: Remove shelled nmr calls from package manifests (#1291)
- #1261 feat: Attach causes to kb's loader errors and retire its lint deferral (#1272)
- #1260 refactor: Fix lint and retire rule deferrals (#1265)

codeassembly-mcp-v0.2.5
- deps: Upgrade all deps to latest version
- #1290 tooling: Upgrade eslint-config-typescript to 10 and complete manifest metadata (#1301)
- #1289 tooling: Remove shelled nmr calls from package manifests (#1291)
- #1264 refactor: Consolidate error-message extraction on toolbelt.errors' describeError (#1284)

codeassembly-run-core-v0.3.0
- deps: Upgrade all deps to latest version
- #1290 tooling: Upgrade eslint-config-typescript to 10 and complete manifest metadata (#1301)
- #1289 tooling: Remove shelled nmr calls from package manifests (#1291)
- #1264 refactor: Consolidate error-message extraction on toolbelt.errors' describeError (#1284)
- #1261 feat: Attach causes to kb's loader errors and retire its lint deferral (#1272)
- #1260 refactor: Fix lint and retire rule deferrals (#1265)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

refactoring Improvement to code without change in functionality scope:agents

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Clear agents' lint warnings, adopt toolbelt.errors, and retire the deferred-lint mechanism

1 participant