Intent Lineage, Backlog Horizons & Domain Governance Specification

Intent Lineage, Backlog Horizons & Domain Governance Specification

Document Status: Living True Specification (Single Source of Truth)
Authority: Architecture, Platform Engineering, Governance & TPM
Related Epics & Issues: #352 (Governance Reform), #306 (Documentation Standards)
Related Documents: CAPABILITY_LIFECYCLE_AND_UPSELL.md, EVALUATION_AND_LINTER_SUITE.md, CLIENT_REVIEW_RUBRIC.md

---

1. Executive Summary & Core Intent

This specification establishes the governance standards for project management, technical documentation, architectural decision-making, and verification across SiteSwarm.

Autonomous AI execution requires clear, unambiguous boundaries. Without disciplined intent governance, AI agents exhibit well-known systemic failure modes:

1. The “Ticket Factory” Antipattern: Spawning hundreds of disconnected tickets from fleeting remarks, substituting continuous creation for continuous planning.
2. Domain Boundary Bleed: Blurring technical architecture with commercial pricing guesses, or dictating legal, tax, and founder governance affairs.
3. Premature Over-Specification (Enterprise Inflation): Gathering unnecessary scope (e.g. enterprise on-call rotations, multi-tier escalation ladders) instead of designing minimal flexible abstractions that defer decisions.
4. The “CI Green” Illusion: Equating passing unit tests with mocked functions to verified production software.
5. Anchored Research Spikes: Creating research tickets with hallucinated answers already in the description, short-circuiting genuine discovery.

This specification codifies the rules and invariants that eliminate these failure modes.

---

2. The Lineage of Intent & The 4-Horizon Backlog Framework

Work is never created in isolation. Every technical task must trace its lineage directly from founder intent down to verifiable code.

flowchart TD
    H3["Horizon 3: Ideas & Brainstorms\n(Tagged: needs-grooming | Quarantined)"]
    H2["Horizon 2: Strategic Epics & Milestones\n(Human-Ratified Architectural Goals)"]
    H1["Horizon 1: Shovel-Ready Task DAG\n(Topologically Ordered Execution Waves)"]
    H0["Horizon 0: Active Worktree Execution\n(pm ship #N in wt isolation)"]

    H3 -.->|Human Ratification & Grooming| H2
    H2 -->|Topological Decomposition| H1
    H1 -->|Autonomous Dispatch| H0

2.1 The Four Horizons

Horizon	Definition	Allowed State	Execution Eligibility
Horizon 3: Ideas & Parking Lot	Passing thoughts, potential future capabilities, or brainstormed agency services mentioned by the founder (e.g. “maybe we do quote calculators or SMS broadcast later”).	GitHub issue tagged needs-grooming.	STRICTLY QUARANTINED. Cannot be scheduled, dispatched, or added as a prerequisite.
Horizon 2: Strategic Epics	Coherent platform capabilities, architectural refactors, or client milestones that have been explicitly prioritized and ratified by the founder.	GitHub issue tagged epic.	Parent container for shovel-ready tasks.
Horizon 1: Shovel-Ready Tasks	Decomposed, dependency-linked issues with explicit acceptance criteria, verification scripts, and non-overlapping file scopes.	GitHub issue tagged priority:*.	Eligible for wave scheduling (pm fleet, pm work).
Horizon 0: Active Execution	In-flight implementation in a dedicated Git worktree (wt).	GitHub issue tagged status:in-progress.	Actively executing under pm ship.

2.2 The Idea Triage & needs-grooming Protocol

• Preserve Zero Untracked Work: Whenever the founder mentions a new idea, potential feature, or optimization, an issue must be created so ideas are never lost.
• Mandatory needs-grooming Label: If the issue is not part of the active roadmap or current execution milestone, it MUST carry the needs-grooming label.
• The Quarantine Invariant:
  • An issue carrying needs-grooming is strictly blocked from execution by pm ship, pm fleet, or pm work.
  • It CANNOT be inserted as a dependency or prerequisite into active Horizon 1 tasks.
  • It remains in quarantine until a human explicitly reviews, prioritizes, and removes the label.

---

3. Strict Domain Separation Invariants

