TenantAtlas/specs/439-branch-topology-local-evidence-truth/plan.md

Implementation Plan: Spec 439 - Branch Topology and Local Evidence Truth

Branch: feat/439-branch-topology-local-evidence-truth | Date: 2026-07-10 | Corrected: 2026-07-11 | Spec: specs/439-branch-topology-local-evidence-truth/spec.md Input: Corrected Spec 439 branch-topology and engineering-evidence remediation. Status: Implemented and reconciled; merge-ready locally with an external activation condition.

Lifecycle boundary: Imperative phase text and readiness gates below preserve the approved preparation-time execution plan. Current task completion, evidence, residuals, and merge status are owned by tasks.md and implementation-report.md.

Summary

Implement one bounded repository-governance slice that:

1. first replaces the obsolete universal dev branch rule through the current Constitution Amendment Procedure;
2. validates that amendment before synchronizing directly conflicting authoritative instructions;
3. resolves branch family separately from the concrete Git ref;
4. maps ordinary platform work to platform-dev and ordinary website work to website-dev;
5. permits dev only for explicitly classified repository integration/promotion;
6. removes silent stream fallback to dev, origin/dev, or HEAD~1;
7. preserves the original test process result through report refresh;
8. makes existing blocking/advisory budget profiles affect the final command result correctly;
9. validates required JUnit/report evidence and detects contradictions;
10. proves the contract with deterministic local fixtures.

The implementation changes governance documents, repository tooling, tests, and existing local evidence/report wiring only. It does not change product runtime, rendered surfaces, data, RBAC, OperationRun behavior, deployment, or remote branch administration.

Technical Context

Language/Version: Markdown governance documents; Bash; PHP 8.4.15 for existing test-support code Framework/Test Stack: Laravel 12 repository, Pest 4, PHPUnit 12, Symfony Process already available Storage: Existing filesystem test artifacts only; no database changes Project Type: Monorepo with apps/platform, apps/website, root scripts, Spec Kit, and Gitea workflow declarations Primary Constraints: Constitution amendment first; Sail-first for PHP/Pest; no network-dependent fixtures; no product runtime; no new dependency; no generic branch graph Performance Goal: Focused fixtures remain small and deterministic; existing Fast Feedback and Confidence budgets remain the no-regression boundary Scale/Scope: Three known long-lived branches, fixed work classifications, existing local lane/report entry points

Correction Preflight Evidence

Spec correction began on feat/439-branch-topology-local-evidence-truth at 71e3745a with only the existing untracked Spec 439 package.

Confirmed current repo truth:

• Constitution 2.16.0 still contains the universal dev branch rule.
• The Amendment Procedure requires an explicit Constitution update PR, rationale, impacted templates/specs, SemVer decision, and Last Amended update.
• No authoritative repo rule requires a separate preceding Amendment Spec.
• Agents.md still contains directly conflicting universal dev instructions.
• The current changed-file guard defaults to origin/dev and then HEAD~1.
• The PR fast-feedback workflow explicitly fetches/passes origin/dev.
• TestLaneManifest::renderLatestReport() supplies exitCode 0 and returns 0 unconditionally.
• TestLaneReport::parseJUnit() currently extracts duration data only.
• TestLaneBudget already owns trigger-aware blocking/advisory classifications.
• Spec 438 remains deferred and unimplemented.

Implementation Phase 0 MUST revalidate these call paths and governance rules on current HEAD. Material drift requires reconciliation of the active artifacts before mutation.

Governance Decision

Amendment posture

The branch-topology amendment is inside Spec 439 scope and is Phase 1. It is not an external prerequisite.

The same Spec 439 feature PR may contain:

1. the narrow Constitution amendment;
2. its required Sync Impact, rationale, impacted-artifact list, SemVer decision, and Last Amended update;
3. directly dependent implementation after the Phase 1 validation gate.

No Phase 2-8 work is authorized before the Phase 1 amendment is applied and validated. The Amendment Procedure does not require a second feature spec, but the Constitution itself remains authoritative until Phase 1 changes it.

SemVer handling

