17 · install-half-archon-dir
What this scenario proves
The install guard checks only one file to decide if Archon is already present:
js
if (await pathExists(path.join(targetDir, '.archon', 'soul.md'))) { ... }So if the target has a .archon/ directory without a soul.md inside (typical of a half-aborted earlier install, a manually-created empty governance directory, or a corrupted state), archon install will treat the project as a clean target and proceed.
This scenario locks that behaviour down so it does not silently change. It is intentionally documented as a sharp edge (see Known limitations) and pairs with the install-matrix discussion of guard semantics.
Test environment
| Fixture | fixtures/sandbox-node-ts + injected half-archon |
| IDE | Cursor |
| Manifest version under test | v0.1.x |
Pre-conditions
- Fixture copied — runner-managed.
- No
.archon/soul.mdexists. .archon/sentinel.txtinjected as prerequisite (so.archon/as a directory already exists).
Steps
text
1. Inject `.archon/sentinel.txt` with a marker line.
2. Run `archon install --with=cli`.
3. Observe install proceeds without complaint.Expected outcome
| Check | Expected |
|---|---|
| Step 2 exit code | 0 |
.archon/soul.md | created (the install was not blocked) |
.archon/sentinel.txt | preserved (not deleted by install) |
.archon/drift.md install rows | exactly 1 |
.archon-backup-* | absent (no --force was needed because the guard didn't fire) |
Demo recordings
Recording coming soon
install-half-archon-dir.mp4IDE chat-panel walkthroughdocs/public/videos/install-half-archon-dir.mp4 once recorded. See videos/README for upload conventions. $ archon doctor .
[L1 Structural] OK
[L2 Contract] OK
[L3 Hints] OK
✔ Recording coming soon — placeholderdocs/public/asciinema/install-half-archon-dir.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-half-archon-dir| Started (UTC) | Manifest | Runner | Result | Duration | Notes | Record |
|---|---|---|---|---|---|---|
2026-06-08 08:17:12 UTC | v0.1.0 | cli | ✅ passing | 317 ms | — | JSON |
2026-06-07 07:10:17 UTC | v0.1.0 | cli | ✅ passing | 321 ms | — | JSON |
2026-06-06 06:34:41 UTC | v0.1.0 | cli | ✅ passing | 334 ms | — | JSON |
2026-06-05 07:14:07 UTC | v0.1.0 | cli | ✅ passing | 306 ms | — | JSON |
2026-06-04 07:56:44 UTC | v0.1.0 | cli | ✅ passing | 323 ms | — | JSON |
2026-06-03 08:24:18 UTC | v0.1.0 | cli | ✅ passing | 343 ms | — | JSON |
2026-06-02 08:00:52 UTC | v0.1.0 | cli | ✅ passing | 341 ms | — | JSON |
2026-06-01 08:40:46 UTC | v0.1.0 | cli | ✅ passing | 338 ms | — | JSON |
2026-05-31 07:02:24 UTC | v0.1.0 | cli | ✅ passing | 332 ms | — | JSON |
2026-05-30 06:27:53 UTC | v0.1.0 | cli | ✅ passing | 317 ms | — | JSON |
2026-05-29 06:59:40 UTC | v0.1.0 | cli | ✅ passing | 324 ms | — | JSON |
2026-05-28 06:59:33 UTC | v0.1.0 | cli | ✅ passing | 312 ms | — | JSON |
2026-05-27 07:09:42 UTC | v0.1.0 | cli | ✅ passing | 317 ms | — | JSON |
2026-05-26 06:52:09 UTC | v0.1.0 | cli | ✅ passing | 291 ms | — | JSON |
2026-05-25 07:20:22 UTC | v0.1.0 | cli | ✅ passing | 322 ms | — | JSON |
2026-05-24 06:41:53 UTC | v0.1.0 | cli | ✅ passing | 321 ms | — | JSON |
2026-05-23 06:16:50 UTC | v0.1.0 | cli | ✅ passing | 316 ms | — | JSON |
2026-05-22 06:54:18 UTC | v0.1.0 | cli | ✅ passing | 319 ms | — | JSON |
2026-05-21 06:58:04 UTC | v0.1.0 | cli | ✅ passing | 328 ms | — | JSON |
2026-05-20 06:53:38 UTC | v0.1.0 | cli | ✅ passing | 318 ms | — | JSON |
2026-05-19 06:53:18 UTC | v0.1.0 | cli | ✅ passing | 316 ms | — | JSON |
2026-05-18 07:01:47 UTC | v0.1.0 | cli | ✅ passing | 338 ms | — | JSON |
2026-05-17 06:27:36 UTC | v0.1.0 | cli | ✅ passing | 325 ms | — | JSON |
2026-05-16 06:04:40 UTC | v0.1.0 | cli | ✅ passing | 317 ms | — | JSON |
2026-05-15 06:37:59 UTC | v0.1.0 | cli | ✅ passing | 327 ms | — | JSON |
2026-05-14 06:28:57 UTC | v0.1.0 | cli | ✅ passing | 325 ms | — | JSON |
2026-05-13 06:30:25 UTC | v0.1.0 | cli | ✅ passing | 298 ms | — | JSON |
2026-05-12 06:19:01 UTC | v0.1.0 | cli | ✅ passing | 322 ms | — | JSON |
2026-05-11 06:45:35 UTC | v0.1.0 | cli | ✅ passing | 303 ms | — | JSON |
2026-05-10 06:16:45 UTC | v0.1.0 | cli | ✅ passing | 351 ms | — | JSON |
2026-05-09 05:52:39 UTC | v0.1.0 | cli | ✅ passing | 292 ms | — | JSON |
2026-05-08 05:33:36 UTC | v0.1.0 | cli | ✅ passing | 341 ms | — | JSON |
2026-05-07 11:01:03 UTC | v0.1.0 | cli | ✅ passing | 305 ms | — | JSON |
2026-05-07 09:54:54 UTC | v0.1.0 | cli | ✅ passing | 326 ms | — | JSON |
2026-05-07 09:45:13 UTC | v0.1.0 | cli | ✅ passing | 489 ms | — | JSON |
2026-05-07 06:15:45 UTC | v0.1.0 | cli | ✅ passing | 252 ms | — | JSON |
2026-05-06 11:45:37 UTC | v0.1.0 | cli | ✅ passing | 288 ms | — | JSON |
2026-05-06 11:44:06 UTC | v0.1.0 | cli | ✅ passing | 293 ms | — | JSON |
2026-05-06 11:19:26 UTC | v0.1.0 | cli | ✅ passing | 627 ms | — | JSON |
Known limitations
- This is a documented sharp edge, not a bug fix in disguise. The install guard is intentionally narrow (
soul.mdis the canonical "Archon was here" marker; bare.archon/directories are common during scaffolding). If the team ever decides the guard should also fire on a non-empty.archon/, this scenario must flip its expectations. - Does not check what happens if
.archon/manifest.mdexists butsoul.mddoes not — that is a more subtle half-state worth a follow-up scenario.
Cross-references
- Protocol page:
/setup/install - Source:
docs/source-files/tools/archon-cli/lib/install.mjsline 31. - Install matrix: Install Matrix
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": "inject .archon/sentinel.txt (no soul.md)",
"write_file": {
"path": ".archon/sentinel.txt",
"content": "half-archon sentinel for scenario 17\n"
}
}
],
"steps": [
{
"name": "archon install --with=cli",
"cli": "install",
"flags": ["--with=cli"]
}
],
"assertions": [
{ "file_exists": ".archon/soul.md" },
{ "file_exists": ".archon/sentinel.txt" },
{ "file_contains": { "path": ".archon/sentinel.txt", "substr": "half-archon sentinel" } },
{ "cmd_zero": ["node", "__sb-check.cjs", "drift-install-count", "1"] },
{ "cmd_zero": ["node", "__sb-check.cjs", "no-backup-dir"] },
{ "cmd_zero": ["python3", "scripts/archon-check.py", "--root", "."] }
],
"notes": "Documents the install guard's narrow check (soul.md only). A bare .archon/ does not block install."
}