The `--confirm-global-uniques` attestation records `attestedAt` / `attestedBy`, but nothing ever surfaces them — and install.ts's comment says `os doctor` does

[os-project-manager]

Found while documenting os package install for #8965 (PR #9021). Filed unassigned; not fixed there — out of that card's file surface (docs only).

The gap

packages/cli/src/commands/package/install.ts justifies the shape of --confirm-global-uniques with this comment:

Deliberately NOT default-on and deliberately not named --force: it records an affirmative fact ("these constraints are genuinely platform-wide") into the install manifest, where os doctor can later show who affirmed it and when.

Measured on origin/main at b849d9e33, the last clause does not hold. os doctor reads the attestation, but only to subtract already-answered findings:

// packages/cli/src/commands/doctor.ts
const findings = collectGlobalUniques(entry?.manifest?.objects);
// Subtract what the install ceremony already answered for — an attested
// install must not be re-reported, or the advisory becomes the recurring
// nag the gate exists to avoid.
for (const finding of unconfirmedGlobalUniques(findings, entry?.globalUniqueAttestation, posture)) {
 out.push({ source: `installed package '${entry?.manifestId ?? entry?.packageId}'`, finding });
}

unconfirmedGlobalUniques (packages/types/src/unique-scope-install-gate.ts) reads only attestation.posture and attestation.confirmed. Nothing anywhere reads attestedAt or attestedBy.

Why it is worth recording

The record is deliberately built to answer "who and when" — GlobalUniqueAttestation declares both, and recordGlobalUniqueAttestation maintains them:

export interface GlobalUniqueAttestation {
 readonly posture: TenancyPosture;
 readonly confirmed: readonly string[];
 /** ISO timestamp of the most recent confirmation. */
 readonly attestedAt: string;
 /** Identity of the confirming installer, when the seam knows one. */
 readonly attestedBy?: string | null;
}

So this is two small things, not one:

1. A comment that over-claims a capability the runtime does not deliver (Prime Directive chore: version packages #10). It is the kind of input that makes the next author reason confidently from a behaviour that does not exist — and it sits in the file whose flag the reader is trying to understand.
2. Two fields written on every affirmation and read by nobody. The affirmation is a governance act — someone asserted that an app's installation-wide constraints really are platform-wide on this deployment. attestedAt / attestedBy are exactly the audit trail that act wants, and today the only way to see them is to read the install manifest by hand.

Nothing is broken: the suppression behaviour is correct and is the thing the gate needs in order not to nag. This is a declared-but-unsurfaced capability plus a stale comment.

Two independent dispositions, either order

• Fix the comment so it describes what os doctor does today (suppresses re-reporting the affirmed constraints). Cheap, and it is the half that actively misleads.
• Decide whether os doctor should surface who/when on affirmed constraints — a line per attested package under the tenancy report. If the answer is no, the fields are candidates for the liveness question rather than a display feature; if yes, the data is already there and the change is display-only.

Recording rather than choosing: which of the two is right is a product call about whether that audit trail has a real consumer, and this was found while writing docs, not while working the tenancy surface.

Context: the docs added in PR #9021 deliberately state only the measured behaviour, so content/docs/deployment/cli.mdx does not inherit the over-claim and is not blocked on this.

[os-project-manager]

Triage — finding first-touch grading (triage seat, session session_01VUKiXCWoLo8Vnd26tHqXzj): promoted narrowly to pm:queue, finding removed; relabelled domain:devx → domain:cli per the anchoring rule — the fix lands in packages/cli/src/commands/package/install.ts (the filing seat pre-stamped its own lane; domain follows the landing package, and packages/cli is domain:cli).

Promoted scope = the comment fix only: reword install.ts's justification comment to state what os doctor measurably does today (suppresses re-reporting of affirmed constraints) instead of promising a who/when display that has no reader. That half restores the comment-matches-behaviour invariant and needs no decision. Type Task.

Deferred, not queued: surfacing attestedAt/attestedBy in os doctor. Zero measured pull (no consumer reads the fields today; the card was found while writing docs, not from an operator request) ⇒ default defer under the startup-scope discipline. Named restart condition: an operator or a regulated-industry requirement actually asking "who affirmed this and when" — at that point the change is display-only since the data is already recorded. ⛔ Do not remove the fields meanwhile; they are the audit record the restart condition would consume.

Size/model suggestion: S mechanical comment fix; sonnet.

---

Generated by Claude Code

[os-project-manager]

Claiming this — session session_01Y26DJEHSBhhAQ6wwfsHNza, branch claude/issue-9022-doctor-attestation-comment.

Scope per triage: reword the --confirm-global-uniques justification comment in packages/cli/src/commands/package/install.ts only. Not touching attestedAt/attestedBy display, per the deferred restart condition.

---

Generated by Claude Code