The implementation MUST not predetermine PATCH. Replacing the universal dev rule is a semantic governance change. Phase 1 must select and justify the version under the current policy; a backward-incompatible interpretation requires MAJOR, while any MINOR decision requires an explicit rationale explaining why the change is an expansion rather than an incompatible redefinition.

Amendment boundary

Allowed:

• replace only the universal dev branch rule;
• define dev, platform-dev, and website-dev roles;
• define scope-specific feature base, normal target, and diff baseline;
• require explicit cross-stream/promotion classification;
• forbid silent wrong-family and HEAD~1 fallback;
• update required amendment metadata;
• identify directly conflicting authoritative artifacts for Phase 2.

Forbidden:

• general Constitution cleanup or reduction;
• UI/UX, security, architecture, provider, RBAC, OperationRun, or product-governance changes;
• skill reorganization;
• unrelated guidelines/docs cleanup;
• runtime, deployment, or remote-administration changes.

Amendment-first close-out evidence

The Phase 1 hard execution gate remains unchanged. Close-out proof does not attempt to reconstruct wall-clock mutation order from the final diff. It uses the final Constitution amendment, exact boundary and unrelated-scope controls, synchronized dependent instructions and implementation, task/report process attestation, and the absence of a conflicting final state.

No commit, tag, patch, or snapshot checkpoint was mandated before Spec 439 implementation began; none is retroactively claimed. Any future plan requiring independently reconstructable chronology must define and capture that checkpoint before its first mutation.

Development Stream and Merge Strategy

• Work classification: repository-governance.
• Feature base: platform-dev.
• Feature branch: feat/439-branch-topology-local-evidence-truth.
• Normal merge target: platform-dev.
• Promotion to dev: later explicit integration work, outside Spec 439.
• Website convergence: no delivery contract is created; website family behavior is proven through deterministic fixtures only.
• Constitution amendment delivery: included in the same feature PR and applied before dependent implementation on the feature branch.

This strategy does not rename, synchronize, merge, or rebase long-lived branches.

Canonical Branch Topology

Branch	Role	Ordinary Feature Base	Normal Target	Diff Baseline
dev	Repository-wide integration and promotion	explicit only	explicit promotion/integration	explicit
platform-dev	TenantPilot platform integration	platform-dev	platform-dev	platform-dev
website-dev	Website integration	website-dev	website-dev	website-dev

Repository-governance work is explicitly classified by affected scope. Spec 439 is platform-owned repository governance and therefore uses platform-dev for base, target, and baseline. Cross-stream and promotion work must declare a target and may target dev. The existence of dev never implies fallback.

Unified Resolver Contract

The resolver makes two separate decisions. This section intentionally matches spec.md verbatim in substance and priority.

Stage 1 - Resolve the branch family

Priority:

1. explicit CLI or workflow branch-family input;
2. pull-request target branch from event context;
3. active spec metadata or explicit spec classification;
4. current feature-branch naming plus repository-scope signals;
5. otherwise fail closed.

Rules:

• Explicit input MUST be validated against a known branch family.
• A present PR target is authoritative when it maps to a known branch role.
• Spec metadata MUST NOT contradict a valid PR target.
• Branch-name and path/scope signals are subordinate detection aids and are never sufficient when ambiguous.
• The highest-priority usable signal selects the candidate family, but every other present authoritative signal MUST be checked for conflict.
• A real conflict, including explicit family platform with PR target website-dev, MUST fail with an actionable conflict diagnostic.
• No source may silently override a contradictory authoritative source.
• There is no silent default to dev.

Stage 2 - Resolve the concrete Git reference

After the branch family is known:

1. explicit validated Git ref for the selected branch family;
2. matching remote ref, for example origin/platform-dev;
3. matching local ref, for example platform-dev;
4. validate ancestry and compute the merge base;
5. otherwise fail closed.

Rules:

• Only refs belonging to the selected branch family are valid.
• Missing origin/platform-dev MUST NOT fall back to origin/dev.
• Missing origin/website-dev MUST NOT fall back to origin/dev.
• HEAD~1 is not a valid integration-baseline fallback.
• An explicit cross-stream/promotion target may use dev only after Stage 1 classified the work accordingly.
• Output MUST include branch family, expected integration branch, selected ref, target commit, merge-base commit, and resulting base range.
• Failure output MUST include the conflicting or attempted signals/refs, explicit override guidance, and confirmation that no diff ran.

