From 9cb3e157b309af404c9eb158bcda47ca782d4b7b Mon Sep 17 00:00:00 2001 From: Dotta <34892728+cryppadotta@users.noreply.github.com> Date: Tue, 13 Oct 2026 10:50:03 -0500 Subject: [PATCH] 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 --- .greptile/files.json | 4 ++++ rules/README.md | 5 +++++ rules/product-harness-responsibility.mdc | 26 ++++++++++++++++++++++++ 3 files changed, 35 insertions(+) create mode 100644 rules/product-harness-responsibility.mdc diff --git a/.greptile/files.json b/.greptile/files.json index fc2430e09f..a537dbd352 100644 --- a/.greptile/files.json +++ b/.greptile/files.json @@ -12,6 +12,10 @@ "path": "rules/pull-request-review.mdc", "description": "Existing Paperclip review guidance for PR descriptions, UI evidence, and growth of large source files." }, + { + "path": "rules/product-harness-responsibility.mdc", + "description": "Product requirements and review criteria for harness responsibility, minimal user-facing internals, truthful progress, and human decisions." + }, { "path": "rules/chat-channel-platform-boundaries.mdc", "description": "Architecture requirements and review criteria for separating chat channel platform implementations from shared orchestration.", diff --git a/rules/README.md b/rules/README.md index 2e7edf1d70..4fa6390aa9 100644 --- a/rules/README.md +++ b/rules/README.md @@ -27,5 +27,10 @@ When adding or changing a rule: the scope covers representative files and excludes unrelated directories. 4. Keep detailed policy in the rule file instead of copying it into tool settings. +Product behavior is covered by +[`product-harness-responsibility.mdc`](product-harness-responsibility.mdc): routine +work belongs to the harness, and user-facing detail must support an outcome or a +real decision. This applies to orchestration as well as UI. + See the [Greptile file-reference documentation](https://www.greptile.com/docs/code-review/greptile-config-reference) for the manifest format. diff --git a/rules/product-harness-responsibility.mdc b/rules/product-harness-responsibility.mdc new file mode 100644 index 0000000000..4297181583 --- /dev/null +++ b/rules/product-harness-responsibility.mdc @@ -0,0 +1,26 @@ +--- +description: Keep routine work in the harness and expose only useful product details. +alwaysApply: true +--- + +# Let the harness handle routine work + +Applies to product design, implementation and review across UI, orchestration, +setup, settings and user-facing errors. + +If the system knows the next step and can safely perform it under existing +authority, the harness owns it. + +- Implement routine retries, reconnection, lease maintenance and finalization in + the owning service. Do not turn orchestration gaps into user checklists. +- Each control and detail must enable a real decision, resolve uncertainty or help + use a result. Keep incidental internal states and identifiers out of default views. +- Keep normal operation quiet. Show brief, contextual status only when useful, + backed by observed server state. Never hide blockers or imply progress that has + not occurred. +- Do not ask task users to certify infrastructure facts. + +**Review:** Check that harness responsibility is implemented, visible details +serve a purpose the user should affect. + +Apply this rule to changed flows; unrelated redesign is not required.