16 · install-force-reinstall

What this scenario proves

archon install --force is the documented escape hatch when an adopter genuinely wants to reset their Archon installation (e.g. recovering from a corrupted .archon/). The expected behaviour is:

The previously-installed files are backed up into a fresh .archon-backup-<iso-timestamp>/ sibling directory.
The full manifest is re-projected on top of the existing layout.
A second ## install row is appended to .archon/drift.md — making the drift ledger an honest installation history of the project (one row per install, including forced re-installs).

This is the positive counterpart of 15 · install-rejects-reinstall.

Test environment


Fixture	`fixtures/sandbox-node-ts`
IDE	Cursor
Manifest version under test	v0.1.x

Pre-conditions

Fixture copied — runner-managed.
First archon install --with=cli succeeds (prerequisite).

Steps

text

1. Run `archon install --with=cli --force` a second time.
2. Observe:
     - exit 0
     - log line "[archon install] backups will be written to .archon-backup-…"
3. Verify backup directory and drift ledger row count.

Expected outcome

Check	Expected
Step 1 exit code	0
`.archon/soul.md`	exists (re-written)
`.archon-backup-<iso-timestamp>/`	exists (at least one such directory)
`.archon/drift.md` install rows	exactly 2
Pre-existing host files (`package.json`, `src/todo.ts`)	unchanged

Demo recordings

Recording coming sooninstall-force-reinstall.mp4IDE chat-panel walkthrough

Will be replaced by docs/public/videos/install-force-reinstall.mp4 once recorded. See videos/README for upload conventions.

install-force-reinstall.cast

$ archon doctor .
[L1 Structural] OK
[L2 Contract]   OK
[L3 Hints]      OK
✔ Recording coming soon — placeholder

Will be replaced by docs/public/asciinema/install-force-reinstall.cast embedded via the asciinema-player web component. See asciinema/README for the recording command.

Run records

bash

node scripts/sandbox-run.mjs --only=install-force-reinstall

Started (UTC)	Manifest	Runner	Result	Duration	Notes	Record
`2026-06-08 08:17:11 UTC`	`v0.1.0`	cli	✅ passing	535 ms	—	JSON
`2026-06-07 07:10:16 UTC`	`v0.1.0`	cli	✅ passing	542 ms	—	JSON
`2026-06-06 06:34:40 UTC`	`v0.1.0`	cli	✅ passing	594 ms	—	JSON
`2026-06-05 07:14:06 UTC`	`v0.1.0`	cli	✅ passing	545 ms	—	JSON
`2026-06-04 07:56:43 UTC`	`v0.1.0`	cli	✅ passing	609 ms	—	JSON
`2026-06-03 08:24:17 UTC`	`v0.1.0`	cli	✅ passing	583 ms	—	JSON
`2026-06-02 08:00:51 UTC`	`v0.1.0`	cli	✅ passing	752 ms	—	JSON
`2026-06-01 08:40:45 UTC`	`v0.1.0`	cli	✅ passing	567 ms	—	JSON
`2026-05-31 07:02:23 UTC`	`v0.1.0`	cli	✅ passing	555 ms	—	JSON
`2026-05-30 06:27:53 UTC`	`v0.1.0`	cli	✅ passing	546 ms	—	JSON
`2026-05-29 06:59:39 UTC`	`v0.1.0`	cli	✅ passing	572 ms	—	JSON
`2026-05-28 06:59:33 UTC`	`v0.1.0`	cli	✅ passing	587 ms	—	JSON
`2026-05-27 07:09:41 UTC`	`v0.1.0`	cli	✅ passing	559 ms	—	JSON
`2026-05-26 06:52:08 UTC`	`v0.1.0`	cli	✅ passing	500 ms	—	JSON
`2026-05-25 07:20:21 UTC`	`v0.1.0`	cli	✅ passing	546 ms	—	JSON
`2026-05-24 06:41:52 UTC`	`v0.1.0`	cli	✅ passing	546 ms	—	JSON
`2026-05-23 06:16:50 UTC`	`v0.1.0`	cli	✅ passing	549 ms	—	JSON
`2026-05-22 06:54:17 UTC`	`v0.1.0`	cli	✅ passing	549 ms	—	JSON
`2026-05-21 06:58:04 UTC`	`v0.1.0`	cli	✅ passing	571 ms	—	JSON
`2026-05-20 06:53:37 UTC`	`v0.1.0`	cli	✅ passing	537 ms	—	JSON
`2026-05-19 06:53:18 UTC`	`v0.1.0`	cli	✅ passing	553 ms	—	JSON
`2026-05-18 07:01:46 UTC`	`v0.1.0`	cli	✅ passing	586 ms	—	JSON
`2026-05-17 06:27:36 UTC`	`v0.1.0`	cli	✅ passing	545 ms	—	JSON
`2026-05-16 06:04:40 UTC`	`v0.1.0`	cli	✅ passing	553 ms	—	JSON
`2026-05-15 06:37:59 UTC`	`v0.1.0`	cli	✅ passing	568 ms	—	JSON
`2026-05-14 06:28:56 UTC`	`v0.1.0`	cli	✅ passing	575 ms	—	JSON
`2026-05-13 06:30:24 UTC`	`v0.1.0`	cli	✅ passing	503 ms	—	JSON
`2026-05-12 06:19:00 UTC`	`v0.1.0`	cli	✅ passing	538 ms	—	JSON
`2026-05-11 06:45:34 UTC`	`v0.1.0`	cli	✅ passing	513 ms	—	JSON
`2026-05-10 06:16:44 UTC`	`v0.1.0`	cli	✅ passing	575 ms	—	JSON
`2026-05-09 05:52:37 UTC`	`v0.1.0`	cli	✅ passing	2.29 s	—	JSON
`2026-05-08 05:33:35 UTC`	`v0.1.0`	cli	✅ passing	587 ms	—	JSON
`2026-05-07 11:01:03 UTC`	`v0.1.0`	cli	✅ passing	521 ms	—	JSON
`2026-05-07 09:54:53 UTC`	`v0.1.0`	cli	✅ passing	572 ms	—	JSON
`2026-05-07 09:45:12 UTC`	`v0.1.0`	cli	✅ passing	800 ms	—	JSON
`2026-05-07 06:15:44 UTC`	`v0.1.0`	cli	✅ passing	521 ms	—	JSON
`2026-05-06 11:45:36 UTC`	`v0.1.0`	cli	✅ passing	574 ms	—	JSON
`2026-05-06 11:44:06 UTC`	`v0.1.0`	cli	✅ passing	586 ms	—	JSON
`2026-05-06 11:19:26 UTC`	`v0.1.0`	cli	✅ passing	587 ms	—	JSON

