[auto] fix: bootstrap --yes vs --force separation + backup + orphan detection

[stackbilt-admin]

Autonomous Task

Task ID: 80a25dcb-7073-4f9e-ba21-01c0dbc8a22b
Authority: auto_safe
Exit code: 0

Task Prompt

Fix Charter bootstrap UX when running on existing repos with pre-existing .ai/ content. This is the top adoption blocker — bootstrap currently nukes existing ADF modules.

GitHub Issue: #65

Changes needed (in priority order):

1. Separate --yes from --force

Currently const force = options.yes; — these should be independent flags.

• --yes: non-interactive, accept defaults, but REFUSE to overwrite existing non-scaffold ADF files
• --force: explicitly allow overwriting existing content
• --yes without --force should skip overwriting files that already exist and contain non-scaffold content (check if content differs from the scaffold template)

2. Backup before overwrite

Before overwriting any existing .ai/ files:

• Copy originals to .ai/.backup/<filename>.<timestamp>
• Print a warning listing what will be overwritten with byte counts
• When --force is used, still backup but proceed without prompting

3. Register orphaned modules

After bootstrap scaffold generation, scan .ai/ for .adf files not referenced in manifest.adf:

• Print warning: "Found N unregistered .adf modules: X, Y, Z"
• Auto-register them as ON_DEMAND modules in the manifest
• Don't delete them, don't ignore them

4. Fix package.json detection for worker preset

When preset is worker, also check common nested locations:

• web/package.json
• worker/package.json
• src/package.json
• app/package.json
  Use the first one found if root package.json doesn't exist.

How to find the code

• Bootstrap command: look for the bootstrap command handler (likely src/commands/bootstrap.ts or similar)
• The force = options.yes line is the starting point
• Manifest handling: look for manifest generation/parsing code
• Package.json detection: look for npm install logic in the bootstrap flow

Verification

• npm run typecheck must pass
• npm test must pass
• Test manually: create a temp dir with existing .ai/core.adf, run bootstrap --yes,

Result Summary

All changes committed. Here's a summary of what was done:

Changes made

1. Separated --yes from --force (priority 1)

• adf.ts: adfInit and adfCreate no longer treat --yes as --force. --yes = non-interactive; --force = allow overwrite.
• setup.ts: setupCommand same separation applied.
• bootstrap.ts: Already correctly separated (confirmed).

2. Backup before overwrite (priority 2)

• bootstrap.ts: Backup filenames now include ISO timestamps: .ai/.backup/<file>.<timestamp> (e.g., core.adf.2026-03-26T12-00-00-000Z)
• Overwrite warnings now include byte counts (e.g., ".ai/core.adf has custom content (142 bytes); skipping scaffold overwrite")
• Per-file backup warnings when --force is used

3. Register orphaned modules (priority 3)

• bootstrap.ts: In --yes mode, orphaned .adf modules are now auto-registered as ON_DEMAND in the manifest (previously only prompted interactively)

4. Package.json detection for worker preset (priority 4)

• setup.ts: loadPackageContexts now also checks worker/, src/, and app/ directories for package.json

Validation

• TypeScript typecheck: pass
• All 309 tests across 29 files: pass

TASK_COMPLETE

---

Generated by AEGIS task runner. Review before merging.