Add mistake recovery, diff, grep, force push; lock the store; version the format

reset unstages or moves the branch; amend rewrites the head commit;
rebase replays a branch, preserving every entry. diff compares the
intent on two refs and grep searches it. add -F records intent from a
file or stdin. push --force rewrites a remote branch after a local
rewrite (the transport carries ?force=1). A lockfile serializes
concurrent writers, refs write atomically, and .lore/version stamps
the on-disk format. Agent rules now forbid recording secrets.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: raymondjacobson

README

@@ -91,6 +91,34 @@ use
         lore materialize --ref experiment
         lore materialize --ref 4b6f04 -o BRIEF.txt
 
+        long or quoted intent reads from a file, or stdin with "-":
+
+        lore add -F prompt.txt
+        git log -1 --format=%B | lore add -F -
+
+        made a mistake?  unstage it, rewrite the last commit, or move
+        the branch.  objects are never deleted, so nothing is lost:
+
+        lore reset                         unstage everything
+        lore reset <id>                    unstage one entry by id prefix
+        lore reset --to <commit>           point the branch elsewhere
+        lore amend -m "better summary"     fold staged intent into HEAD
+        lore rebase main                   replay this branch onto main
+
+        rewrite before you push when you can.  remotes only fast-forward,
+        so pushing rewritten history is refused unless you force it:
+
+        lore push --force                  rewrite the remote branch
+
+        force-push only branches you own, and tell collaborators: their
+        next pull merges the old history back unless they reset to the
+        rewritten branch.
+
+        read the history without materializing all of it:
+
+        lore diff main experiment          intent on one side, not the other
+        lore grep "rate limit"             search intent, case-insensitive
+
 
 example
         a worked example: an agent builds a feature from intent alone.
@@ -104,6 +132,8 @@ storage
         HEAD            current branch
         config          identity and named remotes
         index           staged intent, not yet committed
+        version         on disk format version
+        lock            held briefly during writes; delete if stale
         objects/<id>    content addressed entries and commits
         refs/heads/<b>  branch pointers
         refs/remotes/   last-known commit on each remote branch
@@ -130,7 +160,7 @@ remotes
 
         a remote url is a filesystem path or a lorehub url (see below).
         push sends only the objects the remote lacks, then moves the
-        ref, and must fast-forward.
+        ref, and must fast-forward unless forced (lore push --force).
 
         identity is a git-style name and email, recorded on every entry
         and commit so a server can attribute work.  set it with lore
@@ -168,11 +198,19 @@ agents
             durable rules for how the project works, not one-off bug
             reports or anything personal.  it is cheap, do it often.
 
