epic: Open-source the complete single-user Answer Engine application

[bradtaylorsf]

Goal

Make the public Answer Engine repository own the complete single-user application and all supporting non-commercial APIs. A fresh local install must expose the same core product experience as enterprise, while the private repository adds only roles, RBAC, teams, billing, and permissions through explicit extension seams.

Non-Technical Summary

The first repository split shipped the memory engine with a six-file Memory/Ask/Import UI, while the proven library workspace application remained private. Restore the full product: content, imports, tags, libraries, answers, recipes, artifacts, reports, dashboards, batch jobs, settings, access tokens, and local audit history. No normal single-user workflow may require curl, Auth0, a manually created API key, or enterprise code.

Why This Matters

• The public project currently presents a stripped-down replacement rather than the actual Answer Engine product.
• Users must be able to organize imported Claude, Codex, Cowork, document, and web content into tags and libraries locally.
• One shared core application prevents OSS and enterprise behavior from drifting.
• The commercial boundary must be easy to explain and enforce: roles, RBAC, teams, billing, and permissions only.

Architecture Observations

• OSS currently has 6 web UI source files; enterprise has 196 and already contains the proven library-as-workspace experience from enterprise epics #439 and #509.
• OSS exposes only content import/list/detail/delete/lineage and agent query/retrieve/summarize/ask routes. Supporting neutral schemas, migrations, routes, services, workers, and UI must move with their product surfaces.
• Preserve tenant_id scoping but use the existing auto-provisioned local tenant and browser session in single-user mode.
• Enterprise must consume the pinned OSS application and inject paid navigation, routes, identity, authorization, and billing. Do not copy two independent core UIs.
• Graphify is excluded from this workflow.

Ordered Sub-Issues

• chore: bootstrap alpha-loop and codify the OSS product boundary #7 - Bootstrap alpha-loop configuration and codify the corrected product boundary. Implement and merge this setup child manually before starting the epic runner.
• feat: port the neutral application data model and API foundation #8 - Port the neutral application data model and API foundation.
• feat: restore the shared application shell and primary workflows #9 - Restore the shared application shell and primary workflows.
• feat: restore advanced non-paid product workflows #10 - Restore advanced non-paid product workflows.
• feat: add enterprise extension contracts and product-parity guards #11 - Add enterprise extension contracts and product-parity guards.
• test: prove complete local product parity on real imported history #12 - Prove complete local product parity on real imported history.

Gated Final Acceptance

• test: prove complete local product parity on real imported history #12 - Prove complete local product parity on real imported history. It is intentionally not ready or in the executable queue until feat: add enterprise extension contracts and product-parity guards #11 and enterprise issue the-answerai/answer-engine-enterprise#964 merge. Then label it ready, append it to Ordered Sub-Issues, and run final verification.

Acceptance Criteria

• Fresh @answer-engine/create install opens the complete single-user app without login or manual API-key setup.
• Users can manage content, imports, tags, libraries, answers, recipes, artifacts, reports, dashboards, batch jobs, settings, access tokens, and local audit history through the UI.
• Existing Claude, Codex, and Cowork history is visible, searchable, organizable, and usable in grounded answers.
• OSS contains no roles, RBAC, teams, billing, or permission-management implementation.
• Enterprise consumes the shared OSS UI/core and adds only paid capabilities via explicit extensions.
• All child acceptance criteria and final epic verification pass.

Dependencies and Sequencing

• Corrects the product boundary established by enterprise issue the-answerai/answer-engine-enterprise#957.
• Reuses the completed behavior from enterprise epics #439 and #509; this is a migration and composition effort, not a redesign.
• Run batch size 1. Migrations, route registration, shared types, hooks, and the React shell have high overlap.
• After feat: add enterprise extension contracts and product-parity guards #11 merges, complete enterprise issue the-answerai/answer-engine-enterprise#964 before making test: prove complete local product parity on real imported history #12 ready.

Verification Expectations

• Run pnpm verify after each integration boundary and from a clean checkout at completion.
• Verify clean database migrate/init plus installer idempotence.
• Use agent-browser for desktop and 375px mobile visual verification of every restored workflow.
• Exercise create/edit/delete and error states, not merely page rendering.
• Prove the final app against real Claude, Codex, and Cowork records and verify grounded citations plus lineage.
• Run alpha-loop run --verify-only 6 and independently inspect issues, PRs, checklist state, learning files, and the enterprise pin before completion.