Known limitations

Does not verify the content of the backup directory matches the previous .archon/ byte-for-byte. The current contract only promises a backup exists; granular content equality is a deeper test for a future scenario.
Does not measure the time interval between the two install rows; if a maintainer ever wires drift-row chronology into a contract, this scenario gains a new assertion.

Cross-references

Protocol page: /setup/install
Companion scenario: 15 · install-rejects-reinstall
Source: docs/source-files/tools/archon-cli/lib/install.mjs lines 71–86.

json

{
  "runnable": "cli",
  "fixture": "fixtures/sandbox-node-ts",
  "ide_platform": "cursor",
  "prerequisites": [
    {
      "name": "drop sandbox check helper",
      "write_file": {
        "path": "__sb-check.cjs",
        "content": "const fs=require('fs');const op=process.argv[2];const args=process.argv.slice(3);if(op==='drift-install-count'){const want=Number(args[0]);const c=fs.readFileSync('.archon/drift.md','utf8');const m=c.match(/^## install /gm);const n=m?m.length:0;if(n!==want){console.error('drift install rows: want',want,'got',n);process.exit(1)}process.exit(0)}if(op==='no-backup-dir'){const found=fs.readdirSync('.').some(function(x){return x.indexOf('.archon-backup-')===0});if(found){console.error('unexpected .archon-backup-*');process.exit(1)}process.exit(0)}if(op==='has-backup-dir'){const found=fs.readdirSync('.').some(function(x){return x.indexOf('.archon-backup-')===0});if(!found){console.error('expected .archon-backup-* missing');process.exit(1)}process.exit(0)}if(op==='pkg-name-equals'){const p=require('./package.json');if(p.name!==args[0]){console.error('package.json name mutated:',p.name);process.exit(1)}process.exit(0)}if(op==='file-includes'){const text=fs.readFileSync(args[0],'utf8');if(text.indexOf(args[1])===-1){console.error(args[0],'missing',args[1]);process.exit(1)}process.exit(0)}if(op==='drift-modules-excludes'){const c=fs.readFileSync('.archon/drift.md','utf8');const re=new RegExp('^- Modules:.*\\\\b'+args[0]+'\\\\b','m');if(re.test(c)){console.error(args[0],'unexpectedly listed');process.exit(1)}process.exit(0)}console.error('unknown op:',op);process.exit(2);\n"
      }
    },
    {
      "name": "first archon install",
      "cli": "install",
      "flags": ["--with=cli"]
    }
  ],
  "steps": [
    {
      "name": "force reinstall",
      "cli": "install",
      "flags": ["--with=cli", "--force"]
    }
  ],
  "assertions": [
    { "file_exists": ".archon/soul.md" },
    { "file_exists": "package.json" },
    { "file_exists": "src/todo.ts" },
    { "cmd_zero": ["node", "__sb-check.cjs", "has-backup-dir"] },
    { "cmd_zero": ["node", "__sb-check.cjs", "drift-install-count", "2"] },
    { "cmd_zero": ["node", "__sb-check.cjs", "pkg-name-equals", "acme-todos"] },
    { "cmd_zero": ["python3", "scripts/archon-check.py", "--root", "."] }
  ],
  "notes": "Positive test: --force overrides the guard, creates .archon-backup-*, appends a second install row, leaves host files alone."
}

16 · install-force-reinstall ​

What this scenario proves ​

Test environment ​

Pre-conditions ​

Steps ​

Expected outcome ​

Demo recordings ​

Run records ​

Known limitations ​

Cross-references ​