Skip to main content

Implementation Plan Critical Review

Date: 2026-02-18 Reviewer perspectives: CTO, CISO, Product Owner, Architect Status: Round 2 complete Scope: Review of Doc 15 + latest W1 UX/logic/scope + Visual QA plan

1. Executive Verdict​

Doc 15 is now directionally correct on the founder's core model:

  1. Authority Path is the durable object.
  2. Finding is the user/API/UI term.
  3. Exposure is a derived posture concept (not a navigational entity).

The plan is implementable, but four high-priority alignment items remain before coding should start at scale.

2. What Is Now Correct​

AreaVerdictNotes
Terminology modelCorrectfindings is primary persistence; no separate exposures collection in Doc 15.
Pipeline shapeCorrect target6-stage target remains architecturally valid for long-term platform design.
UX object modelCorrectCluster -> Authority Paths -> Path Detail flow is represented.
Temporal lifecycleCorrect directionPath-level finding timing (effective_from, resolved_at, intervals) supports first seen/last seen views.
Operations requirementCorrectObservability and alerting are explicitly required via architecture/02-processing-pipeline.md (sections 9-11).

3. Remaining Inconsistencies and Risks​

High 1 - W1 baseline docs vs W1.1 architecture scope are still mixed​

ux.md, logic.md, and scope.md still frame baseline W1 as bounded and mostly non-persistent, while Doc 15 is a W1.1 architecture move (persistent authority paths + path-bound temporal findings).

Impact:

  • Teams can mis-scope delivery (implement baseline W1 while expecting W1.1 outcomes).
  • Review feedback appears contradictory across docs.

Recommendation:

  1. Add an explicit scope header in wedge docs: "Baseline W1" vs "W1.1 persistent authority-path model".
  2. Mark Doc 15 as the implementation source of truth for W1.1.
  3. Add cross-links from wedge docs to Doc 15 for persistence/lifecycle behavior.

High 2 - Status semantics need one canonical mapping​

Current model uses platform finding status values (active, acknowledged, remediated, false_positive) while UX text uses "Active/Resolved" language.

Impact:

  • API and UI may diverge in filtering and badge logic.
  • Incorrect status analytics in clusters and posture cards.

Recommendation:

  1. Keep storage/API canonical: remediated.
  2. Keep UI label: Resolved.
  3. Add one status mapping table in Doc 15 and API docs.

High 3 - Risk cluster drill-down contract must be frozen before UI build​

Founder flow requires:

  • Overview (top clusters)
  • Cluster detail page (authority path rows + inline expansion)
  • Separate authority paths inventory page
  • Path detail page

Doc 15 contains this flow, but contract details are still underspecified for implementation handoff (row fields, expand payload shape, paging/filter guarantees).

Impact:

  • UI rework risk after backend delivery.
  • Divergent implementations across pages using similar data.

Recommendation:

  1. Define one shared AuthorityPathListItem response contract used by both cluster-detail and authority-paths pages.
  2. Freeze required row fields from UX spec (ID, name, last execution, executions 30d, ownership status, data domains, egress, finding pills).
  3. Require cursor pagination + stable sort key by default.

High 4 - Visual QA plan sequencing still over-invests in soon-to-change surfaces​

Some QA items target pages that are being replaced in the path-first rollout.

Impact:

  • Avoidable engineering churn.
  • Delay on critical architecture work.

Recommendation:

Use two QA batches:

  1. Pre-migration must-fix: B1, D1, D2, D4, U2, U6.
  2. Post-path rollout or skip: D3, U1, U3, U4, U5, U7.

4. Critical Naming and Taxonomy Rules​

To avoid another naming collision:

  1. Keep canonical finding type codes unchanged (orphaned_ownership, dormant_authority, reachable_sensitive_domain, unknown_identity_binding, unproven_execution, scope_drift, llm_egress, external_egress, ownership_ambiguous, ownership_unknown).
  2. Do not introduce duplicate _path finding-type variants.
  3. Represent path scope using path_id (and optional scope=path|entity|all query filter).
  4. Keep "Exposure" only as computed posture language, not as entity/page/route naming.

Phase 0 - Decision lock and doc alignment (1 day)​

  1. Lock W1.1 as the active implementation scope.
  2. Add baseline vs W1.1 boundary notes to scope.md and logic.md.
  3. Confirm status mapping (remediated -> UI "Resolved").

