Complete upload-adjacent readiness work: transactions, cross-file authorization, canonical installation

[is-bo]

Completes three of the five items left unfinished after #53, and fixes several defects found while doing so. This is partial — two items are not done and are listed explicitly below. Do not merge on the assumption that the completion work is finished.

Baseline 3f73177 · candidate 1f7342b · 9 commits · package version unchanged at 0.1.0, no tag, no release.

What is complete

Missing-transaction analysis (new)

There was no transaction detection in the CLI at all. This adds a deterministic analyzer that flags multi-step write workflows where a partial failure would violate an evidenced consistency invariant, and wires it into the per-file pass so the rules actually execute rather than being declared only.

Relatedness is structural: writes must share an entity identifier, a foreign key, or dataflow before they are grouped, so a function containing several independent writes stays clean. Boundaries resolve through Prisma, Knex, Sequelize, TypeORM, Drizzle, Mongo sessions, raw BEGIN/COMMIT, local aliases, and one level of wrapper delegation. Anything unresolvable becomes NOT_VERIFIED.

Two defects were found by the new regression matrix and fixed:

• isKnownTransactionChain branched on segments.length === 1, which routed every single-hop member call — prisma.$transaction, knex.transaction — down an alias-only path where a vendor API could never match. Correctly wrapped transactions were being reported.
• hasDataAccessReceiver gated ambiguous verbs behind a receiver-name check, so writes on a handle from a custom wrapper matched no known data-access name and were not detected as writes at all. An unresolved boundary produced no finding in either direction — silently safe, which the contract forbids.

Cross-file authorization middleware

classifyRouteGuards accepted any unresolved middleware whose identifier began with require/ensure/authorize/etc. as a proven guard. Since an imported symbol never resolved to a local body, every cross-file guard took that path: an imported requireAdmin whose body only calls next() suppressed the route finding entirely.

Classification now goes through a corpus-wide resolver that reads the body an import actually names — following relative imports, renamed and default exports, barrel re-exports, and factories, under explicit hop, file, and cycle budgets, reusing scope.ts for module resolution rather than adding a second resolver. The three in-file helpers are deleted, so there is one implementation.

Verified on cross-file fixtures: an imported requireAdmin that never denies now fails; tollbooth that returns 403 is clean; barrel re-export resolves; external package, cycle, and dynamic import are all NOT_VERIFIED rather than proven.

Canonical installation layout

Six host roots each carried a full copy of every managed file. They now carry a SKILL.md adapter that preserves host discovery frontmatter and names the canonical playbook by relative path. No symlinks, so Windows and paths containing spaces behave identically. Codex remains a documented exception: it reads agents/openai.yaml with ordinary tooling, so agents/ and assets/ are still copied verbatim into .agents only.

	Files	Bytes
Before	804	6,704,066
After (134 canonical + 286 host)	420	2,229,170
Reduction	−47.8%	−66.7%

The layout would have shipped broken. installer.ts reads bundled content from PACKAGE_ROOT/.fullstack-forge, but that directory was missing from the package files allowlist, so the entire managed payload was excluded from the tarball. Fresh install, upgrade, and offline install all failed with ENOENT on a packed archive. In-repo tests could not catch this because they read the working tree.

Verified on Windows at a path containing a space:

• smoke:install — 46 skills, automatic activation, 0 symlinks, clean uninstall
• smoke:upgrade — migration from the previous full-copy layout, doctor ready, 46 per root, 0 symlinks, clean uninstall
• offline:install — six roots at 46 skills, cache-only npm, unreachable registry, 0 symlinks, clean uninstall

One upload false positive closed

FF-UPLOAD-MIME-001 fired whenever a file mentioned a content-type token and did not literally contain magic|signature|fileTypeFromBuffer|decode|sniff. Validation is routinely factored into a shared helper whose body the in-file regex cannot read, so hardened upload paths were published as confident HIGH failures purely because their validation lived in another module.

When the upload payload is passed to an imported function, the finding is now NOT_VERIFIED and its evidence names the delegate. Detection is structural — import bindings plus an AST walk for a call receiving the payload — not a name list. Trusting client MIME with no validation anywhere still fails; proven in-file signature validation is still clean.

This closes the false-positive class. It is not upload analyzer completion — see below.

What is NOT done

• Upload analyzer coverage (0A). The three target rule families were not rewritten structurally, no new fixtures were added for them, and non-multer coverage is unchanged.
• Playbook deduplication (0C). Not started; boilerplate remains at its current level and is not measured here.
• Independent verification, external benchmarking, and release-readiness scoring. Not performed.
• npm run test:coverage and npm audit were not run. Only Node 24.14.1 was exercised — not 20 or 22 — and no CI evidence was collected for the nine-job OS/Node matrix.

Known defects found but not fixed

• Upload analysis is multer-only. The analyzer is gated on upload.(any|array|fields|single), so presigned S3/GCS, busboy, formidable, and Next.js route handlers receive no upload analysis. Their "clean" result is indistinguishable from genuinely hardened code, which is the more dangerous failure mode.
• FF-AUTHZ-OBJECT-001 fires behind proven guards. Any delete({ where: { id } }) reports HIGH even when a proven admin guard sits in front. Defensible in principle — role access is not per-object ownership — but on real repositories this has the shape of a systemic HIGH false-positive class. Pre-existing; flagged rather than changed, since suppressing it could hide genuine BOLA bugs.

Validation

npm run check passes end to end on Node 24.14.1 / Windows: format, lint, typecheck, 867 tests (866 pass, 1 skipped, 0 fail), all validators, packaging (9 archives, 1083 entries), and secret scan (1180 files, 0 findings). Baseline was 845 tests; the 22 added are the transaction, guard-resolution, and upload-delegation matrices.

Three test files and three smoke scripts asserted the old full-copy layout. They were rewritten to assert the property that matters — canonical content exists, adapters point at it, unselected hosts stay untouched — and are stricter than before, not weaker. transactions.ts, guard-resolution.ts, and managed-layout.ts had never been linted (they were untracked); doing so surfaced 8 real defects, all fixed at source.

🤖 Generated with Claude Code