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

Feature Specification: Spec 439 - Branch Topology and Local Evidence Truth

Feature Branch: feat/439-branch-topology-local-evidence-truth Created: 2026-07-10 Corrected: 2026-07-11 Status: Implemented and reconciled - merge-ready locally with an external activation condition Type: Engineering Foundation / Local Governance / Evidence Integrity Priority: High Development Stream: repository-governance with platform-owned implementation base Feature Base: platform-dev Normal Merge Target: platform-dev Input: Direct user-provided corrected Spec 439 candidate and final manual review findings.

Lifecycle boundary: Readiness, authorization, and “next action” statements below record the requirements-preparation snapshot. Current implementation, evidence, and merge status are owned by tasks.md and implementation-report.md.

Preparation Selection Summary

• Selected candidate: Branch Topology and Local Evidence Truth.
• Source: Direct user-provided candidate. The automatic candidate queue was not used to invent adjacent scope.
• Roadmap relationship: Bounded remediation for repository-listed CI/configuration status drift and current local review/evidence defects.
• Why selected: Current repo truth confirms both trust defects: the changed-file guard defaults to origin/dev or HEAD~1, while the lane report refresh can replace the real execution result with success. Blocking budget classification is not yet guaranteed to affect the final command result.
• Close alternatives deferred: Full Gitea CI activation, branch protection, deployment gates, release/promotion automation, broad skill cleanup, spec metadata reconciliation, and Spec 438 implementation.
• Completed/deferred-spec guardrail: Spec 437 is completed read-only context. Spec 438 is merged as a deliberately deferred, non-implemented package and MUST remain unchanged.
• Smallest viable slice: First amend only the obsolete Constitution branch rule, then synchronize directly conflicting authoritative instructions, then implement one fixed branch-family/base resolver and compatible corrections to the existing local lane result/report path with deterministic fixtures.
• Feature description: Establish scope-specific branch roles and trustworthy local branch/evidence results without changing product runtime or activating new remote governance.

Spec Candidate Check

• Problem: Local feature review can use the wrong integration base, and local test reports can contradict the execution that produced them.
• Today's failure: Platform history between dev and platform-dev can pollute a feature diff; website work lacks equivalent explicit protection; a failed test can be refreshed into a passed report; a blocking budget can remain non-blocking at process level.
• User-visible improvement: Developers and reviewers see only the current feature's changes and can trust that local PASS means execution, required evidence, and every blocking condition succeeded.
• Smallest enterprise-capable version: A narrowly scoped Constitution amendment, direct instruction synchronization, fixed mappings for the known branch roles, fail-closed two-stage resolution, persisted test-result truth, and focused deterministic fixtures.
• Explicit non-goals: No generic branch graph, release orchestrator, general Constitution rewrite, all-spec metadata migration, Gitea branch protection, new CI lane activation, deployment gate, product runtime change, or broad documentation cleanup.
• Permanent complexity imported: One small branch-resolution seam, a few compatible report/evidence fields, one narrow Constitution rule amendment, and focused repository-governance tests. No model, table, product enum/state family, UI concept, or runtime service.
• Why now: The defects affect current local review and implementation evidence before deployment or remote merge gates are required.
• Why not local: The same branch-family truth serves platform and website validation, and the same lane-result truth serves multiple existing report entry points. Duplicated call-site fixes would preserve contradiction risk.
• Approval class: Core Enterprise.
• Red flags triggered: #2 New Meta-Infrastructure and #4 Foundation wording.
• Defense: The resolver is limited to fixed current branch roles and existing consumers, introduces no configurable branch graph, and repairs confirmed false evidence rather than preparing hypothetical infrastructure. The Constitution change replaces one obsolete branch rule and does not reopen unrelated principles.
• Score: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexität: 2 | Produktnähe: 1 | Wiederverwendung: 2 | Gesamt: 11/12.
• Decision: approve.

Candidate and Readiness Decision

• Candidate Gate: PASS.
• Approval Class: Core Enterprise.
• Spec Readiness Gate: READY.
• Implementation Posture: Targeted governance and evidence remediation.
• Implementation Authorization: AUTHORIZED.
• First authorized mutation: The narrowly scoped Constitution branch-topology amendment defined by this spec.
• Dependent-work gate: No instruction, resolver, guard, workflow, test-support, test, report, or budget implementation may begin until the Phase 1 amendment has been applied on the implementation branch and validated against the Constitution amendment procedure.
• Acceptance posture: The amendment and dependent implementation may be delivered in the same Spec 439 feature PR. The current governance sources require an explicit Constitution update PR, rationale, impacted-artifact list, SemVer decision, and Last Amended update; they do not require a separate preceding feature spec.
• Depends on: Spec 437 merged into platform-dev.
• Independent from: Spec 438, which remains deferred, unimplemented, and unchanged.
• Blocks: Trustworthy local spec review, reliable local lane reports, and later remote continuous-governance work.

Constitution Amendment Authorization

Governance basis

