📝🧑‍💻 - Establish the Domus SDD foundation product vision and architecture #2

Is there an existing issue for this?

• I have searched the existing issues.

What part of the documentation needs an update?

Other

Describe the documentation update

Establish Domus through Spec-Driven Development before application implementation. Investigate the actual conventions in vypdev/copilot and the application patterns in vypdev/homeassistant-gateway. Prepare a product vision, architecture alternatives, proposed ADRs, glossary, phased roadmap, and eleven Draft SDDs covering platform, household identity and permissions, tasks, recurrence and calendar, points and rewards, shopping, inventory, Home Assistant entities/services and automation, application experience, and delivery quality/channels.

Use Copilot's original twenty-section specification contract, explicit requirements, observable acceptance cases, risk-derived numeric test budgets, and reciprocal traceability. All issues, documentation, code, identifiers, and comments belonging to Domus must be in English. Spanish is used only in conversation with the owner.

The existing gateway is already integrated into Home Assistant. Do not install, change, or redesign it. Domus owns its entities, services, structured responses, and domain behavior; Home Assistant's existing MCP subsequently consumes those capabilities. Domus does not implement an MCP server.

Why is this update needed?

The repository currently contains only its minimal README and the existing Copilot installation. The profile declares preBranchSdd=true, but the specification prerequisites do not exist yet. The enabled documentation workflow is the appropriate route for a documentation-only foundation.

Acceptance:

1. Inherited conventions and intentional differences have primary-source references.
2. All eleven Draft SDDs cover the twenty canonical concerns and have unique capability ownership.
3. Normative requirements map to explicit acceptance cases, case counts, owners, and documentation.
4. Proposed capabilities do not claim implemented code, executed tests, or live acceptance.
5. Architecture alternatives, configuration, security, recovery, migration, and blocking decisions are explicit.
6. Draft validation is reproducible and distinguished from Copilot gate readiness.
7. No Copilot implementation or installed automation is modified.

Additional resources

• https://github.com/vypdev/copilot/blob/f5e5a4cf9a80248994469cd88ad55eecab5b95ca/specs/README.md
• https://github.com/vypdev/copilot/blob/f5e5a4cf9a80248994469cd88ad55eecab5b95ca/specs/_template.md
• https://github.com/vypdev/copilot/blob/f5e5a4cf9a80248994469cd88ad55eecab5b95ca/docs/issues/pre-branch-sdds.mdx
• https://github.com/vypdev/homeassistant-gateway/blob/9d4e159182f7c955406c37fd372ee3ec50ed2b87/docs/architecture.md
• https://github.com/vypdev/homeassistant-gateway/blob/9d4e159182f7c955406c37fd372ee3ec50ed2b87/docs/frontend-design.md

Additional context or comments

This issue follows the installed documentation form. The owner's attachment ends at the start of section 10.2, Barcode support, after “Support common product identifiers such”. Document that evidence boundary rather than inventing missing instructions.

The owner explicitly prohibits changes to Copilot, including its repository and installed guidance, profiles, workflows, templates, and scripts. Only an existing dependency-preparation setup file may be considered if required; no such change is currently needed. Any validator limitation is reported, not patched around.

A maintainer starts this admitted issue with in-progress. The GitHub Action owns the exact remote branch. Prepare reviewable drafts outside the checkout until that branch is published and verified. Do not invent a remote branch or apply lifecycle labels as a contributor agent. This task does not authorize application implementation, merge, release, or deployment.

Confirmed owner decisions: both Supervisor App/Ingress and standalone Container are first-release targets; all functional domains are included in that first release; every participant has their own HA account. Clean Architecture is mandatory, meaningful tests and maximum coverage start with the first code, a project-owned CI Check workflow runs all tests on each PR update, and Stable/experimental Edge channels must coexist with separate data/credentials/HA IDs. Google Chrome dogfooding is authorized at http://homeassistant.local:8123/ using identifiable test data and explicit cleanup.

