[v1 readiness][kratos] CLI/report contract freeze and schema evidence

[JeremyDev87]

[v1 readiness][kratos] CLI/report contract freeze and schema evidence

Goal

Freeze the v1 CLI/report contract before any version bump so scan, report, diff, and clean have stable output, exit, and schema semantics.

Source of Truth

• Parent epic: [v1 readiness] Kratos release gate epic (no version bump) #90
• Repo: JeremyDev87/kratos
• Parent implementation plan artifact: /Users/pjw/.hermes/thread-workcells/discord/282499436049858561/1508085811139051580/TASKS/v1-ddplan-issues/IMPLEMENTATION_PLAN.md
• Version bump, tag, publish, CI dispatch, branch, commit, and PR creation are out of scope for this issue.

Wiki Context Manifest

• Queries attempted: frontend evidence gates release evidence contract, code is not cheap AI maintenance cost ratio, alex core invariants SSoT No Silent Fallback idempotency, 12-factor agents runtime contract event log release workflow, overeager coding agents task scope destructive action, prompt assets skill issue planning evidence
• Wiki sources read: [wiki: frontend/evidence-gates.md], [wiki: principles/code-is-not-cheap.md], [wiki: principles/alex-core-invariants.md], [wiki: harness-engineering/12-factor-agents-runtime-contract.md], [wiki: harness-engineering/overeager-coding-agents-scope-contract.md], [wiki: harness-engineering/prompt-assets.md], [wiki: raw/2026-05-24-ai-maintenance-cost-ratio-source-map.md]
• Relevant wiki facts: v1 readiness requires artifact/runtime/evidence bundles, not only test-green; release and wrapper flows must preserve SSoT, atomicity, idempotency, and No Silent Fallback; destructive or fix-like commands need task-scope/evidence gates; AI-generated velocity must lower future maintenance cost rather than add broad v1 scope.
• remember-wiki applicability / skip reason: skipped; target repos are JeremyDev87/* personal CLI repos, not Remember/dramancompany repos.
• Non-wiki inference: repo-specific split below is based on live local repo docs/config/workflows and npm registry checks performed before issue creation.

Quality Lens Router Output

• Applicable gate families:
  • evidence-contract: v1 readiness, package install, CLI output, release/publish, and fallback claims need concrete proof.
  • simplicity-deletability: v1 work must prefer contract/evidence gaps over broad new features or nonessential abstractions.
  • tdd-systematic-debugging: false-positive, fallback, exit-code, and packaging regressions should be fixture/test-backed.
• Skipped gates:
  • frontend-design: not-applicable; CLI/runtime/docs work only.
  • vercel-agent-skills: not-applicable; no React/Next/Vercel/mobile surface.
  • deploy-token-safety: limited; no token/deploy mutation in this issue, only release credential evidence requirements.

Evidence Contract

• Required evidence:
  • Candidate SHA/version alignment evidence when a candidate is selected.
  • Repo test evidence plus source CLI smoke.
  • npm pack / packed-install evidence for the user-consumed artifact.
  • Release workflow/check/dist-tag/GitHub Release evidence where release automation is touched.
  • Explicit fallback/unsupported-platform evidence where wrapper/native-runtime selection is touched.
• Evidence not applicable:
  • Browser screenshot/DOM: not-applicable, CLI repos.
  • Production URL: not-applicable, npm/GitHub release surface only.
• Blocking evidence gaps:
  • Final v1 version bump/tag is intentionally out of scope for this issue set.

Owned files / likely touched areas

• crates/kratos-core/src/report*
• crates/kratos-cli/src/commands/report.rs
• crates/kratos-cli/src/commands/scan.rs
• crates/kratos-cli/tests/**
• crates/kratos-core/tests/**
• docs/plans/** if used for contract notes

Inspect-only files

• README*.md
• CONTRIBUTING.md
• package.json
• .github/workflows/**

Must not touch

• package version bump files except if tests need read-only inspection
• release tags
• publish workflows dispatch

Implementation steps

1. Inventory current command help/output/exit behavior.
2. Define schemaVersion and report field stability notes.
3. Add or update focused contract tests for summary/json/md and existing diff/clean behavior.
4. Record any intentionally deferred v1.1+ behavior instead of silently changing output.

Parallelization note

Can run in parallel with packaging/release audit if it avoids workflow and README files.

Dependencies / blocked by

Parent only; can run before other Kratos child issues.

Validation / evidence required

• cargo test --workspace
• npm run verify
• direct CLI smoke for scan/report/diff/clean where available

Completion criteria

• Required validation evidence is pasted into the PR body or final issue comment.
• No v1 version bump/tag/publish is performed.
• If any required evidence is unavailable, the issue remains open with the gap classified as Medium/High rather than being marked complete.

[JeremyDev87]

ddalggak 계획

라이브 이슈/레포 근거:

• 이슈 #91은 scan, report, diff, clean의 v1 CLI/리포트 계약을 동결하고 schema evidence를 남기는 것이 목표입니다.
• 열린 PR은 현재 없습니다.
• 현재 코드에는 schemaVersion: 2 직렬화/파싱과 summary/md/json CLI smoke가 이미 있으나, v1 계약을 한 곳에서 검증 가능한 문서/상수로 고정하는 증거가 부족합니다.
• 작업 범위는 허용된 crates/kratos-core/src/report*, CLI 테스트, core 테스트, docs/plans/** 안으로 제한하고 버전/태그/릴리스 파일은 건드리지 않겠습니다.

구현 계획:

1. 리포트 JSON v1 소비자 계약(스키마 버전, 최상위 키, summary/findings/graph 키, CLI 출력/exit semantics)을 코드/문서로 명시합니다.
2. serializer가 그 계약 상수를 사용하도록 하여 schema key drift를 줄입니다.
3. core/CLI contract 테스트를 추가해 scan/report/diff/clean의 안정 출력과 에러/성공 exit code를 증거로 남깁니다.
4. cargo test --workspace, npm run verify, 직접 CLI smoke로 검증 후 draft PR을 만들고 독립 리뷰 코멘트를 남기겠습니다.