The current Constitution's Amendment Procedure allows an explicit PR to update .specify/memory/constitution.md when the PR includes a short rationale, an impacted templates/specs list, a SemVer decision under the existing policy, and an updated Last Amended date. Neither the Constitution, Agents.md, nor current Spec Kit tooling requires a separate preceding feature spec for that amendment.

Spec 439 therefore authorizes the amendment as its first mandatory implementation step. This authorization does not itself amend the Constitution. The existing rule remains repo truth until Phase 1 changes and validates it.

Authorized amendment scope

The amendment MAY only:

1. replace the obsolete universal statement that every feature branch starts from dev;
2. define dev as repository-wide integration and promotion, platform-dev as the platform integration branch, and website-dev as the website integration branch;
3. define scope-specific feature bases, normal targets, and diff baselines;
4. require explicit classification and target declaration for cross-stream integration and promotion work;
5. forbid silent fallback to an unrelated branch family or HEAD~1;
6. authorize synchronization of directly conflicting authoritative instructions after the amendment is validated;
7. update the Constitution Sync Impact Report, version, and Last Amended fields required by the existing amendment procedure.

Forbidden amendment scope

The amendment MUST NOT include:

• a general Constitution reduction or rewrite;
• UI/UX rule cleanup;
• skill reorganization;
• an architecture-principle audit;
• security-guideline cleanup;
• changes to unrelated Constitution principles;
• product runtime, persistence, RBAC, provider, OperationRun, customer-output, or deployment semantics.

Mandatory gate sequence

• Phase 0 is read-only revalidation.
• Phase 1 applies and validates the narrow Constitution amendment.
• Phases 2 through 8 are blocked until Phase 1 succeeds.
• Failure to validate the amendment stops all dependent work; it does not authorize a workaround in instructions, scripts, workflows, or tests.

Amendment-first Evidence Sufficiency

The prospective amendment-first execution order remains mandatory. Close-out of FR-005, INV-001, INV-002, SC-002, and T056 uses this evidence contract:

1. The final Constitution amendment is present in the repository state.
2. Exact contract tests protect the authorized amendment boundary and required amendment metadata.
3. Constitution content outside the authorized branch-topology and required amendment-metadata boundary remains unchanged, with the permitted range verified by normalization or hash controls.
4. Dependent instructions and implementations agree with the amended Constitution.
5. tasks.md and implementation-report.md attest that Phase 1 validation preceded dependent work.
6. No final repository file conflicts with the Constitution effective after Phase 1.
7. Independent chronological Git evidence is required only when a commit, tag, patch, or snapshot checkpoint was explicitly required before the first mutation.
8. Any future spec requiring independently reconstructable chronology MUST define and capture that checkpoint before the first mutation.

Spec 439 required no such pre-mutation historical checkpoint. Its close-out MUST NOT claim one retroactively.

Stop Conditions

Stop the affected implementation slice and report the finding when:

• the Constitution amendment cannot satisfy the current Amendment Procedure without broader principle changes;
• amendment review reveals a mandatory separate governance process not present during this correction;
• the named branch or evidence defect no longer exists on implementation HEAD and the active artifacts have not been reconciled;
• branch classification requires an unresolved product/release decision beyond the fixed current topology;
• deterministic local proof requires network access, remote mutation, live Gitea administration, or deployment activation;
• the work expands into a generic branch-management, release, CI-platform, or governance framework;
• Spec 438 or another completed/deferred spec would need modification.

An independently provable later sub-slice may continue only when all preceding phase gates remain satisfied.

Branch and Integration Strategy

Canonical branch roles

Branch	Role
dev	Repository-wide integration and promotion branch
platform-dev	Integration branch for TenantPilot platform work
website-dev	Integration branch for website work

Normal feature routing

Workstream	Feature Base	Normal PR Target	Diff Baseline
Platform	platform-dev	platform-dev	platform-dev
Website	website-dev	website-dev	website-dev
Cross-stream / Promotion	explicitly declared	explicitly declared; may be dev	explicitly declared
Repository governance	explicitly classified by affected scope	explicitly declared	explicitly declared

Spec 439 is repository-governance work with a platform-owned implementation base and normal target of platform-dev. Later platform-dev to dev promotion is outside this spec.

dev may intentionally lag platform-dev or website-dev. Divergence is not itself a defect. The defect is comparing or targeting ordinary stream work against the wrong branch family.

No repo-backed platform-dev/dev to website-dev convergence contract is created here. Website behavior is mandatory as a deterministic resolver/diff contract, but delivery of the tooling onto website-dev requires separately governed integration work.

Unified Resolver Contract

The resolver makes two separate decisions. Spec, plan, tasks, fixtures, guard integration, and workflow declarations MUST use this exact contract.

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.

Spec Scope Fields

• Scope: Repository governance and shared engineering evidence only.
• Primary Routes: N/A - no application routes or pages.
• Data Ownership: N/A - no workspace-, environment-, provider-, or customer-owned data changes.
• RBAC: N/A - no authorization behavior changes.
• Workspace / Managed Environment Isolation: N/A - no application data access.

In Scope

