Skip to content

docs: x-FuSa spec v1.14.0 — detection heuristics, attestation, traceability MUSTs, coverage metrics - #83

Merged
SoundMatt merged 1 commit into
mainfrom
spec-artifact-attestation-enforcement
Jul 28, 2026
Merged

SoundMatt merged 1 commit into
mainfrom
spec-artifact-attestation-enforcement

Conversation

@SoundMatt

Copy link
Copy Markdown
Owner

Summary

Follows directly from v1.13.0 (evidence-artifact schemas + content-quality baseline). That release said what good content looks like but left it unenforceable — no detection algorithm, no accountability, no required traceability, no completeness metric. This closes those four gaps.

1. §1.6.1 Detection heuristics — concrete, checkable rules instead of prose:

  • Rule A (placeholder text) — deny-list match, always an ERROR (FUSA-STUB001), disposition-suppressible only.
  • Rule B (blanket qualitative fallback) — distinct-value-ratio < 0.1 across ≥10 entries, a WARNING (FUSA-STUB002) by default, deliberately advisory since a similarity score can misfire on genuinely repetitive-but-real content.

2. §1.6.2 Attestation — the false-flag fix. Rather than trying to make the heuristic perfectly precise, an artifact can carry an optional attestation object (status, implementationAuthor, independentReviewer, reviewedAt, contentHash) reusing the exact independence model already in FuSaOps' own vv package (ISO 26262-2:2018 §6.4). A non-stale (hash-pinned), genuinely-independent "reviewed" attestation suppresses Rule B. --strict/--require-attestation escalates an unsuppressed Rule B finding to exit 1. This is the DCO pattern applied to evidence artifacts: nothing blocks by default, a project that wants a hard gate turns it on, and the gate is satisfied by an honest human assertion, not by gaming the similarity score.

3. Traceability MUST — .fusa-hara.json's safetyGoals[].fssrRef promoted from SHOULD (singular) to fssrRefs MUST, ≥1 entry — a safety goal with no decomposing requirement is exactly the gap ISO 26262-8 Clause 6 traceability exists to prevent.

4. Completeness metrics — fmea/tara gain summary.coveragePct + --min-coverage N, mirroring trace --func-coverage, so an artifact can't quietly analyze 5 convenient cases while looking thorough by entry count alone.

SpecVersion bumped 1.13.0 → 1.14.0. Scope note (unchanged from v1.13.0): spec-design only, no tool implements any of this yet, FuSaOps doesn't consume it.

Test plan

  • go build ./... / go vet ./... — clean
  • go test ./... — all packages pass
  • Manual diff review — doc-only change plus the two version constants

…bility MUSTs, coverage metrics

Closes the enforcement gap left by v1.13.0: schemas and a
content-quality baseline existed but had no detection algorithm, no
accountability mechanism, no required traceability, and no
completeness metric.

- §1.6.1 Detection heuristics: concrete placeholder-text (always
  ERROR, disposition-suppressible) and blanket-qualitative-fallback
  (advisory WARNING) rules, flowing through the existing Finding/
  fingerprint/disposition machinery.
- §1.6.2 Attestation: a DCO-style mechanism reusing the vv package's
  independent-reviewer model, so an imperfect similarity heuristic
  doesn't produce false-positive gates -- a named independent reviewer
  can vouch for content instead.
- .fusa-hara.json: safetyGoals[].fssrRef promoted SHOULD -> fssrRefs
  MUST (>=1 entry), closing a real ISO 26262-8 Clause 6 traceability
  gap.
- fmea/tara: new summary.coveragePct + --min-coverage N, mirroring
  trace --func-coverage, so these artifacts can't quietly analyze only
  the easy cases.

Bumps SpecVersion 1.13.0 -> 1.14.0.

Signed-off-by: SoundMatt <SoundMatt@users.noreply.github.com>
@SoundMatt
SoundMatt merged commit 4ffeedc into main Jul 28, 2026
13 checks passed
@SoundMatt
SoundMatt deleted the spec-artifact-attestation-enforcement branch July 28, 2026 18:12
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant