CLI Reference

Submodule-Aware Flags

The following flags are available on most spec-operating commands, including validate, validate-all, spec-check, matrix, seed-lint, fixtures-lint, invariants-check, governance-check, canonical-lint, canonical-integrity, spec-quality-lint, hallucination-lint, forward-replay-check, milestone-state, and canon-schema-alignment. Per-command exceptions (per CLAUDE.md): canon-accept takes --git-root (and --repo-root) but not --spec-root; most specdev json subcommands take --repo-root only; and diagnostic/utility commands (ai-help, env-check, dependency-order-lint, dag-lint, extraction-intent-check, prompt-context) take --repo-root only; update takes spec_dir (positional) + --repo-root only and does not accept --spec-root or --git-root; seed-index takes spec_dir (positional) + --repo-root + --git-root but not --spec-root, and hardcoded-seed-check takes --repo-root + --git-root only (no positional, no --spec-root). Run <command> --help to confirm the supported flags for any subcommand:

Flag	Description	Default
`--repo-root`	Path to devspec_toolkit directory (for schema resolution)	`.`
`--spec-root`	Path to the spec directory (for submodule deployments where spec/ is outside toolkit)	`None` (uses `repo_root/spec`)
`--git-root`	Path to the host repo git root (for submodule deployments where git root differs from toolkit root)	`None` (uses `repo_root`)

Examples

# Standard (non-submodule) usage — intentionally flagless: when spec/ lives under the
# toolkit root, --spec-root/--git-root default correctly and are omitted on purpose.
./tools/run_specdev.sh validate-all spec --repo-root ./devspec_toolkit

# Submodule deployment
./tools/run_specdev.sh validate-all spec \
  --repo-root ./devspec_toolkit \
  --spec-root ./spec \
  --git-root .

# Forward replay check with explicit roots
./tools/run_specdev.sh forward-replay-check \
  --repo-root ./devspec_toolkit \
  --git-root . \
  --spec-root ./spec

Developer Reference

This reference collects recurring facts that developers need while authoring or reviewing specs. It replaces ad-hoc snippets scattered across multiple documents; other guides intentionally link here for the canonical commands and troubleshooting flow.

Terminology

Term	Definition
Step	Numbered phase of the spec lifecycle (00–16c, 02a, 13a)
Artifact	Machine-checked JSON file for a step (`spec/NN_name.json`)
Guide	Human playbook describing a step (`spec/NN_name.guide.md`)
Prompt	AI instruction file (`prompts/prompt_NN_name.md`)
DoR	Definition of Ready requirements for completing a step
traceRef	Identifier linking FRs ↔ APIs ↔ fixtures ↔ NFRs

Naming & Schema Conventions

