ccqa 1.31.4 → 1.32.0

package/dist/bin/ccqa.mjs

@@ -4775,6 +4775,18 @@ const PerspectiveStatusSchema = z.object({
 	target: z.string().min(1).optional()
 }).strip();
 /**
+* One step of a spec, transcribed verbatim for display. Exactly one shape per
+* step: an include step carries the block name it invokes (its params stay in
+* the spec — they are wiring, not procedure), an action step carries the
+* instruction and what it expects. Never authored or reworded here: like
+* `title`, this is a mechanical copy the next `ccqa perspectives` rewrites.
+*/
+const PerspectiveStepSchema = z.object({
+	include: z.string().min(1).optional(),
+	instruction: z.string().optional(),
+	expected: z.string().optional()
+}).strip();
+/**
 * One test case in the inventory.
 *
 * - `title` is transcribed verbatim from the spec.yaml.
@@ -4786,11 +4798,12 @@ const PerspectiveStatusSchema = z.object({
 *   steps (the opening screen, the state the test assumes, and the setup
 *   prerequisites such as which role logs in). Optional: a spec may not
 *   express all of them.
+* - `steps` is the procedure itself, transcribed verbatim (never authored —
+*   see PerspectiveStepSchema) so the hub UI can show a case in full without
+*   a repo checkout. The spec.yaml stays the single source of truth: this
+*   copy is rewritten wholesale every time the inventory is regenerated, the
+*   same way `title` is.
 * - `note` is a human-only field. Regenerating perspectives preserves it.
-*
-* The detailed test procedure and expected results are deliberately NOT
-* duplicated here — the spec.yaml steps are the single source of truth for
-* those. The Markdown view links back to the spec instead of restating them.
 */
 const PerspectiveSpecSchema = z.object({
 	specName: z.string().min(1),
@@ -4799,6 +4812,7 @@ const PerspectiveSpecSchema = z.object({
 	startScreen: z.string().optional(),
 	testCondition: z.string().optional(),
 	preconditions: z.array(z.string().min(1)).optional(),
+	steps: z.array(PerspectiveStepSchema).optional(),
 	status: PerspectiveStatusSchema,
 	changedAt: z.string().optional(),
 	note: z.string().optional()
@@ -7396,7 +7410,8 @@ const SpecVerdictSchema = z.enum([
 	"inProgress",
 	"needsRepair",
 	"rerunNeeded",
-	"verified"
+	"verified",
+	"manuallyVerified"
 ]);
 /**
 * Which hole in the deploy log made the hub assume a deploy reached this spec
@@ -7452,6 +7467,57 @@ z.object({
 /** Body of `DELETE /projects/:project/locks?profile=`. */
 const ReleaseLocksRequestSchema = z.object({ holder: z.string().min(1) });
 /**
+* A person's word that they checked a spec's behaviour by hand against the
+* deployed environment. It overrides the verdict, never the ledgers: the
+* drift entry that parked the spec stays open, so the repair loop keeps its
+* reason to fix the test, while the verdict stops asking a person for what a
+* person already did.
+*
+* Anchored to the deploy head at the moment it was recorded, so it lapses on
+* its own — a deploy reaching the spec, or the spec being edited, ends its
+* coverage the same way those end a run's (ADR-0010). One per spec: a new
+* attestation replaces the previous one.
+*/
+const AttestationSchema = z.object({
+	by: z.string().min(1),
+	at: z.string(),
+	note: z.string().optional(),
+	deployedSha: z.string().nullable()
+});
+/** The per-(project, profile) attestation document: "feature/spec" → the standing attestation. */
+const AttestationsSchema = z.object({ specs: z.record(z.string(), AttestationSchema).default({}) });
+/**
+* Why an attestation stopped covering the spec. One reason is named even when
+* several hold, in the order the checks run (coverage, then the spec's own
+* edits, then a later red run) — enough for a reader to see what to verify
+* before attesting again.
+*/
+const AttestationLapseSchema = z.enum([
+	"deployReached",
+	"cannotPlace",
+	"specEdited",
+	"newerRed"
+]);
+/** Body of `PUT /projects/:project/attestations?profile=`. */
+const PutAttestationRequestSchema = z.object({
+	spec: z.string().min(1).max(512),
+	by: z.string().min(1).max(256),
+	note: z.string().max(4e3).optional()
+});
+/** Body of `DELETE /projects/:project/attestations?profile=`. */
+const DeleteAttestationRequestSchema = z.object({ spec: z.string().min(1).max(512) });
+z.object({
+	project: z.string(),
+	profile: z.string(),
+	spec: z.string(),
+	attestation: AttestationSchema
+});
+z.object({
+	project: z.string(),
+	profile: z.string(),
+	specs: z.record(z.string(), AttestationSchema)
+});
+/**
 * One spec's verdict, the two axes it was derived from, and the three ledger
 * coordinates the view shows alongside them. The coordinates are always
 * present (null when the spec has no such entry); the optional fields appear
@@ -7469,6 +7535,10 @@ const SpecRerunSchema = z.object({
 	auditAssumedReached: RerunUnknownReasonSchema.optional(),
 	executionAssumedReached: RerunUnknownReasonSchema.optional(),
 	specChangedSince: z.string().optional(),
+	manual: AttestationSchema.optional(),
+	manualLapsed: AttestationSchema.extend({ because: AttestationLapseSchema }).optional(),
+	manualLapsedByDeploy: DeployRefSchema.nullable().optional(),
+	manualLapsedReason: RerunUnknownReasonSchema.optional(),
 	heldBy: SpecLockSchema.nullable(),
 	lastRun: SpecLedgerEntrySchema.nullable(),
 	lastGreen: SpecLedgerEntrySchema.nullable(),
@@ -7711,7 +7781,7 @@ async function fetchRerunReport(hubCtx, profile) {
 		throw new RunUsageError(`--only-hub-rerun-needed: could not ask the hub which specs need a re-run: ${errMessage(err)}`);
 	}
 	const parsed = RerunReportSchema.safeParse(report);
-	if (!parsed.success) throw new RunUsageError(`${FLAG$1}: this hub's re-run answer is not in a shape this ccqa understands — it is likely older than this CLI. Upgrade the hub, or select with --only-affected-by <ref> instead.`);
+	if (!parsed.success) throw new RunUsageError(`${FLAG$1}: this hub's re-run answer is not in a shape this ccqa understands — the hub and this CLI are on different versions, and either side being newer can cause it (a newer hub may answer with verdicts this CLI does not know). Align the two, or select with --only-affected-by <ref> instead.`);
 	report = parsed.data;
 	if (report.deployHead === null) throw new RunUsageError(`--only-hub-rerun-needed: no deploy has been recorded for profile "${profile}" of project "${hubCtx.project}", so nothing can be compared against. Wire \`ccqa hub deploy record\` into the deploy job, or select with --only-affected-by <ref> instead.`);
 	return {
@@ -7723,7 +7793,8 @@ const SUMMARY_ORDER$1 = rankedOrder({
 	needsRepair: 0,
 	rerunNeeded: 1,
 	inProgress: 2,
-	verified: 3
+	manuallyVerified: 3,
+	verified: 4
 });
 /**
 * Narrow `specs` to the ones the hub says are worth running.
@@ -7733,7 +7804,9 @@ const SUMMARY_ORDER$1 = rankedOrder({
 * cannot vouch for, are both as uncovered as one a deploy demonstrably
 * invalidated (ADR-0014). `needsRepair`, `inProgress` and `verified` are never
 * selected: running them repairs nothing, races something already in flight,
-* or repeats work that is still current.
+* or repeats work that is still current. `manuallyVerified` is never selected
+* either — the test is still the broken one the attestation stands in for,
+* and running it would only relabel a person's answer with a machine failure.
 */
 function selectSpecsNeedingRerun(specs, report) {
 	const counts = /* @__PURE__ */ new Map();
@@ -9518,7 +9591,37 @@ const pushCommand = new Command("push").description("Upload the report directory
 	meta("specs", `${run.specs.passed}/${run.specs.total} passed`);
 	info(`${resolveBaseUrl(opts)}/#/runs/${run.id}`);
 }));
-const hubCommand = new Command("hub").description("Client for a ccqa hub: push run results and manage sessions/variables/prompts used by `ccqa run`. See docs/hub.md.").addCommand(pushCommand).addCommand(deployCommand).addCommand(costCommand).addCommand(sessionCommand).addCommand(varCommand).addCommand(promptCommand);
+const attestCommand = new Command("attest").argument("<feature/spec>", "Spec id, e.g. checkout/happy-path").description("Record that a person checked a spec's behaviour by hand against the deployed environment. The verdict answers manuallyVerified instead of asking a person for what a person already did — the drift ledger is untouched, so the repair loop keeps its reason to fix the test. The attestation lapses on its own when a deploy reaches the spec or the spec is edited.").requiredOption("--profile <name>", "Environment that was checked (e.g. 'stg'). The attestation is anchored to its current deploy head.").option("--by <name>", "Who checked. Required unless --revoke.").option("--note <text>", "What was checked and how — the reader deciding whether to trust it sees this.").option("--revoke", "Withdraw the spec's attestation instead of recording one.").option(...hubUrlOption).option(...hubTokenOption).option("--project <name>", "Hub project. Defaults to the current directory's name.").option("--cwd <path>", "Directory the default --project name is resolved against.").action(withHubErrors(async (rawSpecId, opts) => {
+	const project = resolveProject(opts);
+	const hub = connect(opts);
+	let specId;
+	try {
+		const parsed = parseSpecPath(rawSpecId);
+		specId = `${parsed.featureName}/${parsed.specName}`;
+	} catch (err) {
+		error(errMessage(err));
+		process.exit(2);
+	}
+	if (opts.revoke) {
+		await hub.deleteAttestation(project, { profile: opts.profile }, specId);
+		header("hub attest", `${specId} revoked`);
+		return;
+	}
+	if (!opts.by) {
+		error("--by <name> is required: an attestation is a person's word, and it needs the person");
+		process.exit(2);
+	}
+	const res = await hub.putAttestation(project, { profile: opts.profile }, {
+		spec: specId,
+		by: opts.by,
+		...opts.note !== void 0 ? { note: opts.note } : {}
+	});
+	header("hub attest", specId);
+	meta("by", res.attestation.by);
+	meta("anchored to deploy", res.attestation.deployedSha ?? "(no deploy log)");
+	info("the verdict answers manuallyVerified until a deploy reaches this spec or the spec is edited");
+}));
+const hubCommand = new Command("hub").description("Client for a ccqa hub: push run results and manage sessions/variables/prompts used by `ccqa run`. See docs/hub.md.").addCommand(pushCommand).addCommand(deployCommand).addCommand(costCommand).addCommand(sessionCommand).addCommand(varCommand).addCommand(promptCommand).addCommand(attestCommand);
 /** Loose check that a fetched session is agent-browser storage-state, mirroring loadStorageState. */
 function isStorageStateShape(state) {
 	return typeof state === "object" && state !== null && Array.isArray(state.cookies) && Array.isArray(state.origins);
@@ -17154,6 +17257,7 @@ async function buildSkeleton(tree) {
 				specName: s.specName,
 				title: meta.title,
 				summary: "",
+				...meta.steps.length > 0 ? { steps: meta.steps } : {},
 				status,
 				...lastEdit ? { changedAt: lastEdit } : {}
 			};
@@ -17227,7 +17331,8 @@ function noteKey(featureName, specName) {
 function readSpecMeta(specName, specYaml) {
 	if (specYaml === null) return {
 		title: specName,
-		mode: DEFAULT_SPEC_MODE
+		mode: DEFAULT_SPEC_MODE,
+		steps: []
 	};
 	try {
 		const parsed = parse(specYaml);
@@ -17235,16 +17340,39 @@ function readSpecMeta(specName, specYaml) {
 		const modeResult = SpecModeSchema.safeParse(parsed.mode);
 		return {
 			title,
-			mode: modeResult.success ? modeResult.data : DEFAULT_SPEC_MODE
+			mode: modeResult.success ? modeResult.data : DEFAULT_SPEC_MODE,
+			steps: transcribeSteps(parsed.steps)
 		};
 	} catch {
 		return {
 			title: specName,
-			mode: DEFAULT_SPEC_MODE
+			mode: DEFAULT_SPEC_MODE,
+			steps: []
 		};
 	}
 }
 /**
+* The spec's procedure, copied verbatim for the inventory: an include step
+* keeps only the block name (its params are wiring, not procedure), an
+* action step keeps its instruction/expected text. Anything malformed is
+* skipped — the inventory never fails over one bad step, matching how the
+* rest of this sweep treats a broken spec.
+*/
+function transcribeSteps(raw) {
+	if (!Array.isArray(raw)) return [];
+	const steps = [];
+	for (const step of raw) {
+		if (typeof step !== "object" || step === null) continue;
+		const s = step;
+		if (typeof s.include === "string" && s.include.length > 0) steps.push({ include: s.include });
+		else if (typeof s.instruction === "string" && s.instruction.length > 0) steps.push({
+			instruction: s.instruction,
+			...typeof s.expected === "string" && s.expected.length > 0 ? { expected: s.expected } : {}
+		});
+	}
+	return steps;
+}
+/**
 * Resolve a spec's generation target for coverage derivation, from its
 * already-read spec.yaml. Best-effort: an unparseable spec or a target that
 * can't be resolved (unknown id, agent-browser-only field misuse) falls back
@@ -18346,7 +18474,7 @@ function requireKey(config) {
 	return config.encryptionKey;
 }
 /** Validate the `:project`/`:profile` route params into a store scope. */
-function requireScope(ctx) {
+function requireScope$1(ctx) {
 	return {
 		project: requireSafeSegment(ctx.params.project, "project"),
 		profile: requireSafeSegment(ctx.params.profile, "profile")
@@ -18356,7 +18484,7 @@ function requireScope(ctx) {
 function createPutSessionHandler(config) {
 	return async (ctx) => {
 		const key = requireKey(config);
-		const scope = requireScope(ctx);
+		const scope = requireScope$1(ctx);
 		const name = requireSafeSegment(ctx.params.name, "name");
 		const body = await readBody(ctx.req, MAX_SECRET_BODY_BYTES);
 		const blob = encodeEncryptedBlob(encrypt(new Uint8Array(body), key));
@@ -18368,7 +18496,7 @@ function createPutSessionHandler(config) {
 /** GET /api/v1/projects/:project/sessions/:profile — metadata only (names + timestamps). */
 function createListSessionsHandler(config) {
 	return async (ctx) => {
-		const scope = requireScope(ctx);
+		const scope = requireScope$1(ctx);
 		const entries = await config.store.list(scope);
 		sendJson(ctx.res, 200, { sessions: entries.map((e) => ({
 			name: e.name,
@@ -18385,7 +18513,7 @@ function createListSessionsHandler(config) {
 function createGetSessionHandler(config) {
 	return async (ctx) => {
 		const key = requireKey(config);
-		const scope = requireScope(ctx);
+		const scope = requireScope$1(ctx);
 		const name = requireSafeSegment(ctx.params.name, "name");
 		const stored = await config.store.get(scope, name);
 		if (!stored) throw new HttpError(404, "not_found", `session "${name}" not found for ${scope.project}/${scope.profile}`);
@@ -18396,7 +18524,7 @@ function createGetSessionHandler(config) {
 /** DELETE /api/v1/projects/:project/sessions/:profile/:name */
 function createDeleteSessionHandler(config) {
 	return async (ctx) => {
-		const scope = requireScope(ctx);
+		const scope = requireScope$1(ctx);
 		const name = requireSafeSegment(ctx.params.name, "name");
 		await config.store.delete(scope, name);
 		ctx.res.statusCode = 204;
@@ -18407,7 +18535,7 @@ function createDeleteSessionHandler(config) {
 function createPutVariableHandler(config) {
 	return async (ctx) => {
 		const key = requireKey(config);
-		const scope = requireScope(ctx);
+		const scope = requireScope$1(ctx);
 		const name = requireSafeSegment(ctx.params.name, "name");
 		const body = await readBody(ctx.req, MAX_SECRET_BODY_BYTES);
 		const parsed = PutVariableRequestSchema.safeParse(JSON.parse(body.toString("utf8") || "{}"));
@@ -18427,7 +18555,7 @@ function createPutVariableHandler(config) {
 */
 function createListVariablesHandler(config) {
 	return async (ctx) => {
-		const scope = requireScope(ctx);
+		const scope = requireScope$1(ctx);
 		const includeValues = ctx.url.searchParams.get("include") === "values";
 		const key = includeValues ? requireKey(config) : config.encryptionKey;
 		const entries = await config.store.list(scope);
@@ -18462,7 +18590,7 @@ function createListVariablesHandler(config) {
 /** DELETE /api/v1/projects/:project/variables/:profile/:name */
 function createDeleteVariableHandler(config) {
 	return async (ctx) => {
-		const scope = requireScope(ctx);
+		const scope = requireScope$1(ctx);
 		const name = requireSafeSegment(ctx.params.name, "name");
 		await config.store.delete(scope, name);
 		ctx.res.statusCode = 204;
@@ -18801,7 +18929,7 @@ function createGetAuditNeedHandler(storage) {
 //#endregion
 //#region src/hub/api/handlers/locks.ts
 /** A spec-key list and three short strings; nothing here should approach this. */
-const MAX_BODY_BYTES$3 = 1024 * 1024;
+const MAX_BODY_BYTES$4 = 1024 * 1024;
 /**
 * POST /api/v1/projects/:project/locks?profile=
 *
@@ -18815,7 +18943,7 @@ function createAcquireLocksHandler(storage) {
 	return async (ctx) => {
 		const project = requireSafeSegment(ctx.params.project, "project");
 		const profile = requireProfileParam(ctx.url);
-		const body = await readJsonBody(ctx.req, MAX_BODY_BYTES$3, AcquireLocksRequestSchema, "lock request");
+		const body = await readJsonBody(ctx.req, MAX_BODY_BYTES$4, AcquireLocksRequestSchema, "lock request");
 		let result = {
 			granted: [],
 			denied: []
@@ -18844,7 +18972,7 @@ function createReleaseLocksHandler(storage) {
 	return async (ctx) => {
 		const project = requireSafeSegment(ctx.params.project, "project");
 		const profile = requireProfileParam(ctx.url);
-		const body = await readJsonBody(ctx.req, MAX_BODY_BYTES$3, ReleaseLocksRequestSchema, "release request");
+		const body = await readJsonBody(ctx.req, MAX_BODY_BYTES$4, ReleaseLocksRequestSchema, "release request");
 		await storage.locks.update(project, profile, (current) => releaseAll(current, body.holder));
 		ctx.res.writeHead(204).end();
 	};
@@ -18857,7 +18985,7 @@ function createReleaseLocksHandler(storage) {
 * 5000 keys of 256 `\uXXXX`-escaped characters — so a conforming client is
 * never answered 413 by a limit the documented bounds don't mention.
 */
-const MAX_BODY_BYTES$2 = 8 * 1024 * 1024;
+const MAX_BODY_BYTES$3 = 8 * 1024 * 1024;
 function requireAckKey(ctx) {
 	return {
 		project: requireSafeSegment(ctx.params.project, "project"),
@@ -18884,7 +19012,7 @@ function createGetAckHandler(storage) {
 function createPutAckHandler(storage) {
 	return async (ctx) => {
 		const key = requireAckKey(ctx);
-		const body = await readJsonBody(ctx.req, MAX_BODY_BYTES$2, PutAckRequestSchema, "ack body");
+		const body = await readJsonBody(ctx.req, MAX_BODY_BYTES$3, PutAckRequestSchema, "ack body");
 		const ack = await storage.acks.put(key.project, key.profile, key.name, body.keys);
 		sendJson(ctx.res, 200, {
 			...key,
@@ -18893,6 +19021,80 @@ function createPutAckHandler(storage) {
 	};
 }
 //#endregion
+//#region src/hub/api/handlers/attestations.ts
+/** Far above the largest body `PutAttestationRequestSchema`'s bounds admit. */
+const MAX_BODY_BYTES$2 = 64 * 1024;
+function requireScope(ctx) {
+	return {
+		project: requireSafeSegment(ctx.params.project, "project"),
+		profile: requireProfileParam(ctx.url)
+	};
+}
+/**
+* GET /api/v1/projects/:project/attestations?profile= — the raw document,
+* standing and lapsed alike. Whether one still covers its spec is `/rerun`'s
+* answer; this exists so a lapsed attestation can still be found and revoked.
+*/
+function createGetAttestationsHandler(storage) {
+	return async (ctx) => {
+		const scope = requireScope(ctx);
+		const doc = await storage.attestations.get(scope.project, scope.profile);
+		sendJson(ctx.res, 200, {
+			...scope,
+			specs: doc.specs
+		});
+	};
+}
+/**
+* PUT /api/v1/projects/:project/attestations?profile= — record that a person
+* checked a spec by hand. The hub stamps the time and the profile's deploy
+* head: the anchor must be what the hub knows was deployed at this moment,
+* not what the caller believes. Replaces any previous attestation for the
+* spec.
+*/
+function createPutAttestationHandler(storage) {
+	return async (ctx) => {
+		const scope = requireScope(ctx);
+		const [body, head, targets] = await Promise.all([
+			readJsonBody(ctx.req, MAX_BODY_BYTES$2, PutAttestationRequestSchema, "attestation body"),
+			storage.deploys.head(scope.project, scope.profile),
+			requireSpecTargets(storage.perspectives, scope.project, "what can be attested")
+		]);
+		if (!targets.some((target) => target.key === body.spec)) throw new HttpError(400, "unknown_spec", `spec "${body.spec}" is not in project "${scope.project}"'s perspectives document — attest with the canonical feature/spec key, or push \`ccqa perspectives\` first`);
+		const attestation = {
+			by: body.by,
+			at: (/* @__PURE__ */ new Date()).toISOString(),
+			...body.note !== void 0 ? { note: body.note } : {},
+			deployedSha: head?.sha ?? null
+		};
+		await storage.attestations.update(scope.project, scope.profile, (current) => ({ specs: {
+			...current.specs,
+			[body.spec]: attestation
+		} }));
+		sendJson(ctx.res, 200, {
+			...scope,
+			spec: body.spec,
+			attestation
+		});
+	};
+}
+/**
+* DELETE /api/v1/projects/:project/attestations?profile= — revoke a spec's
+* attestation. Deleting one that does not exist is 200 like deleting one that
+* does: the caller asked for its absence, and it is absent.
+*/
+function createDeleteAttestationHandler(storage) {
+	return async (ctx) => {
+		const scope = requireScope(ctx);
+		const body = await readJsonBody(ctx.req, MAX_BODY_BYTES$2, DeleteAttestationRequestSchema, "attestation body");
+		await storage.attestations.update(scope.project, scope.profile, (current) => {
+			const { [body.spec]: _, ...rest } = current.specs;
+			return { specs: rest };
+		});
+		sendJson(ctx.res, 200, { removed: body.spec });
+	};
+}
+//#endregion
 //#region src/hub/api/handlers/spend.ts
 /** One entry is a handful of short fields; anything larger is a malformed client. */
 const MAX_BODY_BYTES$1 = 4 * 1024;
@@ -18965,7 +19167,7 @@ function specMovedSince(changedAt, baselineSha, baselineAt, deployTimes) {
 	return changedAt > (baselineSha && deployTimes.get(baselineSha) || baselineAt) ? changedAt : null;
 }
 function computeRerun(input) {
-	const { specs, ledger, log, touchIndex, drift, locks, now } = input;
+	const { specs, ledger, log, touchIndex, drift, locks, attestations, now } = input;
 	const range = buildRange(log, touchIndex);
 	const deployTimes = deployedAt(log);
 	const out = {};
@@ -18983,11 +19185,23 @@ function computeRerun(input) {
 		if (auditMoved && audit.audit !== "due") audit = { audit: "due" };
 		if (runMoved && execution.execution === "passed") execution = { execution: "stale" };
 		const held = heldBy(locks, spec.key, now);
+		let verdict = decide(audit.audit, execution.execution, held);
+		const manualState = readAttestation(attestations.specs[spec.key], spec, coords.lastRed, range, log, deployTimes);
+		if (manualState?.kind === "covers" && !held && verdict !== "verified") verdict = "manuallyVerified";
 		out[spec.key] = {
-			verdict: decide(audit.audit, execution.execution, held),
+			verdict,
 			...auditMoved || runMoved ? { specChangedSince: auditMoved ?? runMoved } : {},
 			...audit,
 			...execution,
+			...manualState?.kind === "covers" ? { manual: manualState.attest } : {},
+			...manualState?.kind === "lapsed" ? {
+				manualLapsed: {
+					...manualState.attest,
+					because: manualState.because
+				},
+				...manualState.because === "deployReached" ? { manualLapsedByDeploy: manualState.byDeploy } : {},
+				...manualState.reason ? { manualLapsedReason: manualState.reason } : {}
+			} : {},
 			heldBy: held,
 			...coords
 		};
@@ -18995,6 +19209,50 @@ function computeRerun(input) {
 	return out;
 }
 /**
+* Does the attestation still speak for what is deployed? Checked in the order
+* the lapse enum documents: deploy coverage first (a sha the log cannot place
+* reads as reached, ADR-0014, with the hole kept as an annotation), then the
+* spec's own edits — compared against when the person looked, because they
+* read the spec as it stood that moment, which `specMovedSince` covers via a
+* null baseline sha — then a red run recorded after them, which is newer
+* information than their word. The null-sha case is the profile that had no
+* deploy log when they checked: their word covers exactly as long as that
+* stays true.
+*/
+function readAttestation(attest, spec, lastRed, range, log, deployTimes) {
+	if (!attest) return null;
+	const coverage = attest.deployedSha === null ? log.entries.length === 0 ? { kind: "current" } : {
+		kind: "unanswerable",
+		reason: "unknownDeployedSha"
+	} : freshness(attest.deployedSha, spec.key, range);
+	if (coverage.kind === "touched") return {
+		kind: "lapsed",
+		attest,
+		because: "deployReached",
+		byDeploy: coverage.touchedByDeploy
+	};
+	if (coverage.kind === "unanswerable") return {
+		kind: "lapsed",
+		attest,
+		because: "cannotPlace",
+		reason: coverage.reason
+	};
+	if (specMovedSince(spec.changedAt, null, attest.at, deployTimes)) return {
+		kind: "lapsed",
+		attest,
+		because: "specEdited"
+	};
+	if (lastRed !== null && lastRed.at > attest.at) return {
+		kind: "lapsed",
+		attest,
+		because: "newerRed"
+	};
+	return {
+		kind: "covers",
+		attest
+	};
+}
+/**
 * Axis 1, derived from the same freshness answer `--only-hub-audit-needed`
 * reads. The label only speaks once the audit is known to be current: a
 * verdict about an older commit says nothing about the one running now.
@@ -19098,13 +19356,14 @@ function createGetRerunHandler(storage) {
 	return async (ctx) => {
 		const project = requireSafeSegment(ctx.params.project, "project");
 		const profile = requireProfileParam(ctx.url);
-		const [specs, ledger, log, touchIndex, drift, locks] = await Promise.all([
+		const [specs, ledger, log, touchIndex, drift, locks, attestations] = await Promise.all([
 			requireSpecTargets(storage.perspectives, project, "which specs need a re-run"),
 			storage.ledger.getMerged(project, profile),
 			storage.deploys.getLog(project, profile),
 			storage.deploys.getTouchIndex(project, profile),
 			storage.driftLedger.getMerged(project),
-			storage.locks.get(project, profile)
+			storage.locks.get(project, profile),
+			storage.attestations.get(project, profile)
 		]);
 		const head = log.entries[log.entries.length - 1];
 		sendJson(ctx.res, 200, {
@@ -19118,6 +19377,7 @@ function createGetRerunHandler(storage) {
 				touchIndex,
 				drift,
 				locks,
+				attestations,
 				now: /* @__PURE__ */ new Date()
 			})
 		});
@@ -19842,6 +20102,7 @@ const HTML_BODY = `
               <button class="fchip" id="persp-chip-needsrepair" data-f="needsRepair" aria-pressed="false" type="button"><span data-i18n="perspectives.rerun.state.needsRepair">Needs repair</span><span class="fcount"></span></button>
               <button class="fchip" id="persp-chip-rerunneeded" data-f="rerunNeeded" aria-pressed="false" type="button"><span data-i18n="perspectives.rerun.state.rerunNeeded">Re-run needed</span><span class="fcount"></span></button>
               <button class="fchip" id="persp-chip-inprogress" data-f="inProgress" aria-pressed="false" type="button"><span data-i18n="perspectives.rerun.state.inProgress">In progress</span><span class="fcount"></span></button>
+              <button class="fchip" id="persp-chip-manuallyverified" data-f="manuallyVerified" aria-pressed="false" type="button"><span data-i18n="perspectives.rerun.state.manuallyVerified">Manually verified</span><span class="fcount"></span></button>
               <button class="fchip" id="persp-chip-verified" data-f="verified" aria-pressed="false" type="button"><span data-i18n="perspectives.rerun.state.verified">Verified</span><span class="fcount"></span></button>
             </div>
             <div class="spacer"></div>
@@ -20567,6 +20828,9 @@ const CSS = `
   .sg-audit-undecided { background: var(--info); }
   .sg-verified, .sg-audit-clean, .sg-exec-passed { background: var(--pass); }
   .sg-inprogress, .sg-audit-due, .sg-exec-never { background: var(--muted-2); }
+  /* A person's word, not the machine's — kept off the pass/fail palette both
+     axes share so it never reads as either one. */
+  .sg-manual { background: var(--violet); }
 
   .search { flex: 1; min-width: 200px; max-width: 340px; display: flex; align-items: center; gap: 7px; border: 1px solid var(--border-strong); border-radius: var(--radius-sm); padding: 0 10px; height: 32px; background: var(--surface); }
   .search svg { width: 15px; height: 15px; flex: none; color: var(--muted-2); }
@@ -20605,6 +20869,11 @@ const CSS = `
   .badge.rr-unknown .d { background: var(--info); }
   .badge.rr-none { background: var(--surface-3); color: var(--muted); border-color: var(--border); }
   .badge.rr-none .d { background: var(--muted); }
+  /* A person's attestation, not the audit/run pipeline's own verdict — kept
+     off that palette (rr-repair/rr-needed/rr-none/passed) the same way
+     sg-manual is kept off the summary bar's. */
+  .badge.rr-manual { background: var(--violet-bg); color: var(--violet); border-color: var(--violet-border); }
+  .badge.rr-manual .d { background: var(--violet); }
   .cellsub { display: block; margin-top: 3px; max-width: 260px; color: var(--muted); font-size: 11.5px; line-height: 1.45; }
   .graded-mark { color: var(--fg-dim); font-weight: 600; }
   .cellsub a { color: var(--muted); text-decoration: none; border-bottom: 1px dotted var(--border-strong); }
@@ -20660,6 +20929,11 @@ const CSS = `
   .d-paths { display: flex; flex-wrap: wrap; gap: 6px; }
   .d-paths code { white-space: nowrap; }
   .d-prose + .d-paths { margin-top: 6px; }
+  .manual-attest { margin-top: 14px; }
+  .steps-box { margin-top: 14px; max-width: 900px; }
+  .steps-box .slabel { font-size: 12px; color: var(--muted); margin-bottom: 4px; }
+  .d-steps { margin: 4px 0 0; padding-left: 18px; display: flex; flex-direction: column; gap: 10px; font-size: 13px; color: var(--fg-dim); white-space: pre-line; }
+  .d-steps .step-expected { display: block; margin-top: 2px; font-size: 12.5px; }
   .notebox { margin-top: 14px; max-width: 900px; }
   .notebox .nlabel { font-size: 12px; color: var(--muted); margin-bottom: 4px; }
   .notebox textarea { width: 100%; min-height: 54px; resize: vertical; font: inherit; font-size: 13px; color: var(--fg-dim); background: var(--surface); border: 1px solid var(--border-strong); border-radius: var(--radius-sm); padding: 8px 10px; }
@@ -20700,6 +20974,7 @@ const CLIENT_JS = `
   var THEME_KEY = "ccqa-hub-theme";
   var PROJECT_KEY = "ccqa-hub-project";
   var PROFILES_KEY = "ccqa-hub-profiles";
+  var ATTEST_BY_KEY = "ccqa-attest-by";
 
   // ── i18n ──────────────────────────────────────────────────────────────
   // Chrome + labels only. Model output (headline/recommendation/reasoning) is
@@ -20788,6 +21063,8 @@ const CLIENT_JS = `
       "perspectives.ov.cases": "cases", "perspectives.ov.features": "features",
       "perspectives.d.preconditions": "Preconditions", "perspectives.d.startScreen": "Start screen",
       "perspectives.d.testCondition": "Condition", "perspectives.d.spec": "spec",
+      "perspectives.d.steps": "Steps", "perspectives.d.stepInclude": "Include: {name}",
+      "perspectives.d.stepExpected": "Expected:",
       "perspectives.note.label": "Note",
       "perspectives.note.placeholder": "Notes about this case…",
       "perspectives.note.saved": "Saved",
@@ -20800,6 +21077,7 @@ const CLIENT_JS = `
       "perspectives.rerun.state.needsRepair": "Needs repair",
       "perspectives.rerun.state.rerunNeeded": "Re-run needed",
       "perspectives.rerun.state.inProgress": "In progress",
+      "perspectives.rerun.state.manuallyVerified": "Manually verified",
       "perspectives.rerun.state.verified": "Verified",
       "perspectives.rerun.vsDeploy": "judged against deploy",
       "perspectives.rerun.noDeployHead": "no deploy recorded for this profile",
@@ -20835,6 +21113,19 @@ const CLIENT_JS = `
       "perspectives.rerun.noDeployLogBanner": "No deploy has been recorded for profile {profile}, so no case can be judged. Wire ccqa hub deploy record into the deploy job for this environment.",
       "perspectives.rerun.deployHead": "deploy head",
       "perspectives.drift.graded": "confirmed",
+      "perspectives.manual.attestButton": "Mark as manually verified",
+      "perspectives.manual.revokeButton": "Revoke manual verification",
+      "perspectives.manual.promptBy": "Who is verifying this?",
+      "perspectives.manual.promptNote": "Note (optional)",
+      "perspectives.manual.confirmRevoke": "Revoke the manual verification for this case?",
+      "perspectives.manual.error": "Could not save — retry",
+      "perspectives.manual.verifiedBy": "{by} manually verified this ({at})",
+      "perspectives.manual.lapsed.deployReached": "the manual verification lapsed when a deploy reached this case",
+      "perspectives.manual.lapsed.deployReachedNamed": "the manual verification lapsed when deploy {sha} reached this case ({at})",
+      "perspectives.manual.lapsed.cannotPlace": "the manual verification lapsed — its baseline deploy could not be placed in the log",
+      "perspectives.manual.lapsed.specEdited": "the manual verification lapsed when the spec was edited",
+      "perspectives.manual.lapsed.newerRed": "the manual verification lapsed after a later run failed",
+      "perspectives.manual.lapsed.unrecognized": "the manual verification lapsed for a reason this UI does not recognise",
       "prompt.card.record": "Recording browser actions",
       "prompt.card.live": "Live run (AI-driven)",
       "prompt.card.playwright": "Playwright test generation",
@@ -20952,6 +21243,8 @@ const CLIENT_JS = `
       "perspectives.ov.cases": "ケース", "perspectives.ov.features": "機能",
       "perspectives.d.preconditions": "前提条件", "perspectives.d.startScreen": "開始画面",
       "perspectives.d.testCondition": "実行条件", "perspectives.d.spec": "spec",
+      "perspectives.d.steps": "手順", "perspectives.d.stepInclude": "ブロック: {name}",
+      "perspectives.d.stepExpected": "期待結果:",
       "perspectives.note.label": "note",
       "perspectives.note.placeholder": "このケースについてのメモ…",
       "perspectives.note.saved": "保存しました",
@@ -20964,6 +21257,7 @@ const CLIENT_JS = `
       "perspectives.rerun.state.needsRepair": "修正待ち",
       "perspectives.rerun.state.rerunNeeded": "要再実行",
       "perspectives.rerun.state.inProgress": "進行中",
+      "perspectives.rerun.state.manuallyVerified": "手動確認済み",
       "perspectives.rerun.state.verified": "検証済み",
       "perspectives.rerun.vsDeploy": "判定基準: デプロイ",
       "perspectives.rerun.noDeployHead": "このプロファイルにはデプロイの記録がありません",
@@ -20999,6 +21293,19 @@ const CLIENT_JS = `
       "perspectives.rerun.noDeployLogBanner": "プロファイル {profile} にデプロイの記録がないため、どのケースも判定できません。この環境のデプロイジョブに ccqa hub deploy record を組み込んでください。",
       "perspectives.rerun.deployHead": "最新デプロイ",
       "perspectives.drift.graded": "人が確認",
+      "perspectives.manual.attestButton": "手動で確認した",
+      "perspectives.manual.revokeButton": "手動確認を取り消す",
+      "perspectives.manual.promptBy": "確認者名を入力してください",
+      "perspectives.manual.promptNote": "メモ（任意）",
+      "perspectives.manual.confirmRevoke": "このケースの手動確認を取り消しますか？",
+      "perspectives.manual.error": "保存に失敗しました — 再試行してください",
+      "perspectives.manual.verifiedBy": "{by}さんが手動確認（{at}）",
+      "perspectives.manual.lapsed.deployReached": "手動確認はデプロイの到達により失効",
+      "perspectives.manual.lapsed.deployReachedNamed": "手動確認はデプロイ {sha}（{at}）の到達により失効",
+      "perspectives.manual.lapsed.cannotPlace": "手動確認は基準デプロイをログで特定できず失効",
+      "perspectives.manual.lapsed.specEdited": "手動確認はspecの編集により失効",
+      "perspectives.manual.lapsed.newerRed": "手動確認は直後の実行失敗により失効",
+      "perspectives.manual.lapsed.unrecognized": "このUIが認識できない理由により手動確認が失効",
       "prompt.card.record": "ブラウザ操作の記録",
       "prompt.card.live": "ライブ実行（AI操作）",
       "prompt.card.playwright": "Playwrightテスト生成",
@@ -21132,6 +21439,17 @@ const CLIENT_JS = `
     try { window.localStorage.removeItem(PROJECT_KEY); }
     catch (e) { console.warn("ccqa hub: could not clear stored project:", e); }
   }
+
+  // Remembered across attestations so the prompt's default is whoever last
+  // used this browser, not a blank field every time.
+  function loadAttestBy() {
+    try { return window.localStorage.getItem(ATTEST_BY_KEY) || ""; }
+    catch (e) { return ""; }
+  }
+  function storeAttestBy(by) {
+    try { window.localStorage.setItem(ATTEST_BY_KEY, by); }
+    catch (e) { /* non-fatal: next prompt just starts blank again */ }
+  }
   function loadProfileMap() {
     try {
       var raw = window.localStorage.getItem(PROFILES_KEY);
@@ -23080,6 +23398,11 @@ const CLIENT_JS = `
       "/rerun?profile=" + encodeURIComponent(state.profile);
   }
 
+  function attestationsPath() {
+    return "/api/v1/projects/" + encodeURIComponent(state.project) +
+      "/attestations?profile=" + encodeURIComponent(state.profile);
+  }
+
   // Resolves { report } or { note } and never rejects: a hub that predates
   // the endpoint costs only the columns it feeds, not the whole tab. A 404
   // here can only mean "no such route" — the endpoint's own 404 is "the
@@ -23158,6 +23481,37 @@ const CLIENT_JS = `
     return text === prefix + reason ? t(prefix + "unrecognized") : text;
   }
 
+  // Who attested and when, plus their note if they left one — the whole
+  // reason a "manuallyVerified" verdict has no evidence row of its own.
+  function manualAttestationText(manual) {
+    var text = t("perspectives.manual.verifiedBy").replace("{by}", manual.by).replace("{at}", relTime(manual.at));
+    return manual.note ? text + " — " + manual.note : text;
+  }
+
+  // An attestation that no longer covers what is deployed, named alongside
+  // whatever the current verdict's own reason is (rerunCellWhy appends this)
+  // rather than replacing it — the person deciding whether to attest again
+  // needs both: what the axes say now, and that a person's word used to
+  // stand in for it. deployReached is the only reason with a named cause
+  // (manualLapsedByDeploy) to add when the log could confirm one.
+  function rerunManualLapseText(rr) {
+    var lapsed = rr && rr.manualLapsed;
+    if (!lapsed) return null;
+    if (lapsed.because === "deployReached") {
+      var deploy = rr.manualLapsedByDeploy;
+      return deploy
+        ? t("perspectives.manual.lapsed.deployReachedNamed").replace("{sha}", shortSha(deploy.sha)).replace("{at}", relTime(deploy.at))
+        : t("perspectives.manual.lapsed.deployReached");
+    }
+    if (lapsed.because === "cannotPlace" && rr.manualLapsedReason) {
+      // The same per-hole vocabulary the axes' assumed-reached annotations
+      // use — an empty deploy log and an unjudged range call for different
+      // next actions, so the shrug names which hole it is.
+      return t("perspectives.manual.lapsed.cannotPlace") + " (" + rerunReasonText("perspectives.rerun.why.", rr.manualLapsedReason) + ")";
+    }
+    return rerunReasonText("perspectives.manual.lapsed.", lapsed.because);
+  }
+
   // Every verdict that carries no evidence row explains itself here, in the
   // actionable phrasing the detail panel wants. decide() checks heldBy before
   // the audit axis, so a spec another job already holds must be explained by
@@ -23177,6 +23531,7 @@ const CLIENT_JS = `
         ? rerunReasonText("perspectives.rerun.fix.", rr.auditAssumedReached)
         : t("perspectives.rerun.inProgressHint");
     }
+    if (rr.verdict === "manuallyVerified" && rr.manual) return manualAttestationText(rr.manual);
     return rerunReasonText("perspectives.rerun.fix.", rr.verdict);
   }
 
@@ -23195,16 +23550,23 @@ const CLIENT_JS = `
   // rather than claiming a deploy matched it.
   function rerunCellWhy(rr) {
     var head = perspState.rerun && perspState.rerun.deployHead;
+    var why;
     if (rr.verdict === "rerunNeeded") {
-      if (rr.executionAssumedReached) return rerunReasonText("perspectives.rerun.why.", rr.executionAssumedReached);
-      if (!rr.touchedBy || !rr.touchedBy.length) return t("perspectives.rerun.touchedUnknown");
-      return t("perspectives.rerun.touchedCount").replace("{n}", String(rr.touchedBy.length));
-    }
-    if (rr.verdict === "verified") {
-      if (!head) return t("perspectives.rerun.noDeployHead");
-      return t("perspectives.rerun.vsDeploy") + " " + shortSha(head.sha) + " · " + relTime(head.at);
+      if (rr.executionAssumedReached) why = rerunReasonText("perspectives.rerun.why.", rr.executionAssumedReached);
+      else if (!rr.touchedBy || !rr.touchedBy.length) why = t("perspectives.rerun.touchedUnknown");
+      else why = t("perspectives.rerun.touchedCount").replace("{n}", String(rr.touchedBy.length));
+    } else if (rr.verdict === "verified") {
+      why = !head
+        ? t("perspectives.rerun.noDeployHead")
+        : t("perspectives.rerun.vsDeploy") + " " + shortSha(head.sha) + " · " + relTime(head.at);
+    } else {
+      why = rerunWhyVerdict(rr);
     }
-    return rerunWhyVerdict(rr);
+    // A lapsed attestation is worth saying no matter which verdict the axes
+    // landed on afterwards — it is not that verdict's reason, so it is
+    // appended rather than replacing it.
+    var lapse = rerunManualLapseText(rr);
+    return lapse ? why + " · " + lapse : why;
   }
 
 
@@ -23218,10 +23580,10 @@ const CLIENT_JS = `
   // the pipeline still owes, then what needs nothing. "needsRepair" leads
   // because it is the only verdict a run cannot clear — someone has to repair
   // the spec or the product.
-  var RERUN_ORDER = ["needsRepair", "rerunNeeded", "inProgress", "verified"];
+  var RERUN_ORDER = ["needsRepair", "rerunNeeded", "inProgress", "manuallyVerified", "verified"];
   var RERUN_SEG_CLASS = {
     needsRepair: "sg-needsrepair", rerunNeeded: "sg-rerunneeded",
-    inProgress: "sg-inprogress", verified: "sg-verified"
+    inProgress: "sg-inprogress", manuallyVerified: "sg-manual", verified: "sg-verified"
   };
 
   // The one rule the summary bar and the verdict filter chips both answer
@@ -23235,7 +23597,7 @@ const CLIENT_JS = `
 
   // One verdict per case, bucketed, via rerunVerdictOf above.
   function rerunComposition(verdicts) {
-    var counts = { needsRepair: 0, rerunNeeded: 0, inProgress: 0, verified: 0 };
+    var counts = { needsRepair: 0, rerunNeeded: 0, inProgress: 0, manuallyVerified: 0, verified: 0 };
     verdicts.forEach(function (rr) { counts[rerunVerdictOf(rr)] += 1; });
     return counts;
   }
@@ -23403,7 +23765,7 @@ const CLIENT_JS = `
   // takes the attention colour and re-running — machine work — does not.
   var VERDICT_BADGE = {
     needsRepair: "rr-repair", rerunNeeded: "rr-needed",
-    inProgress: "rr-none", verified: "passed"
+    inProgress: "rr-none", manuallyVerified: "rr-manual", verified: "passed"
   };
 
   function perspVerdictCell(rr) {
@@ -23734,6 +24096,43 @@ const CLIENT_JS = `
     return wrap;
   }
 
+  // Lets a person's own check stand in for the machine's verdict. prompt()/
+  // confirm() rather than a form: the action is rare and the two fields it
+  // needs are short, so a modal would outweigh what it does. reloadRerun()
+  // is the same profile-scoped refresh a profile switch uses — it re-renders
+  // the whole table, so an open detail panel closes along with it.
+  function submitAttestation(method, body) {
+    apiFetch(attestationsPath(), {
+      method: method,
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+    }).then(function () { reloadRerun(); })
+      .catch(function (err) { window.alert(t("perspectives.manual.error") + ": " + err.message); });
+  }
+
+  function manualAttestButton(feature, spec) {
+    var btn = el("button", "btn sm primary", t("perspectives.manual.attestButton"));
+    btn.type = "button";
+    btn.addEventListener("click", function () {
+      var by = window.prompt(t("perspectives.manual.promptBy"), loadAttestBy());
+      if (!by) return;
+      storeAttestBy(by);
+      var note = window.prompt(t("perspectives.manual.promptNote"), "");
+      submitAttestation("PUT", { spec: perspSpecKey(feature, spec), by: by, note: note || undefined });
+    });
+    return btn;
+  }
+
+  function manualRevokeButton(feature, spec) {
+    var btn = el("button", "btn ghost sm del", t("perspectives.manual.revokeButton"));
+    btn.type = "button";
+    btn.addEventListener("click", function () {
+      if (!window.confirm(t("perspectives.manual.confirmRevoke"))) return;
+      submitAttestation("DELETE", { spec: perspSpecKey(feature, spec) });
+    });
+    return btn;
+  }
+
   // Detail row: a definition list of the case's fields plus the note editor.
   // Built with createElement/textContent throughout — every field here is
   // API-derived, so none of it may go through innerHTML.
@@ -23771,6 +24170,44 @@ const CLIENT_JS = `
     }
     frag.appendChild(dl);
 
+    if (spec.steps && spec.steps.length) {
+      var stepsBox = el("div", "steps-box");
+      stepsBox.appendChild(el("div", "slabel", t("perspectives.d.steps")));
+      var stepsList = el("ol", "d-steps");
+      spec.steps.forEach(function (step) {
+        var li = el("li");
+        if (step.include) {
+          li.textContent = t("perspectives.d.stepInclude").replace("{name}", step.include);
+        } else {
+          li.appendChild(document.createTextNode(step.instruction || ""));
+          if (step.expected) {
+            li.appendChild(el("div", "muted step-expected", t("perspectives.d.stepExpected") + " " + step.expected));
+          }
+        }
+        stepsList.appendChild(li);
+      });
+      stepsBox.appendChild(stepsList);
+      frag.appendChild(stepsBox);
+    }
+
+    // A standing attestation always offers revoke — even when it changed
+    // nothing (a held or machine-verified spec), it exists and must stay
+    // findable. A lapsed one is named right here, beside the attest button
+    // the reader is deciding whether to press.
+    var manualBtn = null;
+    if (rr && rr.manual) manualBtn = manualRevokeButton(feature, spec);
+    else if (rr && (rr.verdict === "needsRepair" || rr.verdict === "rerunNeeded")) manualBtn = manualAttestButton(feature, spec);
+    if (manualBtn) {
+      var manualBox = el("div", "manual-attest");
+      if (rr.manual && rr.verdict !== "manuallyVerified") {
+        manualBox.appendChild(el("div", "d-prose", manualAttestationText(rr.manual)));
+      }
+      var lapseLine = rerunManualLapseText(rr);
+      if (lapseLine) manualBox.appendChild(el("div", "d-prose", lapseLine));
+      manualBox.appendChild(manualBtn);
+      frag.appendChild(manualBox);
+    }
+
     var notebox = el("div", "notebox");
     notebox.appendChild(el("div", "nlabel", t("perspectives.note.label")));
     var ta = el("textarea");
@@ -25062,6 +25499,9 @@ function registerRoutes(router, config, queue) {
 	router.get("/api/v1/projects/:project/audit-needed", createGetAuditNeedHandler(storage));
 	router.post("/api/v1/projects/:project/locks", createAcquireLocksHandler(storage));
 	router.delete("/api/v1/projects/:project/locks", createReleaseLocksHandler(storage));
+	router.get("/api/v1/projects/:project/attestations", createGetAttestationsHandler(storage));
+	router.put("/api/v1/projects/:project/attestations", createPutAttestationHandler(storage));
+	router.delete("/api/v1/projects/:project/attestations", createDeleteAttestationHandler(storage));
 	router.get("/api/v1/projects/:project/acks/:name", createGetAckHandler(storage));
 	router.put("/api/v1/projects/:project/acks/:name", createPutAckHandler(storage));
 	router.post("/api/v1/projects/:project/spend", createRecordSpendHandler(storage));
@@ -25351,6 +25791,9 @@ function deployTouchIndexPath(root, project, profile) {
 function specLocksPath(root, project, profile) {
 	return join(root, "locks", project, profile, "locks.json");
 }
+function attestationsPath(root, project, profile) {
+	return join(root, "attestations", project, profile, "attestations.json");
+}
 function ackPath(root, project, profile, name) {
 	return join(root, "acks", project, profile, `${name}.json`);
 }
@@ -25392,6 +25835,22 @@ function createFileAckStore(root) {
 	};
 }
 //#endregion
+//#region src/hub/core/storage/file/attestation-store.ts
+function toAttestations(doc) {
+	const parsed = AttestationsSchema.safeParse(doc);
+	return parsed.success ? parsed.data : { specs: {} };
+}
+function createFileAttestationStore(root) {
+	return {
+		async get(project, profile) {
+			return toAttestations(await readJson(attestationsPath(root, project, profile)));
+		},
+		async update(project, profile, mutate) {
+			return updateJson(attestationsPath(root, project, profile), (current) => mutate(toAttestations(current)));
+		}
+	};
+}
+//#endregion
 //#region src/hub/core/storage/file/artifact-store.ts
 /**
 * Defense-in-depth: `relPath` is expected to already be validated by the
@@ -25875,7 +26334,8 @@ function createFileHubStorage(dataDir) {
 		deploys: createFileDeployStore(dataDir),
 		locks: createFileLockStore(dataDir),
 		acks: createFileAckStore(dataDir),
-		spend: createFileSpendStore(dataDir)
+		spend: createFileSpendStore(dataDir),
+		attestations: createFileAttestationStore(dataDir)
 	};
 }
 //#endregion

package/dist/hub-client/index.d.mts

@@ -213,14 +213,38 @@ declare const AcquireLocksResponseSchema: z.ZodObject<{
   denied: z.ZodArray<z.ZodString>;
 }, z.core.$strip>;
 type AcquireLocksResponse = z.infer<typeof AcquireLocksResponseSchema>;
+/** Answer of PUT (the attestation as stamped) and GET (the whole document). */
+declare const AttestationResponseSchema: z.ZodObject<{
+  project: z.ZodString;
+  profile: z.ZodString;
+  spec: z.ZodString;
+  attestation: z.ZodObject<{
+    by: z.ZodString;
+    at: z.ZodString;
+    note: z.ZodOptional<z.ZodString>;
+    deployedSha: z.ZodNullable<z.ZodString>;
+  }, z.core.$strip>;
+}, z.core.$strip>;
+type AttestationResponse = z.infer<typeof AttestationResponseSchema>;
+declare const AttestationsResponseSchema: z.ZodObject<{
+  project: z.ZodString;
+  profile: z.ZodString;
+  specs: z.ZodRecord<z.ZodString, z.ZodObject<{
+    by: z.ZodString;
+    at: z.ZodString;
+    note: z.ZodOptional<z.ZodString>;
+    deployedSha: z.ZodNullable<z.ZodString>;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+type AttestationsResponse = z.infer<typeof AttestationsResponseSchema>;
 /** Body of `GET /projects/:project/audit-needed?profile=`: one answer per spec. */
 declare const AuditNeedReportSchema: z.ZodObject<{
   project: z.ZodString;
   profile: z.ZodString;
   specs: z.ZodRecord<z.ZodString, z.ZodObject<{
     because: z.ZodEnum<{
-      neverAudited: "neverAudited";
       deployReached: "deployReached";
+      neverAudited: "neverAudited";
       cannotTell: "cannotTell";
       held: "held";
       current: "current";
@@ -252,6 +276,7 @@ declare const RerunReportSchema: z.ZodObject<{
       needsRepair: "needsRepair";
       rerunNeeded: "rerunNeeded";
       verified: "verified";
+      manuallyVerified: "manuallyVerified";
     }>;
     audit: z.ZodEnum<{
       due: "due";
@@ -288,6 +313,38 @@ declare const RerunReportSchema: z.ZodObject<{
       gapInRange: "gapInRange";
     }>>;
     specChangedSince: z.ZodOptional<z.ZodString>;
+    manual: z.ZodOptional<z.ZodObject<{
+      by: z.ZodString;
+      at: z.ZodString;
+      note: z.ZodOptional<z.ZodString>;
+      deployedSha: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+    manualLapsed: z.ZodOptional<z.ZodObject<{
+      by: z.ZodString;
+      at: z.ZodString;
+      note: z.ZodOptional<z.ZodString>;
+      deployedSha: z.ZodNullable<z.ZodString>;
+      because: z.ZodEnum<{
+        deployReached: "deployReached";
+        cannotPlace: "cannotPlace";
+        specEdited: "specEdited";
+        newerRed: "newerRed";
+      }>;
+    }, z.core.$strip>>;
+    manualLapsedByDeploy: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+      index: z.ZodNumber;
+      sha: z.ZodString;
+      at: z.ZodString;
+    }, z.core.$strip>>>;
+    manualLapsedReason: z.ZodOptional<z.ZodEnum<{
+      noSelectionInRange: "noSelectionInRange";
+      selectionUnknown: "selectionUnknown";
+      noDeployLog: "noDeployLog";
+      unknownDeployedSha: "unknownDeployedSha";
+      ambiguousDeployedSha: "ambiguousDeployedSha";
+      deployedShaNotInLog: "deployedShaNotInLog";
+      gapInRange: "gapInRange";
+    }>>;
     heldBy: z.ZodNullable<z.ZodObject<{
       kind: z.ZodEnum<{
         run: "run";
@@ -997,6 +1054,22 @@ interface HubClient {
   releaseLocks(project: string, q: {
     profile: string;
   }, holder: string): Promise<void>;
+  /** Every attestation for the profile, standing and lapsed alike. */
+  getAttestations(project: string, q: {
+    profile: string;
+  }): Promise<AttestationsResponse>;
+  /** Record that a person checked `spec` by hand. The hub stamps the time and deploy head. */
+  putAttestation(project: string, q: {
+    profile: string;
+  }, body: {
+    spec: string;
+    by: string;
+    note?: string;
+  }): Promise<AttestationResponse>;
+  /** Revoke a spec's attestation. Revoking one that does not exist succeeds. */
+  deleteAttestation(project: string, q: {
+    profile: string;
+  }, spec: string): Promise<void>;
   /**
    * Every spec's last `ccqa audit --report-to-hub` result, keyed by "feature/spec". No
    * profile — drift asks whether a spec still describes the code, not

package/dist/hub-client/index.mjs

@@ -182,6 +182,23 @@ function createHubClient(opts) {
 				body: JSON.stringify({ holder })
 			});
 		},
+		getAttestations(project, q) {
+			return json(`${attestationsPath(project)}?${queryString({ profile: q.profile })}`);
+		},
+		putAttestation(project, q, body) {
+			return json(`${attestationsPath(project)}?${queryString({ profile: q.profile })}`, {
+				method: "PUT",
+				headers: { "Content-Type": "application/json" },
+				body: JSON.stringify(body)
+			});
+		},
+		async deleteAttestation(project, q, spec) {
+			await request(`${attestationsPath(project)}?${queryString({ profile: q.profile })}`, {
+				method: "DELETE",
+				headers: { "Content-Type": "application/json" },
+				body: JSON.stringify({ spec })
+			});
+		},
 		getAuditNeed(project, q) {
 			return json(`/api/v1/projects/${encodeURIComponent(project)}/audit-needed?${queryString({ profile: q.profile })}`);
 		},
@@ -305,6 +322,9 @@ function spendPath(project) {
 function locksPath(project) {
 	return `/api/v1/projects/${encodeURIComponent(project)}/locks`;
 }
+function attestationsPath(project) {
+	return `/api/v1/projects/${encodeURIComponent(project)}/attestations`;
+}
 /** Perspectives are one document per project: `/api/v1/projects/<project>/perspectives`. */
 function perspectivesPath(project) {
 	return `/api/v1/projects/${encodeURIComponent(project)}/perspectives`;

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ccqa",
-  "version": "1.31.4",
+  "version": "1.32.0",
   "type": "module",
   "description": "Browser test recorder powered by Claude Code and agent-browser",
   "repository": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ccqa",
-  "version": "1.31.4",
+  "version": "1.32.0",
   "type": "module",
   "description": "Browser test recorder powered by Claude Code and agent-browser",
   "repository": {