[bradtaylorsf]

Controlled session recovery after interrupted #8

The first run was stopped because the #8 planner loaded the excluded Graphify skill. A SIGINT defect then advanced incorrectly into #9. The two root-cause repairs are now merged:

• OSS fix: enforce the epic Graphify exclusion in worker instructions #15 / PR fix: enforce Graphify exclusion in epic workers (#15) #16: explicit Graphify prohibition in every worker instruction source, required feat: port the neutral application data model and API foundation #8/feat: restore the shared application shell and primary workflows #9 interruption learnings, and transient-worktree scan isolation
• Alpha Loop #386 / PR #387: durable SIGINT/SIGTERM cancellation that terminates the active agent and prevents later stages or queue items

Both repairs passed their complete test/build gates. The Alpha Loop release workflow triggered by #387 was cancelled before dependency installation, and the Release job executed zero steps; no npm package was published.

Recovery plan

1. Advance the existing epic session branch from repaired master through a PR (never a direct push).
2. Remove only the verified-empty feat: port the neutral application data model and API foundation #8/feat: restore the shared application shell and primary workflows #9 local worker branches/worktree. Both point exactly at the original empty session-start commit and contain no unique commits or uncommitted files.
3. Let Alpha Loop reclaim the dead PID lock and reuse the deterministic epic session/branch. GitHub checklist and ready labels remain authoritative; feat: port the neutral application data model and API foundation #8 is the first unchecked child.
4. Re-run preflight, sync, and the exact batch-size-1 dry-run. Start the real run only if the queue is exactly feat: port the neutral application data model and API foundation #8, feat: restore the shared application shell and primary workflows #9, feat: restore advanced non-paid product workflows #10, feat: add enterprise extension contracts and product-parity guards #11 with no skips.

Lesson Learned

For interrupted ordered epics, recovery must reconcile three independent authorities: the GitHub checklist, the session branch, and local worker worktrees. Preserve evidence and learnings, but discard only branches proven to have no unique commits so an incorrectly started later child cannot become the resume point.

[bradtaylorsf]

Alpha Loop paused safely during #9

#8 is integrated into the session branch. During #9, mandatory UI verification exposed a browser harness/sandbox mismatch: the worker chose synced playwright-cli, which attempted to create a daemon under a non-writable home cache. The runner was stopped once and correctly preserved #9 without advancing to #10.

Root-cause repair is tracked in #19. After #19 merges and linked-worktree browser smoke verification passes, the existing #9 worktree/session state will be resumed; the ordered epic queue will not be restarted or skipped.

[bradtaylorsf]

Alpha Loop paused safely before #10 implementation

Issue #9 merged into the session and both CI checks passed. When issue #10 began, its mandatory browser setup failed; Alpha Loop warned and continued, so the supervisor stopped it immediately. The issue #10 worktree/checklist were preserved before source edits, and #11 was not started.

The root cause is a stale shared agent-browser daemon whose binary and CWD belonged to the deleted issue #9 worktree. OSS #19 has been reopened for the lifecycle repair. Alpha Loop will also be patched upstream so a failed setup command stops automatically. The existing epic session will resume only after both repairs are verified and synced.

[bradtaylorsf]

Alpha Loop paused before #10: session branch checkout conflict