To keep technical specifications durable and prevent AI hallucination from infecting future intent, strict boundaries are enforced across three distinct domains:

flowchart LR
    subgraph "Domain 1: Technical Engineering (AI Domain)"
        T1[Interfaces & Schemas]
        T2[Type Contracts & Invariants]
        T3[Edge Runtimes & CI/CD]
    end

    subgraph "Domain 2: Commercial Pricing (Founder Domain)"
        C1[Retail Pricing & Retainers]
        C2[Gross Margin Modeling]
        C3[Client Contracts & Invoicing]
    end

    subgraph "Domain 3: Legal, Tax & Founder (Expert Domain)"
        L1[Entity Formation & Tax Election]
        L2[Founder Compensation & Equity]
        L3[Employment & IP Agreements]
    end

    T1 -.->|Decoupled From| C1
    T1 -.->|Decoupled From| L1

3.1 Domain 1: Technical Architecture & Engineering (AI Core Competence)

• Scope: Code, TypeScript types, schemas, edge runtimes, test harnesses, CI/CD, documentation formatting, and architectural contracts.
• Strict Invariant: Technical specifications, schemas, and package code must NEVER contain retail pricing, monthly retainer numbers ($/mo), gross margin math, or commercial packaging tiers.
• Software only knows about entitlements, capability names, and technical tiers (e.g. capability: "analytics", tier: "standard"), never what a client pays for it.

3.2 Domain 2: Commercial Pricing & Packaging (Founder Domain)

• Scope: How SiteSwarm packages services, client retainer pricing, setup fees, and sales pitch scripts.
• Commercial strategy belongs exclusively in non-technical commercial proposals, clearly marked STATUS: DRAFT_COMMERCIAL_PROPOSAL.
• Changing commercial pricing must never require changing software schemas, packages, or architectural documents.

3.3 Domain 3: Legal, Tax & Founder Affairs (Founder & External Expert Domain)

• Scope: LLC vs. S-Corp elections, founder compensation (W-2 salary vs. distributions), IP assignment agreements, moonlighting compliance, and municipal licensing.
• Strict Prohibition: The AI must NEVER make decisions or prescriptive recommendations on these topics. The AI is not a licensed CPA or attorney.
• Allowed Output: The AI may only provide neutral preparation checklists outlining questions and documentation to review with a certified professional. Phrases like “strictly rejected” or “we will elect S-Corp” are forbidden.

---

4. Anti-Anchor Research Spike Protocol (type:research / spike)

Research spikes are intended to eliminate technical uncertainty through empirical testing, prototyping, or documentation analysis.

4.1 Mandatory Research Issue Schema

Every research ticket must adhere to this structure:

1. The Unknown / Core Question: The specific technical question or uncertainty to resolve.
2. The Decision It Blocks: The specific architectural choice or task that cannot proceed until this question is answered.
3. Investigation Methodology: The concrete experiments, benchmark runs, prototype implementations, or official documentation reviews to execute.
4. Objective Evaluation Criteria: The measurable criteria or evidence that will decide the outcome.

4.2 The Anti-Anchor Invariant

• A research ticket MUST NOT contain predetermined conclusions, draft answers, or hallucinated numbers in its description.
• Rule of Thumb: If the answer is already known, it is an implementation task, not research. If the answer is unknown, putting assumptions in the ticket biases future agents and invalidates genuine discovery.

---

5. Minimal Viable Abstraction (MVA) & Deferred Decisions Principle

Premature over-specification is a critical failure mode where early architectures attempt to solve hypothetical enterprise requirements (e.g. complex incident escalation queues, multi-tiered SLA timers, multi-tenant billing engines) before basic utility is established.

5.1 The Principle of Deferred Commitment

• The primary purpose of software architecture is to define flexible boundaries and seams that allow future choices to be deferred safely.
• Abstractions must be minimal: define the interface contract, but do not implement hypothetical enterprise machinery.

5.2 Mandatory “Decisions Intentionally Deferred” Section

Every architectural document, ADR, and True Spec in SiteSwarm must contain an explicit section titled:

Decisions Intentionally Deferred

This section explicitly lists the decisions, integrations, and optimizations that are deliberately postponed to future iterations to preserve simplicity.

5.3 Deferred Decision Harvesting Protocol (type:deferred-decision)