Terminology

• Branch family: The workstream/integration role selected in Stage 1.
• Concrete Git ref: The validated remote, local, or explicit ref selected in Stage 2.
• Merge base: The common commit used to derive feature-relative changes.
• Feature base: The branch from which ordinary work in a family starts.
• Normal PR target: The default integration target for ordinary work in a family.
• Promotion target: An explicitly declared cross-stream/repository integration target, which may be dev.

Proposed Repository Changes

1. Narrow Constitution branch-topology amendment

Update .specify/memory/constitution.md only as authorized by FR-001 through FR-007:

• replace the universal dev statement;
• define all three branch roles and scope-specific routing;
• require explicit cross-stream/promotion classification;
• forbid silent wrong-family and HEAD~1 fallback;
• update the Sync Impact Report, SemVer version, and Last Amended;
• include rationale and impacted templates/specs/instructions.

Validate the amendment diff before any other file changes.

2. Direct authoritative instruction synchronization

After Phase 1 validation:

• update only directly conflicting branch instructions in Agents.md;
• inspect branch-related authoritative skills/instructions and change only confirmed contradictions;
• retain valid platform-dev and promotion guidance;
• record unrelated drift as residual debt;
• do not rewrite historical completed/deferred specs.

3. Small two-stage branch resolver

Add one small root executable, expected at scripts/resolve-feature-base unless Phase 0 proves an existing narrower shared path.

The resolver owns only:

• fixed branch families and current roles;
• Stage 1 signal validation/conflict detection;
• Stage 2 family-matching ref resolution;
• ancestry and merge-base calculation;
• fail-closed diagnostics;
• stable human-readable output plus the smallest machine-readable output needed by existing consumers.

It does not fetch, mutate branches, inspect arbitrary repositories, manage releases, or model user-configurable graphs.

4. Existing changed-file guard integration

Update scripts/check-ui-productization-coverage to consume the unified resolver while preserving:

• its explicit base argument;
• committed/staged/unstaged/untracked collection;
• existing productization checks;
• exit 2 before diff when family/ref resolution fails.

The guard must print family, ref, target, merge base, and base range. No website productization framework is introduced.

5. Existing repository-side workflow declaration coherence

Inspect .gitea/workflows/test-pr-fast-feedback.yml and contract tests.

If current event syntax is repo-locally provable, pass the actual PR target through the unified family/ref contract instead of hard-coded origin/dev. Preserve all triggers, jobs, lanes, artifacts, and schedules.

If syntax is not repo-locally provable, leave the workflow unchanged, record the residual, and do not claim remote validation.

TestLaneManifest::MAINLINE_BRANCH = dev and main-confidence dev push remain valid promotion semantics.

6. Test execution and report-result preservation

Extend the existing TestLaneManifest/TestLaneReport path:

• persist the real test process result during finalizeLane();
• carry it through renderLatestReport();
• derive one final result from execution, required evidence, evidence consistency, report generation, and blocking budget truth;
• keep advisory warnings non-blocking;
• preserve both test and report-generation failure contexts;
• extend the existing schema minimally.

7. JUnit validity and contradiction detection

Extend the smallest existing helper to expose:

• existence and parse validity;
• test, failure, error, and skipped counts;
• derived evidence status;
• affected evidence path in diagnostics.

Missing/malformed evidence, JUnit failure with passed claim, and failed process with apparently successful evidence cannot normalize to PASS.

8. Blocking versus advisory budgets

Keep TestLaneBudget::enforcementProfiles() authoritative:

• hard-fail plus over-budget returns non-zero;
• hard-fail within-tolerance warning is non-blocking absent another failure;
• soft-warn remains visible and non-blocking;
• trend-only remains informational;
• missing data required by an active blocking profile fails closed.

No threshold or profile classification changes are authorized merely to regain green output.

Constitution Check

Readiness gate