The post-repair dry run validated the exact ordered queue (#10, then #11). The real run stopped before either child changed state because the repository root was still checked out on the session branch after sync PR #27 merged; Git therefore rejected Alpha Loop's separate session worktree checkout of the same branch.

No agent or child work ran, and both issues remain ready. The coordinator/session conflict is being repaired through a focused upstream Alpha Loop issue with regression coverage for graceful finalization. After merge/build, the clean coordinator will return to master, the exact dry-run validation will be repeated, and the existing epic session will resume.

[bradtaylorsf]

Epic Verification

Overall: PARTIAL

Verification output could not be parsed; defaulting to partial.

Sub-issue	PR	Status
#7 chore: bootstrap alpha-loop and codify the OSS product boundary	PR	evaluated
#8 feat: port the neutral application data model and API foundation	PR	evaluated
#9 feat: restore the shared application shell and primary workflows	PR	evaluated
#10 feat: restore advanced non-paid product workflows	PR	evaluated
#11 feat: add enterprise extension contracts and product-parity guards	PR	evaluated

---

Verified by alpha-loop

[bradtaylorsf]

OSS #10/#11 integration complete; moving to enterprise composition

PR #14 merged the verified #10 and #11 session into OSS master. PRs #28 and #29 and the integrated session PR all passed verify and container CI; both issues have dedicated learning artifacts. The session PR body was corrected after merge because Alpha Loop had labeled a canceled/missing post-session gate artifact as passed; that engine defect is now tracked in bradtaylorsf/alpha-loop#392.

The premature epic verification returned partial and did not close #6. Its temporary needs-human-input label has been removed because this is the expected sequencing boundary: enterprise #964 must now compose the OSS core, then #12 will be labeled ready and appended as the final unchecked Ordered Sub-Issue for real acceptance.

[bradtaylorsf]

Epic Verification

Overall: PARTIAL

Verification output could not be parsed; defaulting to partial.

Sub-issue	PR	Status
#7 chore: bootstrap alpha-loop and codify the OSS product boundary	PR	evaluated
#8 feat: port the neutral application data model and API foundation	PR	evaluated
#9 feat: restore the shared application shell and primary workflows	PR	evaluated
#10 feat: restore advanced non-paid product workflows	PR	evaluated
#11 feat: add enterprise extension contracts and product-parity guards	PR	evaluated
#12 test: prove complete local product parity on real imported history	PR	evaluated

---

Verified by alpha-loop

[bradtaylorsf]

Epic Verification

Overall: PARTIAL

The supplied evidence does not prove every child acceptance criterion. The diffs attributed to issues #7, #8, and #9 are the unrelated three-file PR #23 browser-preparation change and contain none of those issues’ substantive setup, API, or UI work. The merged PR #14 changes substantively satisfy the advanced-workflow and extension-contract requirements for #10 and #11, although their exact verification and browser results are not fully evidenced. Issue #12 documents successful installation, real-history, UI, grounding, service, and enterprise-parity checks, but its own acceptance record says the required alpha-loop verify-only run returned a partial verdict. Therefore the epic is partial rather than pass.

Sub-issue	PR	Status
#7 chore: bootstrap alpha-loop and codify the OSS product boundary	PR	partial (0/4)
#8 feat: port the neutral application data model and API foundation	PR	partial (0/6)
#9 feat: restore the shared application shell and primary workflows	PR	partial (0/6)
#10 feat: restore advanced non-paid product workflows	PR	partial (5/6)
#11 feat: add enterprise extension contracts and product-parity guards	PR	partial (5/6)
#12 test: prove complete local product parity on real imported history	PR	partial (7/8)

Per-criterion findings (36)

• chore: bootstrap alpha-loop and codify the OSS product boundary #7 • missing — node ../alpha-loop/dist/cli.js sync --check succeeds and configured harness outputs match project templates. — The attributed PR fix: refresh browser dependencies on resume (#19) #23 diff only changes browser:prepare, its repository assertion, and a learning note. It does not add or validate Alpha Loop configuration, templates, or sync output.
• chore: bootstrap alpha-loop and codify the OSS product boundary #7 • missing — node ../alpha-loop/dist/cli.js run --epic 6 --dry-run --validate --batch --batch-size 1 discovers every unchecked child in order. — No dry-run output, queue-order assertion, or related configuration appears in the supplied merged diff.
• chore: bootstrap alpha-loop and codify the OSS product boundary #7 • missing — Vision and agent guidance say all non-paid product UI/APIs belong in OSS and list roles, RBAC, teams, billing, and permissions as the enterprise-only boundary. — The supplied diff does not modify the vision, AGENTS.md, instruction templates, or product-boundary guidance.
• chore: bootstrap alpha-loop and codify the OSS product boundary #7 • unclear — pnpm verify remains green. — A repository test expectation is updated, but the diff contains no complete pnpm verify result.
• feat: port the neutral application data model and API foundation #8 • missing — Clean database migration and rollback paths cover every new table/index/constraint. — The attributed PR fix: refresh browser dependencies on resume (#19) #23 diff contains no migrations, rollback files, schema changes, or migration tests.
• feat: port the neutral application data model and API foundation #8 • missing — CRUD and workflow integration tests pass for tags, libraries, memberships, recipes/artifacts, reports, dashboards, batch jobs, access tokens, and audit records. — No application routes, services, or integration tests for these capabilities appear in the supplied diff.
• feat: port the neutral application data model and API foundation #8 • missing — Library-scoped query/ask returns grounded citations and honors manual include/exclude plus filters. — The supplied diff has no retrieval, ask, library-membership, filtering, or citation implementation.
• feat: port the neutral application data model and API foundation #8 • missing — Existing history rows remain intact and can be assigned tags/libraries. — No history-preservation migration or tag/library assignment implementation is present in the attributed diff.
• feat: port the neutral application data model and API foundation #8 • missing — Route/capability tests prove paid concepts are absent. — The supplied diff contains no route inventory, capability boundary, or paid-concept absence tests.
• feat: port the neutral application data model and API foundation #8 • unclear — pnpm verify passes. — No complete verification result for the issue is included.
• feat: restore the shared application shell and primary workflows #9 • missing — Local root redirects into the complete application without login or manual API-key input. — The attributed PR fix: refresh browser dependencies on resume (#19) #23 diff does not modify application routing, session bootstrap, authentication, or API-key behavior.
• feat: restore the shared application shell and primary workflows #9 • missing — Users can create/edit/delete tags and libraries, assign/unassign content, filter/search/sort/paginate, use bulk actions, inspect raw content/summary/lineage, and import supported content. — No shared shell, pages, hooks, components, or workflow tests appear in the supplied diff.
• feat: restore the shared application shell and primary workflows #9 • missing — Answers can be scoped to a library and show real citations. — The supplied diff contains no Answers UI or library-scoped citation behavior.
• feat: restore the shared application shell and primary workflows #9 • missing — Existing Claude, Codex, and Cowork history appears in content and library workflows. — No source-history rendering, content workflow, or library workflow implementation is included.
• feat: restore the shared application shell and primary workflows #9 • missing — No paid navigation or dead enterprise-only controls appear. — The supplied diff contains no navigation or application-shell changes from which this can be established.
• feat: restore the shared application shell and primary workflows #9 • unclear — Unit/integration tests, pnpm verify, and agent-browser desktop/mobile interaction checks pass. — The diff updates browser preparation infrastructure but provides no issue-specific unit, integration, desktop, mobile, or complete verification results.
• feat: restore advanced non-paid product workflows #10 • met — Recipes can be created, edited, previewed, run, and inspected with progress, history, per-item results, errors, and versioned artifacts. — PR Session: session/epic-6-epic-open-source-the-complete-single-user-answer-engine-application — 2/2 succeeded #14 adds recipe CRUD/version forms, preview and run controls, progress and history displays, detailed per-item output/errors, retry/cancel/export controls, versioned-artifact links, API hooks, and focused tests.
• feat: restore advanced non-paid product workflows #10 • met — Reports and dashboards can be created, edited, viewed, and scoped to libraries. — LibraryAdvanced adds library-bound report and dashboard panels with create, update, selection/view, generation, cancellation/retry, and deletion workflows backed by typed hooks.
• feat: restore advanced non-paid product workflows #10 • met — Batch jobs expose status, progress, results, failures, and safe retry/cancel behavior supported by the API. — The new BatchJobsPage renders status, progress, successful and failed results, errors, exports, terminal-state retry, and active-state cancellation; service and route tests cover safe retry behavior.
• feat: restore advanced non-paid product workflows #10 • met — Access tokens can be minted, copied once, listed, scoped, and revoked without team/permission UI. — SettingsPage implements one-time token display and clipboard copying, token listing, tenant/library scope and read/write capability selection, metadata editing, and revocation without team or role controls. Tests verify the raw token is returned only at creation.
• feat: restore advanced non-paid product workflows #10 • met — Settings and local audit history are fully usable by the local owner. — The settings surface supports local defaults, token administration, and paginated/filterable/exportable audit history with a detail dialog and visible error states.
• feat: restore advanced non-paid product workflows #10 • partial — All workflows pass focused tests, pnpm verify, and agent-browser desktop/mobile checks. — The diff includes focused UI, API, route, service, keyboard-focus, and responsive-related tests, and the learning record reports success. It does not provide exact pnpm verify output or durable desktop/mobile agent-browser execution evidence for this PR.
• feat: add enterprise extension contracts and product-parity guards #11 • met — OSS starts standalone with default local adapters and the full core route manifest. — PR Session: session/epic-6-epic-open-source-the-complete-single-user-answer-engine-application — 2/2 succeeded #14 adds standalone composition defaults, a core route manifest, and tests exercising the application without an enterprise extension.
• feat: add enterprise extension contracts and product-parity guards #11 • met — A fixture extension can inject representative paid navigation/routes/policy without modifying or copying core pages. — Composition tests exercise injected identity, authorization policy, route, navigation item, settings section, and capability metadata around the unchanged core application.
• feat: add enterprise extension contracts and product-parity guards #11 • met — Type/build tests protect the extension contract. — The diff adds public exports, a dedicated library TypeScript configuration and Vite build, composition type tests, runtime-schema validation, and package scripts covering the shared entry point.
• feat: add enterprise extension contracts and product-parity guards #11 • met — Boundary tests fail if a core surface is removed or if roles/RBAC/teams/billing/permissions leak into OSS. — The independent product-boundary inventory, core manifest comparison, public-boundary checker, and repository tests enforce required core surfaces and the five-family paid boundary.
• feat: add enterprise extension contracts and product-parity guards #11 • met — Composition documentation names the enterprise pin/update workflow. — The new enterprise-composition document and README changes describe the pinned OSS consumer and update workflow.
• feat: add enterprise extension contracts and product-parity guards #11 • partial — pnpm verify passes. — The diff contains extensive contract, composition, server, and boundary tests, but one included learning record says the full command encountered a sandbox-only process-inspection failure. A later success record does not include the exact completed pnpm verify result.
• test: prove complete local product parity on real imported history #12 • met — Fresh local install works without Auth0, billing credentials, or manual API-key creation. — The integrated acceptance record documents two successful installer invocations without Auth0, billing credentials, a supplied API key, or agent configuration, including health and remember/recall verification.
• test: prove complete local product parity on real imported history #12 • met — Complete UI workflows pass: content/import/tags/libraries/answers/recipes/artifacts/reports/dashboards/batch/settings/tokens/audit. — The acceptance record lists successful desktop mutations across every named workflow and successful rendering at desktop and 375px mobile widths.
• test: prove complete local product parity on real imported history #12 • met — Expected real inventory is present with no source failures: Claude 848 files, Codex 4105 files, Cowork 112 files. — The recorded authoritative scans report 854 Claude Code, 4,143 Codex, and 112 Cowork files with zero failed rows and parse errors. The verifier correctly treats the stated append-only counts as minimum baselines.
• test: prove complete local product parity on real imported history #12 • met — Every stored history row has a summary and raw archive manifest; sampled archives match SHA-256. — The verifier and acceptance table report tenant-scoped summary/manifest coverage for all stored rows and successful deterministic archive hashing samples for all three sources.
• test: prove complete local product parity on real imported history #12 • met — API and MCP query/ask/lineage succeed with real records and grounded citations from all three sources. — The record documents REST query, lineage, and cited ask checks plus MCP search_content, ask, and inspect_memory checks using selected real Claude Code, Codex, and Cowork records, with citations covering all three.
• test: prove complete local product parity on real imported history #12 • met — Background sync service is installed and verified. — The macOS launch agent is documented as running, and a fresh complete three-source cycle recorded successful completion with zero failures.
• test: prove complete local product parity on real imported history #12 • met — Enterprise issue the-answerai/answer-engine-enterprise#964 is merged and pins the verified OSS revision. — The acceptance record identifies merged enterprise PR #966 and confirms both the enterprise submodule and reviewed manifest pin OSS revision 2cc52e9.
• test: prove complete local product parity on real imported history #12 • partial — pnpm verify, clean migration/init, agent-browser desktop/mobile checks, and alpha-loop run --verify-only 6 pass. — The acceptance record documents successful pnpm verify, idempotent clean migration/init, and desktop/mobile browser checks. However, it explicitly states that the required verify-only command returned verdict=partial because its nested Codex process could not initialize in the managed sandbox; no later passing verify-only result is included.

---

Verified by alpha-loop