Summary
lead-protocol init (with or without -y) unconditionally regenerates every file under .agents/, including files the protocol's own three-layer state model (CORE_RULES.md / PROTOCOL_RULES.md §P3) documents as project-owned and "never overwritten by framework upgrades":
.agents/PROJECT_RULES.md — reverted to the generic [Project Name] placeholder template, discarding all real project identity/context..agents/JOURNAL.md — entries truncated..agents/decisions.jsonl — entries removed..agents/AGENTS_MAP.md — reset to template..agents/sessions/active_sessions.md — reset to template.
Repro
- Have an existing project with a populated
.agents/ scaffold (real PROJECT_RULES.md content, non-trivial JOURNAL.md/decisions.jsonl).
- Install/upgrade the CLI to a newer version (in this case v2.1.4).
- Run
lead-protocol init -y intending an in-place framework upgrade (there is currently no separate upgrade command).
- Observe
git diff / git status — project-layer files are rewritten from generic templates, not merged.
Impact
In our case the working tree was clean, so the change was fully revertible via git restore plus removing the newly-created untracked files (manifest.json, two new test files). On a dirty tree, or without git as a safety net, this would silently destroy project-specific state with no warning and no diff shown first.
Suggested fix
One or both of:
- A dedicated
lead-protocol upgrade command that only touches genuine framework-layer files (CORE_RULES.md, PROTOCOL_RULES.md, modules/, schemas/, scripts/, manifest.json), diffing against the installed CLI version and leaving project-layer files (PROJECT_RULES.md, JOURNAL.md, decisions.jsonl, AGENTS_MAP.md, sessions/active_sessions.md, local/) completely untouched.
- At minimum,
init should refuse to run (or require an explicit --force/confirmation beyond -y) when it detects an existing .agents/PROJECT_RULES.md that doesn't match the fresh-template placeholder content — i.e., detect "this looks like a real project, not a fresh scaffold" and treat it differently from a first-time init.
Workaround used
Manually cloned the target release tag, diffed each file under .agents/ against the local copy, and hand-applied only the files that genuinely differed at the framework layer. Confirmed via lead-protocol validate (same pre-existing errors before/after) and lead-protocol status (correct Product/Kernel version reported afterward) that the result matches what a real upgrade should produce.
Filed from an agent session in mmilanez/leaddocs, companion PR: mmilanez/leaddocs#191
Summary
lead-protocol init(with or without-y) unconditionally regenerates every file under.agents/, including files the protocol's own three-layer state model (CORE_RULES.md/PROTOCOL_RULES.md §P3) documents as project-owned and "never overwritten by framework upgrades":.agents/PROJECT_RULES.md— reverted to the generic[Project Name]placeholder template, discarding all real project identity/context..agents/JOURNAL.md— entries truncated..agents/decisions.jsonl— entries removed..agents/AGENTS_MAP.md— reset to template..agents/sessions/active_sessions.md— reset to template.Repro
.agents/scaffold (realPROJECT_RULES.mdcontent, non-trivialJOURNAL.md/decisions.jsonl).lead-protocol init -yintending an in-place framework upgrade (there is currently no separateupgradecommand).git diff/git status— project-layer files are rewritten from generic templates, not merged.Impact
In our case the working tree was clean, so the change was fully revertible via
git restoreplus removing the newly-created untracked files (manifest.json, two new test files). On a dirty tree, or without git as a safety net, this would silently destroy project-specific state with no warning and no diff shown first.Suggested fix
One or both of:
lead-protocol upgradecommand that only touches genuine framework-layer files (CORE_RULES.md,PROTOCOL_RULES.md,modules/,schemas/,scripts/,manifest.json), diffing against the installed CLI version and leaving project-layer files (PROJECT_RULES.md,JOURNAL.md,decisions.jsonl,AGENTS_MAP.md,sessions/active_sessions.md,local/) completely untouched.initshould refuse to run (or require an explicit--force/confirmation beyond-y) when it detects an existing.agents/PROJECT_RULES.mdthat doesn't match the fresh-template placeholder content — i.e., detect "this looks like a real project, not a fresh scaffold" and treat it differently from a first-timeinit.Workaround used
Manually cloned the target release tag, diffed each file under
.agents/against the local copy, and hand-applied only the files that genuinely differed at the framework layer. Confirmed vialead-protocol validate(same pre-existing errors before/after) andlead-protocol status(correct Product/Kernel version reported afterward) that the result matches what a real upgrade should produce.Filed from an agent session in
mmilanez/leaddocs, companion PR: mmilanez/leaddocs#191