refactor: extract the agent-spec crate (#54)

* refactor: extract the agent-spec crate

Move the declaration model (`spec`), the KDL parser (`kdl_format`), and the
catalog walk (`discovery`) into `crates/agent-spec`, and have st2 consume it.
No behavior change: `spec.rs` and `kdl_format.rs` move byte-for-byte.

st2 re-exports the crate under the original paths (`st2::spec::…`,
`st2::discovery::…`), so `src/main.rs` and the whole test suite are untouched.
The ~9 in-tree consumers change only `crate::spec::` → `agent_spec::spec::`.

`kdl_format` stays private inside the crate, so the published surface is
exactly `spec` + `discovery` — a catalog reader parses through `discover` and
resolves identity/host the one way the runner does.

`validate` needed the pre-lowering `type` and `identity`, which it read via the
`pub(crate)` `parse_raw_file`. Rather than export the permissive on-disk
`RawSpec`, the crate exposes a narrow `Declared { identity, job_type }` and
`parse_declared`. `RawSpec` stays private and free to change.

The root stays a real package — `flake.nix` reads `package.version` from it, and
a virtual manifest has no `[package]`. `cargoTestFlags` gains `--workspace`
because cargo would otherwise select only `st2` and silently stop gating the
crate's 5 unit tests (149 lib tests before = 144 + 5 after).

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
agent-session-id: 8464a883-6285-4cd0-a9ec-3eba09830300
agent-tool: Claude Code
agent-tool-version: 2.1.220
agent-model: claude-opus-5
agent-runtime-profile: /nix/store/i8y8b542cyqi385ywcjw5fvsq24f75v4-coding-agent-runtime-profile/share/coding-agents/profile.json
agent-skills-manifest: /nix/store/i81qxhzlrzcxrrdwpp6i8hagka2gby8y-agent-skills-corpus/share/agent-skills/manifest.json
tooling-profile: dotfiles@unknown-dirty

* docs: link JobType plainly in the Declared docs

`#[cfg(doc)]`-importing a type just to satisfy an intra-doc link is a
construct this tree uses nowhere else; plain backticks read the same and
match the surrounding doc comments.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
agent-session-id: 8464a883-6285-4cd0-a9ec-3eba09830300
agent-tool: Claude Code
agent-tool-version: 2.1.220
agent-model: claude-opus-5
agent-runtime-profile: /nix/store/i8y8b542cyqi385ywcjw5fvsq24f75v4-coding-agent-runtime-profile/share/coding-agents/profile.json
agent-skills-manifest: /nix/store/i81qxhzlrzcxrrdwpp6i8hagka2gby8y-agent-skills-corpus/share/agent-skills/manifest.json
tooling-profile: dotfiles@unknown-dirty

* docs: correct the parse_declared ordering claim

The doc said callers could pair the result positionally with `discover`'s
specs for the same file. They cannot: `resolve_spec` returns `Ok(None)` for
any node failing `looks_like_spec`, so specs are a subset of parsed nodes.
`validate` never pairs positionally, so this is a doc fix only.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
agent-session-id: 8464a883-6285-4cd0-a9ec-3eba09830300
agent-tool: Claude Code
agent-tool-version: 2.1.220
agent-model: claude-opus-5
agent-runtime-profile: /nix/store/i8y8b542cyqi385ywcjw5fvsq24f75v4-coding-agent-runtime-profile/share/coding-agents/profile.json
agent-skills-manifest: /nix/store/i81qxhzlrzcxrrdwpp6i8hagka2gby8y-agent-skills-corpus/share/agent-skills/manifest.json
tooling-profile: dotfiles@unknown-dirty

* test: preserve agent-spec coverage

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: myobie <179+myobie@users.noreply.github.com>

Author: 3 people

Cargo.lock

@@ -1,3 +1,10 @@
+# The root stays a real package (not a virtual manifest): `flake.nix` reads
+# `package.version` out of this file as the single source of truth for the
+# build, and a virtual root has no `[package]` to read.
+[workspace]
+members = ["crates/agent-spec"]
+default-members = [".", "crates/agent-spec"]
+
 [package]
 name = "st2"
 version = "0.1.0"
@@ -16,6 +23,7 @@ path = "src/lib.rs"
 [dependencies]
 # Sync by design: the runner is I/O-light (shell-outs to `pty` plus a
 # folder watch + a sleep), so no tokio. Deps grow per milestone; M0 needs only parse + CLI.
+agent-spec = { path = "crates/agent-spec" }
 anyhow = "1"
 clap = { version = "4", features = ["derive"] }
 clap_complete = "4"

Cargo.toml

@@ -0,0 +1,16 @@
+[package]
+name = "agent-spec"
+version = "0.1.0"
+edition = "2024"
+description = "Parse a catalog of rendered agent specs (KDL/TOML/JSON) into the runner-normative agent job model."
+license = "MIT"
+
+[dependencies]
+anyhow = "1"
+kdl = "6"
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+toml = "0.9"
+
+[dev-dependencies]
+tempfile = "3"

crates/agent-spec/Cargo.toml

@@ -92,10 +92,40 @@ fn collect_spec_files(root: &Path, dir: &Path, acc: &mut Vec<PathBuf>) {
     }
 }
 