• Amendment Procedure: PASS for implementation readiness. Spec 439 authorizes an explicit Phase 1 update with required rationale, impact list, SemVer, and Last Amended handling.
• Current universal dev rule: Known contradiction to be replaced by the first mutation; it does not authorize dependent work before Phase 1 validation.
• PROP-001 / ABSTR-001 / BLOAT-001: PASS. One fixed resolver and one narrow rule replacement are justified by current platform/website and evidence consumers; no general framework.
• SPEC-DISC-001 / LAYER-001: PASS. Governance, branch truth, and evidence truth remain one coherent repair rather than multiple micro-specs or parallel report layers.
• TEST-TRUTH-001 / TEST-GOV-001: PASS by design. Unit and bounded Feature tests protect actual outcomes; Fast Feedback and Confidence are affected lanes; no heavy family.
• PERSIST-001 / STATE-001: N/A for product persistence/state.
• PSC-001 / UI-COV-001: N/A - no rendered UI.
• RBAC / workspace / provider / OperationRun / customer output: N/A.

Phase gate

The plan is ready to start Phase 0 and Phase 1. It is not permission to start Phase 2-8 early. Any dependent diff before recorded Phase 1 validation is a plan violation and must be removed or the implementation stopped.

Product and Runtime Impact

• Platform runtime: none.
• Website runtime: none.
• Database/migrations: none.
• Routes/UI/Filament/Livewire: none.
• RBAC/policies/capabilities: none.
• OperationRun/audit/product evidence: none.
• Customer output: none.
• Assets: none; filament:assets is not required.
• Deployment: no env, migration, queue, scheduler, storage, proxy, or Dokploy change.

Project Structure

Expected implementation surfaces, subject to Phase 0 confirmation:

.specify/memory/constitution.md
Agents.md
scripts/
├── resolve-feature-base
├── check-ui-productization-coverage
├── platform-test-lane                 # only if propagation requires it
└── platform-test-report               # only if propagation requires it
.gitea/workflows/
└── test-pr-fast-feedback.yml          # conditional existing-target correction
apps/platform/
├── composer.json                      # only if compatible entry arguments require it
└── tests/
    ├── Support/
    │   ├── TestLaneManifest.php
    │   ├── TestLaneReport.php
    │   └── TestLaneBudget.php         # authoritative profiles; expected unchanged
    ├── Unit/Support/
    │   ├── TestLaneReportTest.php
    │   └── TestLaneBudgetTest.php
    └── Feature/Guards/
        ├── BranchTopologyContractTest.php
        ├── ConstitutionBranchTopologyContractTest.php
        ├── TestLaneCommandContractTest.php
        ├── TestLaneArtifactsContractTest.php
        ├── CiLaneFailureClassificationContractTest.php
        └── directly affected Ci workflow contract tests
specs/439-branch-topology-local-evidence-truth/
├── spec.md
├── plan.md
├── tasks.md
├── checklists/requirements.md
├── evidence/baseline-attribution.json # compact paired close-out evidence
└── implementation-report.md           # created only during Phase 8

Forbidden runtime paths include apps/platform/app, apps/platform/database, apps/platform/routes, apps/platform/resources, and apps/website/src unless the active spec is corrected before any such change.

Test Strategy

A. Constitution and instruction contracts

Required cases:

1. branch roles and scope routing are present;
2. universal dev feature-base wording is absent from authoritative current instructions;
3. cross-stream/promotion requires explicit target;
4. wrong-family and HEAD~1 fallback are forbidden;
5. unrelated Constitution principles remain unchanged;
6. Sync Impact, rationale, SemVer, and Last Amended are coherent.

B. Branch-topology fixtures

Use Pest with Symfony Process and isolated temporary Git repositories. Each fixture configures identity, commits, branches, and refs without network.

Required cases:

1. platform remote-ref priority;
2. platform local-ref fallback;
3. website remote-ref priority;
4. website local-ref fallback;
5. explicit promotion to dev;
6. missing platform refs fail closed;
7. missing website refs fail closed;
8. diverged platform topology returns only the feature path;
9. diverged website topology returns only the feature path;
10. explicit platform family plus PR target website-dev fails;
11. ambiguous name/path/spec signals fail;
12. explicit wrong-family ref is rejected;
13. success/failure diagnostics contain required fields.

C. Evidence-truth fixtures

