Add experimental read-only plan inspection

Author: myobie

README.md

@@ -183,6 +183,52 @@ agent "<identity>" {
 }
 ```
 
+## Experimental read-only plans
+
+The experimental `st2 plan` surface implements only the inspectable file model from the
+[st2 plans sketch at revision `5c1d142`](https://gist.github.com/myobie/d5ecfac24cd3965e095a5031cd2e00cb/5c1d1427c0556d95d13890e5c5086cd85b25d994).
+It parses either a top-level `plan.kdl`:
+
+```kdl
+plan "ship-remote-approvals" {
+  owner "app-web"
+  version "0000" resource="file:versions/0000.md"
+  version "0001" resource="file:versions/0001.md" {
+    parent "0000"
+    why "Browser proof exposed an approval race."
+  }
+}
+```
+
+or the equivalent agent-local form:
+
+```kdl
+agent "app-web" {
+  plan "review-follow-up" {
+    version "0000" resource="file:review-follow-up.md"
+  }
+}
+```
+
+An agent links an external declaration with `plan-ref "file:relative/plan.kdl"`. Plan identity is
+the explicit KDL value, never the directory. Inline ownership comes from the containing agent;
+external plans require one `owner`. Every version has one relative `file:` resource. Revisions have
+one or more immutable `parent` links and a non-empty `why`; root versions have no parent. The
+frontier is derived as every version with no child, so concurrent siblings remain visible.
+References resolve from the KDL file that declares them and must stay inside the selected catalog.
+
+```sh
+st2 plan validate --catalog examples/plans
+st2 plan list --catalog examples/plans
+st2 plan show ship-remote-approvals --catalog examples/plans
+st2 plan inspect ship-remote-approvals --catalog examples/plans --json
+```
+
+All four commands are read-only. They do not select a current version, write progress, emit events,
+execute a plan, reconcile agents, schedule work, interpret claims, or require CAS. Direct KDL and
+direct human-to-agent planning remain complete workflows; this experiment must earn any larger
+runtime.
+
 st2 provides `CATALOG`, flat native `ST_ROOT`, local `PTY_ROOT`, `ST_AGENT`, and `ST_HOOKS` to the
 task. The complete st2-managed overlay is also persisted in PTY metadata, so a manual `pty restart`
 retains those values. Declarations should not contain machine-specific install paths.

docs/vrs/spec.md

@@ -208,6 +208,23 @@ atomic inbox file → DING attempt → agent reads → archive receipt
 - **R10:** Fleet identities are agents. General-purpose identity kinds are
   unsupported.
 
+### Experimental read-only plan inspection
+
+`st2 plan validate|list|show|inspect` is a non-executing probe for the
+[source plan sketch at revision `5c1d142`](https://gist.github.com/myobie/d5ecfac24cd3965e095a5031cd2e00cb/5c1d1427c0556d95d13890e5c5086cd85b25d994).
+It normalizes top-level external plans and agent-local inline plans into one
+model with explicit plan identity, owner, immutable version/parent links,
+mandatory reasons on revisions, source-relative `file:` resources, and a
+derived frontier that retains concurrent siblings. External `plan-ref` and
+version resources resolve from the declaring KDL file and remain within the
+selected catalog.
+
+The parser is deliberately deny-by-default for plan fields beyond that model.
+It has no current pointer, controller, execution, scheduling, step graph,
+retry, claim, receipt, event, reconciliation, CAS, or mutation behavior. It
+does not yet fulfill R08 plan-progress observability or resolve DQ3; direct KDL
+and direct human-to-agent planning remain first-class.
+
 The owner updates this spec whenever implementation changes.
 Changing [vision.md](./vision.md) or [requirements.md](./requirements.md)
 requires Nathan's explicit approval.

examples/plans/agent.kdl

@@ -0,0 +1,13 @@
+agent "app-web" {
+  host "example"
+  command "true"
+  plan-ref "file:ship-remote-approvals/plan.kdl"
+}
+
+agent "reviewer" {
+  host "example"
+  command "true"
+  plan "review-follow-up" {
+    version "0000" resource="file:review-follow-up.md"
+  }
+}

examples/plans/review-follow-up.md

@@ -0,0 +1,3 @@
+# Review follow-up
+
+Done means the accepted review corrections are present and independently verified.

examples/plans/ship-remote-approvals/plan.kdl

@@ -0,0 +1,9 @@
+plan "ship-remote-approvals" {
+  owner "app-web"
+
+  version "0000" resource="file:versions/0000.md"
+  version "0001" resource="file:versions/0001.md" {
+    parent "0000"
+    why "Browser proof exposed an approval race."
+  }
+}

examples/plans/ship-remote-approvals/versions/0000.md

@@ -0,0 +1,3 @@
+# Ship remote approvals
+
+Done means an authorized reviewer can approve the exact remote change.

examples/plans/ship-remote-approvals/versions/0001.md

@@ -0,0 +1,3 @@
+# Ship remote approvals
+
+Done means an authorized reviewer can approve the exact remote change without racing stale state.

src/lib.rs

@@ -19,6 +19,7 @@ pub mod host_lock;
 pub mod isolate;
 pub mod materialize;
 pub mod message;
+pub mod plans;
 pub mod pretrust;
 pub mod reconcile;
 pub mod resource;

src/main.rs

@@ -269,6 +269,9 @@ enum Command {
         #[command(flatten)]
         ctx: MsgCtx,
     },
+    /// EXPERIMENTAL, READ-ONLY: parse, validate, and inspect versioned catalog plans.
+    #[command(subcommand)]
+    Plan(PlanCmd),
     /// Print a shell completion script for `st2` to stdout (`st2 completions <bash|zsh|fish|…>`).
     /// Generated from the live command tree, so it never drifts from the actual flags.
     Completions {
@@ -339,6 +342,48 @@ enum HooksCmd {
     VerifyOwn,
 }
 
+#[derive(Subcommand)]
+enum PlanCmd {
+    /// Validate every external and inline plan without executing or writing anything.
+    Validate {
+        /// Catalog folder or KDL file. Prefer --catalog; defaults to the selected catalog.
+        #[arg(conflicts_with = "catalog_path")]
+        root: Option<PathBuf>,
+        /// Emit a machine-readable validation receipt.
+        #[arg(long)]
+        json: bool,
+    },
+    /// List normalized plan identity, owner, and derived frontier.
+    List {
+        /// Catalog folder or KDL file. Prefer --catalog; defaults to the selected catalog.
+        #[arg(conflicts_with = "catalog_path")]
+        root: Option<PathBuf>,
+        /// Emit a machine-readable array.
+        #[arg(long)]
+        json: bool,
+    },
+    /// Show normalized intent for one explicit plan identity.
+    Show {
+        identity: String,
+        /// Catalog folder or KDL file. Prefer --catalog; defaults to the selected catalog.
+        #[arg(conflicts_with = "catalog_path")]
+        root: Option<PathBuf>,
+        /// Emit machine-readable normalized intent.
+        #[arg(long)]
+        json: bool,
+    },
+    /// Inspect one plan with source provenance, resolved file paths, and agent references.
+    Inspect {
+        identity: String,
+        /// Catalog folder or KDL file. Prefer --catalog; defaults to the selected catalog.
+        #[arg(conflicts_with = "catalog_path")]
+        root: Option<PathBuf>,
+        /// Emit the complete machine-readable inspection record.
+        #[arg(long)]
+        json: bool,
+    },
+}
+
 #[derive(Subcommand)]
 enum ResourceCmd {
     /// Link a resource (a URL you produced or reference) into your resource list.
@@ -571,6 +616,7 @@ fn main() -> Result<()> {
             enrich,
             ctx,
         } => agents_cmd(catalog, status, json, enrich, ctx),
+        Command::Plan(command) => plan_cmd(command),
         Command::CompileAgent {
             catalog,
             identity,
@@ -638,6 +684,159 @@ fn main() -> Result<()> {
     }
 }
 
+fn plan_cmd(command: PlanCmd) -> Result<()> {
+    match command {
+        PlanCmd::Validate { root, json } => {
+            let root = catalog_arg(root)?;
+            match st2::plans::load(&root) {
+                Ok(catalog) => {
+                    if json {
+                        println!(
+                            "{}",
+                            serde_json::to_string_pretty(&serde_json::json!({
+                                "result": "valid",
+                                "plans": catalog.plans.len(),
+                                "errors": 0,
+                            }))?
+                        );
+                    } else {
+                        println!(
+                            "valid: {} plan{}; read-only (no execution or writes)",
+                            catalog.plans.len(),
+                            plural(catalog.plans.len())
+                        );
+                    }
+                    Ok(())
+                }
+                Err(error) => {
+                    if json {
+                        println!(
+                            "{}",
+                            serde_json::to_string_pretty(&serde_json::json!({
+                                "result": "invalid",
+                                "code": error.code(),
+                                "path": error.path(),
+                                "error": error.to_string(),
+                            }))?
+                        );
+                    }
+                    Err(error.into())
+                }
+            }
+        }
+        PlanCmd::List { root, json } => {
+            let catalog = st2::plans::load(&catalog_arg(root)?)?;
+            if json {
+                let rows = catalog
+                    .plans
+                    .iter()
+                    .map(|plan| {
+                        serde_json::json!({
+                            "identity": plan.identity,
+                            "owner": plan.owner,
+                            "frontier": plan.frontier,
+                        })
+                    })
+                    .collect::<Vec<_>>();
+                println!("{}", serde_json::to_string_pretty(&rows)?);
+            } else {
+                for plan in catalog.plans {
+                    println!(
+                        "{}\towner={}\tfrontier={}",
+                        plan.identity,
+                        plan.owner,
+                        plan.frontier.join(",")
+                    );
+                }
+            }
+            Ok(())
+        }
+        PlanCmd::Show {
+            identity,
+            root,
+            json,
+        } => {
+            let catalog = st2::plans::load(&catalog_arg(root)?)?;
+            let plan = exact_plan(&catalog, &identity)?;
+            let intent = serde_json::json!({
+                "identity": plan.identity,
+                "owner": plan.owner,
+                "versions": plan.versions.iter().map(|version| serde_json::json!({
+                    "identity": version.identity,
+                    "parents": version.parents,
+                    "why": version.why,
+                    "resource": version.resource,
+                })).collect::<Vec<_>>(),
+                "frontier": plan.frontier,
+            });
+            if json {
+                println!("{}", serde_json::to_string_pretty(&intent)?);
+            } else {
+                println!("plan {}  owner={}", plan.identity, plan.owner);
+                for version in &plan.versions {
+                    let marker = if plan.frontier.contains(&version.identity) {
+                        " [frontier]"
+                    } else {
+                        ""
+                    };
+                    println!(
+                        "  version {}{marker}  resource={}",
+                        version.identity, version.resource
+                    );
+                    if !version.parents.is_empty() {
+                        println!("    parents: {}", version.parents.join(", "));
+                    }
+                    if let Some(why) = &version.why {
+                        println!("    why: {why}");
+                    }
+                }
+            }
+            Ok(())
+        }
+        PlanCmd::Inspect {
+            identity,
+            root,
+            json,
+        } => {
+            let catalog = st2::plans::load(&catalog_arg(root)?)?;
+            let plan = exact_plan(&catalog, &identity)?;
+            if json {
+                println!("{}", serde_json::to_string_pretty(plan)?);
+            } else {
+                println!(
+                    "plan {}  owner={}  kind={:?}\n  source: {}\n  referenced-by: {}\n  frontier: {}",
+                    plan.identity,
+                    plan.owner,
+                    plan.source_kind,
+                    plan.source.display(),
+                    plan.referenced_by.join(","),
+                    plan.frontier.join(",")
+                );
+                for version in &plan.versions {
+                    println!(
+                        "  {}: {} -> {}",
+                        version.identity,
+                        version.resource,
+                        version.resolved_resource.display()
+                    );
+                }
+            }
+            Ok(())
+        }
+    }
+}
+
+fn exact_plan<'a>(
+    catalog: &'a st2::plans::PlanCatalog,
+    identity: &str,
+) -> Result<&'a st2::plans::Plan> {
+    catalog
+        .plans
+        .iter()
+        .find(|plan| plan.identity == identity)
+        .with_context(|| format!("no plan '{identity}' found"))
+}
+
 #[allow(clippy::too_many_arguments)]
 fn compile_agent_cmd(
     catalog: &Path,