# Feedback-to-Roadmap Decision Contract v1.0

Date: 2026-07-31  
Status: proposed portfolio contract, planning only  
Plan confidence: **94/100**. One frozen evidence, ownership, and verification contract prevents duplicate backlogs and false completion across every product repository. This is an executive judgment score, separate from fingerprint priority.

## Authority

- GitHub remains the source of truth for issues, releases, and acceptance receipts.
- This versioned repository is the canonical portfolio-docs home. The physical `VPNCHEAP/` parent is not a valid Git repository and owns no canonical artifact.
- Each product plan names semantic revision `v1.0, 2026-07-31`. During this uncommitted planning review it links to the dated public Pages mirror so the contract is not a 404; first repository publication replaces that mirror with the canonical GitHub path and pins the resulting commit SHA in the portfolio release index.
- Historical closure, current implementation state, and real-world verification are separate fields.

## Governing principles

1. Prioritize deduplicated customer harm, not keyword volume.
2. Production traffic counts are denominators, never complaint counts.
3. Synthetic and canary traffic contributes zero reach and zero recurrence.
4. One failure has one accountable integration owner even when several repositories contribute.
5. Fix the earliest failing layer and verify at the customer-visible surface.
6. Historical closure stays in the archive. A recurrence creates a linked regression fingerprint.
7. Implementation is not completion. Only real acceptance evidence promotes `△` to `○`.
8. Never weaken tenant isolation, signed mutation auth, transcript privacy, dirty-tree safety, or VPN network secrecy.

## Evidence contract

Every factual statement carries one label:

- **MEASURED**: reproducible query or instrument result with source, time window, cohort, denominator, deduplication, and synthetic-exclusion rule.
- **OBSERVED**: direct customer report, device reproduction, log, screenshot, or operator observation. It proves behavior, not prevalence or cause.
- **INFERRED**: best causal explanation from evidence. It must name the test that could disprove it.
- **PROPOSED**: intervention, target, or policy. It is never presented as shipped or proven.

Required record: fingerprint, product, platform, version, journey, privacy-safe symptom, first and last seen, unique genuine users or incidents, evidence labels, source links, exclusions, current state, and verification receipt. Raw transcripts, secrets, ingress addresses, and VPN protocols are forbidden.

### Current portfolio baseline

- **MEASURED:** 38 deduplicated historical items plus one current seed.
- **MEASURED:** strict current audit is `○ 1 | △ 25 | ☐ 13 | X 0` across 39 unique items.
- **MEASURED:** ReplyTower production sample contains 1,408 genuine VPNCheap conversations, 8,920 messages, and 1,047 users; 5,543 synthetic canaries are excluded.
- **MEASURED:** structured feedback capture is 0.71%. This measures capture health, not customer satisfaction.
- **MEASURED:** zero exact 2MB complaints appeared in the retained ReplyTower production messages.
- **INFERRED:** a panel PHP `2M` setting is the leading exact-2MB hypothesis because ReplyTower is 10MB effective and the plugin chooses the smallest layer. It remains unconfirmed until the live panel chain is read.

The recall ledger's `CLOSED` field remains historical. The roadmap symbols above use the stricter real-verification definition.

## Priority score

Score each active fingerprint once:

`Priority = Harm + Genuine reach + Evidence + Leverage + Urgency + Verification debt`

| Factor | Points |
|---|---:|
| Harm: cosmetic / friction / degraded / blocker / security-data-loss-outage | 0 / 8 / 16 / 24 / 30 |
| Genuine reach: none / 1 / 2-4 / 5-19 / 20+ users or systemic reproduction | 0 / 3 / 7 / 11 / 15 |
| Evidence tied to the failure: proposed / inferred / observed / measured | 0 / 5 / 12 / 20 |
| Leverage: local / shared layer / multi-platform / portfolio-wide | 0 / 5 / 10 / 15 |
| Urgency: none / release window or rising exposure / active severe harm | 0 / 5 / 10 |
| Verification debt: none / low / material / release-blocking | 0 / 4 / 7 / 10 |

Duplicate mentions add no points. Reach uses unique genuine users or systemic reproduction, never raw messages. Inferred or proposed-only implementation is capped at 54. A severe security, privacy, billing, or data-loss suspicion creates an immediate evidence-acquisition incident instead of an unproven fix.

- **90-100:** P0, operation or release stop.
- **75-89:** P1, enter execution in days 0-30 and close or obtain approved `X` by day 60.
- **55-74:** P2, enter execution in days 31-60 and close or obtain approved `X` by day 90.
- **35-54:** P3, schedule by day 90. It may be accelerated only when it is a low-risk independent prerequisite, does not displace P0-P2 capacity, and the accountable owner records the exception.
- **1-34:** monitor.