• The narrow Constitution branch-topology amendment defined above.
• Synchronization of directly conflicting authoritative branch instructions after the amendment passes.
• A fixed two-stage branch-family and concrete-ref resolver.
• Integration of that resolver into the existing changed-file guard.
• Minimal correction of existing repository-side PR target declarations when repo-locally provable.
• Preservation of original test execution truth through report refresh.
• Required JUnit/report evidence validation and contradiction detection.
• Enforcement of existing blocking/advisory budget classifications in the final local result.
• Deterministic local Git/JUnit/report/budget fixtures.
• Focused validation and an implementation report.

No Legacy / No Backward Compatibility Constraint

• Compatibility posture: Canonical replacement of incorrect branch and result defaults. Structurally valid successful reports remain readable; artifacts lacking newly required execution/evidence truth may be read diagnostically but MUST NOT be accepted as PASS.
• Legacy aliases, fallback readers, hidden routes, duplicate UI, old labels, or historical fixtures kept?: No new compatibility path. Existing historical specs and reports are not rewritten.
• Why clean replacement is safe now: The change affects repository tooling and engineering evidence in a pre-production repository. Incorrect dev/HEAD~1 fallback and false-success behavior are not valid compatibility contracts.

UI Surface Impact

• No UI surface impact
• Existing page changed
• New page/route added
• Navigation changed
• Filament panel/provider surface changed
• New modal/drawer/wizard/action added
• New table/form/state added
• Customer-facing surface changed
• Dangerous action changed
• Status/evidence/review presentation changed
• Workspace/environment context presentation changed

No-impact rationale: Only governance documents, local Git/diff tooling, shared test-lane evidence helpers, focused tests, and existing repository-side workflow declarations are in implementation scope. No rendered platform or website surface changes.

UI/Productization Coverage

N/A - no reachable UI surface impact. No route inventory, design coverage, screenshot, page audit, customer-safe review, or dangerous-action review is required.

Product Surface Impact

• Product Surface Contract applies?: No - no rendered product surface changes.
• Page archetype: N/A.
• Primary user question: N/A.
• Primary action: N/A.
• Surface budget result: N/A.
• Technical Annex / deep-link demotion: N/A.
• Canonical status vocabulary: N/A - engineering report statuses are not product status vocabulary.
• Visible complexity impact: N/A.
• Product Surface exceptions: none.

Browser Verification Plan

• Browser proof required?: no.
• No-browser rationale: N/A - no rendered UI surface changed.
• Focused path / interaction: N/A.
• Console, Livewire, Filament, network, and 500-error checks: N/A.
• Conditional browser lane: Not authorized by this spec. Unexpected rendered-surface scope requires a prior spec/plan correction.

Human Product Sanity Check

• Required?: no.
• No-human-sanity rationale: N/A - no product surface changed.
• Planned result location: Implementation report records the no-surface decision and neutral visible-complexity outcome.

Product Surface Merge Gate Checklist

• No-legacy posture recorded.
• Product Surface Impact is N/A with rationale.
• Browser proof is N/A - no rendered UI surface changed.
• Human Product Sanity is not applicable with rationale.
• Product Surface exceptions are none.
• Implementation report must state Livewire v4 compliance, provider registration location, global-search posture, destructive/high-impact action posture, asset strategy, tests/browser result, deployment impact, visible-complexity outcome, and completed-spec rewrite safety.

Cross-Cutting / Shared Pattern Reuse

• Cross-cutting feature?: yes, limited to repository branch resolution and shared engineering test evidence.
• Systems touched: Constitution branch instruction, directly conflicting authoritative instructions, root changed-file guard, existing test-lane manifest/budget/report path, focused governance tests, and existing PR workflow declaration only when needed to remove a hard-coded target assumption.
• Existing patterns to extend: git merge-base, TestLaneManifest, TestLaneBudget, TestLaneReport, and existing workflow contract tests.
• New abstraction: At most one small fixed branch resolver or equivalent canonical mapping. No registry, configurable graph, or release framework.
• Allowed deviation: none.
• Review focus: One branch-family/ref contract and one final-result contract remain authoritative; no duplicated budget classification or hidden dev fallback.

OperationRun UX Impact

N/A - no OperationRun creation, lifecycle, link, notification, or evidence semantics are touched.

Provider Boundary / Platform Core Check

N/A - no provider/platform product boundary is touched.

UI / Surface Guardrail Impact

Surface / Change	Operator-facing surface change?	Native vs Custom	Shared-Family Relevance	State Layers Touched	Exception Needed?	Low-Impact / N/A Note
Repository tooling and engineering test reports	no	N/A	none	none	no	N/A - repository workflow only

Decision-First Surface Role

N/A - no operator-facing surface changed.

Audience-Aware Disclosure

N/A - no customer, operator, support, report, review-pack, or raw-evidence product surface changed.

UI/UX Surface Classification

N/A - no operator-facing surface changed.

Operator Surface Contract

N/A - no operator-facing surface changed.

Proportionality Review