+/// What a declaration literally *says*, before lowering normalizes it away.
+///
+/// Lowering is lossy by design: a typo'd `type = "srvice"` becomes `JobType::Service`, and an
+/// identity omitted from the content is filled in from the path. Both are invisible in the resolved
+/// [`AgentSpec`], so a linter that wants to fault them has to see the declared form. This is that
+/// view — deliberately narrow, so the permissive on-disk shape itself stays private and is free to
+/// gain fields without breaking readers.
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct Declared {
+    /// `identity` as written in the file. `None` when the file relies on [`path_defaults`].
+    pub identity: Option<String>,
+    /// `type` as written, before it is normalized to `JobType::Service`. `None` when unset.
+    pub job_type: Option<String>,
+}
+
+/// Read the declared (pre-lowering) values of every agent in a file — one per `agent` node for KDL,
+/// 0-or-1 for TOML/JSON, empty for a non-spec extension.
+///
+/// One entry per parsed node, *including* nodes [`discover`] skips as non-specs, so this is not
+/// positionally paired with that file's [`Discovered::specs`].
+pub fn parse_declared(path: &Path) -> anyhow::Result<Vec<Declared>> {
+    Ok(parse_raw_file(path)?
+        .into_iter()
+        .map(|raw| Declared {
+            identity: raw.identity,
+            job_type: raw.job_type,
+        })
+        .collect())
+}
+
 /// Parse a spec file into its raw (pre-resolution) shape — one per `agent` node for KDL, 0-or-1 for
