docs(spec): reconcile the feature 010 defects found during implementation

[mbeacom]

Fifteen defects found by the four implementation sessions reading the specs against each other and against the ADRs. Every one is in an artifact the planning work produced, not in the implementations. Specs only — no code, no task text beyond the corrections described here.

The serious one

contracts/admissibility.md §2 gave metadata.namespace the same character class as metadata.name — [A-Za-z0-9] plus -, _, ..

ADR-0015 binds it through CommonValidatorFunctions.isValidDnsLabel, /^[a-z0-9]+(?:\-+[a-z0-9]+)*$/ — no uppercase, no underscore, no dot. An implementation written to my summary would have silently admitted namespaces the pinned validator rejects, and then canonicalized them: exactly the defect ADR-0015 exists to prevent.

Phase D followed the ADR over the contract, per FR-016's "exactly the four field validators in ADR-0015's table". Verified empirically rather than by reading:

validateNamespace('Default') = false   ✓
validateNamespace('a_b')     = false   ✓
validateNamespace('default') = true    ✓

The contract now matches the code, and carries the discriminating assertion so the error can't recur silently.

Two more of the same shape

• data-model.md §4's AdmissibilityField was wrong in both directions — it omitted apiVersion, which ADR-0015 requires, and added spec.type, which no validator in that table covers.
• §3's DescriptorDocument omitted apiVersion entirely, so a record built to spec could not be admissibility-checked at all. Now carries rawApiVersion and raw.

provenance gets a closed domain

upstream-authored | maintainer-overlay, decided by the maintainer. It previously typed as a bare string while consumer step 2 required "a recognized provenance" — an unsatisfiable pairing that blocked Phase E.

The semantics needed care: under ADR-0020 clause 5 the descriptors are upstream-authored in both cases, so the value describes the annotation's provenance, not the descriptor's. It also doubles as a live adoption signal — zero third-party descriptors carry the annotation today, so upstream-authored only becomes reachable if real adoption occurs.

Five steps, three reasons

T058, T062 and SC-006 all conflated decode steps with rejection reasons. The frozen contract defines five steps but three reasons: step 1 yields the annotation-absent state rather than a rejection, and step 5 delegates to the glob dialect (SC-007's territory).

Phase D left both tasks unchecked rather than manufacture two reasons no contract froze. All three artifacts now say five steps, three reasons, and name them.

Four carried-forward conflicts, resolved without editing spike 009

Recorded in contracts/README.md §4, since spike 009 stays frozen: the namespace class, the unrecognized-manifest-field trigger class, path-validation stage 1's unnamed trigger, and requiredCapabilities arity.

§4.5 records the one place transcription from ADR-0015 was insufficient — the table gives isValidDnsSubdomain's bounds but never its per-label character class — and labels the composition an inference, not a transcription. It's a candidate for an ADR-0015 addendum.

Line numbers → reason strings

Phase A's own allowlist additions shifted both check-deps guards by 41 lines, silently invalidating every citation in tasks.md and in normative package-boundary.md §4.

All citations now name the emitted reason string. A line number is a reference nothing checks; a reason string is asserted verbatim by the test suite, so a stale citation fails the build rather than quietly misleading a reader. The rule is written into the contract as §5.

Also

• T013 now creates negative-cases/ and states it is a shared cross-phase tree whose per-task subdirectories are what make it safe for concurrent worktrees. No task created it before, despite ~20 tasks depositing into it.
• T027 gains a tenth fixture — the all-annotation-absent acceptance case required by snapshot-envelope.md §7 row 1b. Without it the set contains only rejections and cannot prove the validator does not over-reject.
• T009 records that check:deps structurally cannot see schema/ (no package.json, so readWorkspacePackages() never visits it). That clause is held by the isolated linker and observed via typecheck. SC-015 is still discharged, because it requires "the isolation check" to fail — but the deviation is named, not smoothed.
• T100 must match claims, not vocabulary. ADR-0014's terms are binding, so the most honest phrasing — "not reference-verified (rung 2)" — contains the exact strings a naive grep would flag. A check failing on bare occurrence punishes the most honest documentation and rewards silence.

Checks

bun test 1495 pass / 0 fail · typecheck clean · check:deps → core-has-no-adapter-deps: ok · adr lint 20 records, 0 errors.

Still open, and deliberately not decided here

• The barrier branch (mbeacom-t019-independent-audit @ c8e47dd) cannot be pushed by this session — T022 wires the drift check into .github/workflows/ci.yml and the token lacks workflow scope. Only that one commit is affected.
• D9: whether reading node_modules/picomatch/package.json from disk is the intended way to satisfy T063's "read at runtime, never transcribed" without tripping Phase A's import.meta.resolve ban.
• D10: Phase A's source-scan.ts importSpecifiers heuristic false-positives — it read the string 'bulk-import' as an import. Tighten it, or extend EXCLUDED_FROM_SCAN.
• The locality-guard conflict between Phase A's scan and T026/T037.

Standing: ADR-0014 rung 1 only. No rung-2 or rung-3 claim, no release scheduled or prepared. ADR-0012 gate 3 open; gate 4 unmet and not yet testable.

[Copilot]

Pull request overview

Reconciles feature 010 specifications with ADRs and implementation findings.

Changes:

• Corrects admissibility fields and namespace validation.
• Defines annotation provenance and contract precedence.
• Updates validation tasks, fixtures, and dependency-guard citations.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
tasks.md	Revises implementation and evidence tasks.
spec.md	Clarifies annotation decoding criteria.
data-model.md	Updates descriptor, admissibility, and provenance models.
contracts/README.md	Records carried-forward contract conflicts.
contracts/package-boundary.md	Replaces line-number guard citations.
contracts/admissibility.md	Corrects namespace validation rules.