• New source of truth?: No product source of truth. A small repository mapping becomes canonical only for engineering branch resolution.
• New persisted entity/table/artifact?: no.
• New abstraction?: yes, at most one small fixed branch-family/base resolver or equivalent mapping.
• New enum/state/reason family?: no product enum/state family. Work classifications remain command/spec metadata only.
• New cross-domain UI framework/taxonomy?: no.
• Current operator problem: Developers/reviewers can evaluate unrelated history and accept false local PASS evidence.
• Existing structure is insufficient because: Branch defaults are duplicated or hard-coded, and execution/report refresh do not carry one authoritative final result through existing entry points.
• Narrowest correct implementation: Three fixed branch roles, a small two-stage resolver, one narrow Constitution rule replacement, and compatible final-result/evidence checks in existing report classes.
• Ownership cost: A focused Constitution contract, shell/Pest fixtures, and maintenance when the repository intentionally changes branch topology or lane semantics.
• Alternative intentionally rejected: Duplicated branch constants, branch-name-only inference, a general branch graph, report-schema replacement, a separate governance framework, or remote merge-governance activation.
• Release truth: Current repository workflow safety, not future-release preparation.

Testing / Lane / Runtime Impact

• Test purpose / classification: Feature for Constitution/instruction/branch/wrapper/workflow contracts; Unit for JUnit/result/budget consistency. No new Heavy-Governance family.
• Validation lanes: Focused files first, then affected fast-feedback and confidence lanes. Browser, PostgreSQL, and Heavy Governance are N/A.
• Why sufficient: No database, Laravel product runtime, Filament, Livewire, provider, workspace, session, or browser behavior is involved. Deterministic filesystem/process fixtures prove the trust contract directly.
• New or expanded test families: One bounded branch-topology Feature contract plus focused additions to existing Unit/Feature evidence-truth contracts.
• Fixture/helper cost impact: Temporary local Git repositories and small JUnit/report fixtures; no database/factory/seed/provider/workspace defaults.
• Heavy-family visibility: none.
• Budget/baseline/trend impact: Existing Fast Feedback and Confidence thresholds remain unchanged. Correct enforcement may expose existing blocking debt; thresholds MUST NOT be relaxed to regain green output.
• Escalation: document-in-feature for contained lane-result changes; follow-up-spec only for structural remote-CI or release-governance work.
• Reviewer handoff: Verify amendment scope, phase gating, all branch conflict/fallback fixtures, failed/pass report controls, blocking/advisory controls, missing/malformed evidence, and JUnit/report contradiction cases.
• Test-governance preparation outcome: document-in-feature.
• Planned validation commands: Exact focused commands are defined in plan.md and tasks.md; no runtime/browser proof is required.

Context and Problem Statement

TenantPilot has three long-lived development branches with different responsibilities. The current universal dev rule contradicts actual stream ownership and must be replaced before dependent tooling can claim the new topology.

Engineering evidence is trustworthy only when the test process result, required JUnit evidence, generated report, budget enforcement, and final command result agree. Current refresh behavior can replace the real result with success and can leave blocking classifications non-blocking at process level.

Business Value and Primary Users

• Primary users: Platform developers, website developers, spec reviewers, governance maintainers, and test-governance maintainers.
• Business/trust value: Feature scope and implementation evidence become reliable inputs to merge/readiness decisions.
• Before: Reviewers can see unrelated stream history or a passed refreshed report after failed execution.
• After: Reviewers see the feature-relative diff and a PASS only when execution, required evidence, and every blocking condition agree.

Governing Invariants

• INV-001 Amendment first: The branch-topology Constitution amendment is the first mutating implementation step. Close-out evidence follows Amendment-first Evidence Sufficiency and does not imply independent historical chronology without a pre-required checkpoint.
• INV-002 Dependent-work gate: Phases 2-8 cannot begin until Phase 1 is applied and validated. Tasks and the implementation report attest the gate, while final repository state and exact boundary controls corroborate it.
• INV-003 Narrow amendment: No unrelated Constitution principle may change.
• INV-004 Scope-specific integration: There is no universal integration branch for every repository change.
• INV-005 Platform target: Ordinary platform features use platform-dev for base, target, and diff baseline.
• INV-006 Website target: Ordinary website features use website-dev for base, target, and diff baseline.
• INV-007 Valid dev role: dev remains valid for explicitly classified repository integration and promotion.
• INV-008 No stream-to-dev fallback: Missing platform/website refs never select dev, origin/dev, HEAD~1, or an arbitrary commit.
• INV-009 Explicit classification: Cross-stream and promotion work require declared family and target.
• INV-010 Two-stage resolution: Branch family is resolved before a concrete Git ref.
• INV-011 Conflict is failure: Contradictory authoritative signals fail with actionable diagnostics.
• INV-012 Merge-base diff: Feature-relative paths use the merge base of HEAD and the selected ref.
• INV-013 Test failure immutability: Later reporting cannot turn a non-zero test execution into PASS.
• INV-014 Blocking means blocking: A blocking budget affects the final command result.
• INV-015 Advisory means advisory: Advisory thresholds warn without failing solely for the warning.
• INV-016 Evidence agreement: Process, JUnit, report, budget, and final exit cannot materially contradict one another.
• INV-017 Missing required evidence is not success: Missing or malformed required evidence fails closed.
• INV-018 No product runtime change: No platform or website customer behavior changes.
• INV-019 Historical-spec safety: Specs 437 and 438 remain read-only.
• INV-020 Local-only proof: Required proof is deterministic and network-free.

