Factory docs, home
Page navigation

Reference document, shown as written except that local paths appear as placeholders. Where it describes the Factory as intended, read it as design, not current state: only local infrastructure is accepted, no release, customer value or scheduled automation is established, and all 27 customer-value epics remain open. Current state: Factory model.

Owner direction, 28 September 2026: a local browser dashboard for JustSpeakToIt, Pasta, Family Watch, Tally, Focus Sentinel and this factory. The portfolio baseline is implemented and locally verified; expanded decision capabilities remain incremental work. Intent r9.

Portfolio. Show each registered Product's current objective, active Slice, last verified progress, health, blockers and next action. Local inventory precedes registration; preserve dirty worktrees and stable identities. Registration carries explicit operation scope and does not authorise customer releases or publication. The factory uses the same Product contract as its portfolio.

Observability. Read derived views of durable facts, with source, capture time and reporting window. Rebuilding a view never dispatches work. Show project count; work created, verified, rejected, integrated and reverted; issues and PRs where an authenticated source supplies them; measured Outcomes; active focus; and token use/spend by Product, Slice and provider. Keep opened/closed-unmerged PRs, requested changes and rejected proposals distinct. A merge is not release or value. Missing usage/cost is unknown, never zero; distinguish provider-reported estimates from billing. Do not infer human attention from dirty files or financial value from activity counts.

Modularity. Collectors translate external systems into sourced facts; observability owns projections; a typed API exposes presentation data; the dashboard renders it. Product code, Git commands, provider receipts, journal storage and metric calculations stay outside UI components. Product IDs are registry data, not application branches. Replace a collector without changing the dashboard when its fact contract is unchanged; change the view implementation without changing callers when its API is unchanged. Keep queries separate from explicit commands and isolate failed sources. Independent review must verify these boundaries, not merely file organisation.

Interaction. Use focused views that suit the choice: project selection/connection steps, comparable option cards, a release or migration preview, or a blocker repair guide. Each requested decision explains the objective, material trade-offs, recommended option and effect of choosing it. Keep details/evidence one click away. Routine reversible choices proceed autonomously and appear as inspectable decisions; the dashboard must not become an approval queue for self-solvable work.

Project values. Show a small set of concise values and the choices each should change. Owners can add and refine them; retain revisions and stable IDs. A saved revision supplies immutable guidance for future briefs, without rewriting existing acceptance criteria or granting delivery authority. Do not invent values for projects with no source.

Required actions. One central list links real unresolved prerequisites to their Product, evidence and resolution view. Keep missing data informational unless a source establishes an action. Distinguish factory, owner and external responsibility; unknown responsibility is explicit. Dismissing a notice cannot resolve its underlying condition.

True blockers. Show the unavailable prerequisite, affected work, verified remedies already tried, why further authorised remedies cannot progress, and exact steps to resolve it. Include a clear way to recheck after resolution. Preserve independent eligible work. Keep credentials in supported local authentication flows, outside chat, telemetry and evidence.

Acceptance. Register the six real local identities; verify displayed facts against their source and demonstrate updates without double-counting. Exercise absent/stale data, unavailable authentication, failed verification, uncertain effects and empty history. Verify responsive layouts, keyboard operation, option selection and actionable blocker states in a real browser; retain screenshots and independent review. Decisions must reach the same typed domain contracts as other callers. No placeholder counters, decorative controls or synthetic success presented as live portfolio evidence.

Source: docs/human-interface.md