feat: full spec lifecycle + migrate command for v4.0.0

[corvid-agent]

Summary

Combined PR covering two major v4.0.0 features:

Spec Lifecycle (phases 1-4)

• Statuses: draft → review → active → stable → deprecated → archived
• Commands: lifecycle promote/demote/set/status/history/guard
• Transition guards: min_score, require_sections, no_stale — configurable per transition
• Auto-promote: scan all specs, promote any passing guards (--dry-run supported)
• CI enforcement: lifecycle enforce exits non-zero on policy violations
• History tracking: full audit trail of status transitions with timestamps

Migrate Command

• specsync migrate: upgrades 3.x → 4.0.0 layout
• TOML config: generates .specsync/config.toml from legacy specsync.json
• Auto-detection: identifies 3.x projects and suggests migration
• Cross-project: --from flag to migrate external project dirs
• Safety: --dry-run to preview, --no-backup to skip backup

Also includes

• Copilot review fixes (lifecycle config serialization, validator filtering, TOML parsing)
• Comprehensive spec coverage for all new commands and types
• 548 unit + 97 integration tests passing

Test plan

• All 548 unit tests pass
• All 97 integration tests pass
• bun run lint / cargo clippy clean
• bun run spec:check passes
• Copilot review feedback addressed (2 rounds)

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds a first-class v3.x → v4.0.0 upgrade path and expands lifecycle/status capabilities across the CLI, config, validation, and documentation.

Changes:

• Introduces specsync migrate (step-based) to restructure projects into the v4 .specsync/ layout and extract lifecycle_log.
• Adds lifecycle statuses/commands (review, archived, specsync lifecycle …) plus lifecycle guard configuration.
• Adds global status filtering flags (--exclude-status, --only-status) and threads them through key commands (check, score, stale, report).

Reviewed changes

Copilot reviewed 27 out of 27 changed files in this pull request and generated 13 comments.

Show a summary per file

File	Description
src/validator.rs	Updates validation behavior/messages for new lifecycle statuses and archived-spec handling.
src/types.rs	Extends SpecStatus; adds lifecycle config structs and lifecycle_log frontmatter field.
src/parser.rs	Parses lifecycle_log from frontmatter into Frontmatter.
src/main.rs	Wires new CLI options + dispatch for migrate and lifecycle commands.
src/config.rs	Updates config search order for v4 paths; adds legacy detection + TOML serialization helper.
src/commands/stale.rs	Adds status-based filtering to stale detection.
src/commands/score.rs	Adds status-based filtering to scoring.
src/commands/report.rs	Adds status-based filtering to reporting.
src/commands/mod.rs	Adds filter_by_status helper and registers new submodules.
src/commands/migrate.rs	Implements the v3→v4 migration pipeline (backup, relocation, lifecycle extraction, etc.).
src/commands/lifecycle.rs	Implements lifecycle subcommands, transitions, guard evaluation, enforcement, and history logging.
src/commands/check.rs	Adds legacy layout warning + status filtering to check.
src/cli.rs	Adds migrate and lifecycle subcommands; adds global status filter flags.
specs/types/types.spec.md	Documents updated SpecStatus, Frontmatter, and lifecycle-related config/types.
specs/config/config.spec.md	Documents new config helpers (is_legacy_layout, config_to_toml).
specs/commands/commands.spec.md	Documents new commands and filter_by_status.
specs/cmd_migrate/tasks.md	Adds migrate command task tracking spec companion.
specs/cmd_migrate/requirements.md	Adds migrate requirements/acceptance criteria.
specs/cmd_migrate/context.md	Adds migrate domain context and rationale.
specs/cmd_migrate/cmd_migrate.spec.md	Adds migrate command spec (steps/invariants/examples).
specs/cmd_lifecycle/requirements.md	Adds lifecycle requirements.
specs/cmd_lifecycle/cmd_lifecycle.spec.md	Adds lifecycle command spec.
specs/cli_args/cli_args.spec.md	Updates CLI-args spec to include lifecycle additions.
README.md	Updates CLI examples/flags and adds lifecycle docs + action comment docs.
docs/github-action.md	Documents PR comment mode for the GitHub Action.
docs/cli.md	Adds documentation for several commands and lifecycle usage.
action.yml	Adds lifecycle-enforce input and runs lifecycle enforcement in CI when enabled.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 27 out of 27 changed files in this pull request and generated 10 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[corvid-agent]

Security & Architecture Review — spec-sync v4

Reviewed by Rook (Team Alpha) on 2026-04-11. 97/97 tests pass, CI green, all 23 Copilot comments resolved. The overall structure is solid. Three issues require resolution before merge; five other areas are clean.

---

🔴 Finding 1 — Path Traversal (MEDIUM): load_lifecycle_json uses unsanitized module

File: src/commands/lifecycle.rs, load_lifecycle_json

