bootstrap --force fans out to several destructive operations and is advised as a routine remedy

[stackbilt-admin]

Raised during constellation-loop review of PR #304 (issue #298).

The problem

bootstrap --force is a single flag that fans out to several destructive operations at once:

• hook overwrite
• ADF re-scaffold — writeAdfScaffolds (bootstrap.ts:878) overwrites custom .ai/*.adf modules
• config overwrite

Every other command's --force is narrowly scoped to the one thing that command does. Bootstrap's is not, so a user reaching for it to fix one thing can silently lose hand-authored ADF content — the content Charter exists to protect.

It is advised as a routine remedy

bootstrap.ts:962 and bootstrap.ts:964 (the ADF pointer warnings) both tell the user to "use --force to overwrite". PR #304 fixed one such instance (the stale .mcp.json absolute-path case now names a targeted hand-edit and explicitly says not to use --force), but these two remain.

Worth noting these warnings were effectively invisible in text mode until PR #304 — setup-phase warnings were collected but never printed, surfacing only as a count in "Bootstrap complete. N warnings." That is plausibly why the destructive advice went unnoticed.

Possible directions

• Split bootstrap's --force into scoped flags (e.g. --force-hooks, --force-adf, --force-config), keeping --force as an explicit all-of-the-above
• Or keep one flag but make the ADF re-scaffold refuse to overwrite a module that differs from its scaffold template unless separately confirmed
• Either way, stop advising bare --force in warnings where a narrower remedy exists

Follow-up from #304; not changed there to keep that bugfix scoped.

[stackbilt-admin]

Docs sweep update — 2026-09-20

Line references here have shifted, and one piece of the reasoning no longer holds. The substantive ask is unchanged and still open.

Stale line references (#317 refactored bootstrap's phase handling into a single completePhase helper):

Cited	Current
bootstrap.ts:962 / :964 — the two use --force to overwrite warnings	bootstrap.ts:1023 / :1025
bootstrap.ts:878 — writeAdfScaffolds	bootstrap.ts:908

Both warnings still exist verbatim, and --force still fans out to hook overwrite + ADF re-scaffold + config overwrite. Nothing about the core problem changed.

Correction to the visibility note. This issue says the warnings "were effectively invisible in text mode until PR #304 — setup-phase warnings were collected but never printed", offered as a plausible reason the destructive advice went unnoticed. That applies to the setup-phase .mcp.json warning #304 fixed, but not to these two: they are raised in runAdfInitPhase (bootstrap.ts:964), which is phase 3 and has always printed its warnings. They were visible the whole time.

#307 / PR #317 has since closed the visibility gap across every phase — recording a step and printing its warnings are now one operation, so no phase can swallow a warning by omission. That removes the invisibility explanation entirely rather than confirming it.

Unchanged and still worth doing: the three directions listed — scoped --force-* flags, or making the ADF re-scaffold refuse to overwrite a module that differs from its template, or at minimum ceasing to advise bare --force where a narrower remedy exists. #304 set the precedent for the third by replacing one such instance with a targeted hand-edit and an explicit "do not use --force for this".

Auto-updated by /docs skill.