Review: Compass Management Operating Procedure

Steps

1. #1·Section 3 — Adding a New Compass

   ADD-1: Create the source app

   The vf-team compass exists and is live (VERIFIED). The scaffold pattern from `@vf/compass-template` for subsequent clients has not been executed. Reasoning: the package is a pnpm workspace member and follows standard Vite SPA conventions; this should work the same for any client. What would verify: scaffold a second client compass and confirm it builds.

   ASSUMED
2. #2·Section 3 — Adding a New Compass

   ADD-2: Add entry to manifest

   2026-04-23 — vf-team entry is in production manifest with all these fields. Pattern is confirmed.

   VERIFIED
3. #3·Section 3 — Adding a New Compass

   ADD-3: Seed the state file

   `seed-state.js` exists (confirmed in `scripts/compass/` ls). The vf-team state file exists and contains v2 schema with all expected keys. Whether `seed-state.js` generates the correct v2 schema from scratch has not been executed for a second client. The manifest comment instructs running it before first build.

   UNTESTED
4. #4·Section 3 — Adding a New Compass

   ADD-4: Verify HubSpot credentials and company ID

   2026-04-23 — standard VFT HubSpot connectivity. Confirmed working for vf-team extraction (state file shows `companyId: "49241304942"` with real query timestamps).

   VERIFIED
5. #5·Section 3 — Adding a New Compass

   ADD-5: Run first build

   vf-team first build was VERIFIED (state file records `build.lastRunAt: "2026-04-23T10:20:31.517Z"`, `gatesPassed: true`, `outcome: "built"`). Subsequent client builds follow the same orchestrator path. Risk: client HubSpot data sparseness could cause gate failures. Validate data completeness (ADD-4) before building.

   ASSUMED
6. #6·Section 3 — Adding a New Compass

   ADD-6: Commit output and push

   Standard git commit pattern. Gitignore behavior mirrors walkthrough convention. No evidence that a second client's compass has been committed.

   ASSUMED
7. #7·Section 4 — Running the Orchestrator

   ORCH-1: Invocation modes

   2026-04-23 — all four modes are documented in the orchestrator source header and match the vercel.json buildCommand usage (`node scripts/compass/build-all.mjs` no arguments).

   VERIFIED
8. #8·Section 4 — Running the Orchestrator

   ORCH-2: Expected orchestrator output

   2026-04-23 — state file shows `build.outcome: "built"`, `build.gatesPassed: true`, `build.buildDurationMs: 15998`. The exit-0 on per-entry failure is documented in source and was the design lesson from the 2026-04-22 cascade incident.

   VERIFIED
9. #9·Section 4 — Running the Orchestrator

   ORCH-3: Reading orchestrator logs

   Log format is inferred from the orchestrator source code patterns. Specific log strings have not been captured from a live run. Reasoning: the state file records `buildDurationMs` and `outcome`, which are set by the orchestrator, confirming it ran to completion.

   ASSUMED
10. #10·Section 5 — Change Detection and Skip Behavior

    CD-1: Input hashing

    2026-04-23 — state file contains `build.inputHash: "7f8012eb8394acc5"` written by a confirmed build run. The hashing mechanic is described in the orchestrator source as "Design property 1: Change detection."

    VERIFIED
11. #11·Section 5 — Change Detection and Skip Behavior

    CD-2: Force-rebuild override

    2026-04-23 — `--force` flag is documented in orchestrator CLI comment and confirmed in the command help text. Evidence: Showcase verified skip + force behavior in one session per context brief.

    VERIFIED
12. #12·Section 5 — Change Detection and Skip Behavior

    CD-3: Staleness vs. input hash

    2026-04-23 — state file confirms both fields exist independently: `staleness.status: "stale"` and `build.inputHash` are both populated with different semantics. The distinction is documented in the state file schema.

    VERIFIED
13. #13·Section 6 — Quality Gate Flow

    GATE-1: G1 — Source compliance (automated)

    2026-04-23 — state file `extractedFiles` entries all show canonical sources (HubSpot, Content Vault). No synthesis file paths appear in source attribution headers.

    VERIFIED
14. #14·Section 6 — Quality Gate Flow

    GATE-2: G2 — Source attribution (automated)

    2026-04-23 — state file `extractedFiles` entries include `source` fields with explicit canonical source descriptions for each file. G2 enforces this at gate time.

    VERIFIED