Prepared evidence: eleven Draft SDDs, 82 normative requirements and 353 planned acceptance cases. The unchanged Copilot format and consistency functions pass all eleven documents. The unchanged SDK catalog validator reports 33 empty entrypoints/code/tests errors because implementation does not yet exist; no gate readiness or executed application tests are claimed. Copilot remains unchanged.

Owner decisions confirmed on 2026-10-29

Use Python/FastAPI, SQLite, one household per installation, a thin HA integration and Lit/TypeScript/Vite with owned HA-coherent components, Storybook and Playwright. Adults need no completion verification by default; restricted performers need adult approval. Relative recurrence anchors to actual completed_at, with per-task successor timing defaulting to at_completion and at_verification available. Nonexistent wall times advance to the first valid local instant at or after the intended slot.

Collaborative points allocation is configurable in the application, supporting a conserved total, equal shares rounded down/up, decimal shares, full task points per performer and authorized manual shares. The actual total may differ from the base task value; policy snapshots and actual-award reversal remain auditable. Camera/manual barcode workflows include local matching and optional Internet product lookup. Manual shopping requests are extras by default; covered automatic requirements consolidate without duplication.

Both simple/default and optional advanced automation editors are first-release scope over one durable declarative engine. Add its dedicated SDD and fifth ADR without duplicating the native HA integration's ownership. No Copilot implementation, installed resource or gateway changes are authorized. These are specification decisions, not authorization to implement, merge or deploy the application.

Continued SDD review confirmed on 2026-10-29

Task materials use adjustable actual quantities in the completion submission by default, configurable per task. Insufficient stock saves performed work and consumption pending regularization without negative stock; reopening never fabricates a physical return.

Reopening reverses actual points even if already spent. A factual negative balance blocks new redemptions until sufficient credit exists, while fulfilled rewards stay fulfilled. Participation and earned points belong to the actual-work period; required approval controls later spendability.

Missed fixed-schedule occurrences are configurable per task and remain visibly pending by default, with explicit skip preserving history and awarding no points. Recurrence edits show a preview and update only future unstarted work, retaining active work, exceptions and history.

The review adds explicit cycle-based allocation uniqueness, atomic performer shares, out-of-order closure handling, precision validation, durable replay guards and current permissions for operation lookup/replay. All eleven original draft-format/consistency checks pass. The catalog remains blocked by exactly 33 missing implementation-evidence errors, reported upstream without changing Copilot.

The three questions from that review are now answered as recorded below. The contracts remain Draft while engineering/security evidence and detailed permission/resource contracts are completed.

Further owner decisions confirmed on 2026-10-29

• Reopening a prerequisite preserves already-completed dependents, points and material facts, raises a linked review condition and never automatically reopens a chain.
• Disabling automation stops new runs and later steps, allows already-started atomic commands to settle and retains their real effects. Restart/re-enable does not silently resume cancelled work.
• Approved unfulfilled rewards whose backing points were reversed enter a funding hold. Preserve approval/reservation and block delivery while unfunded until credit recovers or an explicit authorized resolution occurs.
• Administrator mapping supports all three requested modes: all HA administrators by default, only the verified setup administrator, or an explicitly selected active HA user. Current trusted identity, source provenance, revocation and last-administrator safety remain required.
• Predefined permission profiles are adjustable per household with explicit per-member exceptions; current backend authorization and hard domain invariants remain authoritative.
• Repeated autumn wall times execute once at the first appearance by default; the household may choose the second. Retain nominal identity and policy/offset evidence without duplicate work.

The latest question batches have no unanswered owner decision. Detailed permission matrices, HA identity/administrator proof and authenticated recovery, library/export interoperability, adapters and resource bounds remain engineering/security gates. All eleven drafts pass the unchanged original format/consistency checks and now contain 82 normative requirements and 353 planned acceptance cases, with no application tests or coverage claimed. Copilot and its installed resources remain unchanged.