IDs: kebab-case only (fr-user-login, api-session-create).
Owner enum: one of {api, ui, system, ops, data, product, business, engineering} (source of truth: schema/core/atoms.schema.json#owner).
Artifacts: include the canonical $schema URI exactly as emitted in the prompt.
File naming: spec/NN_name.json, spec/NN_name.guide.md, ./devspec_toolkit/prompts/prompt_NN_name.md (adjust the toolkit path as needed).
No redefining primitives: reuse atoms/collections/errors from schema/core/.

Path Conventions

See path_conventions.md for canonical path variables ($PRODUCT_ROOT, $TOOLKIT_ROOT, $SPEC_DIR, etc.) and the dual-root convention.

Scope Lock (`spec_dir`)

Enforce scope lock for every repo: set and persist spec_dir explicitly instead of inferring from cwd.
Consumer repos (projects that vendor the toolkit as a submodule): the locked spec_dir is <product-repo>/spec/ — this is where your live spec artifacts live.
Toolkit repo itself: the toolkit does not maintain spec waterfall artifacts and does not run spec validation against itself. Seed templates for host bootstrap live in seed_templates/.
Automation and CI must pass the same spec_dir to every command to avoid path-assumption drift.

Command Cheatsheet

Set up your environment per getting_started.md before running these commands. Every other document links back here so this serves as the canonical command reference. All validation and linting commands below use ./tools/run_specdev.sh (generated by the init script) to enforce virtualenv usage. Alignment commands use specdev align, which is installed alongside the toolkit CLI.

Project Initialization

# Initialize a new project (creates dirs, submodule, venv, hooks, CI)
python3 devspec_toolkit/scripts/init_project.py --target . --strict

Core validation commands

# Unified gate — runs all applicable validation / lint checks (preferred over bare validate-all;
# resolves project canon, so it avoids the false E110s that validate-all alone can emit)
./tools/run_specdev.sh spec-check spec --repo-root ./devspec_toolkit --spec-root ./spec --git-root .

# Validation
./tools/run_specdev.sh validate spec/00_charter.json --repo-root ./devspec_toolkit
./tools/run_specdev.sh validate-all spec --repo-root ./devspec_toolkit --spec-root ./spec --git-root .

# Traceability & fixtures
mkdir -p spec/extras && ./tools/run_specdev.sh matrix spec --repo-root ./devspec_toolkit --spec-root ./spec --git-root . --out spec/extras/trace_matrix.json
./tools/run_specdev.sh fixtures-lint spec --repo-root ./devspec_toolkit --spec-root ./spec --git-root .

# Traceability closure — verifies the full charter-goal -> capability -> FR -> API/fixture
# chain has no dangling links (capability/FR/API/fixture trace-type checks); add --json
# for a machine-readable report; accepts --repo-root, --spec-root, and --git-root
./tools/run_specdev.sh traceability-check spec --repo-root ./devspec_toolkit --spec-root ./spec --git-root .

# Seed enforcement
./tools/run_specdev.sh seed-lint spec --repo-root ./devspec_toolkit --spec-root ./spec --git-root .

# Invariants & Governance
# SPECDEV_INVARIANTS_STRICT=1 is equivalent to passing --strict: promotes unevaluable
# rules (W_INVARIANT_UNEVALUABLE) to fatal errors (E_INVARIANT_UNEVALUABLE)
./tools/run_specdev.sh invariants-check spec --repo-root ./devspec_toolkit --spec-root ./spec --git-root . --sample ./path/to/sample.json
./tools/run_specdev.sh governance-check spec --repo-root ./devspec_toolkit --spec-root ./spec --git-root . --message "feat(spec): add login [fr-initial-login]"

# Quality, hallucination, and canonical integrity
./tools/run_specdev.sh spec-quality-lint spec --repo-root ./devspec_toolkit --spec-root ./spec --git-root .
./tools/run_specdev.sh hallucination-lint spec --repo-root ./devspec_toolkit --spec-root ./spec --git-root .
./tools/run_specdev.sh canonical-lint canon --repo-root ./devspec_toolkit --spec-root ./spec --git-root .
./tools/run_specdev.sh canonical-integrity spec --repo-root ./devspec_toolkit --spec-root ./spec --git-root .

# Canon/schema alignment
./tools/run_specdev.sh canon-schema-alignment --repo-root ./devspec_toolkit --spec-root ./spec --git-root .

# Step-order integrity (strict waterfall)
./tools/run_specdev.sh dependency-order-lint --repo-root ./devspec_toolkit
./tools/run_specdev.sh forward-replay-check --repo-root ./devspec_toolkit --spec-root ./spec --git-root . --base-ref origin/main

# DAG completeness lint (validates downstream_consumers consistency)
./tools/run_specdev.sh dag-lint --repo-root ./devspec_toolkit

# Extraction intent validation (prompts vs step_order.json)
./tools/run_specdev.sh extraction-intent-check --repo-root ./devspec_toolkit

# Environment diagnostic (read-only — prints active config)
./tools/run_specdev.sh env-check --repo-root ./devspec_toolkit

# Prompt workflow reminders
./tools/run_specdev.sh ai-help --step 04

# Changelog utilities (migration system)
./tools/run_specdev.sh changelog --list --repo-root ./devspec_toolkit
./tools/run_specdev.sh changelog --version <version> --repo-root ./devspec_toolkit
./tools/run_specdev.sh changelog --validate <version> --repo-root ./devspec_toolkit

# Trinity milestone-state — deterministic phase-position computation (DEVSPEC-38)
./tools/run_specdev.sh milestone-state --batch-id <batch-id> \
  --repo-root ./devspec_toolkit --spec-root ./spec --git-root .

# Targeted JSON read/query of a spec artifact (avoids direct Read)
./tools/run_specdev.sh json read spec/03_glossary.json '.terms[0].id' --repo-root ./devspec_toolkit
./tools/run_specdev.sh json read-multi spec/03_glossary.json '.terms | length' '.id' --repo-root ./devspec_toolkit

# Targeted JSON edit of a spec artifact (avoids direct Edit/Write)
./tools/run_specdev.sh json patch  spec/03_glossary.json '.terms[0].domain' '"infrastructure"' --repo-root ./devspec_toolkit
./tools/run_specdev.sh json insert spec/03_glossary.json '.terms' '<term-object-json>' --repo-root ./devspec_toolkit
# delete/keys/structure take no --repo-root (jq-only ops)
./tools/run_specdev.sh json delete spec/03_glossary.json '.terms[3]'

`specdev json` — artifact read/query/edit family

Surgical, schema-aware access to spec/*.json artifacts; preferred over direct file reads/writes (the /specdev-context skill drives these under the hood). All positional path arguments are jq paths/filters (e.g. .terms[0].id), not RFC-6901 JSON pointers. --spec-root/--git-root are not accepted by the read/query/write subcommands; resolve-pointers is the exception — it accepts --git-root (used, to anchor relative file-path resolution) and a deprecated --spec-root (accepted but warned-then-ignored; slated for removal). --repo-root support is per-subcommand (see the column below): it is required by resolve-pointers (registry lookup), used by schema for schema discovery (optional — falls back to find_schema_dir) and by patch/insert for differential validation, accepted-but-ignored by read/read-multi, and not accepted at all by keys/structure/delete (passing it errors with "unrecognized arguments").

Subcommand	`--repo-root`	Purpose
`specdev json read <file> <jq-filter>`	accepted (unused)	Evaluate a single jq filter against the artifact
`specdev json read-multi <file> <jq...>`	accepted (unused)	Evaluate several jq filters in one call
`specdev json keys <file> [jq-path]`	✗	List object keys at a jq path
`specdev json structure <file> [jq-path]`	✗	Print the artifact's shape (keys/types)
`specdev json schema <file> <jq-path>`	used (optional)	Navigate the resolved schema at a path (own-first property merge; unions `oneOf`/`anyOf`/`if-then-else`)
`specdev json patch <file> <jq-path> <value>`	used	Set one value; differential schema-validated before write
`specdev json insert <file> <jq-path> <value>`	used	Append into an array; differential schema-validated before write
`specdev json delete <file> <jq-path>`	✗	Remove one node (jq `del()`; no schema validation)
`specdev json resolve-pointers` (pointer list on stdin)	required	Resolve a canonical-ref pointer list; report to `--out <path>` or stdout (also accepts `--git-root`, default cwd)

patch and insert perform always-on differential whole-document validation using the file's own $schema URI: a write is refused only if it introduces a new violation (before/after diff), so one-patch-at-a-time repair is never deadlocked. There is no --no-validate bypass. delete does not validate — it applies a jq del() and writes atomically. specdev json insert --create-schema <uri> seeds a missing target file with {"$schema": "<uri>"} and bootstraps the array-valued field before validating — enabling first-use creation of an artifact (e.g. spec/canon/command_prefixes.json) without a separate file-creation step.

`specdev context` — context preparation family

Drives the /specdev-context skill's Orientation flow (scoped structure/canon reads that feed targeted specdev json calls, rather than reading spec/*.json directly).

Subcommand	Required flags	Purpose
`specdev context structure <spec_dir> --step STEP`	`--step`	Print the artifact shape (keys/types) scoped to one step, for Orientation reads
`specdev context scope <spec_dir> --entry ENTRY`	`--entry`	Resolve the scoped read/jq plan for one canon or spec entry
`specdev context canon --step STEP [--spec-root SPEC_ROOT]`	`--step`	List canon entries relevant to a step; `--spec-root` optionally includes project-tier canon alongside toolkit canon
`specdev context freshness <spec_dir> [--git-root GIT_ROOT]`	none	Report staleness of loaded context relative to upstream step edits
`specdev context review <artifact_path> --step STEP [--entry ENTRY] [--spec-dir SPEC_DIR] [--git-root GIT_ROOT]`	`--step`	Prepare review context for one artifact ahead of a review pass
`specdev context extract`	—	Removed. Errors with a message directing to `specdev json read <file> '<jq>'`, scoped via `specdev context structure` + `specdev json schema`

Registry, Canon & Prompt Maintenance Commands

Subcommand	Purpose
`specdev seed-index spec_dir [--git-root GIT_ROOT] [--json]`	Report seed-doc reference index/coverage across spec artifacts
`specdev prompt-sync [spec_dir] [--spec-root SPEC_ROOT] [--git-root GIT_ROOT] [--json]`	Check prompt files are in sync with their canonical templates
`specdev canonical-autofix spec_dir [--canon-dir CANON_DIR] [--write \| --dry-run] [--json]`	Auto-fix canonical-reference issues; defaults to reporting only — pass `--write` to persist
`specdev glossary-drift-check spec_dir [--spec-root SPEC_ROOT] [--git-root GIT_ROOT] [--json]`	Validate definition parity across glossary terms, canonical proposals, and the canon registry
`specdev completeness-check spec_dir [--spec-root SPEC_ROOT] [--git-root GIT_ROOT] [--json]`	Run pairwise completeness checks (W564–W568) and report coverage ratios
`specdev registry-check --spec-root SPEC_ROOT [--repo-root REPO_ROOT] [--git-root GIT_ROOT] [--json]`	Validate `entry_key_registry.json`: coverage, phantom basenames, and drift against live spec files (R003)
`specdev registry-generate --repo-root REPO_ROOT [--out OUT] [--extraction-paths-out PATH]`	Regenerate `entry_key_registry.json` + `extraction_paths.json` from toolkit schemas (byte-deterministic; run after any schema change — see CLAUDE.md)
`specdev guide <CODE> [--json]`	Show the remediation playbook for an error/warning code, e.g. `specdev guide E110` or `specdev guide E530-INVENTED_ENUM_OR_ID`
`specdev hardcoded-seed-check [--repo-root REPO_ROOT] [--git-root GIT_ROOT] [--json]`	Detect literal seed-doc filenames hardcoded in prompts (W554 regression guard); with `--git-root` also scans `<git-root>/prompts/` for submodule deployments
`specdev upstream-backlog spec_dir [--severity {low,medium,high,critical}] [--status {open,resolved,all}] [--json]`	Aggregate both `plan.ambiguities[]` (16a) and `execution.emergent_ambiguities[]` (16b/16c) across `impl_context` plans by implicated upstream step (read-only)
`specdev canon-accept --from SPEC_FILE [--namespace NAMESPACE] [--owner OWNER] [--repo-root REPO_ROOT] [--git-root GIT_ROOT] [--dry-run] [--json]`	Promote `canonical_proposals` from a spec file into `canon/manifest.json`; with `--git-root`, writes project canon to `<git-root>/spec/canon/` instead (accepts `--git-root`, not `--spec-root` — see CLAUDE.md exception list)

DAG & Extraction Intent Commands

`dag-lint`

Validates the completeness and consistency of the dependency DAG defined in tools/step_order.json. This is a standalone command — it is not included in validate-all.

What it checks:

Every non-terminal step has at least one downstream_consumers entry (E596 DAG_DEAD_END_PRODUCER). Step 16c is exempt as the terminal step.
Every downstream_consumers entry is consistent with the computed step ordering (E599 DAG_CONSUMER_INCONSISTENCY). If step X lists Y as a consumer, Y must appear after X in the steps list.
No circular dependencies in the computed upstream graph (E585 DAG_CIRCULAR_DEPENDENCY).
Prompt extraction intent entries reference only computed upstream steps (W596 UNDECLARED_UPSTREAM_REF).

When to run: After modifying tools/step_order.json or any prompt's ### Extraction Intent section. Also runs automatically via pre-commit hook and CI gate.

`extraction-intent-check`

Validates that each prompt's ### Extraction Intent section is consistent with the allowed upstream steps computed at runtime from tools/step_order.json (all steps preceding the current step in the steps list).

What it checks:

Every allowed upstream dependency has a corresponding extraction intent entry (E597 EXTRACTION_INTENT_UPSTREAM_GAP).
Extraction intent entries reference valid steps (E598 EXTRACTION_INTENT_INVALID_REF).
Intent text is specific (W597 EXTRACTION_INTENT_VAGUE — fewer than 10 words or contains weasel words).
Extraction intent sections are non-empty when present (E591 EXTRACTION_INTENT_EMPTY).

When to run: After adding or modifying ### Extraction Intent sections in prompts.

`env-check`

Read-only diagnostic that prints the active validation configuration. Modifies no state.

What it displays:

All active SPECDEV_* environment variables and their values.
W→E promotion status: ALL (every registered pair via SPECDEV_WARNINGS_AS_ERRORS=1), SELECTIVE (per-code via SPECDEV_PROMOTE_CODES), or OFF. The live pair count is printed from PROMOTABLE_PAIRS.
Forward-replay base ref resolution (explicit, upstream tracking, or fallback).
Spec directory and step_order.json paths.

When to run: When troubleshooting CI failures related to W→E promotion, replay base ref, or configuration issues.

`milestone-state`

Deterministic milestone-state computation for the Trinity loop. Reads spec/impl_context/ms_<batch-id>_plan.json, probes .specdev/findings/ under the host git root, and emits a single JSON object to stdout.

This command replaces the LLM-evaluated milestone_state mode of the specdev-scope agent (DEVSPEC-38, D7/D7a). The specdev-scope agent now delegates to this command and passes its output through unchanged, so the output contract is identical for skills that parse it.

Flags:

Flag	Required	Description
`--batch-id BATCH_ID`	Yes	Milestone batch identifier (e.g. `phase2_newsletter_send`)
`--repo-root REPO_ROOT`	No	Toolkit root directory (schema tier). Default: cwd
`--spec-root SPEC_ROOT`	No	Host spec directory used to locate `spec/impl_context/ms_<batch-id>_plan.json`. Default: `<repo-root>/spec`
`--git-root GIT_ROOT`	No	Host repo git root used to locate `.specdev/findings/` (host-relative, NOT under spec-root). Default: `<repo-root>`

Output contract (JSON to stdout):

{
  "milestone_id": "<string>",
  "groups": [
    {
      "group_id": "<string>",
      "state": "<pending|code_converged|blocked|verified|deferred|wont_do>",
      "implementation_converged_at": "<ISO8601 or null>",
      "reviewer_rounds": "<integer>",
      "findings_resolved_path": "<path or null>",
      "blocking_amb_ids": ["<string>"],
      "blocking_amb_health": [{"id": "<string>", "status": "<string>", "resolved": <boolean>, "well_formed": <boolean>}],
      "fixtures_exercised": ["<string>"]
    }
  ],
  "derived_phase_position": "<pending|impl_in_progress|impl_complete|review_pending|review_complete|operator_pending|closed>",
  "blockers": [
    { "kind": "ambiguity", "id": "<string>", "issue": "<string>" }
  ]
}

Submodule deployment:

specdev milestone-state \
  --batch-id phase2_newsletter_send \
  --repo-root ./devspec_toolkit \
  --spec-root ./spec \
  --git-root .

When to run: When debugging Trinity loop state, verifying phase-position transitions, or smoke-testing the specdev-trinity skill's milestone dispatch.

Note: The former specdev-trinity-plan skill no longer exists as a separate skill; its plan-phase functionality is now /specdev-trinity <batch_id> --phase plan (the default phase — see .claude/skills/specdev-trinity/SKILL.md).

Version Update & Migration

# Sync to current toolkit version (re-stamp or direct to align)
specdev update spec --repo-root ./devspec_toolkit

# Preview what update would do without writing any files
specdev update spec --repo-root ./devspec_toolkit --dry-run

update flags:

Flag	Required	Description
`spec_dir`	Yes	Path to the project `spec/` directory (positional)
`--repo-root REPO_ROOT`	No	Toolkit root directory. Default: cwd (`.`)
`--dry-run`	No	Report what would be done without writing any files. The re-stamp path reports `update_status: would_update` (no write); a migration-requiring diff reports `needs_migration`
`--json`	No	Emit a JSON envelope (`status`, `update_status`, `from_version`, `to_version`, `dry_run`, …) instead of plain text

When specdev update reports schema changes, run the migration workflow first:

# Check status of spec vs toolkit version
specdev align status spec --repo-root ./devspec_toolkit

# Show diff of what needs to change
specdev align diff spec --repo-root ./devspec_toolkit

# Generate an execution plan
specdev align plan spec --repo-root ./devspec_toolkit

# Apply mechanical fixes (auto-mode)
specdev align apply spec --auto --repo-root ./devspec_toolkit

# Generate prompts for AI-assisted migration
specdev align prompts spec --output prompts/migration/ --mode upgrade --repo-root ./devspec_toolkit

# Finalize: full post-migration validation + version stamp (with migration history)
specdev align validate spec --repo-root ./devspec_toolkit

# Restore spec/ from a migration backup (non-interactive)
specdev align rollback spec --repo-root ./devspec_toolkit --backup-dir <backup-name> --yes

Finalize a migration with align validate, not by re-running specdev update. validate stamps spec/specdev_version only after schema + trace-integrity checks pass and records a migration_history entry; update re-stamps after a weaker structural-diff check and omits the audit trail.

align rollback restores spec/ from a backup in spec/migration_backups/. Without --backup-dir it lists available backups and prompts interactively for a selection — --yes alone does not make this non-interactive-safe; it only skips the early guard and the final confirmation prompt, not the backup-selection input() call, which still raises on non-interactive stdin. Pass --backup-dir <name> as well to bypass interactive backup selection entirely and restore that backup directly. --json is not yet supported for this action.

Step-Specific Verification

For deep validation of specific steps (DAGs, cycles, logic), use pytest to run the dedicated integration tests:

pytest devspec_toolkit/tests/integration/test_step_02.py --spec spec/02_system_sketch.json -v
pytest devspec_toolkit/tests/integration/test_step_12.py --spec tests/fixtures/step_12/valid_dag.json -v
pytest devspec_toolkit/tests/integration/test_step_15.py --spec tests/fixtures/step_15/valid_full.json -v

For Step 13a, generate spec/13a_completeness_assessment.json via prompts/prompt_13a_completeness_assessment.md and validate it like any other artifact:

./tools/run_specdev.sh validate spec/13a_completeness_assessment.json --repo-root ./devspec_toolkit

Invoke commands from the root of your host repository so relative paths to spec/ and ./devspec_toolkit/ resolve cleanly.

Strict Execution Policy

Workflow is forward-only.
There is no refinement mode.
Any accepted upstream change requires full replay of all downstream steps before merge.
In strict mode, host-repo CI should run quality, hallucination, dependency-order, and replay checks as blocking gates.

Two-Phase AI Runner Mode

Prompts support a two-phase flow: Clarify (questions only) → Emit (disk-first JSON artifact write).
Agents follow the prompt’s “Operating Flow”, apply the “Self‑Audit Gate”, and ask targeted questions if gating items are missing. Agents read the “Context To Ingest” section for steps that include it; steps that use “Coverage Closure” apply that section instead.
Runners should honor the manifest interaction hints: see docs/agents/manifest.json (interaction_mode: two_phase).
Operational guidance for agents and runner tips: docs/agents/agents.md.

Validation Workflow

Edit the JSON artifact.
Run validate.
Run seed-lint to ensure required seed context is referenced and current.
If any traceability changed, regenerate the matrix and lint fixtures.
Update governance-compliant commit messages per spec/10_governance.json.

Troubleshooting Checklist

Schema not found: run from repo root or configure --repo-root; confirm tools/schema_registry.json.
Unknown Target in fixtures: ensure the target ID (fr-*, api-*, nfr-*, inv-*) exists in the respective spec file.
Invariant evaluation null: check referenced keys in fixtures or adjust the invariant expression.
Governance rejection: match the commit pattern defined in Step 10; ensure pr_rules use allowed enum values.
Glossary failures:
- minItems error: Ensure terms array has at least one item.
- minLength error: Definitions must be >20 chars.
- pattern error: Check domain (kebab-case) and units (alphanumeric/slash) formats. no empty strings allowed.
Implementation Plan failures:
- tech_stack error: Ensure it is an object, not an array.
- milestones error: Ensure every milestone has a deliverables array linkage.
Red Team (Step 11) failures:
- target_ids error: Threats must target an API or Component.
- mitigations error: Must be structured objects, not strings.
Scaffold (Step 15) failures:
- method error: Must be one of GET, POST, PUT, DELETE, PATCH, OPTIONS, HEAD.
- duplicate api_ref: Each API Contract can only be mapped once.
Canon/schema alignment failures (canon-schema-alignment); see error-codes.md for the authoritative E551-E554 definitions:
- E554 CANON_ENUM_DRIFT: Canon kind has entries missing from the paired schema enum.
- E551 SCHEMA_ENUM_EXTRA: Schema enum has values not present in the paired canon kind.
- E552 MISSING_PAIRED_SCHEMA: Schema file referenced in pairing config not found.
- E553 MISSING_ENUM_PATH: JSON path referenced in pairing config not found in schema.
- W552 POTENTIAL_UNREGISTERED_PAIRING: Unregistered schema enum has high overlap (>=80%) with a canon kind; consider adding an explicit pairing.

Architecture Notes

`trace_types.py` (dynamic loading)

trace_types.py now loads valid trace types from canon/kinds/trace_type.json via CanonicalRegistry at import time. If canon loading fails for any reason, it falls back to a hardcoded set of types and aliases. This keeps the canonical registry as the single source of truth while maintaining resilience.

`step_order.json` schema changes

The step_metadata field has been removed.
A downstream_consumers field has been added. It maps each step ID to a list of step IDs that directly consume its output (e.g., "04": ["05", "06", ...]). This replaces the extraction-intent data previously stored in step_metadata and is used by the prompt-context command.

`prompt-context` output format

The prompt-context command now outputs a 2-column table (Step, Name) instead of the previous 3-column format (Step, Name, Extraction Intent). Consumer lists are derived from the downstream_consumers field in step_order.json.

Related Resources

index.md — Navigational overview of every document set.
getting_started.md — Single-path onboarding for new team members.
workflows/discovery.md & workflows/spec_to_impl.md — Conceptual phase breakdowns.
tooling/coverage_matrix.md — How traceability is enforced.
../agents/agents.md — Automation contract used by AI assistants.

FilesExpand file tree

reference.md

Latest commit

History