Fix init lane collisions and refresh eventness docs

Author: marcnulu

README.CORE.EVENTNESS.md

@@ -35,6 +35,15 @@ Short version:
 - routing is prefix/base-driven
 - attention is suffix-driven
 
+Operational repo shape often looks like:
+
+`<prefix>.<base>.<suffix>[.<eventness>][.<ext>]`
+
+In practice:
+- `suffix` is usually the durable artifact or lane anchor
+- the extra right-hand eventness chain expands or collapses current interest
+- `.ext` is optional; most files have one, some do not
+
 ---
 
 ## Meaning of Each Part
@@ -93,6 +102,58 @@ This avoids hardcoding base depth.
 
 ---
 
+## Operational Lifecycle
+
+This repo uses eventness as a recurring pattern:
+
+### 1) Expansion
+
+When interest is live, expand around a stable subject:
+
+`prefix.base.suffix[.expanding.eventness][.ext]`
+
+Examples:
+- `main.command.trace-id.test.todo.current.md`
+- `main.command.trace-id.test.todo.current.reference.md`
+- `main.command.trace-id.test.todo.trigger.event.md`
+
+Expanded files can hold:
+- resume context
+- hypotheses
+- exact `recur` commands to run next
+- references to related files or lanes
+
+### 2) Interest Discovery
+
+During expansion, use `recur` commands to discover what is actually interesting now.
+The files do not replace query-time discovery; they improve it.
+
+Typical loop:
+- `recur files "**.current" -d docs/`
+- `recur files "**.trigger.event" -d docs/`
+- `recur tree "main" --sep . --sep _ --show-sep`
+- `recur find "<symbol-or-text>" --scope "**" -d src/`
+
+This is why eventness works well with humans and LLMs: the repo stores both the current state and the next useful queries.
+
+### 3) Collapse
+
+Once the interest has paid off, collapse the expanded state:
+
+`prefix.base.suffix[.collapsing.eventness][.ext]`
+
+Typical outcomes:
+- keep a stable completion record: `*.complete.*`
+- keep a lower-intensity reminder: `*.future-plan.*`
+- keep a durable rediscovery point: `*.recurring.*`
+- remove the ephemeral file entirely when no residue is worth keeping
+
+### 4) Recurring Rediscovery
+
+`recurring` is apt when the value is not "this is active now" but "this workflow or pattern should be easy to find again later."
+
+---
+
 ## Eventness Score
 
 Eventness is a ranking score for "what should get attention now."
@@ -102,7 +163,7 @@ Suggested formula:
 `eventness = suffix_weight + prefix_prior + freshness + impact + anomaly_bonus`
 
 Where:
-- `suffix_weight`: strongest signal (blocked > current > todo > complete)
+- `suffix_weight`: strongest signal (blocked > current > todo > recurring > complete)
 - `prefix_prior`: domain urgency prior (`ops` may outrank `research`)
 - `freshness`: time decay / staleness
 - `impact`: downstream references, dependency fan-out
@@ -121,6 +182,7 @@ You can detect useful surprises even when not explicitly planned.
 Examples:
 - new suffix pattern appears (`todo.blocker`, `risk.critical`) not in policy
 - missing expected suffix chain (`todo` exists, `todo.current` missing)
+- expanded eventness never collapsed after the interest window closed
 - sudden rise in refs/callers around one base
 - new prefix/base combination with no historical pattern
 
@@ -146,7 +208,9 @@ This model supports both layers from IMPROVEMENT9:
 
 - `main.command.tree.todo.current`
 - `main.command.tree.todo.trigger.event`
+- `main.command.trace-id.test.todo.current.reference`
 - `main.command.checkpoint.todo.next`
+- `main.package.crates-io.recurring`
 - `ops.incident.auth.outage.todo.blocker`
 - `release.v2_3.rc1.risk.high`
 
@@ -168,6 +232,11 @@ recur files "main.command.*.todo.trigger.event" -d docs/
 recur files "main_command_*_todo_trigger_event" -d src/ --sep _
 ```
 
+### Recurring rediscovery (today)
+```bash
+recur files "**.recurring" -d docs/
+```
+
 ### Interest extraction (IMPROVEMENT9 target)
 ```bash
 recur files "main.command.**" -d docs/ \
@@ -209,8 +278,9 @@ Then resolve IDs to files with existing file-layer commands and pull detailed co
 3. Resolve selected IDs to files (`recur files ...`) and extract suffix-bearing IDs (interest signals).
 4. Rank by eventness.
 5. Execute required triggers.
-6. Run recurring completion checklist items (update docs, commit, push).
-7. Rotate current lane.
+6. Collapse the expanded eventness to the right durable residue.
+7. Run recurring completion checklist items (update docs, commit, push).
+8. Rotate current lane.
 
 Humans and LLMs should run the same loop over the same semantic list plus resolved file context.
 
@@ -223,7 +293,8 @@ Keep this lightweight:
 1. Maintain a suffix policy map (suffix -> weight/severity).
 2. Enforce one active `*.todo.current` per lane.
 3. Require `*.todo.trigger.event` for recurring start/complete workflows.