Required cases:

1. failed process remains failed after refresh;
2. passed process remains passed;
3. blocking fast-feedback pull-request budget breach returns non-zero;
4. advisory confidence breach remains warning and zero absent another failure;
5. JUnit failures/errors plus passed claim is contradiction/non-zero;
6. missing required JUnit is non-zero;
7. malformed required JUnit is non-zero;
8. test failure plus report-generation failure preserves both contexts;
9. missing required report artifacts remain publication failure;
10. existing successful consumers remain readable.

D. Focused regression set

At minimum:

• new Constitution/branch-topology contract tests;
• tests/Unit/Support/TestLaneReportTest.php;
• tests/Unit/Support/TestLaneBudgetTest.php;
• tests/Feature/Guards/CiLaneFailureClassificationContractTest.php;
• tests/Feature/Guards/TestLaneCommandContractTest.php;
• tests/Feature/Guards/TestLaneArtifactsContractTest.php;
• tests/Feature/Guards/TestLaneManifestTest.php;
• directly affected workflow contract tests;
• fast-feedback and confidence lanes;
• Sail Pint on dirty PHP files;
• git diff --check;
• forbidden-path and Spec 438 unchanged checks.

E. Full-suite decision

A full product suite is not automatic because no product runtime changes. Fast Feedback and Confidence are required because the shared runner/report path and enforcement profiles change. Browser, PostgreSQL, and Heavy Governance are N/A. Discovering broader cost requires prior spec/plan correction rather than late implicit expansion.

Test-governance preparation outcome: document-in-feature. The bounded Unit/Feature fixture and lane cost is owned and reported by Spec 439; structural remote-CI or release-governance work remains a follow-up-spec.

Mandatory Implementation Phases

Phase 0 - Revalidate Spec readiness

• Recheck branch, HEAD, dirty state, local refs, active package, and no-fetch posture.
• Reconfirm Amendment Procedure and absence of a mandatory separate Amendment Spec.
• Reproduce or statically trace every named defect and direct consumer.
• Protect Specs 437/438 and record baselines.
• Stop or reconcile stale assumptions before mutation.

Phase 1 - Apply the narrowly scoped Constitution branch-topology amendment

• Identify the exact obsolete universal dev rule.
• Amend only branch roles/routing/fallback rules plus required metadata.
• Choose and justify SemVer under current policy; never assume PATCH.
• Update Sync Impact, rationale, impacted artifacts, and Last Amended.
• Validate the amendment diff and record the Phase 1 gate.

Hard Gate: No Phase 2-8 file may change before this gate passes.

Phase 2 - Synchronize directly conflicting authoritative instructions

• Align Agents.md and only preflight-confirmed authoritative contradictions.
• Retain valid promotion and platform-dev guidance.
• Add/update focused contract checks for synchronized branch wording.
• Residualize non-authoritative or unrelated drift.

Phase 3 - Implement branch-family and concrete-reference resolution

• Add failing two-stage resolver fixtures first.
• Implement fixed Stage 1 family selection/conflict validation.
• Implement fixed Stage 2 family-matching ref/merge-base resolution.
• Add success and fail-closed diagnostics.

Phase 4 - Update local diff guards and affected repository-side workflow declarations

• Integrate the resolver into the current changed-file guard.
• Preserve explicit-base and all working-tree change sources.
• Correct the existing PR target declaration only when repo-locally provable.
• Keep all existing triggers, lanes, schedules, and deployment behavior unchanged.

Phase 5 - Repair local test/report evidence truth

• Add failing execution/refresh/JUnit/report fixtures first.
• Persist original execution truth.
• Extend required evidence metadata and contradiction detection.
• Preserve dual failure contexts and compatible successful consumers.

Phase 6 - Repair blocking/advisory budget truth

• Add blocking/advisory/missing-input final-exit controls first.
• Derive one final result from authoritative profiles and other failure sources.
• Keep thresholds and profile ownership unchanged.
• Propagate final result through existing wrappers/entry points.

Phase 7 - Add negative fixtures and run focused proof