-        2.  commit related intent once a unit of work lands:
+        2.  never record secrets.  no api keys, tokens, passwords, or
+            private personal details.  repositories get shared and
+            history is permanent.  paraphrase around the secret ("auth
+            uses the stripe key from the environment") instead of
+            quoting it.  staged something sensitive?  remove it with
+            lore reset before you commit.  already pushed?  rotate the
+            secret; history will not forget it.
+
+        3.  commit related intent once a unit of work lands:
 
                 lore commit -m "short summary"
 
-        3.  to rebuild, materialize and reconcile the tree to the brief.
+        4.  to rebuild, materialize and reconcile the tree to the brief.
             do not commit the brief.
 
         new to lore?  the full guide is at https://lorevcs.com.

src/cli.rs

@@ -9,7 +9,7 @@ use anyhow::{bail, Result};
 use clap::{Parser, Subcommand};
 
 use crate::config::{Identity, Remote};
-use crate::repo::{short, Merge, Repo};
+use crate::repo::{short, Merge, Rebase, Repo};
 use crate::sync::Push;
 
 #[derive(Parser)]
@@ -30,8 +30,11 @@ pub enum Command {
     /// Stage a unit of intent (a prompt, note, or decision)
     Add {
         /// The intent text
-        #[arg(required = true, num_args = 1.., value_name = "TEXT")]
+        #[arg(num_args = 1.., value_name = "TEXT", required_unless_present = "file")]
         text: Vec<String>,
+        /// Read the intent from a file instead; "-" reads stdin
+        #[arg(short = 'F', long, conflicts_with = "text")]
+        file: Option<PathBuf>,
         /// Override the recorded author name
         #[arg(short, long)]
         author: Option<String>,
@@ -50,6 +53,25 @@ pub enum Command {
         #[arg(short, long)]
         email: Option<String>,
     },
+    /// Unstage intent, or move the current branch with --to
+    Reset {
+        /// Staged entry ids (prefixes) to unstage; all of them if omitted
+        ids: Vec<String>,
+        /// Move the current branch to this commit instead of unstaging
+        #[arg(long, value_name = "REF", conflicts_with = "ids")]
+        to: Option<String>,
+    },
+    /// Rewrite the last commit, folding in staged intent or a new message
+    Amend {
+        #[arg(short, long)]
+        message: Option<String>,
+        #[arg(short, long)]
+        author: Option<String>,
+        #[arg(short, long)]
+        email: Option<String>,
+    },
+    /// Replay this branch's commits on top of another branch
+    Rebase { branch: String },
     /// Show commit history, newest first
     Log,
     /// Show a commit's full message and the intent it recorded
@@ -77,6 +99,16 @@ pub enum Command {
         #[arg(short, long)]
         email: Option<String>,
     },
+    /// Show intent that differs between two refs
+    Diff {
+        /// The base ref
+        a: String,
+        /// The other ref
+        #[arg(default_value = "HEAD")]
+        b: String,
+    },
+    /// Search intent for a pattern, case-insensitively
+    Grep { pattern: String },
     /// Render accumulated intent into a brief an agent can rebuild from
     Materialize {
         /// Branch or commit to materialize
@@ -92,6 +124,9 @@ pub enum Command {
     Push {
         remote: Option<String>,
         branch: Option<String>,
+        /// Rewrite the remote branch after amend, rebase, or reset --to
+        #[arg(short, long)]
+        force: bool,
     },
     /// Download remote intent into tracking refs (default: origin)
     Fetch { remote: Option<String> },
@@ -136,12 +171,18 @@ pub fn run(cli: Cli, cwd: &Path) -> Result<()> {
         }
         Command::Add {
             text,
+            file,
             author,
             email,
         } => {
             let repo = Repo::discover(cwd)?;
             let who = identity(&repo, author, email)?;
-            let id = repo.add(&who, &text.join(" "), now())?;
+            let text = match file {
+                Some(p) if p.as_os_str() == "-" => std::io::read_to_string(std::io::stdin())?,
+                Some(p) => std::fs::read_to_string(&p)?,
+                None => text.join(" "),
+            };
+            let id = repo.add(&who, &text, now())?;
             println!("staged {}", short(&id));
         }
         Command::Status => {
@@ -170,6 +211,41 @@ pub fn run(cli: Cli, cwd: &Path) -> Result<()> {
             let id = repo.commit(&who, &message, now())?;
             println!("committed {} {message}", short(&id));
         }
+        Command::Reset { ids, to } => {
+            let repo = Repo::discover(cwd)?;
+            match to {
+                Some(reference) => {
+                    let id = repo.reset_to(&reference)?;
+                    println!("{} is now at {}", repo.current_branch()?, short(&id));
+                }
+                None => {
+                    let n = repo.reset(&ids)?;
+                    println!("unstaged {n} {}", if n == 1 { "entry" } else { "entries" });
+                }
+            }
+        }
+        Command::Amend {
+            message,
+            author,
+            email,
+        } => {
+            let repo = Repo::discover(cwd)?;
+            let who = identity(&repo, author, email)?;
+            let id = repo.amend(&who, message.as_deref(), now())?;
+            println!("amended {}", short(&id));
+        }
+        Command::Rebase { branch } => {
+            let repo = Repo::discover(cwd)?;
+            match repo.rebase(&branch)? {
+                Rebase::UpToDate => println!("already up to date"),
+                Rebase::FastForward(id) => println!("fast-forward to {}", short(&id)),
+                Rebase::Rebased { tip, replayed } => println!(
+                    "replayed {replayed} {} onto {branch}; now at {}",
+                    if replayed == 1 { "commit" } else { "commits" },
+                    short(&tip)
+                ),
+            }
+        }
         Command::Log => {
             let repo = Repo::discover(cwd)?;
             let commits = repo.log()?;
@@ -239,6 +315,40 @@ pub fn run(cli: Cli, cwd: &Path) -> Result<()> {
                 Merge::Merged(id) => println!("merged into {}", short(&id)),
             }
         }
+        Command::Diff { a, b } => {
+            let repo = Repo::discover(cwd)?;
+            let (only_a, only_b) = repo.diff(&a, &b)?;
+            if only_a.is_empty() && only_b.is_empty() {
+                println!("no intent differs between {a} and {b}");
+            }
+            let mut rows: Vec<(char, String, crate::object::Entry)> = only_a
+                .into_iter()
+                .map(|(id, e)| ('-', id, e))
+                .chain(only_b.into_iter().map(|(id, e)| ('+', id, e)))
+                .collect();
+            rows.sort_by(|x, y| x.2.timestamp.cmp(&y.2.timestamp).then(x.1.cmp(&y.1)));
+            for (sign, id, e) in rows {
+                println!("{sign} {} {}", short(&id), oneline(&e.text));
+            }
+        }
+        Command::Grep { pattern } => {
+            let repo = Repo::discover(cwd)?;
+            let needle = pattern.to_lowercase();
+            for (id, e) in repo.grep(&pattern)? {
+                let line = e
+                    .text
+                    .lines()
+                    .find(|l| l.to_lowercase().contains(&needle))
+                    .unwrap_or("")
+                    .trim();
+                println!(
+                    "{} {} {}: {line}",
+                    short(&id),
+                    crate::time::format_ns(e.timestamp),
+                    e.author.label()
+                );
+            }
+        }
         Command::Materialize { reference, out } => {
             let repo = Repo::discover(cwd)?;
             let brief = repo.materialize(&reference, now())?;
@@ -259,17 +369,22 @@ pub fn run(cli: Cli, cwd: &Path) -> Result<()> {
             crate::sync::clone(&url, &target, token())?;
             println!("cloned {url} into {}", target.display());
         }
-        Command::Push { remote, branch } => {
+        Command::Push {
+            remote,
+            branch,
+            force,
+        } => {
             let repo = Repo::discover(cwd)?;
             let remote = remote.unwrap_or_else(|| "origin".into());
             let branch = match branch {
                 Some(b) => b,
                 None => repo.current_branch()?,
             };
-            match crate::sync::push(&repo, &remote, &branch)? {
+            match crate::sync::push(&repo, &remote, &branch, force)? {
                 Push::UpToDate => println!("everything up to date"),
                 Push::Pushed { objects } => {
-                    println!("pushed {branch} to {remote} ({objects} objects)")
+                    let verb = if force { "force-pushed" } else { "pushed" };
+                    println!("{verb} {branch} to {remote} ({objects} objects)")
                 }
             }
         }
@@ -413,8 +528,51 @@ mod tests {
     }
 
     #[test]
-    fn add_requires_text() {
+    fn parses_diff_with_default_and_grep() {
+        match Cli::try_parse_from(["lore", "diff", "main"])
+            .unwrap()
+            .command
+        {
+            Command::Diff { a, b } => {
+                assert_eq!(a, "main");
+                assert_eq!(b, "HEAD");
+            }
+            _ => panic!("wrong command"),
+        }
+        match Cli::try_parse_from(["lore", "diff", "main", "exp"])
+            .unwrap()
+            .command
+        {
+            Command::Diff { a, b } => {
+                assert_eq!(a, "main");
+                assert_eq!(b, "exp");
+            }
+            _ => panic!("wrong command"),
+        }
+        assert!(Cli::try_parse_from(["lore", "diff"]).is_err());
+        match Cli::try_parse_from(["lore", "grep", "rate limit"])
+            .unwrap()
+            .command
+        {
+            Command::Grep { pattern } => assert_eq!(pattern, "rate limit"),
+            _ => panic!("wrong command"),
+        }
+    }
+
+    #[test]
+    fn add_requires_text_or_file() {
         assert!(Cli::try_parse_from(["lore", "add"]).is_err());
+        assert!(Cli::try_parse_from(["lore", "add", "text", "-F", "f.md"]).is_err());
+        match Cli::try_parse_from(["lore", "add", "-F", "-"])
+            .unwrap()
+            .command
+        {
+            Command::Add { text, file, .. } => {
+                assert!(text.is_empty());
+                assert_eq!(file.unwrap().as_os_str(), "-");
+            }
+            _ => panic!("wrong command"),
+        }
     }
 
     #[test]
@@ -431,6 +589,44 @@ mod tests {
         }
     }
 
+    #[test]
+    fn parses_reset_variants() {
+        match Cli::try_parse_from(["lore", "reset"]).unwrap().command {
+            Command::Reset { ids, to } => {
+                assert!(ids.is_empty());
+                assert!(to.is_none());
+            }
+            _ => panic!("wrong command"),
+        }
+        match Cli::try_parse_from(["lore", "reset", "--to", "abc"])
+            .unwrap()
+            .command
+        {
+            Command::Reset { to, .. } => assert_eq!(to.as_deref(), Some("abc")),
+            _ => panic!("wrong command"),
+        }
+        // unstaging ids and moving the branch are mutually exclusive
+        assert!(Cli::try_parse_from(["lore", "reset", "abc", "--to", "def"]).is_err());
+    }
+
+    #[test]
+    fn parses_amend_and_rebase() {
+        match Cli::try_parse_from(["lore", "amend", "-m", "better"])
+            .unwrap()
+            .command
+        {
+            Command::Amend { message, .. } => assert_eq!(message.as_deref(), Some("better")),
+            _ => panic!("wrong command"),
+        }
+        match Cli::try_parse_from(["lore", "rebase", "main"])
+            .unwrap()
+            .command
+        {
+            Command::Rebase { branch } => assert_eq!(branch, "main"),
+            _ => panic!("wrong command"),
+        }
+    }
+
     #[test]
     fn materialize_defaults_to_head() {
         let cli = Cli::try_parse_from(["lore", "materialize"]).unwrap();
@@ -443,6 +639,21 @@ mod tests {
         }
     }
 
+    #[test]
+    fn parses_push_force() {
+        match Cli::try_parse_from(["lore", "push"]).unwrap().command {
+            Command::Push { force, .. } => assert!(!force),
+            _ => panic!("wrong command"),
+        }
+        match Cli::try_parse_from(["lore", "push", "--force"])
+            .unwrap()
+            .command
+        {
+            Command::Push { force, .. } => assert!(force),
+            _ => panic!("wrong command"),
+        }
+    }
+
     #[test]
     fn parses_clone_with_optional_dir() {
         let cli = Cli::try_parse_from(["lore", "clone", "https://lorehub.com/r"]).unwrap();