-4. Run drift checks (missing suffix chains, unresolved refs).
+4. Collapse stale expanded eventness once the interest window closes.
+5. Run drift checks (missing suffix chains, unresolved refs).
 
 ---
 

README.md

@@ -575,6 +575,7 @@ The tribute is also personal. I had the chance to speak with Dennis Ritchie brie
 
 - [Full Tribute](RECUR-TRIBUTE.md) — the Dennis Ritchie note  
 - [White Paper](docs/recur.white.paper.docx) — design and philosophy
+- [Eventness Explained](docs/eventness_explained_whitepaper.docx) - eventness explained in equation form
 - [Proposal](RECUR-PROPOSAL.md) — technical design  
 - [Contributing](CONTRIBUTING.md) — how to contribute  
 - [Implementation](IMPLEMENTATION-COMPLETE.md) — code walkthrough  

docs/eventness_explained_whitepaper.docx

@@ -12,8 +12,8 @@ recur related "main.command.config.trait" -d docs/ --sep .
 
 ## Commands
 
-main.command.config.trait — list/get/set trait parameters in `.recur/config.toml`
-main.command.config.init — initialize `.recur/` directory with full default config
+main.command.config.trait - list/get/set trait parameters in `.recur/config.toml`
+main.command.config.init - initialize `.recur/` directory with full default config
 
 ## trait
 
@@ -27,19 +27,27 @@ recur trait set trace_id.producer_keywords "publish,emit"    # write a value
 ```
 
 Current trait sections:
-- `[traits.trace_id]` — keyword vocabulary for trace-id classification
-- `[traits.traversal_budget]` — depth cap and guardrail defaults
+- `[traits.content_search]` - file-size and binary-file policy for content search commands
+- `[traits.separator_merge]` - merge-specific project policy lane
+- `[traits.stdin]` - stdin path resolution and missing-path policy
+- `[traits.trace_id]` - keyword vocabulary for trace-id classification
+- `[traits.traversal_budget]` - depth cap and guardrail defaults
 
 ## init
 
 `recur init` scaffolds the `.recur/` directory with:
-- `config.toml` — full default config including all `[traits.*]` sections
+- `config.toml` - full default config including all `[traits.*]` sections
 - Ready for `recur trait set` customization per project
+- Deduplicated lane section names when different directories normalize to the same key
 
 ## References
 
 - `docs/main.command.trait.readme.md`
 - `docs/main.command.init.readme.md`
+- `docs/main.command.init.lane-name-collision.complete.md`
 - `docs/main.command.map.readme.md`
+- `julia-tests/main.command.init.test.jl`
+- `julia-tests/main.command.trait.test.jl`
+- `src/main_command_init_impl.rs`
 - `src/main_command_trait_impl.rs`
 - `src/trait/trace_id.rs`

docs/main.command.config.readme.md

@@ -0,0 +1,39 @@
+# Command: init lane-name collision handling - Complete
+
+Status: `complete`
+Date: 2026-04-04
+
+## What Landed
+
+`recur init` now deduplicates generated lane section names when two directories
+normalize to the same config key.
+
+Example collision:
+
+- `test-quick/`
+- `test_quick/`
+
+Both normalize to `test-quick`. Before this fix, `recur init --force` could emit
+duplicate TOML sections and leave `.recur/config.toml` unparsable. Now the later
+lane is suffixed (`test-quick-2`, `test-quick-3`, and so on) so the generated
+config remains valid and `recur trait` can read it immediately.
+
+## Docs + Test Surface
+
+- `docs/main.command.init.readme.md` updated with lane-name collision behavior
+- `docs/main.command.config.readme.md` updated to reflect the full trait surface
+- `julia-tests/main.command.init.test.jl` added as the command-level wrapper
+- `julia-tests/runtests.init.jl` added for init CLI, analyze-mode, and collision coverage
+
+## Evidence
+
+- `cargo test project_config -- --nocapture`
+- `julia julia-tests/main.command.init.test.jl`
+
+## Files
+
+- `src/project_config.rs`
+- `docs/main.command.init.readme.md`
+- `docs/main.command.config.readme.md`
+- `julia-tests/main.command.init.test.jl`
+- `julia-tests/runtests.init.jl`

docs/main.command.init.lane-name-collision.complete.md

@@ -15,6 +15,23 @@ recur init
 Creates:
 - `.recur/config.toml` with detected lanes (for example `src/`, `docs/`, `julia-tests/`)
 - `.recur/checkpoints.md` (if missing)
+- all default `[traits.*]` sections used by `recur trait`
+
+Generated lane names are normalized to lowercase kebab-case section names.
+If two directories collapse to the same normalized lane name, `recur init`
+appends a numeric suffix so the generated TOML stays valid.
+
+Example:
+
+```toml
+[test-quick]
+dir = "test-quick/"
+sep = "-"
+
+[test-quick-2]
+dir = "test_quick/"
+sep = "."
+```
 
 ## Analyze mode
 
@@ -52,3 +69,13 @@ recur files "main_command_**" -d src/ --count
 ```
 
 works without explicitly passing `--sep _` when `src/` is mapped to `_` in config.
