| name | ln-sync |
| description | Refresh `memory/SPEC.md` and `memory/PLAN.md` in mature mode — restore canonical truth, archive retired plan history, delete stale derivative artifacts, and flag drift against code. |
Ln Sync
Audit and refresh the canonical documents so they stay lightweight enough for fast re-entry.
ln-sync is the family-wide ontology repair and garbage-collection pass. Merge equivalent facts, repair stale references, and delete exhausted derivative artifacts. Only docs/archive/PLAN_HISTORY.md acts as archive history.
Apply the repo's pre-release posture: optimize canonical memory for the model we now believe in, not compatibility with stale docs. Retire superseded claims, delete obsolete derivative artifacts, and tighten lexicon drift instead of preserving historical aliases in active truth.
When to run
Prefer ln-sync at these moments:
- milestone boundaries
- before major refactors
- at handoff / context compaction
- when
memory/SPEC.md or memory/PLAN.md feels overweight
Document roles
| File | Authority | Keep live |
|---|
memory/SPEC.md | what and why | product contract, live architecture register, future direction pointers, lexicon, verification stance |
memory/PLAN.md | what's next | sequencing, frontier definitions, near-horizon items, recent completions |
docs/archive/PLAN_HISTORY.md | historical ledger | older completed phases and retired plan history |
HANDOFF.md | derivative volatile transfer | only unfinished chat state not yet reconciled |
memory/CARDS.md | derivative execution queue | only unfinished prepared scope cards inside one frontier item |
memory/REFACTOR.md | derivative temporary execution plan | only unfinished refactor steps |
Procedure
1. Read the current docs
If either memory/SPEC.md or memory/PLAN.md is missing, route to ln-spec or ln-plan first.
2. Weight check
Ask whether each file is still serving re-entry.
- If
memory/SPEC.md is carrying embedded truths, old implementation detail, closed historical debates, or validated assumptions that no longer shape frontier work, prune it.
- If
memory/PLAN.md is mostly completed history, collapse it to a rolling frontier and archive the rest.
- If
HANDOFF.md, memory/CARDS.md, or memory/REFACTOR.md no longer carry live temporary state, delete them.
3. SPEC pass — keep only live architecture
Use the mature SPEC shape as the target unless the project has an explicit alternate shape:
- Product Contract — concept, constraints / non-goals, grouped capability requirements.
- Live Architecture Register — open assumptions, active decisions, critical invariants.
- Future Direction Register — directional bets with PLAN/design-doc pointers.
- Compact model / architecture sections only while they still serve as SPEC authority.
- Lexicon and Verification Design.
For each item in memory/SPEC.md, choose one:
- keep live — still unresolved or still constrains future work
- update — wording / evidence / scope changed
- compress / merge — overlaps another live row or carries too much rationale
- retire embedded — fully shipped and now protected by code/tests/design docs
- move rationale — valuable context, but too detailed for SPEC; keep a short guardrail and link to a design doc
- future direction — not current product contract; move under Future Direction Register or ensure PLAN owns it
- remove — moot, superseded, redundant, or implementation diary
Keep in SPEC
- stable product contract
- constraints and non-goals
- capability requirements
- open assumptions only
- current spine decisions and durable seam-defining decisions
- critical seam-level invariants only
- future direction pointers that shape sequencing
- lexicon
- verification stance / commands / blind spots
Remove from SPEC
- implementation diary entries
- historical completion notes already reflected in code or tests
- micro-variant decisions / invariants that are embedded in a larger seam
- validated assumptions that no longer change future work
- detailed design-doc prose, card styling minutiae, or exhaustive test inventories
- future acceptance criteria that PLAN should own until the work is active
Validated assumptions retire by default. Promote the durable residue only when it still constrains active work: product facts go to Product Contract, architectural authority goes to Active Decisions / Critical Invariants, vocabulary goes to Lexicon, and sequencing implications go to PLAN.
Do not remove durable seam rationale merely because code and tests now exist. Prune micro-decisions, not the architectural spine.
Merge equivalent assumptions, decisions, and invariants instead of carrying parallel rows for the same seam-level fact. When rows merge or move, repair the references that point at them.
When pruning, leave concise HTML comments naming removed IDs when useful. Do not renumber survivors.
4. PLAN pass — restore the rolling frontier
Prefer the conflict-resistant mature shape:
ContextSequencing
ActiveNextParallel / Low-conflictHorizon
Frontier DefinitionsRecently CompletedDependencies
Rules:
- treat frontier items as the canonical plan/Linear/branch units
- treat slices as scoped execution units from
ln-scope / ln-build, usually inside one frontier item
- edit
Sequencing for ordering/status churn; do not move or rewrite Frontier Definitions merely to reorder work
- keep detailed scope-card queues out of
memory/PLAN.md; use memory/CARDS.md for temporary slice execution queues and at most a lightweight pointer from the frontier definition
- move older completed items to
docs/archive/PLAN_HISTORY.md
- keep only the last 2-3 completed items live
- only active / next frontier definitions need detailed acceptance or traceability
- keep dependency diagrams limited to active / next frontier ids
- keep enough
Why now / unlocks context that a fresh thread can understand frontier ordering without reading the full archive
- do not archive handoffs, refactor plans, or sync reports
5. Drift and ontology check
Scan recent code / commits for:
- new domain concepts not reflected in the lexicon
- durable decisions not reflected in
memory/SPEC.md
- active work not represented in
memory/PLAN.md sequencing or frontier definitions
- stale references between
memory/PLAN.md and memory/SPEC.md, especially PLAN links to retired assumptions / decisions / invariants
- equivalent facts that should merge instead of coexisting
- prepared cards in
memory/CARDS.md that should be retired, re-scoped, or reconciled into the next thread's live state
- stale derivative artifacts that should be deleted after reconciliation
6. Garbage-collect derivative artifacts
Delete exhausted temporary artifacts after their useful state has been reconciled:
- remove stale
HANDOFF.md files instead of preserving them as archive breadcrumbs
- remove exhausted
memory/CARDS.md queues instead of letting old prepared cards masquerade as live work
- remove completed
memory/REFACTOR.md files instead of leaving completion notes or pointers
- if an ad hoc planning/status file was created with explicit permission and is now exhausted, reconcile any durable facts, then delete it unless the user asked to keep it
7. Report and update
Produce a concise sync report and make the edits.
## Sync Report
### Pruned
- [items removed, merged, or moved and why]
### Archived
- [history moved to PLAN_HISTORY.md]
### Garbage-collected
- [temporary artifacts deleted and why]
### Drift fixed
- [concept / decision / frontier / traceability updates made]
### Retirement assessment
- [whether embedded items were sufficiently retired, or whether a stronger protocol / follow-up frontier is needed]
### Remaining live items
- [important assumptions or frontier work that still matter]
Routing
After sync, present these options to the user (use tool-ask-question):
| # | Label | Target | Why |
|---|
| 1 | Scope next item | ln-scope | Docs are current and the next slice is ready |
| 2 | Revisit the plan | ln-plan | Sync changed priorities or exposed new frontier work |
| 3 | Back to triage | ln-consult | Direction needs reassessment |
Recommended: 1 if the frontier is still sound, 2 if sync materially changed it.