User Scenarios & Testing

User Story 1 - Governance Maintainer Establishes the Branch Contract (Priority: P1)

As a governance maintainer, I need the obsolete universal dev rule replaced through the existing amendment procedure before dependent tooling adopts scope-specific branches.

Independent Test: The Constitution diff changes only the branch-topology rule and required Sync Impact/version/date metadata; it defines all three roles, records rationale/impacts, and leaves unrelated principles byte-for-byte unchanged.

Acceptance Criteria:

• The amendment is inside Spec 439 scope and is the first mutating step.
• The amendment defines dev, platform-dev, and website-dev roles.
• The amendment records rationale, impacted artifacts, SemVer decision, and Last Amended.
• Directly conflicting authoritative instructions are synchronized only after amendment validation.
• No unrelated Constitution or guideline cleanup occurs.

User Story 2 - Stream Developers See the Real Feature Diff (Priority: P1)

As a platform or website developer, I need validation to use my stream's integration family so unrelated history is excluded.

Independent Test: Diverged temporary repositories for platform and website return only the feature path for the selected family.

Acceptance Criteria:

• Platform resolves to origin/platform-dev or local platform-dev.
• Website resolves to origin/website-dev or local website-dev.
• Missing family refs fail with attempted-ref guidance and no diff.
• Neither family silently selects dev, origin/dev, or HEAD~1.

User Story 3 - Cross-Stream and Promotion Work Are Deliberate (Priority: P1)

As a reviewer, I need conflicting signals to fail and promotion work to use dev only when explicitly classified.

Independent Test: Explicit platform plus PR target website-dev fails, while explicit promotion to dev succeeds.

Acceptance Criteria:

• Branch-family and ref resolution remain separate.
• Conflicting authoritative signals fail.
• A valid ref must belong to the selected family.
• Explicit promotion to dev remains valid.

User Story 4 - Failed Tests Cannot Look Successful (Priority: P1)

As a reviewer, I need report refresh to preserve the real test result.

Independent Test: A non-zero test fixture followed by refresh remains failed in report and final exit; a passing positive control remains passed.

Acceptance Criteria:

• Original execution result is persisted.
• Refresh never hard-codes success.
• Test failure remains visible when report generation also fails.
• Existing valid successful report consumers remain readable.

User Story 5 - Budget and Required Evidence Truth Are Enforced (Priority: P1)

As a test-governance maintainer, I need blocking budgets and required evidence to fail while advisory budgets remain warnings.

Independent Test: Blocking, advisory, contradiction, missing, malformed, and dual-failure fixtures produce their specified statuses and exits.

Acceptance Criteria:

• Blocking breach returns non-zero without threshold relaxation.
• Advisory-only breach remains visible and non-blocking.
• Missing/malformed evidence and contradictions return non-zero.
• Execution, evidence, budget, report, and final-result states remain distinguishable.

Requirements

Constitution Amendment and Phase Gate

• FR-001: Spec 439 MUST authorize the narrow branch-topology Constitution amendment as its first mutating implementation step.
• FR-002: The amendment MUST follow the existing Amendment Procedure, including rationale, impacted-artifact list, SemVer decision, and updated Last Amended date.
• FR-003: The amendment MUST define the three branch roles and scope-specific feature routing in this spec.
• FR-004: The amendment MUST NOT change unrelated Constitution principles or initiate general governance cleanup.
• FR-005: No Phase 2-8 work may begin until the Phase 1 amendment is applied and validated. Close-out evidence for this ordering MUST satisfy Amendment-first Evidence Sufficiency and MUST NOT require or claim independent historical chronology unless a pre-mutation checkpoint was explicitly required.
• FR-006: Directly conflicting authoritative instructions MUST be synchronized after, not before, amendment validation.
• FR-007: The same feature PR MAY carry the amendment and dependent work; no separate preceding Amendment Spec is required by current repo governance.

Branch Roles and Routing

• FR-008: dev MUST mean repository-wide integration and promotion.
• FR-009: platform-dev MUST be the ordinary platform feature base, normal PR target, and diff baseline.
• FR-010: website-dev MUST be the ordinary website feature base, normal PR target, and diff baseline.
• FR-011: Cross-stream, promotion, and repository-governance work MUST declare family, target, and baseline when no unambiguous fixed rule exists.
• FR-012: dev MUST NOT be treated as obsolete or as a silent default.
• FR-013: Divergence between long-lived branches MUST NOT be classified as a defect by itself.

Stage 1 - Branch-Family Resolution

• FR-014: Stage 1 MUST use this priority: explicit family input, PR target, active spec metadata/classification, feature-name plus repo-scope signals, then fail closed.
• FR-015: Explicit family input MUST be validated.
• FR-016: A known PR target MUST be authoritative and MUST be checked against other authoritative signals.
• FR-017: Spec metadata MUST NOT contradict a valid PR target.
• FR-018: Feature-branch names and repository paths MUST be subordinate hints only.
• FR-019: Ambiguous or conflicting signals MUST fail with actionable diagnostics.
• FR-020: Stage 1 MUST NOT silently default to dev.