Every fingerprint priority score includes its six-part breakdown and one dominant-factor sentence. Executive option and plan-confidence scores are separate judgments: they require a dominant-factor justification but do not reuse this customer-harm formula.

## Ownership algorithm

1. State the customer-visible invariant and its authoritative truth source.
2. Assign one **Accountable Integration Owner (A)**: the repository that ships the customer-visible surface and its end-to-end acceptance test.
3. Assign **Responsible Component Owner(s) (R)** to the earliest layer violating the invariant.
4. Keep one canonical GitHub issue in A's repository and link component children in every R repository.
5. R fixes the component. A owns customer-visible acceptance, release discovery, and final closure.

Applied here:

- ReplyTower panel-widget attachment outcome: `xboard-replytower` is A; ReplyTower and the hosting/PHP/Nginx owners are R where their layer fails.
- ReplyTower ticket attachment outcome: ReplyTower is A; the Xboard connector is R for its ticket payload contract.
- VPN stale or false state: the affected platform client is A; core/OS owns tunnel truth, Xboard owns account/node truth, and the boundary adapter owns freshness.
- Portfolio release and governance gaps: `vpncheap-app` is A.

## Roadmap states

- `☐`: not implemented end to end.
- `△`: implemented end to end, real acceptance missing.
- `○`: real acceptance passed and evidence linked.
- `X`: blocked, cut, or not applicable; reason, approver, and revisit condition required.

Transitions: `☐ -> △` after integration; `△ -> ○` only after real acceptance; failed acceptance returns to `☐`; any state can become `X` through an explicit decision.

## Truth-and-Constraint Envelope

Cross-boundary work records:

`subject | authoritative source | value/state | observed_at or generation | effective constraint | safe reason | stale/mismatch policy | accountable owner | verification receipt`

- Attachments: effective maximum is the measured minimum across backend, Nginx, PHP upload, PHP post, and plugin/client constraints. Capability display and rejection must agree.
- VPN: connection truth comes from core/OS; purchase, renewal, and node truth comes from the authoritative server response. UI honors generation and freshness. `○` requires a real device and changed public egress without revealing ingress details or protocol.

## Executive metrics and gates

Track only: active `○/△/☐/X` by priority/repository; archive count separately; evidence completeness; synthetic exclusion; assignment age; `△ -> ○` age and conversion; constraint mismatch rate; structured capture rate; closed-fingerprint regression rate.

### 0-30 days: evidence gate

- 100% of active items fingerprinted, labeled, scored, owned, and given acceptance plus stop criteria.
- All 25 `△` items have real-verification cards.
- Current attachment seed deduplicated and every limit layer measured.
- Stop if synthetic separation is unreproducible, ownership is missing, or privacy/auth boundaries would be crossed.

### 31-60 days: contract gate

- Every P0/P1 is `○` or approved `X`.
- At least 80% of scheduled verification debt becomes `○`.
- Every cross-boundary P0/P1 publishes an envelope and mismatch metric.
- Without device/public-egress proof or measured effective upload limit, remain `△`.

### 61-90 days: portfolio gate

- No scheduled P0/P1/P2 remains `△` or `☐`.
- Every explicit negative signal and escalation creates a structured record.
- Every cross-repo item has a canonical issue, release owner, and verification receipt.
- Two consecutive release windows show zero P0/P1/P2 regression.

## Forbidden patterns

No keyword voting, synthetic inflation, production volume presented as complaints, duplicate issues per layer, owner ping-pong, guessed 2MB root cause, UA-only authorization, UI-declared VPN truth, historical reopening, `△` called done, simulator-only verification, or raw transcript/network-detail evidence.

## Plan-writer checklist

- [ ] Contract revision linked.
- [ ] Every claim labeled MEASURED, OBSERVED, INFERRED, or PROPOSED.
- [ ] Window, denominator, fingerprint, genuine cohort, and exclusions recorded.
- [ ] Historical archive separated from the active tally.
- [ ] Score breakdown, band, and dominant rationale present.
- [ ] One A and all R owners named.
- [ ] `○/△/☐/X` tally shown.
- [ ] Cross-boundary work includes the envelope.
- [ ] Acceptance proves customer-visible behavior at the authoritative source.
- [ ] VPN verification includes a real device and changed public egress.
- [ ] Each phase has metric, exit gate, and stop condition.
- [ ] Privacy, auth, tenant, network-secrecy, and dirty-tree invariants preserved.