To guarantee that decisions intentionally postponed to keep abstractions minimal are never lost into git oblivion:

1. Automated Harvesting: During PR generation, SME evaluations, and wave teardowns, the PM engine scans all ## Decisions Intentionally Deferred sections, PR bodies, and inline code comments (// DEFERRED:, # DEFERRED:).
2. Structured Issue Provisioning: Every deferred item is transformed into a structured GitHub issue:
   • Title: deferred(<scope>): <Concise summary of deferred decision>
   • Body: Context link to origin PR/spec, quoted rationale, and suggested revisit criteria.
   • Labels: type:deferred-decision, needs-grooming, architecture, priority:low.
3. Mandatory Quarantine:
   • Every harvested deferred decision is strictly quarantined under needs-grooming.
   • It CANNOT be scheduled for execution or added as a prerequisite until explicitly reviewed and prioritized in a human grooming session.

---

6. Two-Tier Verification Gate

A pull request or task is NEVER declared ready for human review or merge solely because CI workflows passed. CI passing is a necessary condition, but not a sufficient one.

flowchart TD
    PR[Pull Request Opened] --> T1[Tier 1: Machine Gate\nLint, Types, Unit Tests, CI Workflows]
    T1 -- Failing --> Fix1[Fix in Worktree]
    Fix1 --> T1
    T1 -- 100% Green --> T2[Tier 2: Behavioral / Runtime Proof\nIntegration, E2E, Playwright, Runtime Smoke]
    T2 -- Failing / Missing --> Fix2[Add Tests / Fix Behavior in Worktree]
    Fix2 --> T1
    T2 -- Verified --> Ready[Ready for Human Review & Merge]

6.1 Tier 1: Machine Gate (Automated Static & Unit Checks)

• Zero linter or type errors (pnpm run check).
• Workspace unit tests passing (pnpm test).
• Production build succeeds (pnpm run build).
• GitHub Actions CI 100% green (wait_for_ci.sh).

6.2 Tier 2: Behavioral / Observational Proof (Runtime Gate)

Before declaring work ready for human review, agents must provide concrete evidence that the subsystem works in runtime:

• UI & Frontend: Automated Playwright E2E/smoke test (pnpm run test:a11y or playwright test) or clean ephemeral preview inspection.
• Edge APIs & Workers: HTTP integration test asserting status codes and response bodies against Miniflare/Wrangler local emulation.
• Shared Packages & Plugins: Consumer test verifying that importing and configuring the package in an application compiles, boots, and behaves as expected.
• CLI Utilities & Scripts: Direct execution of the script demonstrating exit code 0 and correct output.

6.3 The Anti-Mocking Invariant

• Unit testing a mocked helper function is NOT behavioral proof that a subsystem works.
• If a pull request only includes unit tests with mocked inputs/outputs and lacks behavioral runtime verification, it must be marked status:needs-integration-test, and CANNOT be reported as READY FOR HUMAN REVIEW.

6.4 The Universal Two-Stage Adversarial Review Pipeline

To eliminate self-grading and guarantee architectural integrity during parallel worktree execution, all tasks must pass a Two-Stage Adversarial Review pipeline before human review or merge:

1. Zero-Dotfile GitHub-Native State:

   • In-flight task handoffs exist exclusively on GitHub (PR bodies, issue milestones, PR reviews).
   • Shared root dotfiles (.pm/HANDOFF.md) are deprecated and eliminated; worker worktrees are strictly barred from modifying shared dotfiles.
   • Machine execution state (.pm/work/state.json) is .gitignored and restricted to the host base branch.

2. Stage 1: Tactical Task Review (pm-reviewer-tactical):

   • Scoped strictly to the individual issue and PR diff.
   • Audits deliverables against acceptance criteria, typecheck/lint cleanliness, local test suites, and 100% green CI.
   • Submits a Tactical PR Review (COMMENT with checklist or REQUEST_CHANGES).

3. Stage 2: Strategic Re-Review & Anti-Faux-Testing Screen (pm-reviewer-strategic):

   • Dispatched by the parent orchestrator with broad epic/PI vision context.
   • Evaluates high-level intent matching, cross-package integration, and executes a mandatory Anti-Faux-Testing Screen.
   • Immediate rejection triggers: tautological assertions, mocks masking missing implementations, skipped test suites, or absence of Tier 2 behavioral proof.
   • Submits the formal PR Review (APPROVE or REQUEST_CHANGES).