• Complete BS-001 through BS-012 and EF-001 through EF-007.
• Run Constitution/instruction, resolver, guard, report, budget, artifact, manifest, and workflow contracts.
• Run Fast Feedback and Confidence.
• Run formatter and diff/scope/history guards.
• Record actual outputs without normalizing failures.

Phase 8 - Produce implementation report and final reconciliation

• Create implementation-report.md only now.
• Reconcile every FR, INV, task, BS/EF fixture, changed file, test, lane, and residual.
• Record the paired clean-baseline/feature attribution with exact SHA, environment and selection equivalence, raw exits, JUnit multiset deltas, performance/budget attribution, and artifact checksums.
• Record Product Surface/browser/deployment N/A fields.
• Record test-governance outcome and final PASS/PASS WITH CONDITIONS/FAIL.

Dependencies and Execution Order

• Phase 0 blocks Phase 1.
• Phase 1 blocks every Phase 2-8 task.
• Phase 2 blocks resolver/tooling work that depends on canonical instructions.
• Phase 3 blocks Phase 4.
• Phase 4 blocks Phase 5; no evidence-truth task may be prepared early.
• Phase 5 blocks Phase 6; no budget-truth task may be prepared early.
• Phase 7 follows the Phase 6 exit gate.
• Phase 8 follows all validation.

Parallelization Contract

• No mutation is parallel with Phase 1.
• Same-file Constitution, instruction, resolver, TestLaneReport, and TestLaneManifest edits are single-owner.
• Branch fixtures are authored only in Phase 3; evidence fixtures start only after the Phase 4 exit gate.
• Workflow declaration work waits for resolver stabilization.
• Budget tests begin only after the Phase 5 exit gate and may run in parallel only with file-disjoint tasks inside Phase 6.
• No task marked parallel may bypass an earlier phase gate or claim evidence before the producing task completes.

Risk Controls

Risk	Control
Constitution scope expands	Exact authorized rule list, unrelated-principle diff check, Phase 1 gate
SemVer is minimized incorrectly	Explicit policy decision and rationale; PATCH forbidden by scope
dev is removed from valid use	Explicit promotion fixture and unchanged main-confidence semantics
Signals silently override	Cross-check present authoritative signals and fail on conflict
Generic branch framework	Fixed families/roles only
Report schema consumer regression	Compatible extension and positive controls
Blocking budget exposes debt	Preserve thresholds and report actual result
Refresh hides failure	Persist original execution result and negative refresh fixture
Missing evidence becomes empty success	Validity/count/path metadata and fail-closed result
Remote-CI scope creeps	Conditional minimal existing declaration only
Historical specs change	Baseline and final byte/diff checks

Complexity Tracking

New structure	Why needed	Simpler alternative rejected because
One narrow Constitution branch rule	Current universal dev rule contradicts repository stream ownership	Instruction-only workaround would violate current Constitution
One small two-stage resolver	Family and concrete ref are different decisions with multiple existing consumers	Duplicated constants and branch-name inference preserve contradiction
Compatible execution/evidence metadata	Refresh must preserve real test/evidence truth	Console-only state cannot survive report refresh

No product entity, status family, taxonomy, package, UI framework, or persistence layer is introduced.

Rollout and Compatibility

• Existing branches are not renamed, deleted, synchronized, rebased, or merged by implementation.
• Existing explicit guard base argument remains supported when family-consistent.
• Existing valid successful reports remain readable.
• Existing thresholds remain unchanged.
• Existing remote workflows are not activated or broadened.
• Platform local review becomes available after merge to platform-dev.
• Website behavior is contract proof only; delivery onto website-dev remains separate integration work.

Implementation Readiness Assessment - Preparation Snapshot

• Candidate Gate: PASS.
• Spec Readiness Gate: READY.
• Implementation Authorization: AUTHORIZED.
• Constitution amendment is in scope and first.
• The Amendment Procedure does not require a separate preceding feature spec.
• Branch roles and two-stage resolver contract are explicit and synchronized with spec.md.
• Evidence truth remains local and bounded.
• No product or external-system decision blocks implementation.
• Phase 2-8 remain conditionally blocked until Phase 1 validation, as intended.

Preparation Plan Gate: READY - begin a separate implementation loop at Phase 0; Phase 1 is the first mandatory mutation.