+
+## Testing
+
+- `julia-tests/main.command.init.test.jl` - command-level wrapper for init CLI coverage
+- `julia-tests/runtests.init.jl` - init command contract, analyze mode, and collision tests
+
+## Related
+
+- `docs/main.command.config.readme.md`
+- `docs/main.command.init.lane-name-collision.complete.md`

docs/main.command.init.readme.md

@@ -1,4 +1,4 @@
-# Command: trait — Complete
+# Command: trait - Complete
 
 Status: `complete`
 Date: 2026-03-06
@@ -17,15 +17,15 @@ to a first-class `Commands::Trait` enum variant in `main.rs`.
 
 ## Files Changed
 
-- `src/main_command_trait_impl.rs` — pub TraitSubcommand, new execute(), removed side-channel
-- `src/main.rs` — Trait variant in Commands enum, match arm, after_help updated
-- `docs/main.command.trait.readme.md` — created (permanent docs)
-- `docs/main.improvement.8.trace-id.todo.current.md` — corrected deferred/implemented status
+- `src/main_command_trait_impl.rs` - pub TraitSubcommand, new execute(), removed side-channel
+- `src/main.rs` - Trait variant in Commands enum, match arm, after_help updated
+- `docs/main.command.trait.readme.md` - created (permanent docs)
+- `docs/main.improvement.8.trace-id.todo.current.md` - corrected deferred/implemented status
 
 ## Test Baseline
 
 - Rust: 120 passed, 0 failed
-- Julia trait tests: `julia-tests/runtests.trait.jl` — CLI contract + traversal budget passing,
+- Julia trait tests: `julia-tests/main.command.trait.test.jl` - CLI contract + traversal budget passing,
   `traversal_budget.min_depth` correctly marked `@test_broken` (future work)
 
 ## Related

docs/main.command.trait.complete.md

@@ -19,8 +19,10 @@ That gives the hierarchy room to add a base, suffix, and eventness cleanly over
 
 Useful mental models:
 
-- `prefix.base.suffix.[eventness-expanded].[ext]`
-- `prefix.base.suffix.[eventness-collapsed].[ext]`
+- `prefix.base.suffix[.expanding.eventness][.ext]`
+- `prefix.base.suffix[.collapsing.eventness][.ext]`
+
+`.ext` is optional. Most files in this repo have one; some do not.
 
 Examples in this repo:
 
@@ -40,11 +42,24 @@ Treat it as a visible marker of interest:
 
 - stable identity lives in `prefix.base.suffix`
 - expanded eventness carries live working context
+- during expansion, use `recur` commands to discover what is interesting and store exact `recur` commands inside the eventness files when that helps resume work
 - collapsed or closed eventness keeps only the amount of signal that still matters
+- collapse usually ends in `complete`, `future-plan`, `recurring`, or full removal of the ephemeral file
+
+## Recurring Lifecycle
+
+Treat eventness as a recurring operating pattern:
+
+1. Expand interest around a stable subject.
+2. Use `recur` commands to discover the next useful questions and commands.
+3. Store those commands in the expanded eventness files when they improve rediscovery.
+4. Collapse once the interest window closes.
+5. Keep only the durable residue that still matters, or remove the file entirely.
 
 ## Eventness Reminder
 
-`recurring` is a valid rediscovery/eventness concept, but most work in this repo is non-recurring improvement work.
+`recurring` is a valid rediscovery/eventness concept, and it is also a good collapsed form when the useful outcome is "remember this pattern next time."
+Most work in this repo is still non-recurring improvement work.
 In practice, expect more files like `todo`, `current`, `complete`, `future-plan`, `reference`, and `trigger.event` than `recurring`.
 
 Use `recurring` when you want a durable "remember this workflow next time" rediscovery point.
@@ -62,8 +77,28 @@ In practice:
 - Use `complete` docs for baseline/history, not for deciding what is left
 - If a feature branch has already been merged, the remaining work usually lives in the `current` improvement and test lanes, not in the old feature branch name itself
 
+## Fast Rehydration Order
+
+When training Skippy or another LLM back into this repo, rehydrate in this order:
+
+1. `docs/eventness_explained_whitepaper.docx` for the deeper eventness theory and equation framing.
+2. `README.CORE.EVENTNESS.md` for the operational model used in this repo.
+3. `docs/main.recur.expert.recurring.md` for the repo-specific rediscovery rules.
+4. `julia-expert/references/recur-playbook.md` for the concrete command workflow.
+
+Then switch from reading to query-time discovery:
+
+```powershell
+recur files "**.current" -d docs/
+recur files "**.recurring" -d docs/
+recur files "**.reference" -d docs/
+recur tree "main" --sep . --sep _ --show-sep
+```
+
 ## Canonical references
 
+- `docs/eventness_explained_whitepaper.docx` - deeper eventness theory and equation framing
+- `README.CORE.EVENTNESS.md` - operational eventness model for this repo
 - `julia-expert/references/recur-playbook.md` - canonical prompt/playbook
 - `docs/AGENT.PROMPT.recur-expert.md` - pointer to canonical prompt
 - `ulu_docs/recur-agent.md` - supplemental older agent notes