15. #15·Section 6 — Quality Gate Flow

    GATE-3: G3 — Build success (automated)

    2026-04-23 — state file records `build.outcome: "built"` and `gatesPassed: true`. Vite build completed for vf-team.

    VERIFIED
16. #16·Section 6 — Quality Gate Flow

    GATE-4: G4 — Content safety (automated)

    Gate is defined in `quality-gates.sh` source. Whether the scan covers all output files (JS bundles + HTML) and which exact forbidden terms it checks has not been verified by reading gate output. Reasoning: the gate passed (state file: `gatesPassed: true`) so it ran without finding violations. The pass is evidence the gate executed, not that its coverage is complete.

    ASSUMED
17. #17·Section 6 — Quality Gate Flow

    GATE-5: G5 — Deploy path (automated)

    2026-04-23 — `ls apps/portal/public/vf-team/compass/` returns `assets` and `index.html`, confirming the deploy target is populated.

    VERIFIED
18. #18·Section 6 — Quality Gate Flow

    GATE-6: G6 — Navigation (runtime, requires Mirror)

    Gate is explicitly marked `requires-runtime` in `quality-gates.sh` source comment and is skipped in automated pipeline. Mirror has not been dispatched to verify navigation on the live vf-team compass.

    UNTESTED
19. #19·Section 6 — Quality Gate Flow

    GATE-7: G7 — Visual consistency (runtime, requires Mirror)

    Same as G6 — `requires-runtime`, skipped in automated pipeline. Mobile overflow defect tracked as HubSpot Task `108388555848` suggests G7 has surfaced a known issue but the gate itself has not been formally run.

    UNTESTED
20. #20·Section 6 — Quality Gate Flow

    GATE-8: G8 — Data completeness (automated)

    2026-04-23 — state file `pages` section shows 5 pages (dashboard, sessions, changelog, stakeholders, roadmap) all with `status: "current"` and non-empty `sourceDigest` values, confirming data was present and complete.

    VERIFIED
21. #21·Section 7 — Freshness Checking

    FRESH-1: check-freshness.js invocation

    2026-04-23 — state file shows `staleness.checkedAt: "2026-04-22T04:02:16.500Z"` and `staleness.reasons: ["202 new session(s) since last build"]`. The script ran and wrote back to the state file.

    VERIFIED
22. #22·Section 7 — Freshness Checking

    FRESH-2: Staleness thresholds

    The state file shows `staleness.newSessionsSince: 202` which confirms session count drift is computed. The exact threshold (any session = stale, or a minimum drift count) is not confirmed from the script source. Reasoning: the state file shows stale at 202 sessions, indicating stale is triggered at >0 drift. Risk: if threshold is configurable, it may differ from this assumption.

    ASSUMED
23. #23·Section 7 — Freshness Checking

    FRESH-3: Atomic write-back

    Atomic write is described in the orchestrator source (Design property 6: "State file is source of truth — atomic write"). Whether `check-freshness.js` uses the same atomic write pattern is assumed by consistency. What would verify: inspect the write method in `check-freshness.js` source.

    ASSUMED
24. #24·Section 8 — Post-Session Automation

    PS-1: /post-session Step 7.5 trigger

    2026-04-23 — Step 7.5 language is in `/post-session` command source. vf-team compass exists at `clients/vf-team/apps/vf-team-compass/`. The detection pattern is confirmed. Evidence that Showcase has been spawned and executed a rebuild via this step is ASSUMED — the state file records a build on 2026-04-23 which may have been triggered this way.

    VERIFIED
25. #25·Section 8 — Post-Session Automation

    PS-2: Showcase spawn pattern in post-session

    The spawn delegation pattern is established and used for `/compass` direct invocation. Whether Step 7.5 has successfully completed a full compass rebuild via Showcase and written a new state file has not been independently confirmed.

    ASSUMED
26. #26·Section 8 — Post-Session Automation

    PS-3: State file update after rebuild

    State file update is a Design property (property 6: State file is source of truth). The vf-team state file has been updated (build timestamp 2026-04-23 is fresh). Whether a full rebuild cycle (post-session → Showcase → orchestrator → state file update → staleness cleared) has been completed end-to-end has not been confirmed.

    ASSUMED