Stage 2 - Concrete-Ref and Merge-Base Resolution

• FR-021: Stage 2 MUST run only after Stage 1 selects a branch family.
• FR-022: Stage 2 MUST use this priority: explicit family-matching ref, matching remote ref, matching local ref, ancestry/merge-base validation, then fail closed.
• FR-023: Refs from another branch family MUST be rejected.
• FR-024: Missing platform/website refs MUST NOT fall back to dev, origin/dev, HEAD~1, or an arbitrary commit.
• FR-025: Explicit promotion may use dev only after Stage 1 classifies it as promotion/cross-stream integration.
• FR-026: Success output MUST include family, expected branch, selected ref, target commit, merge base, and base range.
• FR-027: Failure output MUST include conflicts or attempted refs, override guidance, and confirmation that no diff ran.
• FR-028: Changed paths MUST use merge-base semantics.

Guard, Instructions, and Existing Workflow Declarations

• FR-029: The current changed-file guard MUST consume the unified resolver contract and preserve its explicit base argument.
• FR-030: The guard MUST continue to include committed, staged, unstaged, and untracked active-feature changes.
• FR-031: Existing event-supplied actual targets MUST remain authoritative when valid and family-consistent.
• FR-032: Workflow declarations MAY change only to remove a hard-coded wrong target or propagate the same final-result semantics; no new trigger, lane, schedule, merge gate, or deployment behavior is authorized.
• FR-033: Direct instruction alignment MUST remain limited to confirmed authoritative contradictions.

Test Exit, Report, and Evidence Truth

• FR-034: The test-process exit MUST be captured immediately and persisted in the report contract.
• FR-035: Report refresh MUST derive or receive the stored execution result and MUST NOT hard-code success.
• FR-036: A failed test MUST never be represented as passed.
• FR-037: Refresh MAY run after failure but MUST preserve a non-zero final result.
• FR-038: Dual test/report failure MUST preserve both facts and remain failed.
• FR-039: JUnit parsing MUST distinguish missing, malformed, passed, failed, error-containing, and skipped evidence.
• FR-040: Process/JUnit/report contradictions MUST be visible and non-zero.
• FR-041: Missing or malformed required JUnit/report artifacts MUST NOT produce success.
• FR-042: Existing valid successful reports SHOULD remain readable through minimal compatible extension.

Budget Truth

• FR-043: Existing TestLaneBudget enforcement profiles MUST remain the sole blocking/advisory authority.
• FR-044: Workflow YAML, wrappers, and Composer MUST NOT duplicate budget classification.
• FR-045: A blocking budget breach MUST return non-zero from the final lane/report entry point.
• FR-046: Advisory-only warnings MAY return zero but MUST remain visible.
• FR-047: Thresholds MUST NOT be relaxed or profiles reclassified merely to obtain green output.
• FR-048: Missing/malformed inputs required by an active blocking profile MUST fail closed.
• FR-049: Local and reusable existing CI entry points MUST use the same final-result semantics.

Runtime and Scope Discipline

• FR-050: No product model, migration, controller, service, policy, job, provider, Filament, Livewire, route, view, website component, customer output, or product data behavior may change.
• FR-051: Tests MUST require no network, fetch, live Gitea, PR creation, remote branch mutation, or branch-protection API.
• FR-052: Spec 438 MUST remain deferred, unimplemented, and unchanged.
• FR-053: Remote branch protection, deployment gates, and general CI-platform activation MUST remain out of scope.
• FR-054: The implementation report MUST reconcile every requirement, invariant, fixture, changed file, validation result, and residual.

Required Deterministic Fixtures

ID	Fixture	Expected result
BS-001	Platform remote ref available	origin/platform-dev selected
BS-002	Platform remote ref absent, local ref available	platform-dev selected
BS-003	Website remote ref available	origin/website-dev selected
BS-004	Website remote ref absent, local ref available	website-dev selected
BS-005	Explicit promotion	dev accepted after promotion classification
BS-006	Missing platform family refs	fail closed; no fallback diff
BS-007	Missing website family refs	fail closed; no fallback diff
BS-008	Diverged platform topology	only platform feature path returned
BS-009	Diverged website topology	only website feature path returned
BS-010	Explicit family platform plus PR target website-dev	actionable conflict failure
BS-011	Ambiguous name/path/spec signals	actionable classification failure
BS-012	Explicit ref from wrong family	rejected before merge-base calculation
EF-001	Failed test then refresh	failed report and non-zero exit
EF-002	Passed test	passed report and zero exit
EF-003	Blocking budget exceeded	blocking failure and non-zero exit
EF-004	Advisory budget exceeded	visible warning and zero exit
EF-005	JUnit failure plus passed claim	contradiction and non-zero exit
EF-006	Missing/malformed required evidence	evidence failure and non-zero exit
EF-007	Test failure plus report failure	both contexts visible; non-zero exit

