Review Goals Audit
`pnpm review:goals` is the 10/10 review-goal audit. It collects the local gates
that came out of the project review and separates them from evidence that cannot
be fabricated locally.
Run it locally:
pnpm review:goals
pnpm review:goals:local
pnpm review:goals:check
Use `pnpm review:goals:local` in CI when the expected state is "all local gates
are complete, but real-world evidence is still pending." It exits non-zero only
when `score.incomplete > 0`, and version-5+ artifacts expose the same result as
top-level `localGateStatus: "passed" | "failed"`. Use `pnpm review:goals:check`
for the final strict 10/10 gate; version-20+ artifacts expose that result as
top-level `strictGateStatus: "passed" | "failed"`, and it must keep failing
until production, partner, and customer evidence is actually present.
The command writes timestamped JSON and Markdown evidence to
`artifacts/review-goals/`, including `review-goals-latest.json` and
`review-goals-latest.md`. JSON artifact `version: 45` adds top-level
`readinessClaim`, a machine-readable boundary that names the allowed local-gate
claim, the blocked strict-production claim, and the production proof scopes
still needed before anyone can call the project strict 10/10 ready. Version 44 adds
`blockedByExternalEvidenceGoals[].actionBreakdown[].blockerCount`,
`artifactCount`, and `requirementCount`, so each blocked-goal action exposes
dashboard-ready totals without counting its blocker, artifact, or requirement
arrays. Version 42 adds
`blockedByExternalEvidenceGoals[].scopeBreakdown[].nextActionIds`, so each
named blocked goal can join scoped handoffs to grouped `nextActions` rows
without interpreting legacy `actionIds`. Version 41 adds
`blockedByExternalEvidenceGoals[].scopeCount`, so each named blocked goal shows
whether its remaining work spans one or multiple execution lanes without
counting `executionScopes[]`. Version 40 adds
`blockedByExternalEvidenceGoals[].actionCount`, `commandCount`, and
`artifactCount`, so each named blocked goal exposes dashboard-ready handoff
totals without counting arrays. Version 39 adds
`blockedByExternalEvidenceGoals[].nextEvidenceRequirements` and
`requirementCount`, so each blocked-goal handoff carries its exact acceptance
criteria directly. Version 38 adds
`externalEvidenceBlockerSummary[].nextActionIds` and scoped `actionCount`, so
each blocker-scope summary points directly at the grouped remediation actions.
Version 37 adds
`externalEvidenceBlockerSummary[].nextEvidenceRequirements` and scoped
`requirementCount`, so each blocker-scope summary carries its acceptance
criteria directly. Version 36 adds `nextActionSummary[].actionCount`, so each
execution-scope lane exposes its action total directly while legacy `count`
remains for compatibility. Version 35 adds top-level
`strictGateHandoff.nextActionCount` and scoped
`strictGateHandoff.scopeBreakdown[].nextActionCount`, so strict handoff
dashboards can display executable action totals without counting action ID
arrays. Version 34 adds scoped
`blockedByExternalEvidenceGoals[].scopeBreakdown[].remediationCommands`,
`artifactTargets`, and `nextEvidenceRequirements`, so per-goal blocked
handoffs carry the executable operator payload without joining back through
`actionBreakdown`. Version 33 adds
`blockedByExternalEvidenceGoals[].scopeBreakdown[].actionCount`,
`commandCount`, `artifactCount`, and `requirementCount`, so per-goal blocked
handoffs can display scoped action, command, artifact, and acceptance-criteria
totals without counting nested arrays. Version 32 adds
`strictGateHandoff.requirementCount` and scoped
`strictGateHandoff.scopeBreakdown[].requirementCount`, so dashboards can display
distinct next-evidence acceptance criteria without counting long requirement
arrays; these counts are deduplicated and can be lower than blocker counts.
Version 31 adds `strictGateHandoff.artifactCount` and scoped
`strictGateHandoff.scopeBreakdown[].artifactCount`, so dashboards can display
distinct evidence-artifact target totals without counting arrays. Version 30
adds `strictGateHandoff.commandCount` and scoped
`strictGateHandoff.scopeBreakdown[].commandCount`, so dashboards can display
distinct remediation-command totals without counting arrays; scoped action
counts remain separate because one command can appear in more than one
execution scope. Version 29 adds `strictGateHandoff.goalCount` and scoped
`strictGateHandoff.scopeBreakdown[].goalCount`, so the strict-gate operator
payload exposes affected-goal totals without consumers counting arrays. Version
28 adds
`strictGateHandoff.nextActionIds[]` and scoped
`strictGateHandoff.scopeBreakdown[].nextActionIds[]`, so the strict-gate
operator payload points directly at the executable `nextActions[]` rows without
reconstructing command/scope keys. Version 27 adds
`strictGateHandoff.blockerIds[]` and scoped
`strictGateHandoff.scopeBreakdown[].blockerIds[]`, so the strict-gate operator
payload names the exact failing checks without requiring consumers to join
through goal rows or blocker summaries. Version 26 adds
`strictGateHandoff.scopeBreakdown[]`, so the strict-gate operator payload keeps
deployment-environment and real-world-evidence commands, artifacts, blockers,
goals, and evidence requirements separated without another join. Version 25 adds
`strictGateHandoff.nextEvidenceRequirements[]`, so the consolidated strict-gate
operator payload includes the exact evidence sentences from the scoped action
rows, not only commands and artifact paths. Version 24 adds top-level
`strictGateHandoff`, a machine-readable strict-gate operator handoff that
consolidates failing summary IDs, execution scopes, blocker count, affected
goals, remediation commands, and artifact targets without requiring consumers
to re-join the summary rows. Version 23 extends the runtime invariant guard so
every `strictGateFailureSummary[]` field must match the derived strict-gate
rows, not just the row IDs. Version 22 adds top-level
`strictGateFailureSummary[]`, a structured dashboard-ready form of strict gate
failure rows with kind, scope, blocker counts, goals, commands, artifacts, and
the matching human reason. Version 21 adds top-level
`strictGateFailureReasons[]`, so a failed strict 10/10 gate names the local,
deployment-environment, and real-world evidence lanes that still block launch
readiness instead of forcing dashboards to reconstruct those sentences. Version
20 adds top-level `strictGateStatus`, the machine-readable result for
`pnpm review:goals:check`, so CI, dashboards, and launch handoffs do not have
to infer strict 10/10 readiness from the broader status string. Version 19 keys
`nextActions` by
remediation command plus `executionScope`, so a command that appears in both
deployment setup and real-world evidence collection produces separate action
rows instead of one mixed-scope handoff. Version 18 adds top-level
`externalEvidenceBlockerSummary[]` rows that aggregate raw blocker IDs, goals,
commands, and artifact targets by `executionScope`, independently from grouped
actions, so blocker debt is visible even before operators inspect
`nextActions`. Version 17 is the first shape where
goal-level and report-level external-evidence blocker rows carry their own
`executionScope`, so each blocker can be triaged as `local-refresh`,
`deployment-environment`, or `real-world-evidence` without joining through
`nextActions`. Version 16 is the first shape where
top-level `nextActionSummary[]` rows include distinct `commands` and
`artifactTargets`, so each execution-scope lane is executable without joining
through `nextActions`. Version 15 added `goalIds`, `goalTitles`,
`goalCategories`, and `goalCount`, so each lane identifies the goals it affects
instead of only action and blocker totals. Version 14 added
`blockedByExternalEvidenceGoals[].scopeBreakdown[]` to split each blocked goal's
action IDs, next-action IDs, and blocker IDs by `local-refresh`,
`deployment-environment`, and `real-world-evidence`, so operators can see
whether a named goal needs deploy wiring or real adoption/customer/30-day
evidence. Version 13 localized
`blockedByExternalEvidenceGoals[].actionBreakdown[].nextEvidenceRequirements`
to the blocker IDs for that same goal, so shared commands do not inherit
requirements from unrelated goals. The schema now requires every blocked
external-evidence goal to include at least one blocker id, next action id,
execution scope, remediation command, artifact target, and action-breakdown row,
plus per-action blocker, artifact, and requirement counts, plus all three scope
summary rows, and generated blocker/action/scope/artifact arrays must be
unique, so blocked goals cannot degrade into duplicated or prose-only handoffs.
Version 12 added `actionBreakdown` entries
mapping each command to the goal-local blocker IDs it remediates, version 11
added exact `blockerIds`, version 10 added `nextActionIds`, `executionScopes`,
`remediationCommands`, and `artifactTargets` to those rows, version 9 added the
named blocked-goal records,
version 8 added `score.blockedByExternalEvidence`, version 7 added top-level
`nextActionSummary` counts by execution scope; version 6 added
`executionScope` on each grouped `nextActions` row, version 5 added a top-level
`localGateStatus`, version 4 added machine-readable `artifactTargets`
on each grouped action row, version 3 added machine-readable
`nextEvidenceRequirements`, version 2 was the first shape with top-level
`nextActions`, and earlier version-1 artifacts are
pre-action-plan evidence handoffs. Each JSON artifact includes a `$schema` pointer to
`docs/schemas/review-goals.schema.json` and each goal includes
`evidenceArtifacts` paths that name where proof should land plus
`evidenceArtifactStatuses` observations for the latest local file state
(`missing`, `present`, `pass`, `failed`, `blocked`, and blocker counts). The
service exports the report version as `REVIEW_GOALS_REPORT_VERSION`, and the
script contract tests require the JSON schema `version.const` and emitted report
version to match that constant before the contract is accepted. Before the CLI
prints or writes an artifact, it also compares the generated JSON shape against
the schema-required keys and every `additionalProperties: false` object promised
by the schema for top-level report fields, score fields, goal rows, evidence
rows, blocked-goal handoffs, next actions, and next-action summaries, so
schema/report drift fails before a malformed handoff can be emitted. Goals
that depend on specific checks inside a larger artifact also include
`evidenceArtifactCheckStatuses`; for example, launch readiness now preserves the
specific deployment-preflight and launch-review checks that are passing,
failing, or missing, managed-pilot packets derive entitlement/outreach/
billing/activation/support/KPI/retention checks from the packet fields, long-term and
Era C exit-gate artifacts expose their SLO, uptime, adoption, p95, and KPI
checks, ActivityStreams artifacts expose their consumer and subscription checks,
and Render validation/reconciliation service probes can be complete when their
`/health` checks pass even if the broader production preflight is still failing
for unrelated storage or smoke reasons. Activity
syndication proof also preserves accepted and rejected callback evidence rows;
subscriptions only count when they are active external HTTPS callbacks whose
public, non-placeholder callback host matches the callback URL, are updated
inside the evidence window, and cover Create, Update, and Delete. The coarse
ActivityStreams syndication readiness flag also requires the selected
`activity.declaredConsumers` and `activity.durableSubscriptions` rows to pass,
so a top-level ready artifact cannot hide missing durable subscriptions. Use the
Markdown file as the human handoff summary for the remaining external blockers.
Managed-pilot billing checks also revalidate the invoice reference directly:
demo, fixture, internal, placeholder, sample, smoke, or test invoice tokens fail
the selected `pilot.billing.invoice` gate even if an artifact says billing is
ready. The coarse paid-pilot readiness flag also requires every selected
managed-pilot check to pass: entitlement, billing, outreach, selected account,
activation milestones, support load, required KPIs, and retention signal.
For the Render validation/reconciliation goal, documented local fallback text is
not sufficient: the audit only counts the goal as deployed evidence when both
selected service checks contain passing public HTTPS Render `/health` probe
evidence; HTTP, non-health, placeholder, local, or private-network probe text
remains a deployment blocker.
Before the CLI writes JSON or Markdown artifacts, it validates report invariants
that the JSON schema cannot express: score totals must match the goal list,
`status`, `localGateStatus`, `strictGateStatus`,
`strictGateFailureReasons`, every `strictGateFailureSummary[]` field, and the
consolidated `strictGateHandoff` must match those totals and blocker summaries,
`score.blockedByExternalEvidence` must match the blocked-goal handoff count,
each `blockerCount` must match its blocker IDs, blocked-goal action references
must point at known `nextActions`, and every `nextActionSummary` lane must match
the actions, commands, artifact targets, goals, and blockers in that same
execution scope. Each `nextActions[]` row must contain only blocker IDs whose
raw external-evidence blocker has the same `executionScope`, so deployment
operators cannot accidentally inherit customer, partner, or 30-day evidence
debt from a shared package command.
Selected checks are readiness gates, not decorative annotations. A goal with
`evidenceArtifactCheckStatuses` cannot be counted complete while any selected
check is `fail`, `blocked`, `collecting`, `missing`, or otherwise not ready,
even if a higher-level external flag was set.
The `launchEvidenceReady` coarse flag follows the same rule: it requires the
selected launch-evidence, launch-review, and deployment-preflight rows to pass,
so a hand-edited `status: ready` launch packet cannot hide a failing public URL,
auth, worker scheduler, crawler-preview, Render probe, or SLO/tile check.
Launch readiness selects both `observability.publicBaseUrl` and
`observability.socialPreviewBaseUrl` from deployment preflight, so a localhost,
protected, divergent, or non-HTTPS share URL stays visible as its own 10/10
blocker before crawler-preview evidence is trusted.
It also selects `auth.secret`, `auth.github`, and `auth.routes`, so Auth.js
secret presence, GitHub OAuth credential presence, and deployed signin/session
reachability all stay visible as distinct launch-readiness evidence.
It selects `runtime.workerScheduler` as well, preserving whether projection and
publication drains are scheduled with `CRON_SECRET` or intentionally disabled
behind projection/publish scale flags before those workflows are enabled.
It selects `observability.uptime` from deployment preflight too, so the audit
separates "a production-safe uptime source exists" from the still-external
requirement to accumulate a passing 30-day uptime window; probe-based uptime
must point at the final public HTTPS deployment URL unless a Prometheus source
is configured.
It also selects `evidence.validationService` and
`evidence.reconciliationService` from deployment preflight, so launch readiness
keeps the deployed Render `/health` probes visible alongside the dedicated
Render-services goal.
The 30-day SLO/uptime goal selects the Era C exit-gate checks `sota204P95`,
`publicReadUptime`, `activityFeedAdoption`, and `sota26Kpis`, so performance
misses, insufficient uptime depth, missing external consumers, and KPI export
gaps become their own real-world blocker rows with the
`pnpm era-c:exit-gate:public` remediation command. Its coarse readiness flag
also requires the selected long-term runway rows and these Era C rows to pass,
so a top-level ready runway artifact cannot hide a failing exit-gate check.
It also selects `smoke.crawlerPreview` from both launch evidence and launch
review packets, so social metadata cannot be accidentally dropped from the final
launch-review gate while still appearing green in an earlier smoke step.
Launch evidence packets also carry per-step `nextEvidenceNeeded` and
`remediation` fields for failed or skipped steps, so the top-level audit can be
handed to an operator with concrete commands and artifact paths instead of a
generic "launch readiness blocked" note.
`pnpm review:goals` preserves those fields inside
`evidenceArtifactCheckStatuses` as `nextEvidenceNeeded`,
`remediationCommand`, and `remediationArtifact`, which keeps the JSON schema,
Markdown handoff, and underlying launch packet aligned.
When a source artifact uses launch-preflight or launch-review fields such as
`recommendation`, `command`, or `evidencePath`, the collector normalizes those
into the same next-evidence/remediation fields. Derived pilot, long-term, and
ActivityStreams checks also receive default package-script and artifact targets
so no selected blocker row is left as prose-only evidence debt.
Each goal also includes `externalEvidenceBlockers`, a machine-readable list of
the unresolved real-world evidence requirements. It includes both coarse flags
such as `launchEvidenceReady` and artifact-specific checks such as
`artifacts/launch/launch-evidence-latest.json#hardening.securityDr`, with status,
next evidence, and remediation fields. Coarse external checks carry their own
next-evidence text, operator command, and artifact target, so production launch,
Render service probe, long-term SLO/uptime, ActivityStreams syndication, and
paid-pilot blockers can be handed off without inheriting misleading prose from
the enclosing goal or reverse-engineering the right package script.
The report also flattens all goal-level blockers into a top-level
`externalEvidenceBlockers` array with `goalId`, `goalTitle`, `goalCategory`, and
`goalStatus`, so CI, dashboards, and operator handoffs do not need to walk each
goal before listing the remaining real-world evidence.
The report also includes a top-level `nextActions` array that groups blockers by
remediation command and unions every referenced artifact path into
`artifactTargets`. A grouped action is keyed by both command and
`executionScope`, so the same package script may appear once for deployment
setup and once for real-world proof without collapsing those lanes. A grouped
action keeps every distinct evidence sentence from
the underlying blockers in `nextEvidenceRequirements`, while
`nextEvidenceNeeded` stays as a compact human string, and the display `artifact`
is generated from the same machine-readable target list. It also carries
`executionScope` as `local-refresh`, `deployment-environment`, or
`real-world-evidence`; `blockerIds` are goal-scoped references in the form
`<goalId>:<externalCheckOrArtifactCheckId>` so a blocker reused by launch and a
long-term goal is not collapsed into one ambiguous id, and `blockerCount`
matches the number of scoped references in that list. The top-level
`nextActionSummary` gives counts, action IDs, distinct commands, artifact
targets, blocker totals, distinct goal IDs, goal titles, goal categories, and
goal counts for each scope. That lets stale local reruns, deploy/env fixes, and
customer or 30-day proof be queued separately. This lets one
`pnpm launch:preflight:production` row preserve separate storage, SSL,
role-override, or service-probe requirements without forcing CI or dashboards to
parse prose or path lists. Use this as the short operator run list; keep
`externalEvidenceBlockers` for the full per-check audit trail.
The `score.blockedByExternalEvidence` metric combines `localComplete` and
`externalEvidenceRequired`, making the total number of goals still blocked from
10/10 visible even when one goal is marked `local-gate-complete` rather than
`external-evidence-required`. The top-level `blockedByExternalEvidenceGoals`
array names those same goals with id, title, category, status, next evidence,
blocker count, exact blocker ids, grouped action ids, execution scopes, commands,
artifact targets, a per-goal action breakdown, and a per-goal scope breakdown.
That lets an operator or dashboard list the four external-proof handoffs and see
which command remediates which blocker, with goal-local evidence requirements
and scope-specific blocker totals, without deriving them from the full goals
table or joining through `nextActions`.
The top-level `strictGateStatus` is the final gate result: it is `passed` only
when the report status is `ten-of-ten-ready`; it remains `failed` for both
missing local gates and local-green reports that still need production,
partner, customer, or 30-day evidence.
The top-level `strictGateFailureReasons[]` array is empty only when
`strictGateStatus` is `passed`; otherwise it lists incomplete local gates and
the non-empty blocker lanes with blocker counts, goal counts, and remediation
commands.
The top-level `strictGateFailureSummary[]` array carries the same information in
closed structured rows, including `kind`, optional `scope`, `goalIds`,
`remediationCommands`, and `artifactTargets`, so consumers can filter
deployment-environment blockers from real-world evidence blockers without
parsing prose.
The top-level `strictGateHandoff` object consolidates those strict-gate rows
into one operator payload with summary IDs, execution scopes, blocker count,
exact blocker IDs, exact next-action IDs, affected goal count and IDs/titles,
distinct remediation-command count, remediation commands, distinct artifact
target count, artifact targets, distinct next-evidence requirement count, and
every distinct next-evidence requirement from the matching scoped actions. Its
`scopeBreakdown[]` rows repeat those handoff fields per execution scope, so
deployment-environment work and real-world proof remain separable in dashboards
and launch packets. Its arrays are empty only when the strict gate has passed.
The nightly Era C evidence workflow also runs `pnpm review:goals` and uploads
`artifacts/review-goals/**` so the current 10/10 blocker state is captured with
the SLO, uptime, ActivityStreams, and KPI evidence packet.
The long-term packet also carries a `collectionPlan` with the daily workflow
cadence, next scheduled run, missing distinct SLO/uptime days, missing external
consumer count, and earliest possible ready date when no hard SLO/uptime failure
needs operator intervention.
Status Meanings
| Status | Meaning |
|---|---|
| `complete` | The local command, doc, test, and evidence checks for that goal are present and no external evidence is required. |
| `local-gate-complete` | The local gate exists, but the goal still needs production evidence before it can be counted as truly complete. |
| `external-evidence-required` | The local machinery exists, but real production, partner, or customer evidence is still missing. |
| `incomplete` | A local command, doc, or test is missing and must be fixed before evidence collection is meaningful. |
Current Intent
The audit is allowed to fail `--check` until every real-world blocker is resolved.
That is intentional: the project should not claim 10/10 while SLO history,
external ActivityStreams consumers, or real paid pilot evidence are still absent.
The local-gate command should pass during that interim state, proving the
remaining failures are external evidence requirements rather than missing local
scripts, docs, or tests.
The current local goal is `incomplete: 0`; after that, the remaining blockers must
come from real evidence. The latest local refresh pass also drives
`nextActionSummary.local-refresh` to zero, so remaining action lanes are
deployment-environment setup and real-world evidence collection:
invoice-backed billing evidence.
- production launch readiness and long-term SLO/uptime depth,
- real external ActivityStreams consumers with durable callback subscriptions,
- real managed pilot support, activation, KPI, retention, and non-placeholder
Evidence Artifact Targets
The remaining external blockers are proven by these latest artifacts:
| Blocker | Latest artifact targets |
|---|---|
| Launch readiness | `artifacts/launch/launch-evidence-latest.json`, `artifacts/launch/launch-review-latest.json`, `artifacts/launch/deployment-preflight-latest.json`, `artifacts/exit-gate/era-c-exit-gate-latest.json`; selected launch-review and deployment-preflight checks are listed in `evidenceArtifactCheckStatuses` |
| 30-day SLO and uptime | `artifacts/long-term-evidence/long-term-evidence-runway-latest.json`, `artifacts/long-term-evidence/long-term-evidence-maintenance-latest.json`, `artifacts/long-term-evidence/long-term-evidence-maintenance-latest.md`, `artifacts/exit-gate/era-c-exit-gate-latest.json`, `monitoring/public-read-uptime-history.json`, `artifacts/performance/k6-slo-trend.json`; selected runway SLO/uptime/adoption checks plus Era C `sota204P95`, `publicReadUptime`, `activityFeedAdoption`, and `sota26Kpis` checks are listed in `evidenceArtifactCheckStatuses`, while the maintenance artifact names failed samples, clean passing days, and the earliest failure-free window date |
| ActivityStreams syndication | `artifacts/activity-syndication/activity-syndication-evidence-latest.json`, `storage/activity-consumers.json`, `storage/activity-subscriptions.json`; selected declared-consumer and durable-subscription checks are listed in `evidenceArtifactCheckStatuses`, and accepted/rejected callback rows prove whether external HTTPS subscriptions use public non-placeholder callback hosts, match the callback URL, are fresh, and cover Create/Update/Delete |
| Managed pilot evidence | `artifacts/pilot-evidence/pilot-evidence-latest.json`, `artifacts/pilot-evidence/pilot-evidence-latest.md`; selected entitlement, non-placeholder invoice-backed billing, outreach, activation, support-load, KPI, and retention-signal checks are listed in `evidenceArtifactCheckStatuses` |