4. Interactive In-Worktree Remediation:

   • If either stage requests changes, critiques are relayed to the worker to fix in-place within its active worktree (capped at 2 retries before escalating).
   • Worktrees are cleanly reaped (wt remove --reap) ONLY after Stage 2 approval and 100% green CI.

---

7. Autonomous Delivery Cadence, Grooming & Roadmap Rebalancing

To achieve the confidence required for unattended, nightly autonomous delivery (pm work --nightly), the execution loop enforces strict cadence boundaries to prevent runaway agent drift:

flowchart TD
    W_EXEC[Execute Wave Tasks in Worktrees] --> CADENCE{Completed >= Cadence Limit?\n(Default: 3 tasks or 1 wave)}
    CADENCE -- Yes --> HARV[1. Harvest Deferred Decisions into Tickets]
    HARV --> GROOM[2. Backlog Grooming Cycle & Quarantine Audit]
    GROOM --> BASE_V[3. Base Branch Integration Verification]
    BASE_V --> REB[4. Dynamic DAG & Roadmap Rebalance]
    REB --> BUDGET{Nightly Budget Reached?\n(Default: 9 tasks)}
    BUDGET -- Ceiling Reached --> RETRO[Nightly Checkpoint Handoff & Graceful Pause]
    BUDGET -- Under Budget --> NEXT[Advance to Next Rebalanced Wave]
    NEXT --> W_EXEC
    CADENCE -- No --> W_EXEC

7.1 The Bounded Execution Invariant (“Never Run Wild”)

• Autonomous execution agents must not execute unchecked across wide task batches without re-anchoring.
• Cadence Limit: A rebalance cycle is enforced every $K$ tasks (default: 3 tickets, or upon wave completion).

7.2 The 4-Step Cadence Rebalance Gate

1. Harvest: Scans newly merged PRs, modified specs, and commits for ## Decisions Intentionally Deferred, automatically provisioning quarantined tickets (type:deferred-decision, needs-grooming).
2. Groom: Audits the backlog to enforce quarantine rules, verify anti-anchor constraints on research spikes, ensure zero retail pricing/legal bleed, and resolve satisfied prerequisites.
3. Verify Base Integration: Executes pnpm run check and workspace test suites on the base branch (main) to guarantee that parallel PR merges did not introduce latent regressions.
4. Dynamic Roadmap & DAG Rebalance: Evaluates the dependency DAG against newly completed and harvested issues, reprioritizes the remaining candidate pool, and repartitions into disjoint waves before launching the next wave.

7.3 Nightly Session Ceilings & Graceful Checkpoint

• A single nightly run enforces a strict execution ceiling (default: 9 tickets).
• Once the ceiling is reached or unresolvable blockers emerge, the orchestrator:
  • Synchronizes the Parent PI Story on GitHub.
  • Updates GitHub task checkpoint comments and .pm/work/state.json.
  • Posts an executive handoff comment summarizing completed stories, delivered PRs, harvested deferred decisions, and the groomed next wave.

---

8. Compliance Checklist for Reviewers & Agents

Before opening a PR or declaring a task complete, verify:

• No retail pricing, retainer add-on amounts ($/mo), or margin math in technical specs or code.
• No prescriptive business, tax, or legal determinations for founders.
• Any unplanned or speculative ideas are tagged needs-grooming.
• Research tickets specify questions and methodology, with zero pre-baked conclusions.
• Architectural designs contain an explicit “Decisions Intentionally Deferred” section.
• Intentionally deferred decisions have been harvested into quarantined tickets (type:deferred-decision).
• Two-Tier verification evidence is documented in the PR description and issue completion comment.
• Worktrees do not modify shared dotfiles; task handoff is strictly GitHub-native.
• PR has received Stage 1 (Tactical) and Stage 2 (Strategic / Anti-Faux-Testing) sign-offs.
• For autonomous runs: cadence limits (<= 3 tickets per rebalance) and nightly budgets are strictly respected.