Skip to content

0012 - 1.0 Stability

Context

archfit has completed Phase 0 (integrity), Phase 1 (coverage), and the key Phase 2 deliverables (PR mode, stratified verification, parallel execution). All 17 rules have been tested with positive + negative fixtures, run against CI, and promoted to stability: stable. The output schema has been validated by a conformance test since 0.2.0.

It is time to declare what 1.0 freezes.

Decision

Frozen from 1.0.0 onward

Changes to any item below require a major version bump (2.0.0) and a migration guide.

1. Rule IDs in core and agent-tool packs: - 14 core rules: P1.LOC.001–004, P2.SPC.001, P3.EXP.001, P4.VER.001–003, P5.AGG.001–002, P6.REV.001–002, P7.MRD.001 - 3 agent-tool rules: P2.SPC.010, P7.MRD.002, P7.MRD.003 - IDs may not be renumbered or repurposed. New rules get new IDs. - Severity may be changed with an ADR (not silently).

2. JSON output schema (schemas/output.schema.json): - Required fields: schema_version, tool, target, summary, scores, findings, metrics - Finding fields: rule_id, principle, severity, evidence_strength, confidence, path, message, evidence, remediation - No field may be removed, renamed, or retyped. 1.x minors may add optional fields. - Ordering: findings[] sorted by severity desc → rule_id asc → path asc.

3. Exit codes: - 0: success / findings below threshold - 1: findings at/above --fail-on / contract hard violation - 2: usage error - 3: runtime error - 4: configuration error - 5: contract soft target missed

4. CLI subcommands: scan, check, score, report, diff, pr-check, fix, trend, compare, explain, init, list-rules, list-packs, validate-config, contract, version, help. Names may not be renamed or removed.

5. CLI flags: --format, --json, --fail-on, --config, --depth, --policy, -C, --with-llm, --llm-backend, --llm-budget, --record. Names may not be renamed or removed.

6. Config schema: version: 1. The version field must remain 1 until a breaking config change. New optional fields may be added.

Not frozen (internal)

  • Resolver implementations (detection logic, keyword lists, thresholds)
  • Collector internals
  • Pack registration order
  • Go package layout
  • LLM model defaults
  • Metric names (informational, not contractual)

Consequences

  • Any new rule in core or agent-tool must use a new ID.
  • Changing a rule's severity requires an ADR.
  • The TestStability_AllRulesAreStable CI test enforces the freeze.
  • Output consumers can rely on field presence and types.
  • The migration guide at docs/migration/0.x-to-1.0.md documents the full delta from 0.1.0.