DottaandPaperclip
433d94ee0b
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Feature recipes and Storybook help contributors find behavior, examples, and verification steps. > - Independent feature changes currently update shared catalogs, indexes, and review hashes. > - Those shared files cause merge conflicts and repeated bookkeeping during parallel work. > - This pull request stores metadata in each feature recipe and story, then generates the combined views. > - Contributors can merge independent work without editing a common index. Git and PR evidence retain change and review history. ## Linked Issues or Issue Description **What existing behavior does this improve?** Maintaining the product, agent-access, and Storybook maps while multiple agents change different features. **Current behavior** A story or recipe change can update `catalog.json`, `INDEX.md`, review hashes, verification tables, and tracked generated navigation. Two unrelated changes then conflict in the same files. **Proposed behavior** Each story declares capability links and classification in `parameters.paperclip`. Each feature recipe declares its navigation and optional verification guidance. Startup, build, and UI typechecking discover these sources and generate ignored indexes and Storybook pages. **Reason and benefit** A routine change edits its own source files. Aggregate metadata is rebuilt from the merged checkout. There is no sidecar registry, shared review journal, or hash acknowledgment to maintain. **Breaking changes** The tracked Storybook catalog and index paths are retired. Consumers use `ui/storybook/generated/` or `maps/generated/` after generation. Contributor instructions and the existing feature-gap browser suite use the new paths. Story and overview IDs remain stable. ## What Changed - Move the existing annotations into 262 story files. Preserve classifications, capability associations, exports, and explicit IDs. - Discover all 35 feature recipes. Store section/order beside each recipe and move durable verification routes out of the shared table. - Remove tracked catalogs, inventories, overview pages, and inline preview ordering. Keep authored preview behavior in `preview-base.tsx`. - Generate the Storybook guide, feature/access Markdown indexes, gap report, page-reference inventory, and preview wrapper automatically. - Update the map contracts and maintenance skills to use Git history and revision-specific PR/CI evidence. - Add schema, identity, regeneration, and actual Git merge tests. Run these through the existing UI Vitest suite. Add focused browser navigation checks. This is one coordinated migration. Most of the 367 changed files contain only moved metadata or deleted generated content. Review the generator scripts, map contracts, Storybook configuration, and tests first. No product API or authorization behavior changes. ## Verification Passed: - `node scripts/check-maps.mjs`: 35 paired areas and 175 capabilities. - `node scripts/storybook-catalog.mjs --check`: 262 suites and 2,485 authored stories after incorporating current master. - `node --test scripts/check-maps.test.mjs scripts/storybook-catalog.test.mjs scripts/storybook-feature-index.test.mjs`: 28 tests, including independent branches merged in both orders with identical generated output and no tracked changes. - `pnpm --filter @paperclipai/ui exec vitest run storybook/map-tooling.test.ts`: the CI entrypoint runs those map tests. - `pnpm check:token-gates`. - `pnpm -r typecheck` and `pnpm build` before the final master rebase. - `pnpm build-storybook`: all 2,517 original story/docs URLs retained. Current master contributes exactly four additional recovery stories. - Focused Playwright navigation checks: search and open a feature without examples; expand verification guidance and check source links; retain capability order and follow a related Foundations suite. The final clean Storybook build passed after deleting every ignored map output. Post-rebase UI typechecking and both browser tests passed. The working tree stays clean after generation. The concurrent-cleanup regression fails with `ENOENT` without the fix and passes with it. All GitHub CI gates passed on `00fc7ec18e`, which also received Greptile 5/5 with no unresolved findings. The final merge commit `1c3c5143a6` incorporates master and resolves only the two modify/delete conflicts by retaining removal of the aggregate index and catalog. Master’s new workspace feature and access guidance is preserved. Map validation, catalog generation, overview generation, all 28 map tests, and diff checks pass after conflict resolution. The maintainer explicitly requested merging without another Greptile review. CI has not been rerun to completion on this merge commit. The local repository-wide `pnpm test:run` was stopped before completion after the earlier CI matrix passed; it is not reported as a local pass. No screenshot baselines or production acceptance are claimed. To repeat the browser check against an owned Storybook server: ```sh PAPERCLIP_GAP_STORYBOOK_URL=http://127.0.0.1:6136 pnpm exec playwright test --config tests/storybook-visual/feature-gap-stories.config.ts map-navigation.spec.ts ``` ## Risks - Existing branches need a one-time rebase to move their catalog changes into local annotations. The PR incorporates the recovery changes from current master. - Changing the same story or capability can still produce a meaningful conflict. This removes the shared aggregate bottleneck. - The generator uses Storybook's existing CSF parser. Literal-only annotations and parser regression tests protect the current contract. - Generated Markdown is available after running the generator; the published Storybook provides a browsable guide. - Shared source changes still require review. Removing hashes removes mechanical acknowledgments; it does not establish runtime parity. ## Model Used OpenAI Codex, based on GPT-6, with repository inspection, code execution, and browser-test tools. The exact deployment model ID and context window were not exposed in this session. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] All Paperclip CI gates are green on the previously reviewed head `00fc7ec18e`; final conflict-resolution checks are documented above - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups on `00fc7ec18e`; another review was waived by the maintainer - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>
5.3 KiB
Storybook map
Browse the published feature guide,
or run pnpm storybook for the current checkout. The feature and capability IDs
come from the feature recipes. Product behavior and
permissions remain governed by the implementation spec and access companions.
Authored sources
Each story owns its small parameters.paperclip annotation. There is no authored
central catalog, review ledger, date stamp, source list or fingerprint to update.
Storybook's CSF parser supplies filenames, titles, explicit meta IDs, exports,
play-function counts and story IDs without executing story modules.
const meta = {
id: "tasks-create",
title: "Tasks and conversations/Task creation and lifecycle/Create",
parameters: {
paperclip: {
capabilities: ["tasks/create"],
implementation: "production",
boundary: "fixtures",
notes: "Uses the shipped composer; submission is simulated.",
},
},
};
capabilities is an array of stable area/capability IDs. Its first entry is the
primary home; others cross-list the same suite. An empty array requires an
exception explaining the intentional scope. Shared foundations may use
home: "foundations" with an exception to keep their existing location and links.
The metadata must be literal; place it after any other parameter spreads.
| Field | Values and purpose |
|---|---|
status |
current, proposed, historical, mixed, unreviewed (default). Authored product alignment intent, not a live review certificate. |
implementation |
production, prototype, mixed, guide, unreviewed (default). What actually renders. |
boundary |
fixtures, fixture-server, static, unreviewed (default). What is simulated or requires an owned fixture. |
notes |
Optional durable scenario limits and rationale. Do not append a history of unrelated changes. |
replacement |
Optional repository-relative path of an existing replacement story. |
A production component can use fixtures. A prototype that imports production
primitives remains a prototype of its outer subject. Use unreviewed when intent
or parity is unclear. Preserve useful historical examples and their explanations.
Historical examples, proposals and guides do not remove missing-example gaps.
No annotation or story count proves permissions, persistence, provider behavior,
full recipe coverage or passing tests.
Navigation and outputs
Stories live in ui/storybook/stories/<primary-feature-area>/. Sidebar titles use
the recipe's section and H1 title, followed by the suite name. / in feature
labels becomes , in the sidebar. Preserve explicit CSF IDs across title/folder
changes. Compare the built index.json when changing navigation.
The generator discovers feature recipes and story annotations. It assembles:
ui/storybook/generated/catalog.jsonandfeature-index.json.- A generated Overview story per feature, retaining
feature-map-<area>--overview. ui/storybook/.storybook/preview.tsx, with the literal sidebar order required by Storybook and the authored decorators/fixtures frompreview-base.tsx.- Markdown feature, access, Storybook and verification indexes, plus the current
page inventory, under
maps/generated/.
All these outputs are ignored. Storybook start/build and UI typechecking generate from a fresh checkout. The published Storybook includes the guide and each feature's verification scope. After edits during a dev session, rerun the generator (restart Storybook after navigation changes). Obsolete generated Overview files are removed. Never edit generated outputs or commit them to resolve a merge conflict.
Checks and review
node scripts/check-maps.mjs
node scripts/storybook-catalog.mjs
node scripts/storybook-catalog.mjs --check
node --test scripts/check-maps.test.mjs scripts/storybook-catalog.test.mjs scripts/storybook-feature-index.test.mjs
--write is a compatibility alias for the default generation command. --check
validates authored inputs without requiring existing outputs or writing files.
Checks reject malformed annotations, unknown capabilities, duplicate IDs, broken
map references, missing companions and invalid navigation. CI runs the map tests
through the UI Vitest suite and validates/generates inputs during UI typechecking.
Use Git diffs to select changed stories, rendered subjects, fixtures, and recipes for review. A changed source is a review candidate, not an instruction to refresh metadata on every dependent example. Inspect actual imports and contracts; shared fixture changes can require broad review without broad acknowledgement edits. Keep revision-specific findings and executed evidence in the PR, issue or CI artifact. Move only durable limitations into the affected source annotation or recipe. Past review history remains available through Git.
maintain-storybook owns stories and their annotations; review-storybook exercises
them. Product/access maintenance owns the recipes, including optional capability
verification scope. Use the existing Storybook browser workflow.
Report source inspection, rendering, play assertions, visual comparison and
production acceptance separately. Do not publish new baselines to pass a map cleanup.