Add Pre-v1 Demo Evolution Plan and product-demo rename strategy#129
Merged
Conversation
…n-for-product-improvements
Cross-cutting architecture for the pre-v1 demo increment: Vue 3 SFC + Vue Router + Pinia stack, DDD layering with forbidden-import table, layered Pinia stores (domain wraps agentonomous use-cases, view holds UI-only state), cross-pillar contracts (Scenario, WalkthroughStep, DiffMetric, RunFingerprint, ConfigDraft), determinism fingerprint design (sha-256 truncated to 128 bits over normalized tick stream), persistence contract under demo.v2.* with no migration shims (pre-v1 policy), and Playwright e2e strategy. Companion to PR #129's planning doc. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Per-pillar testable requirements for the pre-v1 demo evolution increment. Covers all 5 pillars (guided walkthrough, cognition diff panel, determinism fingerprint, JSON preview/commit, second scenario) plus the Wave-0 demo rename preflight as separate atomic delivery slice. Each pillar section follows a uniform structure: outcome, FRs, data shapes, acceptance criteria (Given/When/Then), out-of-scope, and inter-pillar dependencies. Cross-cutting NFRs (determinism, performance, accessibility, i18n) and a storage contract restate invariants the design doc fixes shapes for. Open questions are tracked under OQ-* tags deferred to per-pillar plan kickoffs. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Six per-pillar roadmaps following the repo's chunked-PR-slice convention (rows = mergeable PR scopes; not bite-sized TDD steps). Each plan links back to the planning doc + design doc + spec, declares its wave + plan dependencies, lists chunked roadmap rows with file targets and spec FRs, and ends with verification gates + DoD + a Done log section that future slice-PRs append to. Plans: - 2026-04-26-pre-v1-demo-rename-preflight.md (Wave 0, single atomic PR) - 2026-04-26-pre-v1-demo-guided-walkthrough.md (Pillar 1, Waves A-C) - 2026-04-26-pre-v1-demo-cognition-diff-panel.md (Pillar 2, Waves A-B) - 2026-04-26-pre-v1-demo-determinism-fingerprint.md (Pillar 3, Waves A-C) - 2026-04-26-pre-v1-demo-json-preview-commit.md (Pillar 4, Wave B) - 2026-04-26-pre-v1-demo-second-scenario.md (Pillar 5, Waves B-C) Every downstream PR cut from these plans must include "Tracks: #129" in its body, tick its row in the planning doc's Tracker table in the same diff, and get added to PR #129's GitHub tasklist. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…tracker table (#129) Patches the planning doc landed by #129 with three additions: - "Document set" section after Purpose: links to the design doc, the spec, and the six per-pillar plans; states PR #129 stays docs-only and serves as the umbrella tracker; documents the contract every downstream PR must follow ("Tracks: #129" body line, tracker-table tick, GitHub tasklist row). - "Tracker table" section before the milestone checklist: canonical per-pillar status table (Wave, Pillar, Plan link, Status, PR) updated in lockstep with each downstream PR. - Milestone checklist bullets now link to the owning plan file so reviewers can jump from the M1/M2/M3 view to the chunked roadmap. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Owner
Author
|
@codex review This PR has expanded from a single planning doc into the umbrella tracker for the pre-v1 demo evolution increment. It now contains:
PR remains docs-only; implementation lives in downstream PRs that will reference Please review for:
|
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 1e98bcf4b1
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Comment on lines
+119
to
+121
| - **Tour resumption guard** (`/tour`): if no active session exists, | ||
| initialize it deterministically from the tour's known-good seed before | ||
| rendering the step. |
There was a problem hiding this comment.
The route guard here says /tour should reinitialize from a fixed "known-good" seed whenever no active session exists, but the spec’s P1-AC-2 requires reload to resume on the same step with the same scenario and seed the user already had. These contracts conflict: implementing this guard as written will reset seed state on reload and fail the walkthrough acceptance behavior.
Useful? React with 👍 / 👎.
| | From | May not import | | ||
| |---|---| | ||
| | `components/**` | `agentonomous`, `examples/product-demo/src/demo-domain/**` | | ||
| | `views/**` | `examples/product-demo/src/demo-domain/**` (use stores instead) | |
There was a problem hiding this comment.
agentonomous imports from views in lint table
The DDD section states presentation code (views/ and components/) must not import agentonomous directly, but the ESLint forbidden-import table only blocks demo-domain/** for views/**. If this table is enforced verbatim, views can still import core domain APIs directly, so IAC-5 can pass while the documented layering rule is violated.
Useful? React with 👍 / 👎.
Comment on lines
+71
to
+72
| - Per-scenario persistence keys: `demo.v2.session.lastSeed.<scenarioId>`, | ||
| `demo.v2.config.committed.<scenarioId>`. Switching scenarios does not |
There was a problem hiding this comment.
This introduces per-scenario suffix keys for seed/config, but other companion docs define and use unsuffixed keys (demo.v2.session.lastSeed, demo.v2.config.committed). Keeping both patterns in the umbrella tracker creates incompatible implementations across pillars and risks failing P5’s scenario-isolation requirement once teams implement their slices independently.
Useful? React with 👍 / 👎.
Comment on lines
+415
to
+417
| - **P5-AC-4.** A demo presenter can articulate "same core, different | ||
| behavior surface" in ≤ 20 seconds using only what is visible in the | ||
| UI. |
There was a problem hiding this comment.
P5-AC-4 is framed as presenter ability ("can articulate ... in ≤20 seconds"), which is not an observable product behavior with deterministic pass/fail steps like the other acceptance criteria. That makes pillar sign-off ambiguous and weakens FR→AC traceability because teams cannot prove completion via automated or repeatable manual verification.
Useful? React with 👍 / 👎.
Luis85
pushed a commit
that referenced
this pull request
Apr 26, 2026
…uct-demo) PR #129 is the umbrella tracker for the pre-v1 demo evolution increment. Wave 0 of that increment is an atomic single-PR rename of examples/nurture-pet/ -> examples/product-demo/, with the rename PR sweeping every reference across scripts, Pages workflow, README, CI and tests. This plan touches the demo workspace in Task 8 (Playwright smoke), so the two PRs need an explicit coordination contract. Choices: (a) Pre-rename in this plan to anticipate Wave 0 (b) Stay on examples/nurture-pet/ and let the rename PR sweep us Picked (b). Reasoning: develop currently contains only nurture-pet/; shipping a plan that references product-demo/ before Wave 0 merges would point at a path that does not exist, breaking Step 8.0 (path sanity check) and Step 8.4 (local Playwright run against preview server). A single mechanical sed in the Wave 0 PR converges everything; pre-renaming would force manual reconciliation in two places. Changes: - Architecture bullet now points at the demo workspace via that description rather than a hardcoded directory name; cross-refs the new coordination section. - New 'Coordination with PR #129 (demo rename)' section between Out of scope and File structure: explains the rename, the path policy table, and the explicit sequencing rule (decide at start of Task 8; if Wave 0 has merged, merge develop into this branch and substitute paths; if Wave 0 has not merged, proceed verbatim and ping the Wave 0 PR when it opens). Cites MEMORY.md -> feedback_parallel_pr_plan_conflicts.md for the merge vs rebase preference. - Task 8 gains a 'Demo path' callout block + a new Step 8.0 that greps origin/develop for the demo dir name and tells the worker whether to substitute. - Risk register: new bullet 'Demo rename in flight (PR #129 / Wave 0)' warning specifically against shipping examples/product-demo/ paths from this branch before Wave 0 lands. Plan-only commit; no library or workflow code touched. Path strings remain examples/nurture-pet/ literal across all eight rows by design.
1 task
Resolve 4 line-level findings from Codex review of the umbrella tracker: - P1 (design.md, route guards): Tour resumption guard rewritten to preserve the user's seed on reload. Resolution order now: hydrate from `demo.v2.session.lastSeed.<scenarioId>` when tour progress exists; bootstrap from the tour's known-good seed only on cold-start via the "/" CTA; redirect deep-links with no progress to "/". Aligns with spec P1-AC-2 (reload resumes same step + scenario + seed). - P1 (design.md storage table + spec.md P4 + json-preview plan): Persistence keys for per-scenario state are now consistently scenario-suffixed across all docs: - `demo.v2.session.lastSeed.<scenarioId>` - `demo.v2.config.committed.<scenarioId>` Aligns with spec P5-FR-5 (per-scenario isolation) and the second-scenario plan's slice 5.4 contract. - P2 (design.md DDD lint table): `views/**` row now also forbids `agentonomous` imports, matching the DDD prose that treats both views and components as presentation-only. - P2 (spec.md P5-AC-4): Replaced the subjective "presenter can articulate ... in <=20s" criterion with an observable check covering URL <-> persisted activeId <-> shell header agreement within 1 tick of a scenario swap, plus an ARIA-labelled scenario heading so the swap is observable to assistive tech. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Owner
Author
|
@codex review Re-review request — addressed all 4 findings from the previous round in commit dfa665f:
Please reconfirm or surface any remaining issues. |
|
Codex Review: Didn't find any major issues. Swish! ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
If Codex has suggestions, it will comment; otherwise it will react with 👍. Codex can also answer questions or update the PR. Try commenting "@codex address that feedback". |
Luis85
pushed a commit
that referenced
this pull request
Apr 26, 2026
Restructures the plan from one monolithic 1388-line file under one big PR into an umbrella-tracker pattern matching PR #129: - The original docs/plans/2026-04-26-quality-automation-routines.md is now the umbrella tracker (~268 lines): role, goals, coordination with PR #129, tracker table, downstream-PR contract, shared resolve_action_sha helper, risk register, archive policy. No implementation steps live in this file anymore. - Eight new self-contained chunk plans under docs/plans/: 2026-04-26-quality-codeql.md (~158 lines, row 1) 2026-04-26-quality-dep-triage-bot.md (~141 lines, row 2) 2026-04-26-quality-actions-bump-bot.md (~100 lines, row 3) 2026-04-26-quality-plan-recon-bot.md (~108 lines, row 4) 2026-04-26-quality-bundle-trend.md (~230 lines, row 5) 2026-04-26-quality-determinism-replay.md (~252 lines, row 6) 2026-04-26-quality-mutation-testing.md (~175 lines, row 7) 2026-04-26-quality-demo-smoke.md (~263 lines, row 8) Each chunk plan stands alone: Files block, full step list with bite-sized TDD where applicable, acceptance criteria, and a per-chunk Tracks: #130 + tracker-row-tick contract. Why split now: - Reviewer cost. After three Codex passes the monolithic plan had grown past 1390 lines and review latency was dominating the iteration loop. - Parallelism. Eight chunk plans can be picked up by eight independent agents/sessions concurrently from origin/develop, all ticking back into the same umbrella tracker. - Bounded blast radius. Each row's downstream PR is small enough to Codex-review fast, revert cleanly if needed, and ship without blocking the others. Downstream PR contract codified in the umbrella section 'Downstream PR contract': branch off develop (NOT off this tracker branch), include 'Tracks: #130' body line, tick the tracker row in the same diff (no follow-up tracker-update PRs), pass npm run verify, pin every new GHA uses: ref via the umbrella's resolve_action_sha helper, no changeset (tooling-only). The PR #129 demo-rename coordination is preserved in both the umbrella plan AND the demo-smoke chunk's own coordination section. Shared resolve_action_sha helper lives once in the umbrella; chunks link to it instead of duplicating. This commit is plan-restructure only — no library, workflow, or script code is added by it. Each downstream chunk PR delivers its own implementation.
This was referenced Apr 26, 2026
Owner
Author
|
Tracker continues at issue #132. This PR has done its job — landing the planning doc + design doc + spec + 6 plans. After this merges, ongoing tracking (downstream PR tasklist, status table) lives at #132. Future downstream PRs should reference Doc references back to PR #129 in the landed files remain accurate as historical pointers to where the doc set originated. |
Luis85
pushed a commit
that referenced
this pull request
Apr 26, 2026
Adds a long-lived GitHub Issue (#131) as the durable tracker that survives PR merges. PR #130 ships the plan files; the issue tracks every downstream chunk PR via auto-flipping task list and stays open until the plans are archived to docs/archive/plans/. Changes: - Umbrella plan header gains a 'Durable tracker' callout linking Issue #131 with the close-when criteria. - Umbrella's downstream-PR contract section now requires BOTH body lines on chunk PRs: Tracks: #130 (planning PR — supplies the chunk plan) Tracks: #131 (durable issue tracker — auto-ticks on merge) - All 8 chunk plan headers updated to cite both #130 (umbrella plan) and #131 (durable issue tracker). - All 8 chunks' embedded 'gh pr create --body ...' blocks now emit both Tracks lines so worker agents inherit the contract verbatim. The Issue itself was created via gh issue create. It captures: - Origin (the 2026-04-26 'are there more things we can or should automate' question). - Resulting plan layout (umbrella + 8 chunks). - Auto-flipping task list mirroring the umbrella tracker table. - Same coordination with #129 + same risk register summary. - Closes-when criteria: every chunk PR merged + plans archived. PR #130 body also rewritten to point at #131 and explain the PR-vs-issue split (PR is the planning surface and closes; issue is the durable surface and survives). Plan-only commit. No code, no workflow, no script changes.
7 tasks
Luis85
added a commit
that referenced
this pull request
Apr 26, 2026
…/product-demo (#134) ## Summary Wave-0 of the pre-v1 demo evolution increment. Atomic delivery slice: rename + scripts + workflow + ESLint rules + doc sweep + Playwright skeleton + legacy-key purge — all in one diff, splitting forbidden by the plan's own *atomic delivery slice* rule. Gates every downstream pillar PR. - Renames `examples/nurture-pet/` → `examples/product-demo/` (history preserved via `git mv`). - Wires `npm run e2e` (root + demo workspace) so all later pillar PRs can rely on it. - Encodes the design's DDD forbidden-import + determinism rules in a demo-scoped `examples/product-demo/eslint.config.js`; new `lint:demo` step is part of `npm run verify`. Existing nurture-pet baseline stays exempt until pillar 5.2 refactors it. - Sweeps every `examples/nurture-pet` reference outside `.worktrees/` and `docs/archive/`; archives the now-shipped rename plan. - Fixes tracker references in plan / spec / design / six pillar plans (issue #132 supersedes the originating PR #129). - Updates issue #132 body context — see follow-up comment on this PR for the tasklist row. - New `examples/product-demo/src/app/main.ts` runs the legacy `nurture-pet.*` + un-prefixed `demo.*` localStorage purge on first load (spec STO-3) before handing off to the existing baseline. ## Verification - `npm run verify` — green (format / lint / lint:demo / typecheck / 523 tests / build / docs). - `npm run e2e` — exits 0 against placeholder spec. - `npm run demo:build` — succeeds; artefacts at `examples/product-demo/dist`. - `git grep "examples/nurture-pet" -- ':(exclude).worktrees/**' ':(exclude)docs/archive/**'` — zero matches (R-AC-3 met). - Pages workflow's resolved artefact path is `examples/product-demo/dist` (R-FR-7). ## Out of scope - Pillar implementation (layered subpaths under `examples/product-demo/src/{components,views,demo-domain,stores}/` stay empty; pillar PRs add files there). - Updating `examples/nurture-pet` references inside `docs/archive/**` or `.worktrees/**` (excluded from the verification grep per the plan). - Changeset — docs / scripts / workflow change with no library-behaviour change. ## Test plan - [x] `npm run verify` green - [x] `npm run e2e` exits 0 - [x] `npm run demo:build` succeeds; `dist/` resolves at `examples/product-demo/dist` - [x] `git grep "examples/nurture-pet"` returns zero outside the excluded paths - [x] Pages workflow `path:` field resolves to `examples/product-demo/dist` - [ ] Codex review pass (pending) - [ ] CI green on `develop`-targeted PR Tracks: #132 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Luis Mendez <hallo@luis-mendez.de> Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Luis85
added a commit
that referenced
this pull request
Apr 26, 2026
…h sweep (#138) Tracks: #131 ## What changed The dep-triage-bot prompt landed in #136 with a rolling-tracker pattern (`Dependency triage — develop`, append-comment-per-run, `Last triaged SHAs` mapping in the body). The daily code-review bot has since refactored to issue-per-run (#135) — this PR brings dep-triage-bot in line, and promotes the convention to the umbrella so every future cloud routine inherits it. ### Convention applied - **Dedicated GitHub label per routine.** No shared `automation` umbrella label. - **Issue per run.** Body holds the run's full punch list. Owner closes manually once everything in the body is resolved. - **Quiet runs leave no trace.** No-op runs do NOT open an issue. - **Per-object state on the artifact, not on a shared tracker.** For dep-triage that means an HTML comment marker `<!-- dep-triaged:<head-sha7>:<action> -->` on the Dependabot PR itself, read at the start of the next run for skip detection. ### Files - `docs/dep-triage-bot/PROMPT.md` — replaced rolling-tracker output, idempotency, and process-gate sections with issue-per-run + per-PR-comment-marker. Hard-rules + dry-run + failure-handling sections updated to match. - `docs/dep-triage-bot/README.md` — output sink description, setup checklist, tradeoffs, and a new "Bot label convention" table mapping each routine to its label. - `docs/plans/2026-04-26-quality-automation-routines.md` (umbrella) — added a new "Cloud-routine output convention" subsection under "Downstream PR contract" so rows 3+ inherit the rule. Updated row 3 + row 4 chunk plans inline so their PRs follow it: no-op leaves no trace, only failures open a labelled per-run issue. - `docs/plans/2026-04-26-quality-actions-bump-bot.md` — output / failure-handling sections rewritten to the new convention. - `docs/plans/2026-04-26-quality-plan-recon-bot.md` — same. ### Demo-path sweep (Wave 0 of #129 / merged as #134) The Wave-0 rename of `examples/nurture-pet/` → `examples/product-demo/` merged on 2026-04-26 (commit `c734d6a`). This PR sweeps the lingering `examples/nurture-pet/` references in the active quality plans + the dep-triage-bot prompt so the chunk plans + cloud routine all point at the post-rename path: - `docs/dep-triage-bot/PROMPT.md` — three references swapped; the now-stale Wave-0 sequencing conditional dropped. - `docs/plans/2026-04-26-quality-automation-routines.md` — "Coordination with PR #129" section condensed to a `RESOLVED` stub linking to #134; risk-register row updated. - `docs/plans/2026-04-26-quality-dep-triage-bot.md` — example-shape comment swapped. - `docs/plans/2026-04-26-quality-demo-smoke.md` — every path swapped; the "Step 0: Decide demo path" pre-flight + the "Rename-coordination follow-up" footer collapsed to a one-paragraph `RESOLVED` stub. Other lingering `nurture-pet` references live in archived plans, code JSDoc, and one test file — those are out of scope for this PR (separate cleanup-sweep follow-up if the owner wants the codebase fully aligned). ### Labels created in repo ``` gh label create dep-triage-bot --color FBCA04 --description "Per-run findings from the weekly dep-triage cloud routine" gh label create actions-bump-bot --color D93F0B --description "Failure issues from the weekly actions-bump cloud routine" gh label create plan-recon-bot --color 1D76DB --description "Failure issues from the monthly plan-recon cloud routine" ``` `review-bot` and `docs-review` were already in place. ## Verification - `npm run verify` — green locally. - Doc-only diff (no `src/**`, no changeset). - No `dep-triage-bot` issues exist yet, so there is no rolling-tracker issue to retire — this lands the convention for the routine's first real run. --------- Co-authored-by: Luis Mendez <hallo@luis-mendez.de>
Luis85
added
the
roadmap:v1-demo
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Role — umbrella tracker for the pre-v1 demo evolution increment
This PR is the umbrella tracker for the pre-v1 demo evolution increment. It stays docs-only for the duration of the increment — implementation lives in downstream PRs cut from
develop.Documents in this PR
docs/product/2026-04-26-pre-v1-demo-evolution-plan.md— the what + why (baseline, scope, pillars, sequencing, milestones, tracker table).docs/specs/2026-04-26-pre-v1-demo-evolution-design.md— the cross-cutting how (Vue/Pinia/Router architecture, DDD layering, cross-pillar contracts, determinism fingerprint design, persistence contract).docs/specs/2026-04-26-pre-v1-demo-evolution-spec.md— per-pillar testable requirements (FRs, data shapes, acceptance criteria, NFRs).docs/plans/2026-04-26-pre-v1-demo-*.md:Downstream PR contract
Every PR cut from these plans must:
Tracks: #129,Downstream PRs (auto-flips on merge)
Add
- [ ] #NNN — short descriptionrows here as downstream PRs are opened.Original motivation (planning-doc PR description)
Motivation
Description
docs/product/2026-04-26-pre-v1-demo-evolution-plan.mdcapturing baseline capabilities, increment thesis, scope, and explicit product demo direction.agentonomouslayers and presentational code in Vue components usingPiniaandVue Router.examples/nurture-pettoexamples/product-demowith required repository updates (scripts, docs, GitHub Pages workflow, tests) and acceptance criteria fornpm run demo:dev/demo:buildand Pages publishing.Testing
npm run verifyand verifying the Pages workflow and demo build during the implementation slices.Codex Task