mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-28 12:04:41 +01:00
572bef4ba7679451ac1543db25cb8ebd533bf919
8
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
 Devin FoleyandPaperclip
|
a2d26a83fe |
fix(inbox): keep automatic work out of Mine by default
Keep channel and routine attribution out of Mine unless the person participates directly, is assigned the task, or receives a current addressed request. Apply the same source rules to unread state, archives, and task notifications. Preserve direct comments and current human action requests. Restore the two expressions damaged by redaction during the earlier master merge. Co-Authored-By: Paperclip <noreply@paperclip.ing> |
||
|
DottaandPaperclip
|
3bbc2104b6 |
docs: map missing product and operator capabilities (#16990)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - The feature map records product entry points and verification recipes. > - The paired agent access map records APIs and permission boundaries for the same capability IDs. > - The new index in #16987 made several missing capabilities easier to find. > - Those gaps hid existing assistant, privacy, cost, and operator workflows. > - This pull request adds 15 capabilities with source references, test scope, and manual checks. > - Readers can find these workflows without treating documentation or structural checks as live proof. ## Linked Issues or Issue Description Refs: #16987. Related map work: #16025 and #16214. A search of related pull requests found no duplicate of these additions. **Issue type** Missing documentation. **Where is the issue?** `maps/feature-map/` and `maps/agent-access-map/`. **What's wrong?** The maps omit public assistant MCP connections, private task and project sharing, subscription fees, cost-recording recovery, agent API keys, keyboard entry points, and several operator CLI workflows. **Suggested fix** Add product recipes and matching access records. Show the full capability IDs in the README index and each page. Keep the existing ID format and all 175 existing IDs. Exclude AI account pools. ## What Changed - Add the `assistant-connections` family with setup, consent, device login, client use, and revocation. - Add `tasks/privacy`, `projects/privacy`, `budgets-costs/subscriptions`, and `budgets-costs/accounting-recovery`. - Add `agents/api-keys`, `agents/managed-agent-setup`, and `navigation-preferences/command-palette`. - Add `cli-operations/feedback-export`, `chat-channels/outbound-email`, and `instance-operations/runtime-setup`. - Pair all 15 additions with access rules, source evidence, manual checks, and explicit coverage gaps. Update the visible index to 35 families and 190 capability IDs. - Add cross-links from existing access, connection setup, search, and CLI recipes. Do not change the schema or add AI account pools. - Clarify that the task Share sheet displays direct and inherited access. Manage inherited access at its ancestor or project source. ## Verification - `node scripts/check-maps.mjs` passes: 35 areas and 190 paired capability IDs, with valid references and contract fields. - `node --test scripts/check-maps.test.mjs scripts/storybook-feature-index.test.mjs` passes: 17 tests. - `node scripts/storybook-feature-index.mjs` and `git diff --check` pass. - A comparison with the base confirms all 175 existing IDs remain and exactly the intended 15 IDs were added. The README index matches the discovered feature metadata. - `node scripts/storybook-catalog.mjs` cannot run because this checkout lacks `storybook/internal/csf-tools` and installed workspace dependencies. - `pnpm -r typecheck`, `pnpm test:run`, and `pnpm build` were attempted. All stopped before their task ran: the pnpm 9.15.4 bootstrap could not fetch and verify its registry packages in this environment. - Source review covers the documented UI, CLI, routes, services, and existing tests. No live browser, provider, or authorization journey was run. New access records remain `baseline`, `source-only`, and `not-run`. - Greptile and the Paperclip reviewer both rate current commit `bb8eb797b0a1dc26256faf2f0e57cbe7abc9adcf` 5/5. The inherited-access review thread is resolved. - [GitHub CI](https://github.com/paperclipai/paperclip/actions/runs/39466772379) passes for that commit, including typecheck, build, unit tests, Runner checks, and browser tests. Browser shard 7 passed after one retry for a runner shutdown. All PR checks are successful, neutral, or skipped. ## Risks - Low runtime risk: this change only edits maps. No application behavior, API, dependency, or schema changes. - Source-reviewed recipes can drift or miss deployment-specific behavior. The records state their limits and require live checks before a capability is marked verified. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - OpenAI Codex, model ID `gpt-6.1-sol`, 475,000-token context window, xhigh reasoning effort, with tool use and code execution. ## 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 - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing> |
||
|
DottaandPaperclip
|
9ef434fe79 |
docs: expose feature map IDs and add a recipe index (#16987)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Its feature map describes user journeys and their verification paths. > - The map already defines feature IDs and full capability IDs. > - The README and child pages did not show those IDs consistently. > - Readers need those IDs to connect issues, tests, stories, and evidence. > - This pull request adds a recipe index and displays the existing IDs. > - The benefit is clear references across the product and agent access maps. ## Linked Issues or Issue Description **Issue type** Missing documentation. **Where is the issue?** `maps/feature-map/README.md`, the child recipes, and their agent access companions. **What's wrong?** The README sends readers to Storybook to browse features. Child pages show local keys, such as `installation`, without the full `plugins/installation` ID. Readers must inspect the generator to find the full reference. **Suggested fix** List recipe links and existing IDs in the README. Show each feature ID and full capability ID in its child pages. Explain capability IDs and entry-point references. Keep the current keys and anchors. Related work: Refs #15288. Refs #16052. Refs #15983. No duplicate open PR or issue was found by title search. ## What Changed - Add an index grouped by feature area. It lists every recipe, feature ID, and full capability ID. - Explain how IDs are formed and used in issues, tests, Storybook, and evidence. - Add feature IDs to all product recipes and agent access companions. - Show full capability IDs beside recipe keys and below access and Storybook guidance headings. - Preserve existing keys, heading anchors, and generated ID values. Keep the latest upstream company capability in the index. ## Verification - `node scripts/check-maps.mjs` passes for 34 feature families and 175 capability IDs. - `node --test scripts/check-maps.test.mjs scripts/storybook-feature-index.test.mjs` passes all 17 tests. - `node scripts/storybook-feature-index.mjs` passes on this checkout and generates the feature indexes and overview inputs. - `git diff --check` passes. - A source comparison confirms that the README matches the recipe index. After removal of the added ID labels, all 68 child pages match the upstream prose and headings. - Full workspace checks were attempted: `pnpm -r typecheck`, `pnpm test:run`, and `pnpm build`. They could not start because the local pnpm wrapper could not fetch and verify the pinned pnpm 9.15.4 release. This checkout also has no workspace dependencies installed. - `node scripts/storybook-catalog.mjs` could not run because `storybook/internal/csf-tools` is not installed. The direct map and index checks above pass without that dependency. - Remote typecheck, release-registry, and full build checks passed. The first attempts of [server shard 3/12](https://github.com/paperclipai/paperclip/actions/runs/39460473910/job/118758430448) and [server shard 12/12](https://github.com/paperclipai/paperclip/actions/runs/39460473910/job/118758429932) stopped after their runners received a shutdown signal. The test steps were canceled. GitHub rejects the rerun request with HTTP 403: "The workflow run containing this job is already running". Five other CI jobs remain active. The next action is to rerun the two interrupted shards after workflow 39460473910 ends. No application changes were made to address these runner interruptions. - To inspect the result, open the feature-map README, follow a recipe link, and compare its full capability IDs with its access companion. ## Risks - Low risk. The change updates map documentation only. It changes no application code or ID schema. - The readable README index and child labels repeat source IDs. Keep them aligned when a capability changes. - Generated capability descriptions now include the visible ID prefix. Generated IDs, labels, navigation order, and verification fields remain the same. - Full local workspace checks and catalog generation remain unverified for the environment reasons above. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used OpenAI Codex, model `gpt-6.1-sol`, with a 475,000-token context window and `xhigh` reasoning effort. The model used local file tools, shell commands, and GitHub CLI access. ## 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 - [ ] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge Co-authored-by: Paperclip <noreply@paperclip.ing> |
||
|
DottaandPaperclip
|
433d94ee0b |
refactor(maps): generate indexes from local story and feature metadata (#16214)
## 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> |
||
|
DottaandPaperclip
|
be380ba155 |
fix(ui): hide agent-created tasks by default (#16157)
Hide agent-created, system-created, and chat-channel tasks from independent collections by default. Preserve task hierarchy context and existing inbox participation. Add a saved opt-in checkbox without helper text. Co-Authored-By: Paperclip <noreply@paperclip.ing> |
||
|
DottaandPaperclip
|
aded4197e5 |
fix: make multiplayer task toasts personal (#16153)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - A company can have several human users and shared agents. > - Live task events currently produce toasts for any user who can read the task. > - This makes unrelated work interrupt other users. > - This pull request checks each user's task participation before it permits a toast. > - Users receive relevant task notifications while company views continue to refresh. ## Linked Issues or Issue Description **What happened?** Company task activity and agent failures produce noisy toasts for users who have no involvement in the task. **Expected behavior** A task qualifies when the viewer created it, commented on it, is its assigned user, deliberately acted on it under the Mine rules, or has an explicit user mention in its description or a non-deleted comment. Viewing, agent ownership, responsible-user attribution, and parent participation alone do not qualify. **Steps to reproduce** 1. Sign in as two users in the same company. 2. Have the second user create and update a task that does not involve the first user. 3. Observe a task toast in the first user's company view before this fix. The duplicate PR search found no existing change for personal task-toast eligibility. ## What Changed - Extract the existing Mine participation predicate without changing Mine behavior. - Compute task eligibility from stored tasks, comments, and run associations after WebSocket access checks. Use an exact indexed comment-mention lookup with `LIMIT 1`. - Add optional `toastEligible` metadata to each viewer's event copy. Keep it off the shared event bus. - Require eligibility for live task activity and task-linked run errors. Suppress generic agent errors. - Continue cache updates for quiet events. Refetch visible comments when authenticated events omit hydration details. Ignore stale socket callbacks after account or company changes. - Document toast semantics and add feature-map and agent-access-map coverage. - Add persisted-data, socket, UI, and authenticated browser regression coverage. ## Verification - Final commit: `1dc4f9402c5883744738cfe236ad00fa0bb5ca4c`. - All 55 current-head checks passed. Two Storybook checks were skipped because this change does not affect that coverage. - Greptile approved this exact commit with 5/5. The security scan passed. Both review threads are resolved. - Local `pnpm build`, `pnpm -r typecheck`, `pnpm check:token-gates`, and `node scripts/check-maps.mjs` passed. - The focused socket/UI suite passed 123 tests. The persisted eligibility suite passed 9 tests, including long history, exact viewer matching, and regex escaping. The existing Mine service suite previously passed 140 tests. - The named browser case `task toasts follow personal involvement in multiplayer` passed against the final commit in an isolated authenticated instance. It used two real sessions, real WebSocket delivery, and persisted tasks, edits, comments, and mentions. It verified quiet unrelated activity, viewing alone, first and historical mentions, own-action suppression, visible-task suppression, and live cache refresh. - A prior-head server shard passed its single rerun after a fixture-cleanup deadlock. The final-head CI run passed without a rerun. - The broad local run remained in progress when CI completed the full test suite. Local focused checks and CI provide the completed test evidence. ## Risks - This intentionally reduces live notifications. A new client stays quiet against an older server that omits eligibility. - Eligibility queries add work to live event delivery. A lookup failure suppresses the toast and still delivers the authorized event. - Deleted mentions cease to qualify unless another participation rule applies. Historical comment authorship retains the existing Mine behavior. - No database migration or notification-settings change is required. ## Model Used OpenAI Codex with GPT-6 assisted with implementation, tests, documentation, and PR preparation. It used repository tools, shell commands, and browser automation. The runtime did not expose an exact backend revision or context-window size. ## 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 - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge Co-Authored-By: Paperclip <noreply@paperclip.ing> |
||
|
|
83e13db8fa |
fix(inbox): keep automatic recovery cleanup out of personal participation (#16063)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - The personal inbox uses issue activity to identify a person's participation. > - Issue reads can cancel stale recovery actions and record that cleanup as the reader's action. > - This adds unrelated tasks to the inbox and refreshes their activity timestamps. > - A workspace owner hold can also alternate between creation and cancellation after a task finishes. > - This pull request corrects cleanup attribution, excludes historical read cleanup, and retains one exact owner hold. > - Agents can read authorized issue activity to diagnose the same problem themselves. ## Linked Issues or Issue Description Refs #15742 excludes logs by the execution-recovery actor from activity timestamps. This PR covers reader-attributed stale recovery cleanup, personal inbox participation, exact workspace owner holds, and sandbox issue activity access. I searched open issues and PRs for recovery inbox and activity bridge fixes. I found no duplicate for this defect. **What happened?** Loading issue lists cancels stale recovery actions under the reader's identity. The personal inbox treats those rows as user participation. One completed issue had hundreds of such rows and no edits or comments by the affected reader. A retained native workspace owner repeatedly creates a verification action that read projections then cancel. Sandbox agents cannot inspect the issue activity because the reverse bridge rejects the route. **Expected behavior** Automatic cleanup belongs to the system and does not add an issue to a reader's inbox. Historical cleanup rows remain auditable but do not count as participation or recent activity. An unresolved physical workspace owner keeps one stable verification action. Agents can inspect activity only for issues their identity may read. **Steps to reproduce** 1. Finish a task whose native run retains an unverifiable workspace owner receipt. 2. Repeat workspace recovery checks and GET requests for issue detail, compact lists, and recovery actions. 3. Observe new recovery action IDs and reader-attributed cancellations in the activity history. 4. Query the personal inbox for that reader and observe the unrelated task. 5. From a sandbox agent, request GET /api/issues/:id/activity and observe Route not allowed. **Paperclip version or commit** Observed at |
||
|
DottaandPaperclip
|
7d9b93aee2 |
docs: establish paired feature and agent access maps (#16025)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Contributors use the feature map to understand and verify product capabilities. > - Agents need APIs and usable entry points within their permission boundaries. > - Product recipes and agent access need separate records with shared capability IDs. > - This pull request establishes that contract and gives maintenance ownership of both maps. > - The benefit is repeatable access review without changing product behavior or permissions. ## Linked Issues or Issue Description Refs: #15983, which added the portable verification skills and updated the feature map. This is its contract-only follow-up. Related: #15288 added the original feature map. **Issue type** Missing documentation and maintenance contract. **Where is the issue?** The product map, its missing agent access companions, and the verification skills. **What's wrong?** There is no shared convention for API presence, agent entry points, permission boundaries, access gaps, or evidence. An API declaration does not prove that a permitted native or remote agent can use it. **Suggested fix** Keep the product and agent access maps as siblings under `maps/`. Reuse capability IDs. Record representative source inventory separately from operation review and live proof. Keep both maps aligned through the maintenance skill. ## What Changed - Move the existing product map to `maps/feature-map/`. Preserve its recipes and Poteto format. Update relative links and add companion links. - Add `maps/agent-access-map/` with 35 area files and 171 matching capability IDs. Seed representative API operations, agent paths, policies and known gaps from the reviewed source inventory. Mark entries as `baseline`, `source-only`, and live verification `not-run`. - Define the shared contract in `maps/README.md`. Track API presence, agent availability, policy, evidence and review depth separately. Require operation enumeration before marking a broad capability operation-reviewed. - Extend `maintain-verification-skill` to reconcile both maps and inspect actual route policy and production tool admission. Update creation, verification, notices and contributor references to use the shared contract. - Add `scripts/check-maps.mjs` and ten regression tests. Check matching areas/IDs, indexes, references, contract fields, API method/path examples, justified exceptions and evidence-state consistency. - Keep the coverage inventory unchanged. Preserve skill invocation policies and both MIT license blocks. No product API, permission, UI, runtime helper, migration, dependency or workflow changes. ## Verification - Passed: `node scripts/check-maps.mjs` reports 35 paired areas and 171 matching capability IDs. All local map references resolve. - Passed: `node --test scripts/check-maps.test.mjs` runs ten tests. Fixtures cover missing companions, renamed/orphan/duplicate IDs, broken references, missing operation fields, empty exceptions, missing API examples, empty policy fields, and verified evidence without passed verification. - Passed: metadata validation for all three verification skills. Skill and contributor links resolve. Invocation policies and both license blocks are unchanged. - Compared relocated recipes with current master. Contents differ only in relative links and companion links. `coverage.json` is byte-for-byte unchanged. Master's updated read-only interaction test reference is retained. - Passed: `git diff --check`. The branch starts from current master and contains only this contract change. - Repository-wide typecheck, tests and build were not run locally for this documentation and Node structural-check scope. Live agent access was not exercised. Those gaps are explicit in the baseline entries; the structural check does not certify behavior. CI and automated review are pending. ## Risks - The companions are representative source baselines. They are not complete operation inventories or passed agent journeys. - The checker cannot establish actual permissions, native tool admission, operation completeness or truthful live evidence. Maintenance must inspect source and verify with the actual permitted agent context. - External links to the old product-map directory may need updates. Repository references have been updated. - Existing access gaps and board/user restrictions remain recorded. This contract does not change authority or implement missing paths. ## Model Used OpenAI GPT-6 through Codex assisted with this change. The session does not expose the exact serving model ID, configured context-window size, or reasoning setting. Capabilities used: source analysis, file edits, shell commands, and structural regression tests. ## 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 - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge Co-authored-by: Paperclip <noreply@paperclip.ing> |