Temporary Git fixtures MUST create their own histories, MUST NOT depend on real divergence counts, and MUST require no network.

Non-Functional Requirements

• Resolution and evidence outcomes MUST be deterministic from local inputs.
• Diagnostic failures MUST be actionable and name conflicting signals, attempted refs, or affected evidence files.
• Shell tooling MUST remain portable to the repository's current Bash environment.
• Report changes MUST remain compatible for existing valid successful consumers where truth can be preserved.
• New tests MUST stay filesystem/process-only and avoid database or product application boot unless an existing narrow convention requires it.
• Constitution changes MUST remain reviewable as a narrow branch-rule diff with explicit Sync Impact and SemVer rationale.

Explicit Non-Goals

• No general Constitution cleanup, shortening, reorganization, or audit.
• No UI/UX, security, architecture, provider, RBAC, OperationRun, or product-surface governance changes.
• No merge or synchronization among dev, platform-dev, and website-dev.
• No branch rename or deletion.
• No generic branch graph, release manager, or multi-repository router.
• No broad skill or instruction cleanup beyond directly conflicting authoritative branch statements.
• No full Gitea administration, branch protection, remote merge blocking, deployment gate, staging activation, or production activation.
• No new heavy/browser/PostgreSQL lane activation.
• No all-spec metadata migration, historical report reconciliation, Ledger/Roadmap rewrite, or Spec Candidates update.
• No implementation of Spec 438.
• No product runtime, customer-facing, database, RBAC, provider, OperationRun, audit-domain, or UI changes.

Assumptions

• The current Amendment Procedure remains authoritative and does not require a separate preceding feature spec.
• platform-dev and website-dev remain the ordinary integration branches for their streams.
• dev remains the repository-wide integration/promotion branch.
• Existing TestLaneBudget profiles express the intended current blocking/advisory decisions.
• Existing lane reports may be minimally extended with execution/evidence metadata.
• The current feature branch remains the implementation branch; Phase 0 revalidates HEAD, refs, and dirty state without fetching.

Risks and Mitigations

• R-001 Amendment scope creep: Diff only the branch rule and required Sync Impact/version/date metadata; stop on unrelated principle changes.
• R-002 dev treated as obsolete: Keep explicit promotion-to-dev fixture and canonical role text.
• R-003 False stream detection: Cross-check all present authoritative signals; conflicts fail.
• R-004 Generic framework creep: Fixed branch roles/classifications only.
• R-005 Existing blocking breaches become visible: Do not weaken thresholds; fix the cause or record a separately justified decision.
• R-006 Report consumer breakage: Extend the existing schema minimally and retain positive controls.
• R-007 Remote-CI scope creep: No new triggers/lanes/gates; remote execution remains residual unless a minimal existing declaration correction is repo-locally provable.
• R-008 Historical spec damage: Verify Spec 437 and Spec 438 unchanged.

Success Criteria

• SC-001: Phase 1 produces one narrow Constitution branch-topology amendment satisfying rationale, impact-list, SemVer, and Last Amended rules.
• SC-002: The amendment-first sequence required by FR-005 is process-attested in tasks.md and implementation-report.md and corroborated by the final Constitution state, exact amendment-boundary and unrelated-scope controls, synchronized dependent artifacts, and the absence of a conflicting final state. Independent historical chronology is required only when a pre-mutation checkpoint was specified; Spec 439 specified none and claims none retroactively.
• SC-003: All twelve BS fixtures pass deterministically without network.
• SC-004: All seven EF fixtures pass deterministically.
• SC-005: Platform and website fixtures never silently select dev, origin/dev, or HEAD~1.
• SC-006: Conflicting authoritative signals and wrong-family refs fail before diff execution.
• SC-007: Failed tests, missing evidence, contradictions, and blocking budgets return non-zero.
• SC-008: Advisory-only budgets remain visible and non-blocking.
• SC-009: Relevant existing lane/report/guard contracts remain green.
• SC-010: No product-runtime or rendered-surface file changes occur.
• SC-011: Spec 438 remains byte-for-byte unchanged by the implementation branch.
• SC-012: The implementation report contains a complete requirement/task/fixture/result reconciliation and a permitted final verdict.

Mandatory Implementation Phases

1. Phase 0 - Revalidate Spec readiness: Read-only branch, HEAD, dirty-state, governance-process, defect, and consumer revalidation.
2. Phase 1 - Apply the narrowly scoped Constitution branch-topology amendment: Amend the obsolete rule, Sync Impact Report, SemVer, and Last Amended only.
3. Phase 2 - Synchronize directly conflicting authoritative instructions: Align Agents.md and only other confirmed authoritative contradictions.
4. Phase 3 - Implement branch-family and concrete-reference resolution: Add tests first, then the fixed two-stage resolver.
5. Phase 4 - Update local diff guards and affected repository-side workflow declarations: Consume the resolver and remove only proven wrong-target assumptions.
6. Phase 5 - Repair local test/report evidence truth: Preserve execution result and validate JUnit/report consistency.
7. Phase 6 - Repair blocking/advisory budget truth: Derive final exit from authoritative profiles without changing thresholds.
8. Phase 7 - Add negative fixtures and run focused proof: Complete fallback/conflict/evidence controls and focused lanes.
9. Phase 8 - Produce implementation report and final reconciliation: Record all evidence, residuals, scope checks, and final verdict.

