mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-23 17:33:51 +02:00
4413bb262fbe7df60d0df8c2de4463cbb5c6d4d7
7
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
 DottaandPaperclip
|
13a83dd68a |
docs: require sleep-aware background work in reviews (#17138)
## Thinking Path
> - Paperclip manages agents in instances that can be idle between
tasks.
> - Recurring empty database and network checks can keep idle instances
and databases awake.
> - Worker migrations already use events, transaction-aware signals, and
shared deadlines.
> - New features can still add idle scans unless contributors and code
reviewers share an explicit rule.
> - This PR makes that rule discoverable through the repository rule
loader and Greptile.
> - The rule applies to added or expanded behavior without requiring
unrelated legacy polling to be removed.
## Linked Issues or Issue Description
Refs #15625, #17000, #17094, #17106, and #17129.
**Current behavior**
The repository has module ownership and runtime dependency rules, but no
explicit review requirement against new idle polling. A new duty in a
heartbeat tick can undo the benefits of previous worker migrations.
**Proposed behavior**
Require events for changed state, transaction-aware signals for
database-produced work, and shared scheduling for real deadlines. Reject
recurring empty scans, including scans disguised as scheduler callbacks.
Review narrow polling exceptions against concrete obligations and sleep
impact.
**Reason and benefit**
Make sleep-aware design a default review expectation. Preserve delivery,
ambiguous-commit recovery, drain/resume, and external wake correctness
while preventing new permanent idle traffic. Existing unrelated polling
stays outside the requested change.
## What Changed
- Add rules/sleep-aware-background-work.mdc for server, database,
adapter, plugin, and runner background paths, including
server/src/index.ts.
- Require concrete triggers, pending-work predicates, quiet conditions,
actual deadlines, and lifecycle evidence.
- Describe narrow exceptions for active operations and external sources,
with required scope, stop conditions, and sleep limitations.
- Distinguish in-process scheduling from durable Cloud wake coverage.
- Register the matching scopes in .greptile/files.json and link the rule
from rules/README.md.
- Reuse the existing module-boundary rule for ownership instead of
duplicating provider policy.
## Verification
- Passed: JSON parsing, required rule metadata, exact parity between
frontmatter globs and Greptile scopes, and all repository links.
- Passed: 15 representative path matches, including server startup,
nested service workers, producer routes, tests, database signals,
adapters, plugins, and both runner source trees. UI, CLI, docs, and
workflow paths remain outside this rule's glob scope.
- Passed: git diff --check.
- Manually checked contrasting review cases: reject a new empty queue
interval; reject an always-rescheduled empty scan; allow an actual retry
deadline; allow a bounded active readiness probe with lifecycle cleanup;
leave untouched legacy loops alone; reject sleep approval based only on
an internal timer.
- No runtime code changed. Application builds and tests were not rerun
for this rules-only change. This validates rule structure and intended
interpretation, not future reviewer compliance or deployed sleep.
- Greptile: 5/5 on
|
||
|
DottaandPaperclip
|
14afc12124 |
docs: define module ownership and shared change review (#17087)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Coding agents extend connectors and shared control-plane services. > - Provider details can leak into shared services during these changes. > - Moving code into a new file does not explain why shared behavior must change. > - This pull request adds module ownership and shared-change review rules. > - The rules help agents justify the change before implementation and review. ## Linked Issues or Issue Description **Issue type** Missing documentation. **Where is the issue?** Repository architecture rules and the connector authoring playbook. **What's wrong?** Subsystem rules describe some ownership boundaries. The repository lacks a general rule for deciding which behavior belongs in a feature module, what shared contracts must change, and how to review the resulting scope. An integration can therefore add provider-specific logic to shared code or bundle large platform changes into one connector PR. **Suggested fix** Add a repository-wide rule and load it in Greptile. Apply the rule during connector planning and PR preparation. Keep provider protocol behavior with its owner. Require a reason for shared changes and checks through affected consumers. Related public context: [Notebook connector PR #16984](https://github.com/paperclipai/paperclip/pull/16984). This PR changes instructions only. ## What Changed - Add a concise module-boundary rule for ownership, narrow contracts, shared controls, delivery scope, and verification. - Register the rule as repository-wide Greptile context. - Add planning and PR review steps to the connector playbook. Keep tests and docs with their behavior. ## Verification - Passed rule frontmatter, Greptile registration, referenced-file, and playbook-link checks. - Passed `git diff --check origin/master...HEAD`. - Reviewed the rule against the relevant connector failure and allowed cases: small dispatch branches, one-consumer shared capabilities, and unrelated fixes. - Fresh Greptile and Paperclip reviews both scored commit `759572fe503e1b6dfa9527f53de6c326a2c3bff6` 5/5. No actionable findings or unresolved review threads remain. - Final current-commit GitHub checks: 55 successful, 1 neutral, and 2 skipped; no pending or failed checks. Both required `ci / verify` and `ci / e2e` gates passed. - Initial CI attempt: the build and runtime boot smoke test passed. The spot runner received a shutdown signal during the clean public npm install check, canceling that step and failing the build job. [Interrupted job log](https://github.com/paperclipai/paperclip/actions/runs/39601811838/job/119228042468). Retried failed jobs once. Attempt 2 passed the complete build, runtime boot, and clean-install verification. The initial runner interruption remains recorded here. - Full local application checks are unavailable: this checkout has no workspace dependencies, and `pnpm -r typecheck` stopped during pnpm bootstrap because registry fetches failed and the requested pnpm version could not be verified. Local application tests and build were not run. GitHub checks must pass before merge. ## Risks - The rule could cause unnecessary abstractions or extra PRs if applied mechanically. It permits small dispatch branches and useful capabilities with one consumer. It rejects arbitrary file counts and unrelated restructuring. - Prose and metadata checks do not prove that future agents will follow the rule. Hosted review receives it when this branch is reviewed. ## Model Used - OpenAI Codex: `gpt-6-astra` authored the guidance; `gpt-6.1-sol` prepared delivery. Both used reasoning, filesystem tools, and GitHub tooling. Context window size was not recorded in the available model settings. ## 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 (focused documentation and metadata validation; application checks unavailable as stated above) - [x] I have added or updated tests where applicable (no runtime change; targeted structural checks cover the changed instructions) - [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
|
13e5128164 |
docs: preserve runtime and verification lessons (#16379)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Its control plane shares execution capacity across requests and agent orchestration. > - A dependency can return a small value while doing slow or repeated work underneath. > - Tests can check that value while mocks hide the behavior that affects other work. > - A later passing retry can also leave an earlier material failure unexplained. > - This pull request records general rules for dependency work, verification, and acceptance. > - The benefit is a durable review habit that applies beyond the runner incident. ## Linked Issues or Issue Description Refs #15683. Refs #16335. The staging runner incident exposed a gap in how we establish the operational cost of a dependency call. The original platform check read a small field from a process report. The call could block shared execution, and value-focused mocks did not exercise that behavior. The fix replaced that probe with bounded asynchronous work. This proposal addresses the reasoning and evidence gap, without assigning blame or prescribing one API or timeout for future work. The acceptance guidance also preserves material failures after a retry passes. It does not assert that every earlier test failure had the same cause as this incident. Related proposal checked: #14275 covers release sign-off templates. This PR covers implementation assumptions and verification evidence. ## What Changed - Add a scoped rule for dependency work in server, adapter, and runner execution paths. Cover blocking, repetition, cost growth, cancellation, and the effect on unrelated work. - Require evidence that can disprove the consequential assumption introduced by a change. Identify behavior removed by mocks and exercise the relevant boundary. - Register the rule in the Greptile manifest with matching path scope. Existing `AGENTS.md` instructions route coding agents to matching rules. - Add failure preservation to the verification skill. Link it from the repository-wide PR review rule. Keep recovery and resolution distinct. - Include examples and exceptions so cosmetic edits and ordinary pure transformations do not acquire unnecessary test requirements. ## Verification - Passed `git diff --check` and the repository PR template and duplicate-search validators. - Passed a local Python structural check: manifest JSON parses; rule globs and Greptile scopes match; seven representative runtime paths match; five unrelated paths do not; the evidence link and heading resolve; existing agent and reviewer loading instructions are present. - Manually applied the rule to a network-filesystem configuration getter, a repeated remote permission check, and an already-loaded map lookup. The first two need evidence about their new dependency risk. The last does not require fault testing by default. - Attempted `pnpm -r typecheck`, `pnpm test:run`, and `pnpm build`. The installed pnpm launcher could not fetch registry data to verify the requested pnpm version. Using the cached project version reached typecheck, which failed because workspace dependencies are absent (`@types/node` missing). Tests and build remain unverified locally. - Greptile reviewed commit `e56d1ec70f3ebffe697b35cc637975b8d8198681` at 5/5 with no unresolved review threads. CI is still running. These structural checks establish instruction wiring, not future compliance by an agent or reviewer. ## Risks - The main risk is adding ceremony to low-risk edits. The rule limits requests to concrete risks introduced by changed behavior and explicitly exempts unrelated work. - Instructions depend on contributors and reviewers reading and applying them. This change adds no automated runtime regression gate. - No application behavior, schema, dependency, lockfile, or workflow changes. ## Model Used OpenAI Codex, GPT-6 family. The exact serving model ID, context window, and configured reasoning effort are not exposed in this session. Used reasoning, repository inspection, shell tools, and patch editing. ## 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 available in this session) - [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 - [ ] I have run tests locally and they pass - [x] I have added or updated tests where applicable (guidance-only change; structural validation described above) - [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> |
||
|
Nicky LeachandPaperclip
|
c4e80ccdc8 |
chore(db): prune obsolete migration snapshots and document retention (#16194)
## Thinking Path > - Paperclip uses versioned PostgreSQL migrations to preserve application data. > - Drizzle uses schema snapshots to generate future migrations. > - The database package already prunes snapshots to the five newest files. > - PR #15749 added three snapshots but left eight in the resulting tree. > - This PR removes the three excess files and documents the retention requirements. > - Coding agents and Greptile receive the same scoped rule for future migration changes. ## Linked Issues or Issue Description Refs #15749. Related: #16191 includes overlapping snapshot cleanup with its new migration. This PR isolates the existing excess and the repository rule; it has no dependency on that feature. **What happened?** The migration metadata directory contains snapshots 0331–0338. The existing pruning script retains only the newest five, but the older three were left in master. **Expected behavior** Keep snapshots 0334–0338. Commit snapshot pruning alongside additions and recheck the combined tree after rebases or merges. Preserve all SQL migrations and journal entries. **Steps to reproduce** At master commit |
||
|
DottaandPaperclip
|
9cb3e157b3 |
docs: keep routine product work in the harness (#16193)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - The runtime and server handle routine execution and recovery. > - Product flows can expose internal steps that the system can handle safely. > - Users then have to operate infrastructure to achieve their original goal. > - This pull request adds a short rule that assigns this work to the harness. > - The benefit is a calm product experience with useful details and real choices. ## Linked Issues or Issue Description **Issue type** Missing documentation. **Where is the issue?** `rules/` and the repository review configuration. **What's wrong?** The repository has no shared product rule for harness responsibility and useful user-facing detail. Recovery can become a user checklist even when the system knows the next safe step. Related implementation: #15824. **Suggested fix** Require the harness to perform routine work within its existing authority. Require visible controls and details to serve a real decision or useful outcome. Keep progress truthful and apply the rule to changed flows. ## What Changed - Add the short product rule in `rules/product-harness-responsibility.mdc`. - Register it as a repository-wide review rule in `.greptile/files.json`. - Link the rule from `rules/README.md`. ## Verification - `git diff --check origin/master...HEAD` passed. - Node assertions passed for rule frontmatter, unique reviewer registration, repository-wide scope, all registered file paths and the README link. - The diff contains only three rule/documentation files. No application behavior changes. Application typecheck, tests and build were not run for this documentation change. - Review the rule's scope and read its four product requirements and review criterion. All applicable CI checks passed on head `89803a6cd7`. Greptile gave 5/5 with no unresolved findings. ## Risks The rule affects future product design and review. It applies to changed flows and does not require unrelated redesigns. Existing permissions, approvals and runtime safeguards remain in force. No migration or deployment is required. ## Model Used OpenAI Codex, GPT-6, with repository inspection, tool use and code execution. The exact serving model ID and context-window size were not exposed in this session. The user edited and approved the final short rule. ## 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
|
e67db42dc9 |
docs: define heartbeat execution design principles (#16190)
## Thinking Path > - Paperclip coordinates AI agents and their work. > - Heartbeat controls when that work starts, who owns execution, and how it settles. > - The extracted modules need shared architectural guidance as they evolve. > - Rules should protect those boundaries without freezing the current implementation. > - This PR adds scoped heartbeat principles for contributors and reviewers. > - The rule helps future changes preserve execution authority and recoverable work. ## Linked Issues or Issue Description **Issue type** Missing documentation. **Where is the issue?** The heartbeat service has a module map but no scoped architectural rule under `rules/`. **What's wrong?** Changes span admission, execution, completion, and recovery. Reviewers need shared principles for authority, ownership, and settlement across these boundaries. **Suggested fix** Add a concise heartbeat rule, route contributors to it from `AGENTS.md`, and register the same scope for Greptile. Keep implementation details in the code and existing developer documentation. Related: #16172 established scoped repository rules. #15984 completed the latest heartbeat extraction. Searches found no duplicate heartbeat-guidelines PR. ## What Changed - Add `rules/heartbeat-execution-boundaries.mdc` with a folder guide, a concise map of existing module responsibilities, and six design principles. - Keep `heartbeat.ts` focused on coordination: extend an existing owner or extract cohesive modules when new behavior would substantially grow it, with tests and explicit contracts. - Cover current execution authority, explicit ownership, distinct completion obligations, recovery intent, durable state, and visible uncertainty. - Register matching paths in `.greptile/files.json` and link the rule from `AGENTS.md` and `doc/DEVELOPING.md`. - Include behavioral review criteria and flag substantial coordinator growth or mixed responsibilities while allowing justified cohesion and ordering exceptions. ## Verification - Parsed the rule YAML and Greptile JSON. Confirmed that the rule globs exactly match the Greptile scope. - Checked 14 positive and negative scope cases with Node's `path.matchesGlob`, including nested heartbeat modules, sibling services, regression tests, and unrelated paths. - Verified local links and heading anchors, including the existing heartbeat module map, and confirmed all 20 named modules exist. Reviewed their responsibility descriptions against the current code and developer documentation. - `git diff origin/master --check` passed after rebasing onto current master. - Reviewed the principles against the current heartbeat code and tests. The diff changes four documentation and review-configuration files. - Application typecheck, runtime tests, and build were not run locally. This worktree has no installed dependencies. CI and review status are tracked below. - CI passed on `a17f5a2cc82b7bb7e4629d4a2d9e3a766e27c5c0`: 55 successful checks, two skipped, no failures or pending checks. This includes typecheck, build, server/runner tests, and browser tests. - Greptile reviewed the same commit at 5/5 with no findings or unresolved review threads. ## Risks The rule can influence later implementation and review decisions. It applies to changed heartbeat behavior and permits justified contract changes with tests. The scoped globs exclude unrelated subsystems. This PR does not change application behavior. Hosted loading of the new rule has not been demonstrated by the local configuration checks. ## Model Used OpenAI GPT-6 Astra (`gpt-6-astra`) via Codex, with repository inspection, file editing, and command execution. The context-window size was not exposed to 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 (scoped rule/configuration checks described above) - [x] I have added or updated tests where applicable (documentation/configuration validation; no runtime changes) - [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
|
7ac0354b51 |
docs: track chat channel rules and Greptile configuration (#16172)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Chat channels connect shared task workflows to several platforms. > - Recent refactors moved platform behavior into named channel folders. > - Authors and reviewers need a durable rule that preserves these boundaries. > - Review settings also need version control and an explicit source of rules. > - This pull request adds scoped MDC rules and a staged migration of supported Greptile settings into Git. ## Linked Issues or Issue Description **Issue type** Missing documentation and versioned review configuration. **Where is the issue?** Root contributor instructions, chat channel architecture guidance, and Greptile configuration for this repository. **What's wrong?** The channel folder boundary is established in the refactor but has no focused rule for future changes. Greptile settings and custom context are maintained in the dashboard. **Suggested fix** Keep canonical rule bodies under `rules/`. Route coding agents through `AGENTS.md` and load matching rules through `.greptile/files.json`. Preserve supported review settings in `.greptile/config.json` and document the remaining dashboard controls. Related work: #15823 and #16080. A search for related rule PRs found no duplicate configuration change. ## What Changed - Add `rules/chat-channel-platform-boundaries.mdc`. Its scope covers `server/src/services/chat-channels/**` and the sibling `chat-channels.ts` entry point. - Define provider folder ownership, shared workflow boundaries, typed dependencies, behavior-preserving extraction, and dispatch exceptions. - Add rule-loading instructions to root `AGENTS.md` and `.greptile/rules.md`. - Add explicit, scoped context references in `.greptile/files.json`. - Record observed review triggers, the Dependabot exclusion, Base tier, High strictness, summary options, fix prompts, status checks, and disabled auto-approval in `.greptile/config.json`. - Move existing PR-description, source-file growth, and repository-specific screenshot guidance into `rules/pull-request-review.mdc`. - Document supported settings, remaining dashboard controls, and the staged cutover. The dashboard was inspected read-only; no settings or saved rules were changed. ## Verification - Parse both MDC headers with Ruby `YAML.safe_load`: passed. - Parse both Greptile JSON files and verify documented field types and observed values: passed. - Verify all four context references resolve to repository files: passed. - Compare scoped MDC globs with the corresponding Greptile scope: passed. - Check ten positive and negative scope cases with Node `path.matchesGlob`: passed. Includes the service entry point, nested provider files, and unrelated runner, connection, and UI paths. - Verify the scope covers all 101 tracked chat-channel files: passed. - `git diff --check`: passed. - Application typecheck, `pnpm test:run`, and build were not run locally. This change contains only guidance and reviewer configuration, and this worktree has no installed application dependencies. No runtime behavior or application tests changed. - Greptile reviewed commit `32647dfd001289a297b9d43c381371da8575df38`: 5/5, eight files reviewed, zero comments. Hosted CI is still running. ## Risks - Instructions depend on agent and reviewer compliance; these files are not deterministic lint rules. - The new MDC directory is explicitly routed through `AGENTS.md` and Greptile. Cursor does not automatically discover arbitrary `rules/` directories. - This preserves the observed High strictness setting, which the dashboard says omits P2 comments. It does not change that review policy. - Dashboard instructions and custom rules remain additive. Their copies were not disabled during read-only inspection. The repository-specific no-screenshot rule explicitly takes precedence over the conflicting older organization instruction. - Draft review, the required 5/5 status threshold, image badges, and other controls without documented config equivalents remain in the dashboard. See `.greptile/README.md` for the inventory and cutover limitations. ## Model Used OpenAI Codex based on GPT-6. The exact runtime model ID and context-window size are not exposed in this session. Used reasoning, repository inspection, shell validation, official documentation, and read-only browser inspection. ## 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 (configuration parsing and scope checks described above; application suites were not run) - [x] I have added or updated tests where applicable (no runtime change; checked configuration directly) - [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> |