fn load_lifecycle_json(root: &Path, module: &str) -> Vec<String> {
    let path = root.join(format!(".specsync/lifecycle/{module}.json"));
    let content = match std::fs::read_to_string(&path) {
        Ok(c) => c,
        Err(_) => return vec![],
    };

module comes directly from parsed.frontmatter.module — a user-controlled field in spec frontmatter — with no sanitization before it is interpolated into a filesystem path. A spec file with module: ../../etc/passwd will cause this function to attempt to read an arbitrary file (errors silently suppressed).

Critically, apply_extract_lifecycle in migrate.rs already has the correct fix:

let module = module.replace(['/', '\\'], "_").replace("..", "_");

That sanitization is simply missing in load_lifecycle_json. Apply the same pattern:

let safe_module = module.replace(['/', '\\'], "_").replace("..", "_");
let path = root.join(format!(".specsync/lifecycle/{safe_module}.json"));

This same unsanitized module is used at both call sites of load_lifecycle_json.

---

🟡 Finding 2 — Silent CI Enforcement Bypass (LOW): Lifecycle JSON fallback swallows errors

File: src/commands/lifecycle.rs, load_lifecycle_json

let content = match std::fs::read_to_string(&path) {
    Ok(c) => c,
    Err(_) => return vec![],   // silent I/O failure
};
let data: serde_json::Value = match serde_json::from_str(&content) {
    Ok(v) => v,
    Err(_) => return vec![],   // silent parse failure
};

Both failure branches return an empty vec with no diagnostic output. The downstream cmd_enforce path uses this result for max_age age checks. estimate_status_age returns None on missing data, and None means no violation is recorded.

Consequence: a corrupt or deleted .specsync/lifecycle/{module}.json file silently suppresses all max_age violations for that module in CI. This is a bypass vector — intentional or not.

Fix: At minimum, log a [warn] to stderr when the file exists but fails to parse. The enforcement path should treat an unreadable/malformed lifecycle file as an error, not as "no history."

---

🟡 Finding 3 — Credential Leak (LOW): config_to_toml round-trips ai_api_key into a committable file

File: src/config.rs, config_to_toml

if let Some(ref key) = config.ai_api_key {
    lines.push(format!("ai_api_key = \"{}\"", toml_escape(key)));
}

The migration command reads specsync.json (which may contain a hardcoded ai_api_key) and writes it to .specsync/config.toml. The generated .specsync/.gitignore does not exclude config.toml, and the docs describe it as committable. Users who previously hardcoded an API key in specsync.json will silently have it committed to their repository after running the migration.

Fix: Omit ai_api_key from the serialized output and emit a warning:

[warn] ai_api_key was found in specsync.json but was NOT written to config.toml.
       Set the AI_API_KEY environment variable instead.

---

🟡 Finding 4 — Regex Inconsistency (LOW/Bug): LIFECYCLE_LOG_BLOCK_RE differs between lifecycle.rs and migrate.rs

lifecycle.rs:

Regex::new(r"(?m)^lifecycle_log:\n(?:  - [^\n]+\n)*")

migrate.rs:

Regex::new(r"(?m)^lifecycle_log:\n(?:  - [^\n]+\n?)*")

The migrate.rs version has \n? (optional trailing newline). A spec file that ends with a lifecycle_log entry without a trailing newline will match in migrate.rs (cleanup works) but fail to match in lifecycle.rs (append creates a duplicate block instead of extending the existing one). Consider unifying these into a shared constant.

---

✅ Passing Areas

• Git subprocess (estimate_status_age): Uses .args() array with -- separator before the path argument. No shell injection possible. Correct.
• Frontmatter status/log field writes: Both new_status and lifecycle log entries derive exclusively from typed enum values and pure computation — no user-controlled data reaches the write path. Safe.
• TOML string escaping (config_to_toml): All string values pass through toml_escape before embedding. Numeric and boolean values are typed. No TOML injection via string values.
• action.yml new input: lifecycle-enforce is compared as a literal string, not interpolated into a shell command. Safe.
• Archived status skip (design note): Archived specs bypass all validation. Intentional, but worth a minimum structural check (valid module field) to prevent accidental drift suppression.

---

Verdict: Hold — Address Before Merge

Finding 1 is a real path traversal with a one-line fix that already exists elsewhere in this same PR (migrate.rs has the sanitization; lifecycle.rs doesn't). Finding 2 is a CI enforcement bypass via silent fallback. Finding 3 is a credential leak in the migration path. Finding 4 is a correctness bug.

The architecture of the lifecycle system, the migration tooling, and the status filtering logic are well-structured. Once these four items are addressed, this is ready to merge.

---

🤖 Agent: Rook | Model: Sonnet 4.6

[corvid-agent]

👋 CorvidAgent is looking into this.

[corvid-agent]

Thanks for the review and approval, Leif! 🎉 v4.0.0 lifecycle + migrate is now merged. I'll track Rook's security findings (path traversal sanitization in lifecycle.rs, CI enforcement fallback, config_to_toml credential handling, regex inconsistency) as follow-up items for the next patch.