Phase 1 - Foundation fixes and QA essentials (0.5-1 day)​

  1. Fix B1 posture summary contradiction.
  2. Apply D1, D2, D4, U2, U6.

Phase 2 - Authority path persistence (3-4 days)​

  1. authority_paths collection + storage adapter + indexes.
  2. Project-stage materialization and soft-removal lifecycle.
  3. Authority-path list/detail APIs.

Phase 3 - Path-level finding extension (3-4 days)​

  1. Extend FindingDoc with path lifecycle fields.
  2. Path-bound evaluation write pattern.
  3. Path-level finding queries and cluster aggregation.

Phase 4 - Founder UX flow (4-6 days)​

  1. Overview page (2 posture cards + delta + top clusters).
  2. Risk cluster detail page with inline expansion.
  3. Authority paths inventory page.
  4. Authority path detail page.

Phase 5 - Platform-side classification (parallelizable, 2-3 days)​

  1. Move security_relevance, execution_mode, egress_category to platform resolve stage.

Phase 6 - Operational hardening and cleanup gates​

  1. Enforce telemetry/alerts/SLOs.
  2. Run failure drills.
  3. Only then execute cleanup/deprecations.

6. CTO Observability Checklist (Go/No-Go)​

Before production rollout:

  1. Stage-level durations and retry counters emitted.
  2. Alerting active for hard failure, stall, ingestion silence, backlog growth.
  3. Correctness validator active post-sync.
  4. Two weeks stable SLO compliance before deleting legacy surfaces.

7. Closed Decisions (2026-02-18)​

Decision 1 — Path-level rows (not lineage-level)​

Question: When the same workload reaches the same destination through multiple identities, show one row per full path or one grouped row per workload→destination pair?

Decision: One row per full path (AuthorityPathDoc).

Rationale:

  • Findings are bound to specific paths — a Contributor path may have dormant_authority while a Reader path does not. Grouping would merge findings misleadingly.
  • Storage model is path-level; showing anything else adds an abstraction layer that causes UI/API mismatch.
  • Feb 18 mockups show individual identity names per row.
  • Lineage grouping can be added later as a UI-only visual grouping (collapsible rows) without schema or API changes.

Decision 2 — Keep resolved_at, document the mapping​

Question: The status enum value is remediated, the UI label is "Resolved", and the timestamp field is resolved_at. Should the field be renamed to remediated_at?

Decision: Keep resolved_at. Add one-line documentation note.

Rationale:

  • resolved_at is semantically correct — it records when a finding left active state regardless of reason (remediated, false_positive, path_removed).
  • A finding marked false_positive has a resolved_at but was never "remediated" — calling it remediated_at would be wrong for non-remediation closures.
  • Zero code churn. The field already exists in the codebase.
  • Clean separation: WHEN closed (resolved_at) vs WHY closed (resolution_reason) vs HOW DISPLAYED (UI: "Resolved").

Documentation note for API docs: resolved_at is the timestamp when a finding left active state, regardless of resolution reason. The resolution_reason field captures why (remediated, false_positive, path_removed, sensitivity_downgraded). The UI renders status remediated as "Resolved".

Decision 3 — Cluster page: locked context with handoff link​

Question: When a CISO clicks into a Risk Cluster detail page, can they modify filters or is the view locked?

Decision: Locked to cluster context. A "View in Authority Paths" link carries the cluster's conditions as pre-filled filters to the Authority Paths page for ad-hoc exploration.

Rationale:

  • CISO triage flow needs focus — "here are the 12 paths in this cluster" is clearer than editable filter chips.
  • Feb 18 mockups show clusters as distinct cards with their own detail view, not as filter presets.
  • Filter editing infrastructure only needs to exist on the Authority Paths page — no duplication.
  • If users edit all filters away, the cluster page becomes an unlabeled copy of Authority Paths — confusing.
  • Configurable/custom clusters may be added later, but pre-configured clusters that "just work" are the right starting point. Too much flexibility can be harder to comprehend than focused views.

8. Final Recommendation​

Proceed with Doc 15 as the architecture baseline for W1.1, with the four high-priority alignments above completed first.

This keeps founder UX intent intact, avoids exposure/finding model drift, and gives CTO-grade operability for pipeline execution and failures.