-/// TOML/JSON. Non-spec extensions yield an empty vec. Shared by discovery and `validate` (which needs
-/// the *raw* `type` string before it is normalized away, to catch a typo'd `type = "srvice"`).
-pub(crate) fn parse_raw_file(path: &Path) -> anyhow::Result<Vec<RawSpec>> {
+/// TOML/JSON. Non-spec extensions yield an empty vec. Shared by discovery and [`parse_declared`]
+/// (which exposes the *raw* `type` and `identity` before normalization, without leaking [`RawSpec`]).
+fn parse_raw_file(path: &Path) -> anyhow::Result<Vec<RawSpec>> {
     let ext = path.extension().and_then(|e| e.to_str()).unwrap_or("");
     let text = fs::read_to_string(path)?;
     Ok(match ext {

src/discovery.rs crates/agent-spec/src/discovery.rssrc/discovery.rs renamed to crates/agent-spec/src/discovery.rs

@@ -0,0 +1,28 @@
+//! agent-spec — read a catalog of rendered agent declarations.
+//!
+//! One agent is one declarative file, Nomad-style: the agent is the job and its `pty`/`exec` blocks
+//! are the tasks. This crate owns the two halves any reader of that catalog needs and nothing else:
+//!
+//! - [`spec`] — the runner-normative model a declaration lowers to ([`AgentSpec`], [`Task`], …).
+//! - [`discovery`] — the catalog walk: parse every `*.{kdl,toml,json}` that looks like a
+//!   declaration, and resolve each one's `identity`/`host` with the catalog's precedence rule
+//!   (content wins, the path supplies defaults, a mismatch is a warning).
+//!
+//! KDL is the canonical on-disk format; TOML and JSON lower to the same model. The KDL parser is a
+//! private implementation detail — [`discovery`] is the only supported entry point, so every reader
+//! resolves identity and host the same way rather than re-deriving it from filenames.
+//!
+//! st2 consumes this crate, which is what keeps it a reference implementation rather than a copy:
+//! a second reader (a TUI, a linter) sees exactly the fields the runner sees, including the ones
+//! the runner's roster JSON does not carry (`supervisor`, `role`, `workspace`, `host`).
+//!
+//! Render-only fields (`harness`, `model`, `persona`, `permissions`, `transport`, `strategy`,
+//! `meta{}`) are read by the render layer and deliberately dropped here — that is what keeps a
+//! consumer render-agnostic.
+
+pub mod discovery;
+mod kdl_format;
+pub mod spec;
+
+pub use discovery::{Declared, Discovered, SpecError, discover, parse_declared, path_defaults};
+pub use spec::{AgentSpec, JobType, Restart, RestartMode, Task, TaskKind, parse_duration};

src/kdl_format.rs crates/agent-spec/src/kdl_format.rssrc/kdl_format.rs renamed to crates/agent-spec/src/kdl_format.rs

@@ -1,15 +1,15 @@
 //! M1 correctness net: discovery + lowering of VRS `agent.kdl` jobs (spec.md §1–2, §4).
 //!
 //! Builds throwaway catalog folders, writes real job files (KDL/TOML/JSON, services), and
-//! asserts st2 lowers them per the spec: `pty`/`exec` task split, `restart{}`, `type`, `workspace`,
+//! asserts they lower per the spec: `pty`/`exec` task split, `restart{}`, `type`, `workspace`,
 //! `supervisor`; render-only fields ignored; content/path precedence; malformed → error, not halt.
 
 use std::fs;
 use std::path::Path;
 use std::time::Duration;
 
-use st2::spec::TaskKind;
-use st2::{AgentSpec, JobType, discover};
+use agent_spec::spec::TaskKind;
+use agent_spec::{AgentSpec, JobType, discover};
 
 fn write(root: &Path, rel: &str, contents: &str) {
     let path = root.join(rel);
@@ -91,7 +91,7 @@ fn parses_full_kdl_service_job() {
     assert_eq!(r.attempts, 5);
     assert_eq!(r.interval, Duration::from_secs(90));
     assert_eq!(r.delay, Duration::from_secs(5));
-    assert_eq!(r.mode, st2::RestartMode::Fail);
+    assert_eq!(r.mode, agent_spec::RestartMode::Fail);
 
     // tasks: pty "agent" + exec "ding" (sorted by name)
     assert_eq!(s.tasks.len(), 2);
@@ -213,7 +213,10 @@ command = "st2 ding hetz.fetcher"
     let s = &found.specs[0];
     assert_eq!(s.identity, "fetcher");
     assert_eq!(s.job_type, JobType::Service);
-    assert_eq!(s.restart.clone().unwrap().mode, st2::RestartMode::Delay);
+    assert_eq!(
+        s.restart.clone().unwrap().mode,
+        agent_spec::RestartMode::Delay
+    );
     assert_eq!(s.tasks.len(), 2);
     assert_eq!(
         s.tasks.iter().find(|t| t.name == "agent").unwrap().kind,

crates/agent-spec/src/lib.rs

@@ -87,15 +87,21 @@
               --fish completions-fish
           '';
 
-          # Run the hermetic unit tests plus the real lifecycle-hook integration
-          # test. The remaining integration tests assume facilities the Nix build
-          # sandbox deliberately lacks: `/usr/bin/git` on a hardcoded `PATH`,
-          # live PTY backends, or a systemd `--user` manager. They remain native
-          # gates, while the flake proves that its own packaged hooks execute.
+          # Run the hermetic unit tests plus agent-spec's discovery test and the
+          # real lifecycle-hook integration tests. The remaining root integration
+          # tests assume facilities the Nix build sandbox deliberately lacks:
+          # `/usr/bin/git` on a hardcoded `PATH`, live PTY backends, or a systemd
+          # `--user` manager. They remain native gates, while the flake proves
+          # that its parser and packaged hooks execute.
+          # `--workspace` because the root is a real package: without it cargo
+          # selects only `st2` and silently skips the `agent-spec` crate.
           cargoTestFlags = [
+            "--workspace"
             "--lib"
             "--bins"
             "--test"
+            "discovery"
+            "--test"
             "codex_hooks"
             "--test"
             "hooks"

src/spec.rs crates/agent-spec/src/spec.rssrc/spec.rs renamed to crates/agent-spec/src/spec.rs

@@ -16,7 +16,7 @@ use crate::expand::expand_catalog;
 use crate::flapping::FlappingCap;
 use crate::reconcile::reconcile;
 use crate::run::{Runner, SystemRunner, UpReport, detect_host, execute};
-use crate::spec::{AgentSpec, JobType, Task, TaskKind};
+use agent_spec::spec::{AgentSpec, JobType, Task, TaskKind};
 
 macro_rules! eval_log {
     ($($arg:tt)*) => {