Drop the live generator subagent; fix the artifact decoy that broke accept

The first real Claude Code Live run failed, and the subagent was not the cause.

Root cause: progressive publication stages each revision as
`.impeccable/live/artifacts/<id>-r<n>.<source-ext>`, nothing ever deleted them,
and findSessionFile's walker skipped only node_modules/.git/dist/build. It
searches src, app, pages, ... then `.`; a project whose source is not under one of
those (this repo's own site lives in site/pages/) falls through to the `.` walk,
where dot-directories sort before letters. So accept found the artifact instead of
the real file. Two outcomes, both reproduced: where isGeneratedFile returns true
it declines with mode: 'fallback' (what the run hit, after which the agent
hand-carbonized several hundred lines across three stylesheets, including
unrequested drive-by edits); where it returns false, accept writes the variant
into the throwaway artifact and reports handled: true while real source never
changes.

The E2E suite could not have caught this. Every fixture puts source under `src/`,
which is searched before the `.` walk can reach `.impeccable`. Five framework
fixtures and three progressive scenarios pass because of fixture layout, not
because the path works. I read that as evidence and shouldn't have.

- Never search `.impeccable`: it is Impeccable's own state, never project source.
- Retire a session's staged artifacts on accept/discard, so they cannot outlive
  the session and become a decoy for anything else that walks the tree.
- Regression tests use a site/pages layout with artifacts present. All three fail
  against the previous code.

Generator subagent removed, on both harnesses:
The parent must hand-compress the design system into the handoff, and compression
is lossy. Measured on the real run: a 6,826-char handoff carrying exactly one
token reference, after the parent had itself read kinpaku-tokens.css. The subagent
then spent 3 of its first 9 turns hunting DESIGN.md, gave up, and emitted 0
var(--token) uses and 22 raw oklch literals — violating its own spec's "Never
invent raw colors when tokens exist" — including a 1:1 gold-on-gold contrast bug.
Isolation is not a benefit here; knowing the design system is the job. Generation
stays in the main thread, which already holds the tokens and writes them from the
first byte, so carbonize is a move rather than a translation.

Copy edits keep their subagent: applying a known set of ops to a named file is
self-contained, so an isolated context costs nothing. That is the line.

Progressive delivery stays for Codex and Claude Code, main-thread driven. Claude
Code keeps the full benefit because its poll is a background task. Codex's poll
blocks the foreground, so with no subagent the user sees variant 1 early via HMR
but cannot accept it until the trio finishes; that is the cost of the
simplification and it is worth naming.

Prepared with AI assistance under maintainer direction.

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Paul Bakaus
2026-07-17 18:56:23 -07:00
co-authored by Claude
parent 1b194d9751
commit c7b67b3832
6 changed files with 129 additions and 75 deletions
+22 -2
View File
@@ -16,7 +16,7 @@
import fs from 'node:fs';
import path from 'node:path';
import { isGeneratedFile } from './lib/is-generated.mjs';
import { getLiveDir, safeSessionId } from './lib/impeccable-paths.mjs';
import { IMPECCABLE_DIR, getLiveDir, safeSessionId } from './lib/impeccable-paths.mjs';
import { readBuffer as readManualEditsBuffer, writeBuffer as writeManualEditsBuffer } from './live/manual-edits-buffer.mjs';
import { withSourceLockSync } from './live/source-lock.mjs';
import {
@@ -34,6 +34,7 @@ import {
findSourceArtifactManifest,
removeSourceArtifactSession,
} from './live/source-artifact.mjs';
import { removeGenerationArtifacts } from './live/generation-publisher.mjs';
const EXTENSIONS = ['.html', '.jsx', '.tsx', '.vue', '.svelte', '.astro'];
const ACCEPT_LOCK_WAIT_MS = 1_000;
@@ -157,6 +158,10 @@ Output (JSON):
variantId: isDiscard ? null : String(variantNum),
result,
});
// The session is over: drop its staged revision artifacts. Leaving them
// behind is what let a later marker search find a decoy instead of real
// source. Only on success, so a failed accept can still be retried.
removeGenerationArtifacts(id, process.cwd());
}
console.log(JSON.stringify(result));
};
@@ -1037,6 +1042,21 @@ function detectCommentSyntax(filePath) {
// File search (find the file containing session markers)
// ---------------------------------------------------------------------------
/**
* `.impeccable` is the critical entry, and it is not cosmetic.
*
* Progressive publication stages each revision as `.impeccable/live/artifacts/
* <id>-r<n>.<source-ext>`, and those artifacts carry the very marker this search
* looks for. The walk reaches `.` for any project whose source is not under one
* of the privileged dirs above (this repo's own site lives in `site/pages/`), and
* dot-directories sort before letters, so the artifact was found *before* the
* real file. isGeneratedFile then declined the accept, and the agent fell back to
* carbonizing several hundred lines of stylesheet by hand.
*
* Impeccable's own state directory is never project source. Never search it.
*/
const SEARCH_SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', IMPECCABLE_DIR]);
function findSessionFile(id, cwd) {
const marker = 'impeccable-variants-start ' + id;
const searchDirs = ['src', 'app', 'pages', 'components', 'public', 'views', 'templates', '.'];
@@ -1077,7 +1097,7 @@ function searchDir(dir, query, seen, depth) {
for (const entry of entries) {
if (!entry.isDirectory()) continue;
if (['node_modules', '.git', 'dist', 'build'].includes(entry.name)) continue;
if (SEARCH_SKIP_DIRS.has(entry.name)) continue;
const result = searchDir(path.join(dir, entry.name), query, seen, depth + 1);
if (result) return result;
}