lukeed/lane/assets

lane

This repository keeps durable context / memories as Markdown under .lane/. You must read before editing a file, via lane why <path>, then record only the non-obvious constraints or decisions another agent would otherwise have to rediscover.

Workflow

lane new fix-login     # create a branch and worktree
# edit and commit as usual
lane merge             # land on local trunk
lane merge --squash    # land on local trunk as one commit
lane push              # push the lane for a pull request

lane new prints the worktree path. Work there, not in the parent checkout.

lane merge rebases, audits memory, updates local trunk, and removes the lane. Commit or stash tracked changes first.

The push workflow is for protected trunks. After the pull request merges, run lane prune. Use lane ls --json for machine-readable lane state.

Read before editing

lane why src/auth.rs
lane why src/

Run lane why for every file you intend to edit. A directory returns all notes beneath it; --json includes full ids, anchors, timestamps, and note text.

Run lane check before landing. For every stale note, take exactly one action:

lane note confirm <id>              # the note is still true
lane note replace <id> "<rewrite>"  # the constraint has changed
lane note retire <id>               # the constraint no longer applies

An unambiguous id prefix is enough. Use lane note edit <id> for the interactive menu, or the direct commands above in scripts and agent workflows.

Other lifecycle commands:

lane note restore <id>  # restore a retired note
lane note pin <id>      # protect a note from eviction
lane note unpin <id>    # remove that protection

Record what must stay true

Not every file or commit needs a note. Only record significant, non-obvious constraints — never a summary of the change.

Commit Message Trailer(s)

If lane install hooks has been run, then git hooks are active and you can add notes while writing commit messages. Include a Why: trailer when the finding belongs with a commit:

make verification constant-time
 
Why: src/auth.rs#fn verify | early return leaks token length

The form is Why: <path>[#<anchor>] | <text>. The path and | separator are required; omit the anchor to target the whole file.

Run lane install hooks once if trailers are not being captured.

Manually

Record a finding directly when it does not belong to a commit, or if lane install hooks has not been run:

lane note add src/auth.rs -a "fn verify" "must stay constant-time"

Supplying text is non-interactive and defaults to @file when -a is omitted. Omit the text only when you want the interactive prompt.

Anchors

An anchor describes what a note is about:

Run lane anchors <path> --json and prefer the canonical anchor it returns. Ambiguous declaration names are refused with their available choices.

Rules

• Never edit .lane/ by hand; use the lane note commands.
• Do not pass --dirty unless the lane should inherit the parent checkout's uncommitted work.
• Keep each note to one constraint.
• Do not record what a commit changed.

Run lane --help for the command list, or lane <command> --help for details.