## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Contributors and agents read the docs under `doc/` for background on run execution > - `doc/execution-semantics.md` grew to 6,310 lines of per-PR notes > - It was hard to read and it drifted from the code > - The code and tests are the source of truth for execution behavior > - This pull request removes the file and every reference to it > - The benefit is one less stale document that readers can mistake for a requirement ## Linked Issues or Issue Description **Issue type** Outdated or unclear documentation. **Where is the issue?** `doc/execution-semantics.md`, and the docs, rules, skills, maps, code comments and log text that link to it. **What's wrong?** The file is 6,310 lines of notes added one PR at a time. Much of it repeats or contradicts the code. Readers and agents treat it as a contract, but the code and tests decide the behavior. **Suggested fix** Delete the file. Remove each link to it. Keep the documents that link to it. Point at code where a pointer is still useful. Do not move the content to another doc. Refs #10664 (an open docs PR that edits this file; it becomes obsolete). ## What Changed - Delete `doc/execution-semantics.md`. - Remove links and pointers in `doc/PRODUCT.md`, `doc/LOW-TRUST-PRESETS.md`, `doc/TASK-WATCHDOG.md`, `doc/composer-stop.md`, `doc/native-workspace-finalization-recovery.md`, `doc/run-log-events.md`, `doc/runner-internals.md` and `doc/workspace-repositories.md`. - `doc/TASK-WATCHDOG.md` now points at `server/src/modules/active-run-watchdog/` for the silent active-run watchdog. - Remove the link in `rules/upgrade-safe-run-state.mdc` and `maps/feature-map/recovery.md`. - Update the skills `diagnose-why-work-stopped`, `fix-failed-paperclip-run` and `terminal-bench-loop`. The `fix-failed-paperclip-run` skill now points at `server/src/services/heartbeat/` and `server/src/services/recovery/`. - Remove the file from the source anchors in `.devin/wiki.json`. - Remove the doc name from four code comments in `server/` and `ui/`. - The failed-attachment log message no longer ends with a link to the removed doc. Two tests now check the message text instead of the link. - Leave two dated plan files under `doc/plans/` unchanged. They are history. ## Verification - `git grep -i execution-semantics` finds no hits outside `doc/plans/`. - Every relative Markdown link in the changed files resolves. - `node scripts/check-maps.mjs` passes. - `node --test .github/scripts/tests/*.test.mjs` passes (808 tests). - `pnpm verify` was not run locally. The worktree has no `node_modules`. CI runs the changed Vitest files. ## Risks - Low risk. Most changes are docs and comments. - One runtime log line is shorter. It no longer has a link. No logic changes. - Open PRs that edit the deleted file, such as #10664, will conflict. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use and shell 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 - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Repository rules
Keep architectural guidance in focused .mdc files here. Each file is Markdown
with YAML frontmatter containing a description and an alwaysApply boolean.
For scoped rules, set alwaysApply: false and provide comma-separated,
repository-relative globs. For repository-wide rules, set alwaysApply: true
and omit globs. Use ** for all descendants of a directory. Include sibling
entry points explicitly when needed.
Root AGENTS.md tells coding agents to list the rule headers, follow the
descriptions that cover their files, and read a rule body when they make a
design decision in its area or a reviewer cites it. Write each description as
one sentence that states the required behavior, because it is what an agent reads
first. This directory is a repository convention: Cursor does not
automatically load it as .cursor/rules/, and the .mdc extension alone does not
make a tool apply a rule.
Greptile reads matching rule files through .greptile/files.json and receives
loading instructions from .greptile/rules.md. The rule body remains here as
the single source of truth. Repository configuration takes effect when the
files are available on the reviewed branch; local files alone are not visible
to the hosted reviewer.
When adding or changing a rule:
- State the scope, required behavior, examples, exceptions, and review criteria.
- Add its path to
.greptile/files.json. Copy itsglobsinto that entry'sscopearray, one pattern per element. ForalwaysApply: true, omitscope. - Keep the rule's frontmatter and the Greptile scope synchronized. Verify that the scope covers representative files and excludes unrelated directories.
- Keep detailed policy in the rule file instead of copying it into tool settings.
Product behavior is covered by
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 for the manifest format.
Background execution is covered by
sleep-aware-background-work.mdc: new or
expanded work must become quiet, use events and real scheduler deadlines, and
preserve recovery across transactions, drain, and restart. This rule covers
server/src/index.ts and the worker/producer paths in its scope. It does not
require unrelated legacy polling to be migrated in the same PR.