Phases 2-8 MUST NOT begin until Phase 1 has been applied and validated. Phase 0 is the only work permitted before Phase 1.

Parallelization Contract

• Phase 0 and Phase 1 are strictly sequential.
• Phase 2 begins only after the Phase 1 gate and remains sequential for shared instruction files.
• Within Phase 3, branch fixture authoring precedes resolver implementation; same-file test/resolver work is single-owner.
• Phase 4 follows the Phase 3 exit gate.
• Phase 5 follows the Phase 4 exit gate, and Phase 6 follows the Phase 5 exit gate; neither phase may prepare work early.
• File-disjoint tasks may run in parallel only inside the currently released phase; shared TestLaneReport/TestLaneManifest edits are single-owner.
• Phase 7 begins only after Phases 3-6 converge.
• Phase 8 is strictly last.
• No parallel task may bypass an earlier phase gate, edit the same file concurrently, or claim implementation evidence before its producing task completes.

Definition of Done

• The narrow Constitution amendment is applied and validated under the existing Amendment Procedure.
• Directly conflicting authoritative instructions use the same branch roles.
• Spec, plan, tasks, checklist, resolver, guard, and applicable workflow declaration use the same two-stage resolver contract.
• BS-001 through BS-012 and EF-001 through EF-007 pass with recorded expected/actual results.
• Original test exit, required evidence, contradictions, report generation, and blocking/advisory budgets determine one truthful final result.
• Existing thresholds are unchanged.
• No forbidden runtime, UI, deployment, remote-administration, or historical-spec paths changed.
• Required focused tests, lanes, formatter, and diff validation are recorded.
• The implementation report reconciles requirements, invariants, changed files, fixtures, tests, residuals, and final verdict.

Implementation Report Requirements

The later implementation report MUST record:

• branch, HEAD, dirty state, active spec, and local refs for dev, platform-dev, and website-dev;
• whether any fetch occurred;
• the Constitution amendment diff, rationale, impacted artifacts, SemVer decision, Last Amended value, and Phase 1 validation;
• amendment-first process attestation and the corroborating final-state evidence required by Amendment-first Evidence Sufficiency, including checkpoint status and an explicit statement that no independent historical chronology is claimed unless it was required before mutation;
• paired baseline-attribution evidence containing the exact baseline SHA, environment and lane-selection comparison, raw exits, JUnit multiset deltas, performance/budget attribution, and artifact checksums;
• Spec 437/438 protection evidence;
• per-file rationale and requirement/invariant traceability;
• each BS and EF fixture's expected/actual family/ref/merge-base/status/exit;
• test/lane selection and budget/baseline/trend outcomes;
• external Gitea/branch-protection/deployment residuals;
• test-governance outcome: keep, split, document-in-feature, follow-up-spec, or reject-or-split;
• final verdict PASS, PASS WITH CONDITIONS, or FAIL under this spec;
• Livewire v4 compliance; provider registration unchanged at bootstrap/providers.php; global-search posture; destructive/high-impact action posture; asset strategy; browser N/A; deployment impact; visible-complexity result; Product Surface exceptions; completed-spec rewrite safety.

PASS WITH CONDITIONS is permitted only for external remote verification not needed for local correctness. It is forbidden when the amendment gate, branch fixtures, result preservation, blocking budgets, required evidence, contradiction detection, or fail-closed branch-family behavior remain unproved.

Follow-up Spec Candidates

1. Spec Package Metadata and Reconciliation.
2. Capability, Skill and Product-Truth Drift Reporting.
3. Gitea CI and Merge Evidence Activation.
4. Branch Promotion and Release Contract.

These follow-ups are not hidden scope for Spec 439.

Open Questions

No blocking product, governance-process, or external-system question remains. Current repo governance permits the narrowly scoped amendment in the same feature PR. Remote Gitea target-ref verification remains a bounded conditional wiring/residual decision and does not block local correctness.

Final Spec Gate - Requirements-Preparation Snapshot

• Candidate Gate: PASS.
• Spec Readiness Gate: READY.
• Implementation Authorization: AUTHORIZED.
• Constitution-Amendment Posture: In scope as Phase 1, mandatory before every dependent mutation, and limited to the branch-topology rule plus required amendment metadata.
• Application implementation performed during requirements correction: no.
• Next action recorded at requirements-preparation close-out: Start a separate Spec 439 implementation loop at Phase 0, then apply and validate Phase 1 before any dependent work.

Final Requirements-Preparation Statement

Spec 439 is implementation-ready. Its first mandatory implementation step is the narrow Constitution branch-topology amendment. After that gate succeeds, the same feature implements one fail-closed two-stage resolver, corrects local branch and evidence truth, and produces PASS only when execution, required evidence, and every blocking condition agree.