feat: add review-only mutation candidates (#9)

Author: karngyan

.mise.toml

@@ -30,5 +30,5 @@ description = "Run the pull-request quality gate"
 depends = ["ci", "docs", "fmt", "lint", "test"]
 
 [tasks.demo]
-description = "Run the offline Milestone 1 import-to-digest demonstration"
+description = "Run the offline import-to-mutation-candidate demonstration"
 run = "scripts/demo-milestone-1.sh"

Cargo.lock

@@ -7,6 +7,7 @@ members = [
   "crates/autophagy-cli",
   "crates/autophagy-core",
   "crates/autophagy-events",
+  "crates/autophagy-mutations",
   "crates/autophagy-patterns",
   "crates/autophagy-redaction",
   "crates/autophagy-store",
@@ -24,6 +25,7 @@ clap = { version = "4.6.2", features = ["derive", "env"] }
 directories = "6.0"
 globset = "0.4"
 regex = "1.12"
+semver = "1.0"
 serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0"
 sha2 = "0.11"

Cargo.toml

@@ -14,7 +14,9 @@ change because of what happened?”
 The local-only Milestone 1 engine is implemented: AEP v0.1, transactional
 SQLite storage, generic JSONL plus Claude Code and Codex adapters, deterministic
 evidence-linked findings, ingestion redaction, retention, export, and deletion.
-No daemon, mutation generation, replay, or background capture ships yet.
+Phase 2 now generates review-only, zero-permission mutation candidates. No
+daemon, replay, installation, autonomous execution, or background capture ships
+yet.
 
 ## Principles
 
@@ -33,6 +35,7 @@ crates/autophagy-adapter-test-support/  Shared native-adapter conformance checks
 crates/autophagy-cli/      User-facing import, sessions, and search commands
 crates/autophagy-core/     Reusable streaming import application services
 crates/autophagy-events/   AEP Rust types, parsing, and validation
+crates/autophagy-mutations/ Versioned review-only mutation candidates
 crates/autophagy-patterns/ Model-free recurrence detectors and evidence packets
 crates/autophagy-redaction/ Secret rules and project/artifact path policy
 crates/autophagy-store/    SQLite migrations, idempotency, FTS, and deletion
@@ -42,6 +45,7 @@ docs/decisions/           Architecture decision records
 docs/roadmap/              Small pull-request delivery sequence
 docs/specs/aep/0.1/       Versioned AEP JSON Schema and examples
 docs/specs/evidence/0.1/  Versioned deterministic finding contract
+docs/specs/mutation/0.1/  Versioned mutation package contract
 ```
 
 The intended repository structure is documented in
@@ -95,16 +99,16 @@ The [deterministic findings guide](docs/guides/deterministic-findings.md)
 documents recurrence thresholds, signature normalization, counterexamples, and
 the versioned Evidence Packet contract.
 
-## Run the offline milestone demo
+## Run the offline demo
 
 ```sh
 mise run demo
 ```
 
 The demo imports anonymized evidence, emits two deterministic patterns with
 exact evidence IDs, produces a digest that confirms no model or network was
-used, and previews retention deletion. Its temporary database is removed on
-exit.
+used, generates two zero-permission mutation candidates, and previews retention
+deletion. Its temporary database is removed on exit.
 
 Useful privacy and lifecycle commands:
 
@@ -120,6 +124,16 @@ autophagy delete all --confirm delete-all
 See the [privacy and lifecycle guide](docs/guides/privacy-and-lifecycle.md) and
 [threat model](docs/security/threat-model.md) for guarantees and limitations.
 
+Inspect candidate packages directly:
+
+```sh
+autophagy mutations
+autophagy --output json mutations --project /workspace/example
+```
+
+See the [mutation candidate guide](docs/guides/mutation-candidates.md) for the
+contract, refusal behavior, and deliberately unavailable lifecycle actions.
+
 ## Try the contract
 
 Install [mise](https://mise.jdx.dev/), then run:

README.md

@@ -17,6 +17,7 @@ autophagy-adapter-claude-code = { path = "../../adapters/claude-code" }
 autophagy-adapter-codex = { path = "../../adapters/codex" }
 autophagy-core = { path = "../autophagy-core" }
 autophagy-events = { path = "../autophagy-events" }
+autophagy-mutations = { path = "../autophagy-mutations" }
 autophagy-patterns = { path = "../autophagy-patterns" }
 autophagy-store = { path = "../autophagy-store" }
 clap.workspace = true

crates/autophagy-cli/Cargo.toml

@@ -16,6 +16,7 @@ use autophagy_adapter_codex::{
 };
 use autophagy_core::{ImportOptions, ImportSummary, import_jsonl};
 use autophagy_events::Event;
+use autophagy_mutations::{GenerationOutcome, generate_candidates};
 use autophagy_patterns::{DetectorConfig, EvidencePacket, detect};
 use autophagy_store::{
     DeleteAllSummary, DeleteSummary, EventStore, PruneSummary, SearchHit, SessionSummary,
@@ -150,6 +151,16 @@ enum Commands {
         thresholds: ThresholdArgs,
     },
 
+    /// Propose review-only, zero-permission mutation candidates from findings.
+    Mutations {
+        /// Limit candidate generation to one exact project path.
+        #[arg(long, value_name = "PATH")]
+        project: Option<String>,
+
+        #[command(flatten)]
+        thresholds: ThresholdArgs,
+    },
+
     /// Export redacted canonical AEP events as JSONL to standard output.
     Export {
         /// Limit export to one exact project path.
@@ -228,6 +239,7 @@ enum CommandReport {
     Search(Vec<SearchHit>),
     Digest(DigestReport),
     Patterns(Vec<EvidencePacket>),
+    Mutations(Vec<GenerationOutcome>),
     Export(Vec<Event>),
     Prune(PruneSummary),
     DeleteSession(DeleteSummary),
@@ -270,6 +282,7 @@ impl CommandReport {
             | Self::Search(_)
             | Self::Digest(_)
             | Self::Patterns(_)
+            | Self::Mutations(_)
             | Self::Export(_)
             | Self::Prune(_)
             | Self::DeleteSession(_)
@@ -446,6 +459,16 @@ fn execute(cli: Cli) -> Result<CommandReport, CliError> {
             let events = store.list_events_for_detection(project.as_deref())?;
             Ok(CommandReport::Patterns(detect(&events, thresholds.into())))
         }
+        Commands::Mutations {
+            project,
+            thresholds,
+        } => {
+            let database = resolve_database_path(cli.database)?;
+            let store = open_store(&database)?;
+            let events = store.list_events_for_detection(project.as_deref())?;
+            let findings = detect(&events, thresholds.into());
+            Ok(CommandReport::Mutations(generate_candidates(&findings)))
+        }
         Commands::Export { project } => {
             let database = resolve_database_path(cli.database)?;
             let store = open_store(&database)?;
@@ -580,6 +603,7 @@ fn write_report(
                 write_findings(&mut writer, &report.findings)?;
             }
             CommandReport::Patterns(findings) => write_findings(&mut writer, findings)?,
+            CommandReport::Mutations(outcomes) => write_mutations(&mut writer, outcomes)?,
             CommandReport::Prune(summary) => writeln!(
                 writer,
                 "{} sessions · {} events · {} artifacts{}",
@@ -631,6 +655,27 @@ fn write_findings(writer: &mut impl Write, findings: &[EvidencePacket]) -> io::R
     Ok(())
 }
 
+fn write_mutations(writer: &mut impl Write, outcomes: &[GenerationOutcome]) -> io::Result<()> {
+    if outcomes.is_empty() {
+        writeln!(writer, "no mutation candidates above evidence threshold")?;
+    }
+    for outcome in outcomes {
+        match outcome {
+            GenerationOutcome::Candidate { package } => writeln!(
+                writer,
+                "{}\t{}\t{} evidence\tzero permissions\tcandidate",
+                package.mutation_id,
+                package.title,
+                package.hypothesis.supporting_event_ids.len()
+            )?,
+            GenerationOutcome::InsufficientEvidence { finding_id, reason } => {
+                writeln!(writer, "{finding_id}\tinsufficient evidence\t{reason}")?;
+            }
+        }
+    }
+    Ok(())
+}
+
 fn write_codex_import_summary(
     writer: &mut impl Write,
     summary: &CodexImportSummary,

crates/autophagy-cli/src/main.rs

@@ -207,6 +207,21 @@ fn milestone_demo_digests_exports_deletes_and_prunes_offline() {
         2
     );
 
+    let mutations = run_json(&database, ["mutations"]);
+    let candidates = mutations["result"].as_array().expect("candidates");
+    assert_eq!(candidates.len(), 2);
+    for outcome in candidates {
+        assert_eq!(outcome["status"], "candidate");
+        assert_eq!(outcome["package"]["state"], "candidate");
+        assert_eq!(outcome["package"]["permissions"]["network"], false);
+        assert!(
+            outcome["package"]["permissions"]["commands"]
+                .as_array()
+                .expect("commands")
+                .is_empty()
+        );
+    }
+
     let exported = command(&database).arg("export").output().expect("export");
     assert!(exported.status.success());
     let lines = String::from_utf8(exported.stdout).expect("UTF-8 export");

crates/autophagy-cli/tests/cli.rs

@@ -0,0 +1,24 @@
+[package]
+name = "autophagy-mutations"
+description = "Versioned, permission-scoped mutation candidates for Autophagy"
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+repository.workspace = true
+publish = false
+
+[dependencies]
+autophagy-patterns = { path = "../autophagy-patterns" }
+semver.workspace = true
+serde.workspace = true
+sha2.workspace = true
+
+[dev-dependencies]
+autophagy-core = { path = "../autophagy-core" }
+autophagy-store = { path = "../autophagy-store" }
+jsonschema = { version = "0.47", default-features = false }
+serde_json.workspace = true
+
+[lints]
+workspace = true