27. #27·Section 9 — Meeting-Prep Integration

    MP-1: Pavilion freshness check in meeting-prep

    2026-04-23 — `/meeting-prep` command source explicitly instructs Pavilion to run `check-freshness.js` and report `staleness.status`, `staleness.reasons`, `staleness.newSessionsSince`, and `deploy.url`. The state file has `staleness.checkedAt` confirming the script has run.

    VERIFIED
28. #28·Section 9 — Meeting-Prep Integration

    MP-2: Stale compass handling

    2026-04-23 — `/meeting-prep` source explicitly states: "do not block the session or trigger a rebuild. The reasons will surface in the Portal line of the brief footer. Post-session rebuild is Showcase's responsibility."

    VERIFIED
29. #29·Section 9 — Meeting-Prep Integration

    MP-3: No state file exists

    `/meeting-prep` source states this explicitly: "If no .compass-state.json exists, return: status=untracked, reasons=[], url=null." Whether the actual `check-freshness.js` script handles missing state file gracefully is assumed by this instruction.

    ASSUMED
30. #30·Section 10 — Deploy Flow

    DEPLOY-1: Vercel buildCommand chain

    2026-04-23 — `apps/portal/vercel.json` read directly; buildCommand confirmed as shown. Compass is first in chain.

    VERIFIED
31. #31·Section 10 — Deploy Flow

    DEPLOY-2: Per-entry failure isolation (exit 0 behavior)

    2026-04-23 — Design property 5 is stated in orchestrator source: "Top-level exit 0 on per-entry failures — one broken compass does not fail the whole Vercel build." This was the lesson from the 2026-04-22 cascade incident where walkthrough failures took down 12 portals.

    VERIFIED
32. #32·Section 10 — Deploy Flow

    DEPLOY-3: Catastrophic orchestrator failure

    Per source documentation. These conditions have not been triggered in production.

    ASSUMED
33. #33·Section 10 — Deploy Flow

    DEPLOY-4: Gitignore for hashed assets

    The context brief states this mirrors the walkthrough pattern. The `.gitignore` has not been read directly in this session to confirm the exact pattern. What would verify: `grep -r "compass/assets" .gitignore apps/portal/.gitignore`.

    ASSUMED
34. #34·Section 11 — Migrating a Walkthrough to a Compass

    MIG-1: Reference migration playbook

    File `docs/plans/compass-migration-playbook.md` does not exist on disk as of 2026-04-23. The file found at `docs/plans/portal-migration-playbook.md` uses old naming (`@vf/portal-template`, `scripts/portal/`, `.portal-state.json`). This is either: (a) the playbook has not yet been renamed/updated to match compass naming, or (b) the playbook Chris referenced is a different file from what is on disk. Hone must confirm which file is canonical before this step can be marked anything other than BLOCKED.

    BLOCKED
35. #35·Section 11 — Migrating a Walkthrough to a Compass

    MIG-2: 5-step migration flow (summary)

    This summary describes ADD-1 through ADD-6 combined with a decommission step. The decommission step (leaving walkthrough output live during transition) has not been documented or executed for any client other than vf-team, and vf-team's walkthrough (`collective-walkthrough`) was left live separately per state file notes.

    NOT BUILT
36. #36·Section 12 — Failure Modes and Recovery

    FAIL-1: Gate failure — prior output preserved

    2026-04-23 — Design property 3 is stated in orchestrator source: "temp build + gate + swap; failed builds leave the prior deployed output in place."

    VERIFIED
37. #37·Section 12 — Failure Modes and Recovery

    FAIL-2: Extraction failure — non-fatal warning

    Non-fatal warning behavior is implied by the gate architecture (G8 catches empty data files). Whether `extract-data.js` itself handles errors gracefully (try/catch per source) vs. crashes has not been confirmed by reading the full script source.

    ASSUMED
38. #38·Section 12 — Failure Modes and Recovery

    FAIL-3: 2026-04-22 cascade lesson — Vercel cascade prevention

    2026-04-23 — Design property 5 cites this lesson explicitly in source. Confirmed by state file (build succeeded; gatesPassed: true) across a full Vercel deploy cycle.

    VERIFIED
39. #39·Section 12 — Failure Modes and Recovery

    FAIL-4: Mobile overflow defect (HubSpot Task 108388555848)

    Active defect. G7 is runtime-only and has not been executed. The defect is known and tracked but not yet resolved.

    BLOCKED