mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-11 05:11:49 +01:00
refactor: remove SPEC docs and repoint spec citations (#20565)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Contributors and agents read the docs under `doc/` before they change code > - `doc/SPEC.md` and `doc/SPEC-implementation.md` were out of date. `doc/SPEC-implementation.md` became an append-only log: in 60 days it got about 1,645 new lines and lost 181, across 140 commits > - #20557 changed `AGENTS.md` so the code and its tests are the source of truth, and the specs are only background > - This pull request removes the two spec docs. It moves only the sections that live code comments cite into focused docs, and it repoints all other references > - The benefit is one less stale document that agents read and append to ## Linked Issues or Issue Description Refs #20557 (merged). This PR is the follow-up that removes the docs. It is based on `master`, which already contains #20557. **Issue type** Outdated content. The docs are out of date and conflict with the code. **Where is the issue?** `doc/SPEC.md`, `doc/SPEC-implementation.md`, and the code comments and docs that cite them. **What's wrong?** `doc/SPEC.md` and `doc/SPEC-implementation.md` are out of date, but agents still read them and append a paragraph with each fix. **Suggested fix** Delete both files. Move the sections that code cites into focused docs. Repoint the references. ## What Changed - Deleted `doc/SPEC.md` and `doc/SPEC-implementation.md`. - Moved these spec sections, because live code comments cite them: - §9.3.1 "Shared default-open issue writes" → new section in `doc/agent-permission-defaults.md`. - §9.8.1 "Issue-thread interaction resolver contract" → `doc/execution-semantics.md`, "Issue-thread interaction resolution". That section already had most of the contract. I added only the missing parts: the `supersedeOnUserComment` default, the canonical policy list, the addressee and cap rules, the rule that surfaces show the server's effective audience, and the cross-issue budget charge. The short policy summary at the top of the section now points to the list, so the definitions occur one time only. - §9.9 "Task Watchdog Authority Contract" → new "Authority contract" section in `doc/TASK-WATCHDOG.md`. It holds the allowed and disallowed mutation lists and the deferred capabilities. The atomic recovery batch, restoration verification, and interaction rules were already in `doc/execution-semantics.md` §11, so the new section links there and does not repeat them. I did not move the "Downstream acceptance criteria" checklist or the sentence about the CTO and Security sign-off. These were implementation-time notes; the tests now hold that coverage. - §9.10 "Company Skill Policy Contract" → new `doc/company-skill-policy.md`. No focused doc had this contract. I did not move the "Required regression tests" phase checklist. - Did not move any other part of the specs. - Repointed code comments that cited spec sections: - `packages/shared/src/issue-write-denial.ts` (§9.3) → `doc/agent-permission-defaults.md` - `server/src/routes/issues.ts` (§9.9) → `doc/TASK-WATCHDOG.md`, "Authority contract" - `server/src/routes/issues.ts` (§9.3, §9.8.1 cross-issue budget) → `doc/agent-permission-defaults.md` - `ui/src/lib/interaction-audience.ts` and `ui/src/components/InteractionGovernancePanel.tsx` (§9.8.1) → `doc/execution-semantics.md` - `ui/src/lib/skill-policy-denial.ts`, `ui/src/pages/CompanySkills.tsx`, `ui/src/pages/CompanySkills.production.tsx`, `ui/src/pages/SkillStudio.tsx` (§9.10) → `doc/company-skill-policy.md` - `server/src/services/recovery/ownership-invariant-report.ts` (monitor deadline wait path) → `doc/execution-semantics.md` §8. That section already lists the one-shot monitor as a valid wait path. - Resynced the git blob pin for `packages/shared/src/issue-write-denial.ts` in `tests/runner-e2e/source-sdk-public-inputs.json`. The comment edit changed the file's hash, and the Runner support suite checks that pin. I used `node tests/runner-e2e/source-sdk-public-inputs.mjs <HEAD> --write`; only that one pin changed. - Updated `AGENTS.md` §1 so it does not name the deleted files. - Removed the links to the deleted files from `doc/plugins/PLUGIN_SPEC.md`. - Updated the `doc-maintenance` agent skill (`.agents/skills/doc-maintenance/`) so it no longer audits or stages `doc/SPEC.md`. - Removed or replaced references in `maps/README.md`, `maps/feature-map/README.md`, `maps/storybook-map/README.md`, `doc/PRODUCT.md`, `doc/CLIPHUB.md`, `doc/DEPLOYMENT-MODES.md`, `doc/DEVELOPING.md`, `doc/evals.md`, `doc/spec/agent-runs.md`, `doc/AGENTCOMPANIES_SPEC_INVENTORY.md`, `doc/connections/CONNECTOR-PLAYBOOK.md`, `doc/plugins/ideas-from-opencode.md`, `doc/execution-semantics.md`, `doc/TASK-WATCHDOG.md`, and `.devin/wiki.json`. - In `doc/execution-semantics.md`, the "admission is independent of cleanup and accounting" reference now states the rule inline: only a hard stop, an explicit pause, or an inactive company refuses admission. - Kept these references as they are: dated plans in `doc/plans/` and `docs/plans/`, the dated log `doc/logs/2026-05-24-cli-api-parity-e2e-log.md`, `releases/`, the transcript fixture `ui/src/fixtures/runTranscriptFixtures.ts` (it uses the filename only as sample text), and `docs/specs/external-task-protocol.md` (it refers to the Symphony project's own `SPEC.md`). ## Verification - `git grep -n "SPEC-implementation\|SPEC\.md"` (without `releases/`, and ignoring `PLUGIN_SPEC.md` citations) finds only the kept references listed above. - `grep -rn "§9\.\(3\|8\|9\|10\)" ui/src server/src packages/shared/src` finds no results. - `node scripts/check-maps.mjs`: "Maps aligned: 35 areas, 192 capability IDs". - `pnpm check:token-gates`: "All gates clean". - `pnpm exec vitest run --config tests/runner-e2e/vitest.config.ts tests/runner-e2e/source-sdk-public-type.test.ts tests/runner-e2e/source-sdk-evidence.test.ts`: 45 passed. These failed in CI before the pin resync. - `pnpm verify`: exit 2 ("Broader verification required") because `AGENTS.md` is a global CI input. Required CI supplies the broad coverage for this revision. - All code changes are comments only. No runtime behavior changes. The title uses `refactor:` because comments in source files changed. ## Risks - Low risk. The change removes docs and edits comments only. - A reader can lose context from spec sections that I did not move. The text stays in git history. The code and its tests are the source of truth. - External links to the two deleted files will return 404. > 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 - Anthropic Claude Opus 5.5 (`claude-opus-5-5`), in Claude Code with tool use (shell, file edits). Standard context window. ## 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 checks above; CI supplies broad coverage) - [x] I have added or updated tests where applicable (not applicable: docs and comments only) - [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>
This commit is contained in:
DottaandClaude Opus 5.5 authored and GitHub committed
1 parent
3bf7af6c77
commit
9b21dcbdda
34 files changed
+345
-4024
No files matched your search
@@ -1,7 +1,7 @@
|
||||
---
|
||||
name: doc-maintenance
|
||||
description: >
|
||||
Audit README, SPEC, and PRODUCT docs against recent git history for drift and
|
||||
Audit README and PRODUCT docs against recent git history for drift and
|
||||
make minimal PR-ready edits. Use when asked to review docs for accuracy, after
|
||||
major feature merges, or on a schedule.
|
||||
---
|
||||
@@ -15,14 +15,13 @@ Detect documentation drift and fix it via PR — no rewrites, no churn.
|
||||
- Periodic doc review (e.g. weekly or after releases)
|
||||
- After major feature merges
|
||||
- When asked "are our docs up to date?"
|
||||
- When asked to audit README / SPEC / PRODUCT accuracy
|
||||
- When asked to audit README / PRODUCT accuracy
|
||||
|
||||
## Target Documents
|
||||
|
||||
| Document | Path | What matters |
|
||||
|----------|------|-------------|
|
||||
| README | `README.md` | Features table, roadmap, quickstart, "what is" accuracy, "works with" table |
|
||||
| SPEC | `doc/SPEC.md` | No false "not supported" claims, major model/schema accuracy |
|
||||
| PRODUCT | `doc/PRODUCT.md` | Core concepts, feature list, principles accuracy |
|
||||
|
||||
Out of scope: DEVELOPING.md, DATABASE.md, CLI.md, doc/plans/, skill files,
|
||||
@@ -122,7 +121,7 @@ Apply **only** the edits needed to fix drift. Rules:
|
||||
Commit the changes and open a PR:
|
||||
|
||||
```bash
|
||||
git add README.md doc/SPEC.md doc/PRODUCT.md .doc-review-cursor
|
||||
git add README.md doc/PRODUCT.md .doc-review-cursor
|
||||
git commit -m "docs: update documentation for accuracy
|
||||
|
||||
- [list each fix briefly]
|
||||
@@ -184,7 +183,7 @@ were needed, commit the cursor update to the current branch.
|
||||
- If adding a feature mention, match the format of surrounding entries
|
||||
(e.g. if features are in a table, add a table row)
|
||||
- Keep README changes especially minimal — it shouldn't churn often
|
||||
- For SPEC/PRODUCT, prefer updating existing statements over adding new ones
|
||||
- For PRODUCT, prefer updating existing statements over adding new ones
|
||||
(e.g. change "not supported in V1" to "supported via X" rather than adding
|
||||
a new section)
|
||||
|
||||
|
||||
@@ -46,29 +46,6 @@ against the change summary from git history.
|
||||
- [ ] Commands are accurate (`pnpm dev`, `pnpm build`, etc.)
|
||||
- [ ] Link to DEVELOPING.md is correct
|
||||
|
||||
## doc/SPEC.md
|
||||
|
||||
### Company Model
|
||||
- [ ] Fields match current schema
|
||||
- [ ] Governance model description is accurate
|
||||
|
||||
### Agent Model
|
||||
- [ ] Adapter types match what's actually supported
|
||||
- [ ] Agent configuration description is accurate
|
||||
- [ ] No features described as "not supported" or "not V1" that shipped
|
||||
|
||||
### Task Model
|
||||
- [ ] Task hierarchy description is accurate
|
||||
- [ ] Status values match current implementation
|
||||
|
||||
### Extensions / Plugins
|
||||
- [ ] If plugins are shipped, no "not in V1" or "future" language
|
||||
- [ ] Plugin model description matches implementation
|
||||
|
||||
### Open Questions
|
||||
- [ ] Resolved questions removed or updated
|
||||
- [ ] No "TBD" items that have been decided
|
||||
|
||||
## doc/PRODUCT.md
|
||||
|
||||
### Core Concepts
|
||||
|
||||
@@ -3,20 +3,20 @@
|
||||
Maps feature areas to specific document sections so the skill knows where to
|
||||
look when a feature ships or changes.
|
||||
|
||||
| Feature Area | README Section | SPEC Section | PRODUCT Section |
|
||||
|-------------|---------------|-------------|----------------|
|
||||
| Plugins / Extensions | Features table, Roadmap | Extensions, Agent Model | Core Concepts |
|
||||
| Adapters (new runtimes) | "Works with" table, FAQ | Agent Model, Agent Configuration | Employees & Agents, Agent Execution |
|
||||
| Governance / Approvals | Features table, "Why special" | Board Governance, Board Approval Gates | Principles |
|
||||
| Budget / Cost Control | Features table, "Why special" | Budget Delegation | Company (revenue & expenses) |
|
||||
| Task Management | Features table | Task Model | Task Management |
|
||||
| Org Chart / Hierarchy | Features table | Agent Model (reporting) | Employees & Agents |
|
||||
| Multi-Company | Features table, FAQ | Company Model | Company |
|
||||
| Heartbeats | Features table, FAQ | Agent Execution | Agent Execution |
|
||||
| CLI Commands | Development section | — | — |
|
||||
| Onboarding / Quickstart | Quickstart, FAQ | — | User Flow |
|
||||
| Skills / Skill Injection | "Why special" | — | — |
|
||||
| Company Templates | "Why special", Roadmap (ClipMart) | — | — |
|
||||
| Mobile / UI | Features table | — | — |
|
||||
| Project Archiving | — | — | — |
|
||||
| OpenClaw Integration | "Works with" table, FAQ | Agent Model | Agent Execution |
|
||||
| Feature Area | README Section | PRODUCT Section |
|
||||
|-------------|---------------|----------------|
|
||||
| Plugins / Extensions | Features table, Roadmap | Core Concepts |
|
||||
| Adapters (new runtimes) | "Works with" table, FAQ | Employees & Agents, Agent Execution |
|
||||
| Governance / Approvals | Features table, "Why special" | Principles |
|
||||
| Budget / Cost Control | Features table, "Why special" | Company (revenue & expenses) |
|
||||
| Task Management | Features table | Task Management |
|
||||
| Org Chart / Hierarchy | Features table | Employees & Agents |
|
||||
| Multi-Company | Features table, FAQ | Company |
|
||||
| Heartbeats | Features table, FAQ | Agent Execution |
|
||||
| CLI Commands | Development section | — |
|
||||
| Onboarding / Quickstart | Quickstart, FAQ | User Flow |
|
||||
| Skills / Skill Injection | "Why special" | — |
|
||||
| Company Templates | "Why special", Roadmap (ClipMart) | — |
|
||||
| Mobile / UI | Features table | — |
|
||||
| Project Archiving | — | — |
|
||||
| OpenClaw Integration | "Works with" table, FAQ | Agent Execution |
|
||||
+4
-4
@@ -4,7 +4,7 @@
|
||||
"content": "Audience and outcome: write a guided architecture handbook for contributors and coding agents. Help a reader understand the control plane, trace a task through the code, choose the right place to change behavior, and find the tests that protect it. Explain the problem and mental model before introducing symbols. Prefer a concrete example and a short causal explanation to exhaustive class, endpoint, package, or configuration inventories. Use plain language and define abbreviations on first use."
|
||||
},
|
||||
{
|
||||
"content": "Evidence and document authority: use current implementation, schemas, configuration, public exports, and tests to establish what ships in the indexed revision. Read `doc/GOAL.md` and `doc/PRODUCT.md` for intent and `doc/SPEC-implementation.md` for the V1 policy contract; `doc/SPEC.md` provides longer-horizon context. Contributor instructions such as `AGENTS.md` are not implementation evidence. Explain material disagreements between code and policy instead of silently treating either as proof of the other. Plans, historical snapshots, proposed ADRs, prototypes, fixtures, and roadmap entries do not establish shipping behavior. Verify their claims against production wiring and distinguish implemented, gated/experimental, and proposed behavior."
|
||||
"content": "Evidence and document authority: use current implementation, schemas, configuration, public exports, and tests to establish what ships in the indexed revision. Read `doc/GOAL.md` and `doc/PRODUCT.md` for intent; the focused docs under `doc/` (for example `doc/execution-semantics.md`) give background on policy. Contributor instructions such as `AGENTS.md` are not implementation evidence. Explain material disagreements between code and policy instead of silently treating either as proof of the other. Plans, historical snapshots, proposed ADRs, prototypes, fixtures, and roadmap entries do not establish shipping behavior. Verify their claims against production wiring and distinguish implemented, gated/experimental, and proposed behavior."
|
||||
},
|
||||
{
|
||||
"content": "Page contract: each subsystem page should explain the problem it solves, what it owns, its inputs and outputs, authoritative persisted state, and its boundaries with neighboring systems. Trace one representative flow through actual entry points. Include a compact 'Where to change it' map linking responsibilities to source, relevant regression tests with the behavior they protect, and practical investigation steps for characteristic failures. Cite the code that performs a decision or effect rather than an import list or unrelated file. A passing unit fixture does not establish live provider support. Parent pages should offer reading routes, boundary maps, or diagnostic routing instead of repeating all their children."
|
||||
@@ -34,7 +34,7 @@
|
||||
"content": "Introduce the company control plane through one running example: an operator asks an agent to produce a report, the agent works under company policy, and the operator receives an inspectable result. Explain the roles of the board, company, agent, task, execution service, and work product. Offer three linked reading routes: understand the system, make a first change, and diagnose work that stopped. Explain which chapter answers which question and link to official quickstart/operator docs. Keep this page approachable; leave architecture detail, entity mapping, and the complete code trace to its three children."
|
||||
},
|
||||
{
|
||||
"content": "Source anchors: `README.md`, `doc/GOAL.md`, `doc/PRODUCT.md`, `doc/SPEC-implementation.md`, `docs/start/what-is-paperclip.md`, `docs/start/core-concepts.md`, `docs/docs.json`. Verify the example's persisted task/output concepts against `packages/db/src/schema/issues.ts`, `server/src/services/work-products.ts`, and `server/src/__tests__/work-products.test.ts`; do not imply the example is an executed demo."
|
||||
"content": "Source anchors: `README.md`, `doc/GOAL.md`, `doc/PRODUCT.md`, `docs/start/what-is-paperclip.md`, `docs/start/core-concepts.md`, `docs/docs.json`. Verify the example's persisted task/output concepts against `packages/db/src/schema/issues.ts`, `server/src/services/work-products.ts`, and `server/src/__tests__/work-products.test.ts`; do not imply the example is an executed demo."
|
||||
}
|
||||
]
|
||||
},
|
||||
@@ -60,7 +60,7 @@
|
||||
"content": "Use a concept-to-schema/service table for company, agent/org tree, goal, project, task/issue, wake, run, session, approval/interaction, and work product. Explain company scope and documented instance-level exceptions without asserting every table has identical tenancy. Distinguish assignment from execution ownership, parent/child structure from blockers, and business goals from provider session goals. Give concrete examples of atomic checkout, company-boundary rejection, and a durable wait. Explain where these invariants are enforced and tested; leave full state transitions, permissions, and database operations to their owning pages."
|
||||
},
|
||||
{
|
||||
"content": "Source anchors: `doc/SPEC-implementation.md`, `packages/db/src/schema/index.ts`, `packages/db/src/schema/issues.ts`, `packages/db/src/schema/agents.ts`, `packages/db/src/schema/heartbeat_runs.ts`, `packages/db/src/schema/agent_task_sessions.ts`, `packages/shared/src/constants.ts`, `server/src/services/issues.ts`. Regression anchors: `server/src/__tests__/authz-company-access.test.ts`, `server/src/__tests__/issues-service.test.ts`, `server/src/__tests__/heartbeat-auto-checkout.test.ts`."
|
||||
"content": "Source anchors: `doc/execution-semantics.md`, `packages/db/src/schema/index.ts`, `packages/db/src/schema/issues.ts`, `packages/db/src/schema/agents.ts`, `packages/db/src/schema/heartbeat_runs.ts`, `packages/db/src/schema/agent_task_sessions.ts`, `packages/shared/src/constants.ts`, `server/src/services/issues.ts`. Regression anchors: `server/src/__tests__/authz-company-access.test.ts`, `server/src/__tests__/issues-service.test.ts`, `server/src/__tests__/heartbeat-auto-checkout.test.ts`."
|
||||
}
|
||||
]
|
||||
},
|
||||
@@ -367,7 +367,7 @@
|
||||
"content": "Trace representative board/session and agent-key requests through authentication, actor derivation, company access, resource lookup, action policy, and mutation attribution. Verify current support for other credential types rather than presenting a fixed inventory. Explain deployment exposure versus company visibility, resource membership versus permission grants, and default-open versus explicitly restricted operations. Identify legitimate instance-level exceptions and low-trust containment without confusing them with task privacy. Show cross-company and existence-oracle rejection tests. Distinguish core enforcement from optional administrative UI and provider permission settings; link tool grants, secrets, and budgets to their owning pages."
|
||||
},
|
||||
{
|
||||
"content": "Source anchors: `doc/DEPLOYMENT-MODES.md`, `doc/SPEC-implementation.md`, `doc/LOW-TRUST-PRESETS.md`, `server/src/middleware/auth.ts`, `server/src/routes/authz.ts`, `server/src/services/access.ts`, `server/src/services/authorization.ts`, `packages/shared/src/constants.ts`, `packages/db/src/schema/principal_permission_grants.ts`. Regression anchors: `server/src/__tests__/authz-company-access.test.ts`, `server/src/__tests__/authz-existence-oracle-guard.test.ts`, `server/src/__tests__/authz-secret-context.test.ts`."
|
||||
"content": "Source anchors: `doc/DEPLOYMENT-MODES.md`, `doc/agent-permission-defaults.md`, `doc/LOW-TRUST-PRESETS.md`, `server/src/middleware/auth.ts`, `server/src/routes/authz.ts`, `server/src/services/access.ts`, `server/src/services/authorization.ts`, `packages/shared/src/constants.ts`, `packages/db/src/schema/principal_permission_grants.ts`. Regression anchors: `server/src/__tests__/authz-company-access.test.ts`, `server/src/__tests__/authz-existence-oracle-guard.test.ts`, `server/src/__tests__/authz-secret-context.test.ts`."
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
@@ -9,7 +9,7 @@ The invariants and rules below record what has been decided so far. If you think
|
||||
|
||||
Paperclip is a control plane for AI-agent companies.
|
||||
The code and its tests are the source of truth for current behavior.
|
||||
`doc/SPEC-implementation.md` and `doc/SPEC.md` are background. They can be out of date, so do not treat them as requirements when they disagree with the code or with the task.
|
||||
The focused docs under `doc/` are background. They can be out of date, so do not treat them as requirements when they disagree with the code or with the task.
|
||||
|
||||
## 2. Read This First
|
||||
|
||||
|
||||
@@ -16,7 +16,6 @@ Use it when you need to:
|
||||
|---|---|
|
||||
| `docs/companies/companies-spec.md` | **Normative spec** — defines the markdown-first package format (COMPANY.md, TEAM.md, AGENTS.md, PROJECT.md, TASK.md, SKILL.md), reserved files, frontmatter schemas, and vendor extension conventions (`.paperclip.yaml`). |
|
||||
| `doc/plans/2026-03-13-company-import-export-v2.md` | Implementation plan for the markdown-first package model cutover — phases, API changes, UI plan, and rollout strategy. |
|
||||
| `doc/SPEC-implementation.md` | V1 implementation contract; references the portability system and `.paperclip.yaml` sidecar format. |
|
||||
| `docs/specs/cliphub-plan.md` | Earlier blueprint bundle plan; partially superseded by the markdown-first spec (noted in the v2 plan). |
|
||||
| `doc/plans/2026-02-16-module-system.md` | Module system plan; JSON-only company template sections superseded by the markdown-first model. |
|
||||
| `doc/plans/2026-03-14-skills-ui-product-plan.md` | Skills UI plan; references portable skill files and `.paperclip.yaml`. |
|
||||
|
||||
+1
-1
@@ -8,7 +8,7 @@ ClipHub is the public registry where people share, discover, and download Paperc
|
||||
|
||||
## What It Is
|
||||
|
||||
ClipHub is to Paperclip what a package registry is to a programming language. Paperclip already supports exportable org configs (see [SPEC.md](./SPEC.md) §2). ClipHub is the public directory where those exports live.
|
||||
ClipHub is to Paperclip what a package registry is to a programming language. Paperclip already supports exportable org configs (see the [company package spec](../docs/companies/companies-spec.md)). ClipHub is the public directory where those exports live.
|
||||
|
||||
A user builds a working company in Paperclip — a dev shop, a marketing agency, a research lab, a content studio — exports the template, and publishes it to ClipHub. Anyone can browse, search, download, and spin up that company on their own Paperclip instance.
|
||||
|
||||
|
||||
@@ -226,6 +226,5 @@ future public-hosted setup design explicitly changes this policy.
|
||||
## 11. Relationship to Other Docs
|
||||
|
||||
- implementation plan: `doc/plans/2026-02-23-deployment-auth-mode-consolidation.md`
|
||||
- V1 contract: `doc/SPEC-implementation.md`
|
||||
- operator workflows: `doc/DEVELOPING.md` and `doc/CLI.md`
|
||||
- invite/join state map: `doc/spec/invite-flow.md`
|
||||
+1
-2
@@ -2374,8 +2374,7 @@ for storage, import, retention, and lifecycle regression checks. These checks do
|
||||
not qualify a deployed Runner/provider or a zero-outage webserver deploy. Keep
|
||||
the existing persistent volume until the other instance data paths and deploy
|
||||
handoff are separately qualified. See the
|
||||
[implementation contract](SPEC-implementation.md#experimental-native-remote-workspace-authority-2026-10-30)
|
||||
and [snapshot storage contract](DATABASE.md#experimental-remote-workspace-snapshots).
|
||||
[snapshot storage contract](DATABASE.md#experimental-remote-workspace-snapshots).
|
||||
|
||||
## Agent Artifact Uploads
|
||||
|
||||
|
||||
+1
-1
@@ -324,7 +324,7 @@ Canonical mode design and command expectations live in `doc/DEPLOYMENT-MODES.md`
|
||||
|
||||
## Further Detail
|
||||
|
||||
See [SPEC.md](./SPEC.md) for the full technical specification and [TASKS.md](./TASKS.md) for the task management data model.
|
||||
See [TASKS.md](./TASKS.md) for the task management data model.
|
||||
|
||||
---
|
||||
|
||||
|
||||
File diff suppressed because it is too large.
Load diff
-903
@@ -1,903 +0,0 @@
|
||||
# Paperclip Specification
|
||||
|
||||
Target specification for the Paperclip control plane. Living document — updated incrementally during spec interviews.
|
||||
|
||||
Proactive in-app updates let an active standard task or routine publish to its
|
||||
agent's persistent conversation with the run's responsible human. The server
|
||||
derives the destination, enforces current authority and company-visible chat
|
||||
privacy, and persists an attributed, idempotent comment with source-task provenance.
|
||||
Unread state belongs to the viewing human. Sending is independent of task
|
||||
completion and chat execution; future messages remain possible after `/new`.
|
||||
The V1 contract is specified under experimental task-backed agent chat in
|
||||
`doc/SPEC-implementation.md`.
|
||||
|
||||
Experimental standalone cases provide persistent structured work records that can
|
||||
exist independently of execution. Prompt-driven handoffs move their primary
|
||||
ordinary task between agents while retaining case data and history. Existing task
|
||||
permissions, execution ownership, budgets, and review gates remain authoritative;
|
||||
the concrete contract is in `SPEC-implementation.md` and the persistent case
|
||||
handoff implementation plan.
|
||||
|
||||
A terminal handoff to `done` explicitly requests case closure on accepted
|
||||
completion of its primary task. Existing completion and review gates remain
|
||||
authoritative; an open case alone never creates an execution requirement.
|
||||
|
||||
Native agents have dedicated case creation/read/update and handoff tools.
|
||||
Native creation requires first-task kickoff and either `workflowId` or explicit `workflow_document_text`,
|
||||
stored as the primary task's `workflow` Markdown document, with optional additional
|
||||
initial documents. Recommend both a Mermaid `stateDiagram-v2` map and prose
|
||||
defining every transition's conditions, evidence, destination and wait/retry rules;
|
||||
the server does not parse graph labels as executable transition rules.
|
||||
Documents belong to ordinary tasks; cases surface authorized document references
|
||||
and history without copying bodies. Historical case document storage is retained.
|
||||
Case
|
||||
awareness is supplied by the harness; compatible session continuations carry
|
||||
fresh routing information and changed facts, with full context retained for
|
||||
new sessions and resume failure.
|
||||
|
||||
---
|
||||
|
||||
Reusable workflows stay inside the Cases experiment. A workflow is a company-shared
|
||||
name and Markdown prompt; a case may adopt, leave and revisit workflows without
|
||||
changing its primary task. The task's workflow document is the effective copy,
|
||||
so shared edits affect future adoptions and explicit refreshes. Existing handoffs
|
||||
record workflow/phase movement and document revisions, including names as they
|
||||
were at the time. Authoring starts with agents/APIs; the case UI reads current
|
||||
workflow information and history.
|
||||
|
||||
## 1. Company Model [DRAFT]
|
||||
|
||||
A Company is a first-order object. One Paperclip instance runs multiple Companies. A Company does not have a standalone "goal" field — its direction is defined by its set of Initiatives (see Task Hierarchy Mapping).
|
||||
|
||||
### Fields (Draft)
|
||||
|
||||
| Field | Type | Notes |
|
||||
| ----------- | ------------- | --------------------------------- |
|
||||
| `id` | uuid | Primary key |
|
||||
| `name` | string | Company name |
|
||||
| `createdAt` | timestamp | |
|
||||
| `updatedAt` | timestamp | |
|
||||
|
||||
### Board Governance [DRAFT]
|
||||
|
||||
Every Company has a **Board** that governs high-impact decisions. The Board is the human oversight layer.
|
||||
|
||||
Human invitations default to Operator, with company editing, invitations,
|
||||
connections, tools, environments, and audit views available by
|
||||
default. Join approval and member-permission management remain separate grants.
|
||||
An inviter must hold these membership grants to invite a role that includes them.
|
||||
See [human Operator defaults](SPEC-implementation.md#91-board-auth).
|
||||
|
||||
**V1: Single human Board.** One human operator.
|
||||
|
||||
#### Board Approval Gates (V1)
|
||||
|
||||
- New Agent hires (creating new Agents)
|
||||
- CEO's initial strategic breakdown (CEO proposes, Board approves before execution begins)
|
||||
- [TBD: other governance-gated actions — goal changes, firing Agents?]
|
||||
|
||||
Connection tool reviews also appear in task history, with a composer takeover for
|
||||
human approval, decline, or scoped remembered permission. Connections and task
|
||||
views resolve the same review, and the agent continues with the server-recorded
|
||||
outcome. See [the implementation contract](SPEC-implementation.md#124-connection-tool-reviews).
|
||||
|
||||
Model authentication failures also surface a provider-specific Connections card
|
||||
on the task immediately after failure. Users can reconnect inline and resume;
|
||||
legacy agents keep their authentication until an explicit, validated adoption.
|
||||
Missing personal AI credentials found before a run starts use the same card.
|
||||
The responsible user connects their own account inside the task and continues.
|
||||
See [AI Connections](connections/AI-CONNECTIONS.md).
|
||||
|
||||
AI connections also expose an on-demand, credential-scoped usage probe. It
|
||||
reports provider windows, scoped exhaustion, reset times and overage observations
|
||||
for downstream decisions, with explicit unknown/unsupported/error states.
|
||||
Probing does not change runner routing or enforce provider limits automatically.
|
||||
|
||||
#### Board Powers (Always Available)
|
||||
|
||||
The Board has **unrestricted access** to the entire system at all times:
|
||||
|
||||
- **Set and modify Company budgets** — the Board sets top-level token/LLM cost budgets
|
||||
- **Pause/resume any Agent** — stop an Agent's heartbeat immediately
|
||||
- **Pause/resume any work item** — pause a task, project, subtask tree, milestone. Paused items are not picked up by Agents.
|
||||
- **Full project management access** — create, edit, comment on, modify, delete, reassign any task/project/milestone through the UI
|
||||
- **Override any Agent decision** — reassign tasks, change priorities, modify descriptions
|
||||
- **Manually change any budget** at any level
|
||||
|
||||
The Board is not just an approval gate — it's a live control surface. The human can intervene at any level at any time.
|
||||
|
||||
A Board status inquiry does not itself pause unfinished task execution. Native
|
||||
ordinary tasks that report blocking remaining work must continue, register a
|
||||
real wait, or surface a bounded recovery failure. Recorded approvals, questions,
|
||||
dependencies, and pauses remain authoritative; obsolete requests must not replay.
|
||||
|
||||
#### Budget Delegation
|
||||
|
||||
The Board sets Company-level budgets. The CEO can set budgets for Agents below them, and every manager Agent can do the same for their reports. How this cascading budget delegation works in practice is TBD, but the permission structure supports it. The Board can manually override any budget at any level.
|
||||
|
||||
**Future governance models** (not V1):
|
||||
|
||||
- Hiring budgets (auto-approve hires within $X/month)
|
||||
- Multi-member boards
|
||||
- Delegated authority (CEO can hire within limits)
|
||||
|
||||
### Open Questions
|
||||
|
||||
- External revenue/expense tracking — future plugin. Token/LLM cost budgeting is core.
|
||||
- Company-level settings and configuration?
|
||||
- Company lifecycle (pause, archive, delete)?
|
||||
- What governance-gated actions exist beyond hiring and CEO strategy approval?
|
||||
|
||||
---
|
||||
|
||||
## 2. Agent Model [DRAFT]
|
||||
|
||||
A human's personal primary agent is a company-scoped navigation and assignment
|
||||
preference, independent of the org chart, roles, stars, and authority. First human
|
||||
creation initializes it automatically. Later explicit choices persist across
|
||||
devices; recent task/chat choices take precedence. The profile owns the setting
|
||||
and replacement confirmation. See the personal-primary addendum in
|
||||
`SPEC-implementation.md` for persistence and lifecycle rules.
|
||||
|
||||
Every employee is an agent. Agents are the workforce.
|
||||
|
||||
### Cryptographic identity
|
||||
|
||||
Agents have persistent Ed25519 identities, encrypted in their home instance.
|
||||
New agents receive keys during creation; existing agents receive them lazily on
|
||||
their next managed run. Agents can read their keys from the managed process
|
||||
environment, and authorized readers can view or copy the public key from the
|
||||
agent page. This does not grant external authorization or change bearer-token
|
||||
access. See [the implementation contract](AGENT-IDENTITY.md).
|
||||
|
||||
### Agent Identity (Adapter-Level)
|
||||
|
||||
Concepts like SOUL.md (identity/mission) and HEARTBEAT.md (loop definition) are **not part of the Paperclip protocol**. They are adapter-specific configurations. For example, an OpenClaw adapter might use SOUL.md and HEARTBEAT.md files. A Claude Code adapter might use CLAUDE.md. A bare Python script might use command-line args.
|
||||
|
||||
Paperclip doesn't prescribe how an agent defines its identity or behavior. It provides the control plane; the adapter defines the agent's inner workings.
|
||||
|
||||
### Agent Configuration [DRAFT]
|
||||
|
||||
Each agent has an **adapter type** and an **adapter-specific configuration blob**. The adapter defines what config fields exist.
|
||||
|
||||
Configuration reads and changes have separate authority. `agents:read` permits
|
||||
redacted configuration and instruction reads; `agents:configure` includes reads
|
||||
and direct changes. Standard agents have read access by default. Company scope,
|
||||
explicit grant scopes, responsible-user authority and trust restrictions apply.
|
||||
See [agent permission defaults](agent-permission-defaults.md).
|
||||
|
||||
#### Paperclip Protocol (What Paperclip Knows)
|
||||
|
||||
At the protocol level, Paperclip tracks:
|
||||
|
||||
- Agent identity (id, name, role, title)
|
||||
- Org position (who they report to, who reports to them)
|
||||
- Adapter type + adapter config
|
||||
- Status (active, paused, terminated)
|
||||
- Cost tracking data (if the agent reports it)
|
||||
|
||||
#### Adapter Configuration (Agent-Specific)
|
||||
|
||||
Each adapter type defines its own config schema. Examples:
|
||||
|
||||
- **OpenClaw adapter**: SOUL.md content, HEARTBEAT.md content, OpenClaw-specific settings
|
||||
- **Process adapter**: command to run, environment variables, working directory
|
||||
- **HTTP adapter**: endpoint URL, auth headers, payload template
|
||||
|
||||
#### Exportable Org Configs
|
||||
|
||||
A key goal: **the entire org's agent configurations are exportable.** You can export a company's complete agent setup — every agent, their adapter configs, org structure — as a portable artifact. This enables:
|
||||
|
||||
- Sharing company templates ("here's a pre-built marketing agency org")
|
||||
- Version controlling your company configuration
|
||||
- Duplicating/forking companies
|
||||
|
||||
#### Context Delivery
|
||||
|
||||
Configurable per agent. Two ends of the spectrum:
|
||||
|
||||
- **Fat payload** — Paperclip bundles relevant context (current tasks, messages, company state, metrics) into the heartbeat invocation. Suited for simple/stateless agents that can't call back to Paperclip.
|
||||
- **Thin ping** — Heartbeat is just a wake-up signal. Agent calls Paperclip's API to fetch whatever context it needs. Suited for sophisticated agents that manage their own state.
|
||||
|
||||
#### Minimum Contract
|
||||
|
||||
The minimum requirement to be a Paperclip agent: **be callable.** That's it. Paperclip can invoke you via command or webhook. No requirement to report back — Paperclip infers basic status from process liveness when it can.
|
||||
|
||||
#### Integration Levels
|
||||
|
||||
Beyond the minimum, Paperclip provides progressively richer integration:
|
||||
|
||||
1. **Callable** (minimum) — Paperclip can start you. That's the only contract.
|
||||
2. **Status reporting** — Agent reports back success/failure/in-progress after execution.
|
||||
3. **Fully instrumented** — Agent reports status, cost/token usage, task updates, and logs. Bidirectional integration with the control plane.
|
||||
|
||||
Paperclip ships **default agents** that demonstrate full integration: progress tracking, cost instrumentation, and a **Paperclip skill** (a Claude Code skill for interacting with the Paperclip API) for task management. These serve as both useful defaults and reference implementations for adapter authors.
|
||||
|
||||
#### Export Formats
|
||||
|
||||
Two export modes:
|
||||
|
||||
1. **Template export** (default) — structure only: agent definitions, org chart, adapter configs, role descriptions. Optionally includes a few seed tasks to help get started. This is the blueprint for spinning up a new company.
|
||||
2. **Snapshot export** — full state: structure + current tasks, progress, agent status. A complete picture you could restore or fork.
|
||||
|
||||
The usual workflow: export a template, create a new company from it, add a couple initial tasks, go.
|
||||
|
||||
---
|
||||
|
||||
## 3. Org Structure [DRAFT]
|
||||
|
||||
Hierarchical reporting structure. CEO at top, reports cascade down.
|
||||
|
||||
### Agent Visibility
|
||||
|
||||
**Full visibility across the org.** Every agent can see the entire org chart, all tasks, all agents. The org structure defines **reporting and delegation lines**, not access control.
|
||||
|
||||
Visibility settings on an agent profile do not control task privacy. Work is company-open by default; opt-in private tasks and projects use centralized authorization as specified in `SPEC-implementation.md` and `ISSUE-PRIVACY.md`. Sharing a child grants access to it and its descendants. Ancestors and siblings require separate access.
|
||||
|
||||
Each agent publishes a short description of their responsibilities and capabilities — almost like skills ("when I'm relevant"). This lets other agents discover who can help with what.
|
||||
|
||||
### Cross-Team Work
|
||||
|
||||
Agents can create tasks and assign them to agents outside their reporting line. This is the mechanism for cross-team collaboration. These rules are primarily encoded in the Paperclip SKILL.md which is recommended for all agents. Paperclip the app enforces the tooling and some light governance, but the cross-team rules below are mainly implemented by agent decisions.
|
||||
|
||||
#### Task Acceptance Rules
|
||||
|
||||
When an agent receives a task from outside their team:
|
||||
|
||||
1. **Agrees it's appropriate + can do it** → complete it directly
|
||||
2. **Agrees it's appropriate + can't do it** → mark as blocked
|
||||
3. **Questions whether it's worth doing** → **cannot cancel it themselves.** Must reassign to their own manager, explain the situation. Manager decides whether to accept, reassign, or escalate.
|
||||
|
||||
#### Manager Escalation Protocol
|
||||
|
||||
It's any manager's responsibility to understand why their subordinates are blocked and resolve it:
|
||||
|
||||
0. **Decide** — as a manager, is this work worth doing?
|
||||
1. **Delegate down** — ask someone under them to help unblock
|
||||
2. **Escalate up** — ask the manager above them for help
|
||||
|
||||
#### Request Depth Tracking
|
||||
|
||||
When a task originates from a cross-team request, track the **depth** as an integer — how many delegation hops from the original requester. This provides visibility into how far work cascades through the org.
|
||||
|
||||
#### Billing Codes
|
||||
|
||||
Task detail keeps hierarchy separate from creation provenance: the Tasks tab shows
|
||||
all subtasks and, independently, work created from the current task grouped by
|
||||
project or No project. A created subtask may appear in both sections. Creation
|
||||
provenance follows the originating run equally for legacy and native runners.
|
||||
|
||||
Tasks carry a **billing code** so that token spend during execution can be attributed upstream to the requesting task/agent. When Agent A asks Agent B to do work, the cost of B's work is tracked against A's request. This enables cost attribution across the org.
|
||||
|
||||
### Open Questions
|
||||
|
||||
- Is this a strict tree or can agents report to multiple managers?
|
||||
- Can org structure change at runtime? (agents reassigned, teams restructured)
|
||||
- Do agents inherit any configuration from their manager?
|
||||
- Billing code format — simple string? Hierarchical?
|
||||
|
||||
---
|
||||
|
||||
## 4. Heartbeat System [DRAFT]
|
||||
|
||||
The heartbeat is a protocol, not a runtime. Paperclip defines how to initiate an agent's cycle. What the agent does with that cycle — how long it runs, whether it's task-scoped or continuous — is entirely up to the agent.
|
||||
|
||||
### Execution Adapters
|
||||
|
||||
Agent configuration includes an **adapter** that defines how Paperclip invokes the agent. Built-in adapters include:
|
||||
|
||||
| Adapter | Mechanism | Example |
|
||||
| ---------------- | -------------------------- | -------------------------------------------------- |
|
||||
| `process` | Execute a child process | `python run_agent.py --agent-id {id}` |
|
||||
| `http` | Send an HTTP request | `POST https://openclaw.example.com/hook/{id}` |
|
||||
| `claude_local` | Local Claude Code process | Claude Code heartbeat worker |
|
||||
| `codex_local` | Local Codex process | Codex CLI heartbeat worker |
|
||||
| `opencode_local` | Local OpenCode process | OpenCode heartbeat worker |
|
||||
| `pi_local` | Local Pi process | Pi CLI heartbeat worker |
|
||||
| `cursor` | Cursor API/CLI bridge | Cursor-integrated heartbeat worker |
|
||||
| `openclaw_gateway` | OpenClaw gateway API | Managed OpenClaw agent via gateway |
|
||||
| `hermes_local` | Local Hermes process | Hermes agent heartbeat worker |
|
||||
|
||||
The `process` and `http` adapters ship as generic defaults. Additional built-in adapters cover common local coding runtimes (see list above), and new adapter types can be registered via the plugin system (see Plugin / Extension Architecture).
|
||||
|
||||
An adapter's selected execution engine is part of its permission and session
|
||||
contract. Missing prerequisites or engine failures must be surfaced without
|
||||
silently launching a different engine. A default local engine must support
|
||||
normal task work and control-plane coordination; explicit operator restrictions
|
||||
remain authoritative.
|
||||
|
||||
### Adapter Interface
|
||||
|
||||
Every adapter implements three methods:
|
||||
|
||||
```
|
||||
invoke(agentConfig, context?) → void // Start the agent's cycle
|
||||
status(agentConfig) → AgentStatus // Is it running? finished? errored?
|
||||
cancel(agentConfig) → void // Graceful stop signal (for pause/resume)
|
||||
```
|
||||
|
||||
This is the full adapter contract. `invoke` starts the agent, `status` lets Paperclip check on it, `cancel` enables the board's pause functionality. Everything else (cost reporting, task updates) is optional and flows through the Paperclip REST API.
|
||||
|
||||
### What Paperclip Controls
|
||||
|
||||
- **When** to fire the heartbeat (schedule/frequency, per-agent)
|
||||
- **How** to fire it (adapter selection + config)
|
||||
- **What context** to include (thin ping vs. fat payload, per-agent)
|
||||
|
||||
### What Paperclip Does NOT Control
|
||||
|
||||
- How long the agent runs
|
||||
- What the agent does during its cycle
|
||||
- Whether the agent is task-scoped, time-windowed, or continuous
|
||||
|
||||
### Pause Behavior
|
||||
|
||||
When the board (or system) pauses an agent:
|
||||
|
||||
1. **Signal the current execution** — send a graceful termination signal to the running process/session
|
||||
2. **Grace period** — give the agent time to wrap up, save state, report final status
|
||||
3. **Force-kill after timeout** — if the agent doesn't stop within the grace period, terminate
|
||||
4. **Stop future heartbeats** — no new heartbeat cycles will fire until the agent is resumed
|
||||
|
||||
This is "graceful signal + stop future heartbeats." The current run gets a chance to land cleanly.
|
||||
|
||||
### Open Questions
|
||||
|
||||
- Heartbeat frequency — who controls it? Fixed? Per-agent? Cron-like?
|
||||
- What happens when a heartbeat invocation fails? (process crashes, HTTP 500)
|
||||
- Health monitoring — how does Paperclip distinguish "stuck" from "working on a long task"?
|
||||
- Can agents self-trigger their next heartbeat? ("I'm done, wake me again in 5 min")
|
||||
- Grace period duration — fixed? configurable per agent?
|
||||
|
||||
---
|
||||
|
||||
## 5. Inter-Agent Communication [DRAFT]
|
||||
|
||||
All agent communication flows through the **task system**.
|
||||
|
||||
### Model: Tasks + Comments
|
||||
|
||||
- **Delegation** = creating a task and assigning it to another agent
|
||||
- **Coordination** = commenting on tasks
|
||||
- **Status updates** = updating task status and fields
|
||||
|
||||
Low-trust agents can create self-assigned tasks and subtasks within their
|
||||
permitted scope, subject to assignment permissions and the responsible user's
|
||||
authority. Created work retains containment. An authorized user's direct message
|
||||
in their own Agent Chat may authorize an agent to edit its own `AGENTS.md`;
|
||||
outside work and subtasks do not inherit this authority. Permission failures
|
||||
should name the rejected action and the specific restriction.
|
||||
|
||||
There is no separate messaging or chat system. Tasks are the communication channel. This keeps all context attached to the work it relates to and creates a natural audit trail.
|
||||
|
||||
Experimental external chat and voice connections are transports into this task
|
||||
system. They preserve the selected agent, task context, current caller authority,
|
||||
and governed-action checks; a voice session is not a separate authority or inbox.
|
||||
Experimental Agent Chat presents one persistent task per person and agent as a simplified conversation. Chat has a searchable secondary sidebar with agent avatars that lists every eligible agent, conversations first; adding an agent starts or reopens their single conversation. It retains the task composer, transcript, tools, attachments, documents, and existing Subtasks panel, with ordinary company visibility. New execution tasks are ordinary project tasks, not children of the conversation. Idle conversations wait for a message without entering execution-task work queues. Agents clarify goals here and create assigned tasks for substantial execution. `/new` resets provider context at an ordered session boundary within the same task while preserving visible history. `enableAgentChat` is disabled by default; the V1 lifecycle and rollout contract is specified in `SPEC-implementation.md`.
|
||||
|
||||
### Question recipients
|
||||
|
||||
Ordinary Agent Chat questions use the server-owned conversation recipient.
|
||||
Task questions may optionally name a particular user or agent. Explicit user
|
||||
recipients must be valid and authorized in the company before a question is
|
||||
saved. See `SPEC-implementation.md` §9.8.1 for the resolver contract.
|
||||
|
||||
|
||||
Experimental Agent Chat presents one persistent task per person and agent as a simplified conversation. Chat has a searchable secondary sidebar with agent avatars; adding an agent starts or reopens their single conversation. It retains the task composer, transcript, tools, attachments, documents, and existing Subtasks panel, with the task's selected visibility. New execution tasks are ordinary project tasks, not structural children of the conversation; private-source restrictions still flow through their run provenance. Idle conversations wait for a message without entering execution-task work queues. Agents clarify goals here and create assigned tasks for substantial execution. `/new` resets provider context at an ordered session boundary within the same task while preserving visible history. `enableAgentChat` is disabled by default; the V1 lifecycle and rollout contract is specified in `SPEC-implementation.md`.
|
||||
|
||||
### Implications
|
||||
|
||||
- An agent's "inbox" is: tasks assigned to them + comments on tasks they're involved in
|
||||
- A human's Mine inbox and its badge include failed runs attributed to that human, not another user's runs. All retains company-wide failure visibility. Historical unattributed runs remain in the local single-user board's Mine view; see `SPEC-implementation.md` for the routing contract.
|
||||
- The CEO delegates by creating tasks assigned to the CTO
|
||||
- The CTO breaks those down into sub-tasks assigned to engineers
|
||||
- Discussion happens in task comments, not a side channel
|
||||
- If an agent needs to escalate, they comment on the parent task or reassign
|
||||
|
||||
### Task Hierarchy Mapping
|
||||
|
||||
Full hierarchy: **Initiative** (company goal) → Projects → Milestones → Issues → Sub-issues. Everything traces back to an initiative, and the "company goal" is just the first/primary initiative.
|
||||
|
||||
---
|
||||
|
||||
## 6. Cost Tracking [DRAFT]
|
||||
|
||||
Token/LLM cost budgeting is a core part of Paperclip. External revenue and expense tracking is a future plugin.
|
||||
|
||||
### Cost Reporting
|
||||
|
||||
Fully-instrumented Agents report token/API usage back to Paperclip. Costs are tracked at every level:
|
||||
|
||||
- **Per Agent** — how much is this employee costing?
|
||||
- **Per task** — how much did this unit of work cost?
|
||||
- **Per project** — how much is this deliverable costing?
|
||||
- **Per Company** — total burn rate
|
||||
|
||||
Costs should be denominated in both **tokens and dollars**.
|
||||
|
||||
Billing codes on tasks (see Org Structure) enable cost attribution across teams — when Agent A requests work from Agent B, B's costs roll up to A's request.
|
||||
|
||||
### Budget Controls
|
||||
|
||||
Three tiers:
|
||||
|
||||
1. **Visibility** — dashboards showing spend at every level (Agent, task, project, Company)
|
||||
2. **Soft alerts** — configurable thresholds (e.g. warn at 80% of budget)
|
||||
3. **Hard ceiling** — auto-pause the Agent when budget is hit. Board notified. Board can override/raise the limit.
|
||||
|
||||
Budgets can be set to **unlimited** (no ceiling).
|
||||
|
||||
### Open Questions
|
||||
|
||||
- Cost reporting API — what's the schema for an agent to report costs?
|
||||
- Dashboard design — what metrics matter most at each level?
|
||||
- Budget period — per-day? per-week? per-month? rolling?
|
||||
|
||||
---
|
||||
|
||||
## 7. Default Agents & Bootstrap Flow [DRAFT]
|
||||
|
||||
### Bootstrap Sequence
|
||||
|
||||
How a Company goes from "created" to "running":
|
||||
|
||||
1. Human creates a Company and its initial Initiatives
|
||||
2. Human defines initial top-level tasks
|
||||
3. Human creates the CEO Agent (using the default CEO template or custom)
|
||||
4. CEO's first heartbeat: reviews the Initiatives and tasks, proposes a strategic breakdown (org structure, sub-tasks, hiring plan)
|
||||
5. **Board approves** the CEO's strategic plan
|
||||
6. CEO begins execution — creating tasks, proposing hires (Board-approved), delegating
|
||||
|
||||
### Default Agents
|
||||
|
||||
Paperclip ships default Agent templates:
|
||||
|
||||
- **Default Agent** — a basic Claude Code or Codex loop. Knows the **Paperclip Skill** (SKILL.md) so it can interact with the task system, read Company context, report status.
|
||||
- **Default CEO** — extends the Default Agent with CEO-specific behavior: strategic planning, delegation to reports, progress review, Board communication.
|
||||
|
||||
These are starting points. Users can customize or replace them entirely.
|
||||
|
||||
### Default Agent Behavior
|
||||
|
||||
The default agent's loop is **config-driven**. The adapter config contains the instructions that define what the agent does on each heartbeat cycle. There is no hardcoded standard loop — each agent's config determines its behavior.
|
||||
|
||||
This means the default CEO config tells the CEO to review strategy, check on reports, etc. The default engineer config tells the engineer to check assigned tasks, pick the highest priority, and work it. But these are config choices, not protocol requirements.
|
||||
|
||||
### Paperclip Skill (SKILL.md)
|
||||
|
||||
A skill definition that teaches agents how to interact with Paperclip. Provides:
|
||||
|
||||
- Task CRUD (create, read, update, complete tasks)
|
||||
- Status reporting (check in, report progress)
|
||||
- Company context (read goal, org chart, current state)
|
||||
- Cost reporting (log token/API usage)
|
||||
- Inter-agent communication rules
|
||||
|
||||
This skill is adapter-agnostic — it can be loaded into Claude Code, injected into prompts, or used as API documentation for custom agents.
|
||||
|
||||
---
|
||||
|
||||
## 8. Architecture & Deployment [DRAFT]
|
||||
|
||||
### Deployment Model
|
||||
|
||||
**Single-tenant, self-hostable.** Not a SaaS. One instance = one operator's companies.
|
||||
|
||||
#### Development Path (Progressive Deployment)
|
||||
|
||||
1. **Local dev** — One command to install and run. Embedded Postgres. Everything on your machine. Agents run locally.
|
||||
2. **Hosted** — Deploy to Vercel/Supabase/AWS/anywhere. Remote agents connect to your server with a shared database. The UI is accessible via the web.
|
||||
3. **Open company** — Optionally make parts public (e.g. a job board visible to the public for open companies).
|
||||
|
||||
The key constraint: it must be trivial to go from "I'm trying this on my machine" to "my agents are running on remote servers talking to my Paperclip instance."
|
||||
|
||||
#### Agent Authentication
|
||||
|
||||
When a user creates an Agent, Paperclip generates a **connection string** containing: the server URL, an API key, and instructions for how to authenticate. The Agent is assumed to be capable of figuring out how to call the API with its token/key from there.
|
||||
|
||||
Flow:
|
||||
|
||||
1. Human creates an Agent in the UI
|
||||
2. Paperclip generates a connection string (URL + key + instructions)
|
||||
3. Human provides this string to the Agent (e.g. in its adapter config, environment, etc.)
|
||||
4. Agent uses the key to authenticate API calls to the control plane
|
||||
|
||||
### Tech Stack
|
||||
|
||||
| Layer | Technology |
|
||||
| -------- | ------------------------------------------------------------ |
|
||||
| Frontend | React + Vite |
|
||||
| Backend | TypeScript + Express (REST API, not tRPC — need non-TS clients) |
|
||||
| Database | PostgreSQL (see [doc/DATABASE.md](./doc/DATABASE.md) for details — PGlite embedded for dev, Docker or hosted Supabase for production) |
|
||||
| Auth | [Better Auth](https://www.better-auth.com/) |
|
||||
|
||||
### Concurrency Model: Atomic Task Checkout
|
||||
|
||||
Tasks use **single assignment** (one agent per task) with **atomic checkout**:
|
||||
|
||||
1. Agent attempts to set a task to `in_progress` (claiming it)
|
||||
2. The API/database enforces this atomically — if another agent already claimed it, the request fails with an error identifying which agent has it
|
||||
3. If the task is already assigned to the requesting agent from a previous session, they can resume
|
||||
|
||||
No optimistic locking or CRDTs needed. The single-assignment model + atomic checkout prevents conflicts at the design level.
|
||||
|
||||
Agent @-mentions provide context without waking agents or changing task ownership. New work requires explicit assignment, delegation, or a review request; ordinary issue comments can still wake the current assignee.
|
||||
|
||||
Releasing a terminal task clears execution locks while preserving its assigned
|
||||
owner and final status. Assignment remains part of the work history after Done
|
||||
or Cancelled. Releasing unfinished work still relinquishes the agent assignment;
|
||||
only an active `in_progress` task returns to `todo`.
|
||||
|
||||
### Human in the Loop
|
||||
|
||||
Agents can create tasks assigned to humans. The board member (or any human with access) can complete these tasks through the UI.
|
||||
|
||||
When a human completes a task, if the requesting agent's adapter supports **pingbacks** (e.g. OpenClaw hooks), Paperclip sends a notification to wake that agent. This keeps humans rare but possible participants in the workflow.
|
||||
|
||||
The agents are discouraged from assigning tasks to humans in the Paperclip SKILL, but sometimes it's unavoidable.
|
||||
|
||||
### API Design
|
||||
|
||||
**Single unified REST API.** The same API serves both the frontend UI and agents. Authentication determines permissions — board auth has full access, agent API keys have scoped access (their own tasks, cost reporting, company context).
|
||||
|
||||
No separate "agent API" vs. "board API." Same endpoints, different authorization levels.
|
||||
|
||||
### Work Artifacts
|
||||
|
||||
Paperclip manages task-linked work artifacts: issue documents (rich-text plans, specs, notes attached to issues) and file attachments. Agents read and write these through the API as part of normal task execution. Full delivery infrastructure (code repos, deployments, production runtime) remains the agent's domain — Paperclip orchestrates the work, not the build pipeline.
|
||||
|
||||
Self-contained HTML reports can render in an opaque-origin sandbox. The report
|
||||
cannot access the board's cookies, storage, or DOM. Users can switch to the raw
|
||||
source beside Download, which returns the original file.
|
||||
|
||||
Users may start a task with only a prompt. Paperclip uses a short prompt slice as
|
||||
its initial title and asks the assigned agent to name the task early. Explicit
|
||||
user titles are preserved, and naming does not change task execution state.
|
||||
|
||||
Task work mode is explicit persisted state. Requesting a plan in a title or description does not switch the task into planning mode. Standard execution may produce a plan as its requested deliverable; explicit planning mode separately governs plan-only execution and its approval transition.
|
||||
|
||||
### Open Questions
|
||||
|
||||
- Real-time updates to the UI — WebSocket? SSE? Polling?
|
||||
- Agent API key scoping — what exactly can an Agent access? Only their own tasks? Their team's? The whole Company?
|
||||
|
||||
### Crash Recovery: Manual, Not Automatic
|
||||
|
||||
When an agent crashes or disappears mid-task, Paperclip does **not** auto-reassign or auto-release the task. Instead:
|
||||
|
||||
- Paperclip surfaces stale tasks (tasks in `in_progress` with no recent activity) through dashboards and reporting
|
||||
- Paperclip may perform bounded continuity repair with the same assigned agent; when that is exhausted or unsafe, it opens a board-owned recovery action without waking a substitute agent
|
||||
- Paperclip does not fail silently — the auditing and visibility tools make problems obvious
|
||||
- Recovery is handled by humans or by emergent processes (e.g. a project manager agent whose job is to monitor for stale work and surface it)
|
||||
|
||||
**Principle: Paperclip reports problems, it doesn't silently fix them.** Automatic recovery hides failures. Good visibility lets the right entity (human or agent) decide what to do.
|
||||
|
||||
### Plugin / Extension Architecture
|
||||
|
||||
The core Paperclip system must be extensible. Features like knowledge bases, external revenue tracking, and new Agent Adapters should be addable as **plugins** without modifying core. This means:
|
||||
|
||||
- Well-defined API boundaries that plugins can hook into
|
||||
- Event system or hooks for reacting to task/Agent lifecycle events
|
||||
- **Agent Adapter plugins** — new Adapter types can be registered via the plugin system
|
||||
- Plugin-registrable UI components (future)
|
||||
|
||||
The plugin framework has shipped. Plugins can register new adapter types, hook into lifecycle events, and contribute UI components (e.g. global toolbar buttons). A plugin SDK and CLI commands (`paperclipai plugin`) are available for authoring and installing plugins.
|
||||
|
||||
---
|
||||
|
||||
## 9. Frontend / UI [DRAFT]
|
||||
|
||||
### Primary Views
|
||||
|
||||
Each is a distinct page/route:
|
||||
|
||||
1. **Org Chart** — the org tree with live status indicators (running/idle/paused/error) per agent. Real-time activity feed of what agents are doing.
|
||||
2. **Task Board** — Task management. Kanban and list views. Filter by team, agent, project, status.
|
||||
3. **Dashboard** — high-level metrics: agent count, active tasks, costs, goal progress, burn rate. The "glance" view from GOAL.md.
|
||||
4. **Agent Detail** — deep dive on a single agent: their tasks, activity, costs, configuration, status history.
|
||||
5. **Project/Initiative Views** — progress tracking against milestones and goals.
|
||||
6. **Cost Dashboard** — spend visualization at every level (agent, task, project, company).
|
||||
|
||||
### Board Controls (Available Everywhere)
|
||||
|
||||
- Pause/resume agents (any view)
|
||||
- Pause/resume tasks/projects (any view)
|
||||
- Approve/reject pending actions (hiring, strategy proposals)
|
||||
- Direct task creation, editing, commenting
|
||||
|
||||
---
|
||||
|
||||
## 10. V1 Scope (MVP) [DRAFT]
|
||||
|
||||
**Full loop with one adapter.** V1 must demonstrate the complete Paperclip cycle end-to-end, even if narrow.
|
||||
|
||||
### Must Have (V1)
|
||||
|
||||
- [ ] **Company CRUD** — create a Company with Initiatives
|
||||
- [ ] **Agent CRUD** — create/edit/pause/resume Agents with Adapter config
|
||||
- [ ] **Org chart** — define reporting structure, visualize it
|
||||
- [ ] **Process adapter** — invoke(), status(), cancel() for local child processes
|
||||
- [ ] **Task management** — full lifecycle with hierarchy (tasks trace to company goal)
|
||||
- [ ] **Atomic task checkout** — single assignment, in_progress locking
|
||||
- [ ] **Board governance** — human approves hires, pauses Agents, sets budgets, full PM access
|
||||
- [ ] **Cost tracking** — Agents report token usage, per-Agent/task/Company visibility
|
||||
- [ ] **Budget controls** — soft alerts + hard ceiling with auto-pause
|
||||
- [ ] **Default agent** — basic Claude Code/Codex loop with Paperclip skill
|
||||
- [ ] **Default CEO** — strategic planning, delegation, board communication
|
||||
- [ ] **Paperclip skill (SKILL.md)** — teaches agents to interact with the API
|
||||
- [ ] **REST API** — full API for agent interaction (Express)
|
||||
- [ ] **Web UI** — React/Vite: org chart, task board, dashboard, cost views
|
||||
- [ ] **Agent auth** — connection string generation with URL + key + instructions
|
||||
- [ ] **One-command dev setup** — embedded PGlite, everything local
|
||||
- [ ] **Multiple Adapter types** (HTTP, OpenClaw gateway, and local coding adapters)
|
||||
|
||||
### Not V1
|
||||
|
||||
- Knowledge base - a future plugin
|
||||
- Advanced governance models (hiring budgets, multi-member boards)
|
||||
- Revenue/expense tracking beyond token costs - a future plugin
|
||||
- Public job board / open company features
|
||||
|
||||
---
|
||||
|
||||
## 11. Knowledge Base
|
||||
|
||||
**Anti-goal for core.** The knowledge base is not part of the Paperclip core — it will be a plugin. The task system + comments + agent descriptions provide sufficient shared context.
|
||||
|
||||
The architecture must support adding a knowledge base plugin later (clean API boundaries, hookable lifecycle events) but the core system explicitly does not include one.
|
||||
|
||||
---
|
||||
|
||||
## 12. Anti-Requirements
|
||||
|
||||
Things Paperclip explicitly does **not** do:
|
||||
|
||||
- **Not an Agent runtime** — Paperclip orchestrates, Agents run elsewhere
|
||||
- **Not a knowledge base** — core has no wiki/docs/vector-DB (plugin territory)
|
||||
- **Not a SaaS** — single-tenant, self-hosted
|
||||
- **Not opinionated about Agent implementation** — any language, any framework, any runtime
|
||||
- **Not automatically self-healing** — surfaces problems, doesn't silently fix them
|
||||
- **Does not manage delivery infrastructure** — no repo management, no deployment, no file systems (but does manage task-linked documents and attachments)
|
||||
- **Does not auto-reassign work** — stale tasks are surfaced, not silently redistributed
|
||||
- **Does not track external revenue/expenses** — that's a future plugin. Token/LLM cost budgeting is core.
|
||||
|
||||
---
|
||||
|
||||
## 13. Principles (Consolidated)
|
||||
|
||||
1. **Unopinionated about how you run your Agents.** Any language, any framework, any runtime. Paperclip is the control plane, not the execution plane.
|
||||
2. **Company is the unit of organization.** Everything lives under a Company.
|
||||
3. **Tasks are the communication channel.** All Agent communication flows through tasks + comments. No side channels.
|
||||
4. **All work traces to the goal.** Hierarchical task management — nothing exists in isolation.
|
||||
5. **Board governs.** Humans retain control through the Board. Conservative defaults (human approval required).
|
||||
6. **Surface problems, don't hide them.** Good auditing and visibility. No silent auto-recovery.
|
||||
7. **Atomic ownership.** Single assignee per task. Atomic checkout prevents conflicts.
|
||||
8. **Progressive deployment.** Trivial to start local, straightforward to scale to hosted.
|
||||
9. **Extensible core.** Clean boundaries so plugins can add capabilities (Adapters, knowledge base, revenue tracking) without modifying core.
|
||||
|
||||
## Agent visual identity
|
||||
|
||||
Agent appearances are stable, versioned ClipLab end-cap personas, separate from
|
||||
behavioral instructions. Compact surfaces use on-demand cached PNG URLs; larger
|
||||
placements may use a lazy live character. See [agent-personas.md](agent-personas.md)
|
||||
for persistence, migration, rendering, and integration contracts.
|
||||
### Agent chat project handoff (2026-09-11)
|
||||
|
||||
Chat supports research and full plan drafting/revision in its existing plan document. On handoff, each ordinary assigned task receives the relevant plan in its own `plan` document, committed with task creation before execution is scheduled. The source plan remains in the conversation. Plan acceptance hands off execution; it never switches the conversation into implementation.
|
||||
|
||||
Chat instructions require selecting a suitable project, reusing an existing one where appropriate. The project requirement is prompt-only; ordinary projectless tasks remain supported. New parent relationships beneath conversation tasks are rejected by task services, including direct API creation and reparenting. Existing children remain readable/editable and can be moved elsewhere. The Subtasks panel is unchanged.
|
||||
|
||||
The `create_project` runtime tool uses the normal project API with durable idempotency. `list_projects` and `list_project_repositories` support selection. Multiple `repositoryIds` select authorized catalog entries; multiple HTTPS GitHub `repositoryUrls` register existing repositories absent from the catalog. IDs and URLs may be combined, but cannot accompany an explicit `workspace`. URLs do not create repositories on GitHub or grant credentials. Execution uses normal repository access rules. Repository IDs are revalidated against the authenticated run's responsible user and connection grants. Agents should consider proper available repositories, clarify material ambiguity, and use repository-free projects when appropriate for non-code work.
|
||||
|
||||
Confirmed project creation appears as a durable card in the shared task transcript, including selected repository links. Tasks are linked inline. Failed creation never produces a success card. Tool evals cover planning/handoff, project/repository selection, retries, permission and mode denials, and ordinary delegation regressions using the production chat directive.
|
||||
|
||||
Task replies and new tasks submit with Enter by default; Shift+Enter adds a new
|
||||
line. The **Command/Ctrl+Enter to Submit** experiment restores the previous
|
||||
keyboard behavior.
|
||||
|
||||
### Paused task messages
|
||||
|
||||
A paused task takes over the composer with an amber notice and a Resume action.
|
||||
Operators must release the effective task or ancestor pause before sending a new
|
||||
message. The draft stays intact. This applies to both task interfaces and to
|
||||
board comment API requests; an agent may still report interrupted work.
|
||||
|
||||
### External channel failure scope
|
||||
|
||||
An operation-level permission denial must not disable unrelated channel work.
|
||||
Authentication failures pause runtime use while preserving the user's connection
|
||||
setting. Explicit disconnect and provider installation revocation remain enforced.
|
||||
See the implementation spec for publication, provider-reply, and form-open rules.
|
||||
|
||||
### Experimental iMessage Photon channel
|
||||
|
||||
A Photon Cloud project can represent one agent through the existing
|
||||
experimental channel subsystem. DMs and explicitly enabled groups create or
|
||||
continue task-bound conversations. Linked sender identity is the default;
|
||||
telephone numbers, email addresses, names, and group membership do not grant
|
||||
Paperclip authority. Photos/files and ordinary questions/confirmations use the
|
||||
existing attachment, interaction, continuation, and publication contracts.
|
||||
Pause and Disconnect govern runtime behavior independently of the UI gate.
|
||||
Local Mac access, unsolicited conversations, and SMS/RCS
|
||||
fallback are excluded. Live qualification is required before release readiness.
|
||||
Pro shared allocation supports DMs only, with sender enrollment in Photon and
|
||||
separate identity linking in Paperclip. Shared channels reserve one project, not
|
||||
a pool phone number; group admission and publication are disabled. Dedicated
|
||||
allocation retains one selected number and individually enabled groups.
|
||||
|
||||
See [iMessage Photon](connections/IMESSAGE-PHOTON.md) for the implementation
|
||||
contract, setup, recovery, boundaries, and qualification status.
|
||||
|
||||
## Task search relevance
|
||||
|
||||
Task discovery uses PostgreSQL and the existing search indexes, with no external
|
||||
search service or background indexing job. The task-list quick search and full
|
||||
company search share lexical matching and ranking. Known identifiers and direct
|
||||
title matches lead; current conversation and document content supplies supporting
|
||||
evidence. See [Task search relevance](SEARCH.md) for the evaluation rubric,
|
||||
matching contract and reproducible quality tests.
|
||||
|
||||
### Keyboard shortcuts
|
||||
|
||||
Keyboard shortcuts are always enabled for every signed-in user. There is no
|
||||
instance setting and no personal preference that turns them off.
|
||||
|
||||
Managed agents own a persistent file directory across tasks and sessions. The
|
||||
Instructions Editor and stopped agent execution synchronize the same current
|
||||
files, including AGENTS.md and its supporting files. Task working directories and
|
||||
provider home directories remain separate concepts. Concurrent runs synchronize only
|
||||
the files they change, with the last sync winning for the same file. Temporary
|
||||
copies are cleaned up; this storage does not add a revision-history system. See
|
||||
[agent-files.md](agent-files.md) for lifecycle and upgrade compatibility.
|
||||
|
||||
Full agent storage produces a run warning without stopping current or future
|
||||
work. Storage limits constrain saved file changes, not the agent's ability to run
|
||||
and remove files to recover space.
|
||||
|
||||
### Unsafe native workspace exports
|
||||
|
||||
An unsafe workspace link does not fail an accepted native task result. Retry
|
||||
export automatically with confined entries only and keep archive confinement in
|
||||
place. If the export remains unsafe, omit it and finish the saved result under
|
||||
normal completion rules. Record diagnostics only in run logs; do not add a task
|
||||
warning or manual repair action. This also applies to historical unsafe failures:
|
||||
omit the already-rejected export, clear stale repair notices, and finalize the
|
||||
accepted result without another provider turn, even when its old sandbox is
|
||||
unavailable. Preserve current ownership and newer-work fences. See
|
||||
`native-workspace-finalization-recovery.md`.
|
||||
|
||||
### Git-backed skill library sources
|
||||
|
||||
Repositories can supply read-only company skills independently of project repositories.
|
||||
A source tracks repository identity, branch, selected paths, and installed commits;
|
||||
an existing GitHub connection supplies caller-authorized reads. Manual refresh publishes
|
||||
complete local immutable versions, preserving skill identity and assignments. Selection
|
||||
operates on whole skill packages, with inspectable included files, declared runtime
|
||||
requirements, and advisory warnings for missing or external references. A repository
|
||||
package retains supported source files while the user selects which skill entrypoints
|
||||
appear in the library. Authored content remains unchanged and shared files travel to
|
||||
the runtime. A declarative manifest can suggest public entrypoints and setup requirements;
|
||||
new imports keep repository files together and select all discovered skills. Missing
|
||||
references, setup problems and omitted files produce persistent warnings. Files rejected
|
||||
for unsafe execution or secret disclosure are excluded without blocking other files.
|
||||
Oversized repositories use a bounded package of skill folders and referenced files
|
||||
with their original paths. Missing references do not block a valid selected skill;
|
||||
fallback preserves previously installed shared dependencies or retains the old version.
|
||||
The installed file viewer exposes saved repository dependencies. Importing never runs
|
||||
setup or configures host tools. New
|
||||
upstream skills require reviewed selection; removed or deselected skills remain
|
||||
installed. Editing starts with an independent copy. Write-back and PR publication
|
||||
are a later milestone; exact path and commit provenance provide their base.
|
||||
|
||||
## Public assistant connection (opt-in)
|
||||
|
||||
The user-authorized MCP surface connects assistants to an explicitly selected
|
||||
company as the consenting person. It exposes first-party task reads, additive
|
||||
task creation and comments, durable documents and approval links. It reuses
|
||||
existing domain authorization and scheduling; OAuth does not grant agent
|
||||
identity, native run ownership, approval decisions or third-party credentials.
|
||||
See [Public MCP](public-mcp.md) for the implemented instance-side boundary,
|
||||
configuration, plugin packages and outstanding hosted release gates. The
|
||||
[delivery plan](plans/2026-09-30-paperclip-public-mcp-and-plugins.md) separates
|
||||
external agent participation and granted third-party tools into later releases.
|
||||
|
||||
The experimental OpenAI Dot Runner provider uses a separate `/mcp/runner`
|
||||
agent OAuth resource. It reuses browser/device consent and signed event delivery
|
||||
while preserving agent pairing, normal run admission and task authority.
|
||||
Personal grants cannot authorize Runner operations. See
|
||||
[OpenAI Dot Runner](openai-dot-runner.md) for its supported release boundary.
|
||||
|
||||
Personal Meta Muse is another experimental named Runner agent. Its managed
|
||||
receiver uses short-lived pairing and rotating private credentials; its human
|
||||
authorizer remains distinct from the agent identity. Paperclip owns admission,
|
||||
task authority, and native finalization. Detector health alone does not prove
|
||||
execution, and uncertain remote effects prevent overlapping dispatch. See
|
||||
[Personal Muse receiver](muse-personal-agent.md) for setup, stopping limits, and
|
||||
the required live qualification before release.
|
||||
|
||||
### Experimental connection routing
|
||||
|
||||
A virtual AI connection can rotate new task/agent allocations through an
|
||||
authorized pool while preserving session affinity. Admission, credentials and
|
||||
durable recovery remain host responsibilities; policy can be supplied by an
|
||||
opt-in plugin. See [the experimental contract](connections/AI-CONNECTION-ROUTERS.md).
|
||||
|
||||
## Internal agent commentary
|
||||
|
||||
The Audit → Commentary tab exposes searchable suggestions and complaints,
|
||||
with agent/type filters, message previews and full attributed context. The viewer
|
||||
preserves company, commentary-permission and task-privacy boundaries independently
|
||||
of the agent submission path. All human company members can read commentary by
|
||||
default, including viewers, without receiving agent-action audit access.
|
||||
|
||||
`agent_commentary` stores company-scoped, attributed complaints and suggestions
|
||||
as free-form text in the instance database. Legacy agents use the default
|
||||
`complain` and `suggestion-box` runtime skills; native runs use dedicated tools
|
||||
in standard, ask, and planning modes. Submission never changes task disposition
|
||||
or routes feedback externally. See [Agent commentary](agent-commentary.md) for
|
||||
authentication, replay, document-sized limits, inspection, and deletion semantics.
|
||||
|
||||
### Managed decision models
|
||||
|
||||
A company may configure a shared decision model for optional Paperclip features. The instance owns credential resolution, authorization, budget admission, and attributable service charges. Company-sponsored background use is enabled by default during configuration; explicit opt-out persists. User and agent requests keep their own access boundaries and cannot become sponsored background requests after denial. Availability is a cheap local capability check, and metadata-only request history makes service usage inspectable. The implemented V1 contract is in [decision-models.md](decision-models.md).
|
||||
|
||||
|
||||
### Task workspace ownership (2026-10-09)
|
||||
|
||||
Organizational projects, task files, personal agent home, and provider home are separate concepts. App and chat tasks share one workspace policy: preserve a binding or explicit configured folder, otherwise allocate a stable task directory. A repository is optional and can be prepared without creating a project. Optional connection and destination defaults feed the same task policy; they do not grant permissions or relocate existing conversations.
|
||||
|
||||
Agents select authorized workspace/repository intent while the harness owns paths, preparation, persistence and safe transitions. Intentional simultaneous sharing of one physical local/SSH folder remains supported. A subtask never shares its parent's realized workspace: it keeps the parent's project and workspace strategy and gets its own workspace from the project base, exactly as a top-level task in that project would (a project configured for one shared folder still shares that folder across all its tasks). Provider sessions keep their admitted root through completion and recovery. See [SPEC-implementation.md](SPEC-implementation.md) and [the layer architecture](plans/2026-10-09-task-workspaces.md) for the versioned contracts and rollout constraints.
|
||||
|
||||
### Fast responses
|
||||
|
||||
A company may use a shared API model to acknowledge accepted human messages across tasks, agent chat and external channels while normal work starts. Acknowledgements retain their platform provenance and cannot satisfy execution or completion requirements. The bounded inference, authorization, sponsorship and independent accounting contract is defined in [fast-responses.md](fast-responses.md).
|
||||
|
||||
### Retired Pipelines experiment
|
||||
|
||||
Pipelines is no longer a product feature. Its database tables remain for existing
|
||||
data preservation; Cases and Routines continue independently.
|
||||
|
||||
### Recent task navigation summaries
|
||||
|
||||
Recent-task navigation refreshes a bounded, authorized summary projection for
|
||||
its saved task IDs. The projection avoids full task/workspace enrichment and
|
||||
preserves company/task access rules. The HTTP contract is defined in
|
||||
`SPEC-implementation.md` section 10.4.
|
||||
|
||||
### Filesystem access boundary (2026-10-20)
|
||||
|
||||
Filesystem isolation belongs to the OS, execution environment, and storage layout.
|
||||
Paperclip authorizes the current task/run, company, explicitly selected configuration,
|
||||
execution policy, and repository credentials. It does not infer file permissions from
|
||||
other tasks or agents that previously used the same directory, overlapping roots,
|
||||
symlink aliases, or shared Git storage. Existing files under an authorized task root
|
||||
may be read subject to OS access and API path containment.
|
||||
|
||||
Private task records, comments, attachments, run logs, full workspace metadata, and
|
||||
operation logs retain their app authorization. Workspace `_issuePrivacySources` and
|
||||
operation privacy metadata protect app-record disclosure; they do not grant or deny
|
||||
filesystem execution or task-bound file browsing. Current trust and sandbox policy,
|
||||
publication receipts, binding checks, and lifecycle locks remain authoritative.
|
||||
|
||||
Company-managed [Prompt Injection Prevention](prompt-injection-prevention.md)
|
||||
optionally classifies existing tool-result boundaries through a shared OpenRouter
|
||||
connection. Settings → Connections is permanent; valid model verdicts take
|
||||
precedence and dependency failures use the original built-in detector.
|
||||
|
||||
|
||||
### Personal workspace presentation experiments
|
||||
|
||||
A person may opt into an experimental workspace in Settings and return to the
|
||||
classic workspace. The presentation choice belongs to the person across companies
|
||||
on an instance; it does not grant execution capabilities or change shared work.
|
||||
The concrete current contract is in `SPEC-implementation.md` under Personal
|
||||
experimental workspace preference.
|
||||
## Agent connection administration (2026-10-13)
|
||||
|
||||
Standard agents can configure connections through the same domain APIs used by the app, bounded by their grants and their responsible user's current authority. Fresh standard agents for default Operators can manage app/tool connections, chat/email channels, AI accounts and pools, profiles and gateways without additional grants. Existing grants are not backfilled; explicit restrictions persist. Gateway administration retains the responsible human's administrative permission and does not grant agents blanket `tools:admin`.
|
||||
|
||||
The agent performs authorized setup, reuses saved accounts and drafts, and hands off only required human authentication, consent, credential entry or identity confirmation. Saved handoffs resume through existing task continuation after current authority is rechecked. Management, tool execution and approval remain separate. Private accounts, host commands and stored credentials retain their boundaries; agent-issued gateway clients preserve issuer and responsible-user restrictions at use time.
|
||||
|
||||
Authorized policy administration includes user-requested changes that loosen the acting agent’s own tool controls. These writes remain bounded by management grants, resource scope and the responsible user’s current authority; they do not need an additional approval solely because the agent is a target. Subsequent tool calls obey the resulting policy. Agents cannot approve their own governed action requests or edit their own principal permission grants.
|
||||
|
||||
The implementation, operation inventory, permission matrix and fixture qualification are recorded in [Agent API parity for connection configuration](plans/2026-10-13-connection-api-parity.md). Provider fixtures establish API behavior; they do not constitute live provider setup or an empirical agent-success claim.
|
||||
+54
-2
@@ -13,6 +13,7 @@
|
||||
- [Scope enforcement](#scope-enforcement)
|
||||
- [Origin and badges](#origin-and-badges)
|
||||
- [When not to use a watchdog](#when-not-to-use-a-watchdog)
|
||||
- [Authority contract](#authority-contract)
|
||||
- [Reference](#reference)
|
||||
|
||||
---
|
||||
@@ -111,7 +112,7 @@ The mandate also enforces safety constraints that custom instructions **cannot o
|
||||
- No creating another watchdog for the watched subtree. No waking itself. Exactly one reusable review task per watched issue.
|
||||
- Custom instructions can narrow focus or veto specific shortcuts. They cannot grant authority the server does not already give the watchdog.
|
||||
|
||||
The formal authority contract (the full list of allowed and disallowed mutations, plus the ordinary interaction resolver contract) is in [`doc/SPEC-implementation.md`](SPEC-implementation.md) §§9.8.1–9.9.
|
||||
The formal authority contract (the full list of allowed and disallowed mutations) is in [Authority contract](#authority-contract) below. The ordinary interaction resolver contract is in [execution semantics](execution-semantics.md#issue-thread-interaction-resolution).
|
||||
|
||||
### Writing custom instructions
|
||||
|
||||
@@ -172,11 +173,62 @@ If what you actually want is "wake me when this is done," use a routine or an is
|
||||
|
||||
---
|
||||
|
||||
## Authority contract
|
||||
|
||||
A task watchdog is a scoped execution capacity for a configured watchdog agent on one watched issue subtree. It is not a separate principal, does not inherit board auth, and does not expand the selected agent's company boundary. The server must enforce the watchdog contract from persisted watchdog configuration and run context; custom instructions and prompt text can narrow the mandate but cannot expand it.
|
||||
|
||||
The watched subtree is the source issue plus descendants reached through `parent_id`, excluding every issue whose `origin_kind = 'task_watchdog'` and excluding all descendants below those watchdog issues. The generated reusable watchdog issue is outside the watched work subtree for scan purposes, but the watchdog agent may update that reusable watchdog issue to record its own review disposition.
|
||||
|
||||
Task-watchdog wakes must include server-derived capability metadata that names the watched root, reusable watchdog issue, excluded `task_watchdog` origin branches, allowed operations, and denied operations. Watchdogs must use that metadata and server denials for capability discovery; they must not create visible probe issues, comments, or throwaway tasks to learn their permissions.
|
||||
|
||||
### Allowed watchdog mutations
|
||||
|
||||
Within the watched subtree, a watchdog run may perform only mutations that restore or clarify the next live/waiting path:
|
||||
|
||||
- add comments that explain findings, evidence, and next action
|
||||
- create descendant follow-up issues under an included subtree issue, inheriting company, project, goal, and workspace strategy from that subtree; each follow-up gets its own execution workspace
|
||||
- assign or reassign included issues to active, invokable, same-company agents when normal assignment checks and scoped assignment grants allow it
|
||||
- move included issues among `todo`, `in_progress`, `in_review`, and `blocked` when the transition is needed to restore a valid action path
|
||||
- reopen `done` or `cancelled` included issues only with explicit resume metadata and an audit comment when evidence shows the stopped disposition is wrong or incomplete
|
||||
- add, replace, or clear blockers on included issues when the blocker target is in the same company and the change makes the waiting path more accurate
|
||||
- set or refresh a one-shot monitor on an included issue when the current assignee owns the future check
|
||||
- resolve issue-thread interactions through the ordinary resolver-audience path
|
||||
when the watchdog agent otherwise has issue access and the effective policy allows it
|
||||
- update the reusable watchdog issue itself to `done`, `in_review`, or `blocked` with the evidence for the watchdog decision
|
||||
|
||||
Every watchdog-triggered mutation must write activity with the watchdog id, source issue id, watchdog issue id when present, run id, and stop fingerprint. Mutations still use the normal status-transition, blocker, assignment, budget, and company-boundary guards.
|
||||
|
||||
The atomic recovery batch, restoration verification and escalation, and interaction
|
||||
resolution rules for watchdog runs are in
|
||||
[execution semantics §11](execution-semantics.md#11-task-watchdog-for-issue-trees).
|
||||
|
||||
### Disallowed watchdog mutations
|
||||
|
||||
A task watchdog must not:
|
||||
|
||||
- mutate issues outside the watched subtree, except for comments or newly created follow-up issues that are children of included subtree issues
|
||||
- mutate company, project, goal, agent, auth, API key, budget, secret, environment, plugin, or deployment settings
|
||||
- approve or reject rows in the `approvals` table, including hiring, CEO strategy, spend, budget override, or `request_board_approval` decisions
|
||||
- resolve execution-policy decisions unless the watchdog agent is the typed participant under that policy outside of its watchdog capacity
|
||||
- force-release checkout/execution locks, cancel active runs, terminate processes, or perform active-run output watchdog decisions
|
||||
- create visible probe issues, comments, or throwaway tasks to discover whether an operation is allowed
|
||||
- delete issue documents, comments, attachments, work products, or activity records
|
||||
- change the watchdog configuration, select a different watchdog agent, or create nested watchdog configurations
|
||||
- treat custom instructions as authority to bypass approval gates, cross company boundaries, access secrets, or override this contract
|
||||
|
||||
When the safe next action needs one of these disallowed mutations, the watchdog must leave a valid waiting path by commenting, creating an in-subtree escalation/follow-up issue, assigning to the correct owner, or leaving the source issue blocked on a first-class blocker.
|
||||
|
||||
### Deferred capabilities
|
||||
|
||||
Deliberately deferred and disallowed for the first implementation: letting watchdogs cancel active runs, approving board/governance actions, mutating outside the watched subtree, or allowing watchdog agents to modify their own watchdog configuration. Any expansion of those capabilities requires a new product/security review.
|
||||
|
||||
---
|
||||
|
||||
## Reference
|
||||
|
||||
| Topic | File |
|
||||
| -------------------------------- | --------------------------------------------------------------------- |
|
||||
| Authority contract (formal) | [`doc/SPEC-implementation.md`](SPEC-implementation.md) §9.9 |
|
||||
| Authority contract (formal) | [Authority contract](#authority-contract) (this doc) |
|
||||
| Execution semantics (formal) | [`doc/execution-semantics.md`](execution-semantics.md) §11 |
|
||||
| Silent active-run watchdog | [`doc/execution-semantics.md`](execution-semantics.md) §12 |
|
||||
| Database schema | `packages/db/src/schema/issue_watchdogs.ts` |
|
||||
|
||||
@@ -54,3 +54,79 @@ new agents do not persist default overrides. A human permission manager sets
|
||||
individual controls with `agent interaction-permissions:update`; explicit `true`
|
||||
does not override another authorization denial. These controls are separate from
|
||||
principal grants, `canAssignTasks`, and low-trust presets.
|
||||
|
||||
## Shared default-open issue writes
|
||||
|
||||
For standard-trust agents, issue comments, issue field/status updates, child
|
||||
creation under a parent, and assignment share one authorization rule: the
|
||||
target issue must be visible to the agent and the responsible user represented
|
||||
by the run must also be authorized. In V1, issue visibility defaults to the
|
||||
whole company, so these writes are company-wide by default.
|
||||
|
||||
The shared rule does not widen low-trust, `skill_test`, or `task_bridge` key
|
||||
scopes. It also does not replace run-lifecycle controls: checkout ownership,
|
||||
active-run conflicts, status-transition validation, interaction ownership,
|
||||
budget gates, and pause gates remain independently enforced. Comment access is
|
||||
structurally downstream of issue read access (`issue:comment` is a subset of
|
||||
`issue:read`).
|
||||
|
||||
Low-trust agents may create self-assigned tasks and subtasks inside their existing
|
||||
project or root-task scope. Both creation endpoints enforce task-assignment
|
||||
authorization, including responsible-user and protected-assignment checks, even
|
||||
when the new task is unassigned. Created tasks retain the effective containment
|
||||
policy and quarantined source attribution. Self-assigned decomposition does not
|
||||
count as delegation back to another agent. Persistent instruction changes remain
|
||||
restricted except for self-edits requested through authenticated owner chat.
|
||||
That exception requires the current accepted identity and a recorded direct
|
||||
board-message wake, and rechecks the user's current instruction-editing permission
|
||||
when saving. It does not extend to outside work, subtasks, peer instructions, or
|
||||
other privileged configuration. Denials name the specific restriction.
|
||||
|
||||
Authenticated board direction permits a low-trust agent to execute its own
|
||||
human conversation or the exact task explicitly assigned or addressed by a human.
|
||||
This server-owned exception is bound to the current assignee and the run's task;
|
||||
it uses existing conversation identity and authenticated execution-request records,
|
||||
including same-task retry ancestry. It does not expand inherited boundaries or
|
||||
grant privileged tools. Backlog assignments retain the existing human requester
|
||||
without starting a run. Reassignment transactionally cancels prior human requests,
|
||||
including service/plugin writes; cancelled runs cannot authorize later retries. See [low-trust presets](LOW-TRUST-PRESETS.md) for containment details.
|
||||
|
||||
Project or repository access is a separate boundary from exact-task direction.
|
||||
A workspace project denial appears on the task with a link to the agent's
|
||||
Permissions / Trust settings. Board operators with `agents:create` can add
|
||||
same-company projects through `POST /api/agents/:id/project-access`; the operation
|
||||
locks the agent, preserves existing permissions and audits added projects.
|
||||
Saving does not retry work. The task offers explicit Retry after the required
|
||||
projects are allowed, and dispatch rechecks authorization. Readiness checks the
|
||||
task's current organizational project and selected workspace source, including
|
||||
a valid pending selection. Moving the task to an allowed project does not clear
|
||||
a retained source's access requirement. Existing setup failures with the exact
|
||||
project-boundary denial also receive the explanation on reload, without assuming
|
||||
that the task's current project caused the historical failure. A stale or
|
||||
unavailable workspace selection stays in the non-retryable failure state; it
|
||||
does not ask the user to grant project access that cannot repair the selection.
|
||||
|
||||
Cross-issue writes are contained per heartbeat run. An agent-authored comment
|
||||
may wake the target assignee, including an explicit `resume: true` comment on a
|
||||
`done` or `cancelled` issue, but the wake remains agent-class and is subject to
|
||||
the normal agent rewake throttle; comment presentation cannot give it human
|
||||
wake privileges. Agent issue comments and updates require a persisted heartbeat
|
||||
run bound to the authenticated agent and company; missing, invalid, or mismatched
|
||||
run context fails closed before mutation. A run may attempt at most 20 cross-issue comments, issue
|
||||
updates, or issue-thread interaction resolutions across one shared counter. The
|
||||
server records each attempt with its source issue, target issue, run, count, and
|
||||
rollout mode, and fails closed with the cap in the error once enforcement is
|
||||
active. Writes to the run's own source issue are not counted. Assignee self-comments do not
|
||||
wake the assignee, and a non-assignee comment cannot mint a mention grant.
|
||||
|
||||
Agent @-mentions are context links only: they do not wake the mentioned agent,
|
||||
assign work, or forward comments to another task. Normal comment feedback still
|
||||
routes to the current assignee. Work for another agent requires explicit
|
||||
assignment, delegation, or a review request.
|
||||
|
||||
Agent-authored issue comments persist the responsible user derived from the
|
||||
authenticated actor; clients cannot choose that attribution. Each comment also
|
||||
records the write-policy reason, and spoof attempts fail with an audited 422.
|
||||
Every issue PATCH emits an `issue.updated` activity receipt containing the
|
||||
actor, responsible user, run, authorization reason, and field-level before/after
|
||||
changes so both agent and board edits are visible in the issue activity stream.
|
||||
@@ -0,0 +1,106 @@
|
||||
# Company skill policy
|
||||
|
||||
This document describes the company skill policy contract. The code and its tests
|
||||
are the source of truth; see `server/src/services/company-skill-policy.ts`
|
||||
and its tests.
|
||||
|
||||
## Product default
|
||||
|
||||
An authenticated agent may perform normal company-skill work without a skill-specific grant when the target company has no explicit skill policy. This includes creating, importing, installing, editing, updating, testing, resetting, and removing skills. Core MUST NOT introduce a `skills:author` prerequisite, a draft-only default, or an activation-approval default.
|
||||
|
||||
Authorization order is fixed:
|
||||
|
||||
1. Enforce non-configurable platform invariants.
|
||||
2. Evaluate the company's explicit skill policy when one exists.
|
||||
3. Otherwise allow the authenticated company agent.
|
||||
|
||||
Non-configurable invariants include authenticated actor identity, exact company scoping, source and workspace path containment, package and frontmatter validation, secret redaction/non-export, immutable audit attribution, and any hard runtime isolation rule. A policy rule, legacy grant, plugin, or EE configuration cannot override these invariants.
|
||||
|
||||
For avoidance of doubt:
|
||||
|
||||
- Local-path imports, updates, resets, and project scans MUST resolve under a Paperclip-known local workspace root or a Paperclip-managed skill root. Arbitrary host filesystem paths are invalid even when the caller is otherwise authorized. Caller-supplied `source`, `sourceLocator`, or similar path strings are descriptive input only; they MUST NOT expand authority beyond those approved roots.
|
||||
- Remote imports and updates MUST normalize to a known source category, require validated HTTPS or catalog sources, and resolve immutable content before install (for example pinned Git commit/content hash or pinned package version). Unknown schemes, unknown source categories, symlink escapes, and out-of-tree files fail closed before persistence.
|
||||
- Unsafe executable content, fetch-and-exec patterns, and secret exfiltration or non-redacted secret material are platform safety failures. Policy cannot waive them; the route MUST reject the operation before any new skill version, install, update, or reset is persisted.
|
||||
- Mandatory activity attribution is part of the invariant boundary. If the required audit record for a skill mutation or policy mutation cannot be persisted, the mutation MUST fail or roll back; do not return success with missing auditability.
|
||||
|
||||
## Canonical actions and resources
|
||||
|
||||
The version 1 evaluator uses these stable action identifiers:
|
||||
|
||||
- `skills.create`: create or fork a company-authored skill and create skill versions
|
||||
- `skills.import`: import or scan skills from a workspace, Git source, URL, or package
|
||||
- `skills.install`: install a catalog or externally sourced skill into the company
|
||||
- `skills.edit`: change skill metadata, name, files, test inputs, or test templates
|
||||
- `skills.update`: install a newer upstream revision
|
||||
- `skills.test`: start, cancel, or remove a skill test run and run a skill audit
|
||||
- `skills.reset`: restore the installed/upstream revision
|
||||
- `skills.remove`: delete a company skill
|
||||
|
||||
Policy resources may include `skillId`, stable `skillKey`, `sourceType`, and `sourceLocator`. The stable source categories are `workspace`, `catalog`, `git`, `external_package`, `generated`, and `unknown`; adapters may preserve a more specific source value as metadata, but policy evaluation MUST normalize it to one of these categories. Core derives actor and company identity from authentication and derives known resource fields from stored data; a mutation client cannot authorize itself by supplying actor or resource identity fields.
|
||||
|
||||
## Version 1 policy document
|
||||
|
||||
Absence of a policy record is semantically equivalent to the following document, but core SHOULD avoid materializing records for untouched companies:
|
||||
|
||||
```json
|
||||
{
|
||||
"schemaVersion": 1,
|
||||
"revision": 0,
|
||||
"defaultEffect": "allow",
|
||||
"rules": []
|
||||
}
|
||||
```
|
||||
|
||||
An explicit policy has a monotonically increasing `revision`, a `defaultEffect` of `allow` or `deny`, and ordered rules. Each rule contains a stable `id`, integer `priority`, `effect` (`allow` or `deny`), a subject selector (`all_agents`, agent ids, or role names), one or more canonical actions, and optional resource selectors for skill ids/keys and normalized source types/locators. An omitted resource selector matches every resource for the listed action.
|
||||
|
||||
Rules are evaluated by ascending `priority`, then stable rule id; the first matching rule decides. If no rule matches, `defaultEffect` decides. This supports both the normal open policy with targeted deny rules and an opt-in restricted preset with default deny plus explicit allow rules. Core MUST validate policy documents atomically and reject ambiguous, unknown-version, unknown-action, cross-company, or malformed selectors with `422`.
|
||||
|
||||
Every decision returned by the evaluator has this stable shape:
|
||||
|
||||
```json
|
||||
{
|
||||
"allowed": false,
|
||||
"action": "skills.install",
|
||||
"reason": "explicit_rule",
|
||||
"policyRevision": 7,
|
||||
"matchedRuleId": "deny-external-packages",
|
||||
"remediation": "Contact a company administrator to change the skill policy."
|
||||
}
|
||||
```
|
||||
|
||||
`reason` is one of `platform_invariant`, `no_policy_default`, `explicit_rule`, `policy_default`, or `legacy_compatibility`. Mutation routes MUST use this evaluator and return `403` with code `skill_policy_denied` and the non-sensitive decision fields when an explicit restriction denies an operation. Denials must identify the action and remediation without exposing hidden rule data, secrets, or another company's policy.
|
||||
|
||||
Platform-invariant failures are not policy denials and MUST use stable machine-readable error codes so clients can distinguish non-overridable safety failures from optional administrative restrictions. Version 1 requires a finite code set covering at least:
|
||||
|
||||
- `skill_authentication_required`
|
||||
- `skill_company_boundary_denied`
|
||||
- `skill_workspace_boundary_denied`
|
||||
- `skill_source_validation_failed`
|
||||
- `skill_unsafe_content_blocked`
|
||||
- `skill_secret_handling_blocked`
|
||||
- `skill_policy_admin_required`
|
||||
|
||||
Core Skill Studio and Paperclip EE MUST treat those codes as hard platform failures, not as prompts to loosen policy.
|
||||
|
||||
## Core API and ownership boundary
|
||||
|
||||
Core owns and ships these company-scoped endpoints:
|
||||
|
||||
- `GET /companies/:companyId/skill-policy` returns the effective versioned policy, its revision, and whether it is materialized or the open default.
|
||||
- `PUT /companies/:companyId/skill-policy` atomically replaces the policy and requires the caller's expected revision; stale writes return `409`.
|
||||
- `DELETE /companies/:companyId/skill-policy` removes explicit configuration and restores the open default.
|
||||
- `POST /companies/:companyId/skill-policy/evaluate` simulates decisions for administrative tooling without performing a skill mutation.
|
||||
|
||||
Policy reads, writes, deletion, and simulation enforce company access. Policy mutation and cross-principal simulation require board administration authority or the existing `users:manage_permissions` capability; ordinary skill access does not. Every policy mutation writes an activity event containing the actor, previous revision, new revision, and a redacted change summary. Skill mutation activity logging remains required independently of the policy decision.
|
||||
|
||||
Paperclip EE owns the detailed editor, presets, protected-skill management, policy simulation UX, and policy-specific audit views. EE consumes the core endpoints and does not implement a second evaluator. Core may expose a concise effective-policy summary and denial state, but MUST NOT depend on EE for enforcement or make EE installation a prerequisite for normal skill work.
|
||||
|
||||
## Compatibility and availability
|
||||
|
||||
- Existing companies with no explicit restriction adopt the open default, including companies that previously depended on missing grants to deny skill changes. Release notes and upgrade guidance MUST call out this behavior change.
|
||||
- Existing explicit restriction policies remain effective after migration.
|
||||
- Legacy `skills:create` and `skills:suggest-changes` positive grants remain accepted in APIs and portability packages. Historically either positive grant authorized the broad company-skill mutation surface, so in an explicit restricted policy either grant remains a compatibility allow fallback for all eight canonical skill actions only when no explicit rule matched. They never override an explicit deny or a platform invariant. With no explicit policy they are redundant because the default already allows the action.
|
||||
- Legacy `skills:suggest-changes` consent state is not a platform invariant for company skills and does not add a second mutation gate under the open-default policy. Companies that require approval or consent before skill changes must express that restriction through explicit skill-policy rules; authentication, company boundaries, source containment, validation, auditability, and runtime safety remain non-configurable invariants.
|
||||
- Import preview MUST report whether a package contains an explicit skill policy or legacy grants and how each will map. Import apply MUST preserve explicit policies, normalize supported legacy grants, and reject unknown policy versions rather than silently weakening them.
|
||||
- Export MUST include explicit skill policy configuration and retained legacy grants in `.paperclip.yaml`, never secret values or environment-specific paths. An unconfigured company exports no synthetic restriction.
|
||||
- If Paperclip EE is unavailable or removed, core continues to enforce stored policies and expose the policy API. Normal skill work remains available under the open default; explicit denials use core remediation text rather than a broken EE-only link.
|
||||
@@ -789,8 +789,8 @@ This is the implementation sequence an autonomous coding agent should follow.
|
||||
|
||||
### Phase 0: Establish scope and preserve the worktree
|
||||
|
||||
1. Read `AGENTS.md`, `doc/GOAL.md`, `doc/PRODUCT.md`,
|
||||
`doc/SPEC-implementation.md`, `doc/DEVELOPING.md`, and `doc/DATABASE.md`.
|
||||
1. Read `AGENTS.md`, `doc/GOAL.md`, `doc/PRODUCT.md`, `doc/DEVELOPING.md`,
|
||||
and `doc/DATABASE.md`.
|
||||
2. Read this runbook, [the connections overview](./README.md), and
|
||||
[the security threat model](./SECURITY-THREAT-MODEL.md).
|
||||
3. Inspect `git status --short`. Existing changes belong to the user or another
|
||||
|
||||
+1
-1
@@ -520,7 +520,7 @@ is a broken user outcome or invariant, not an individual red cell.
|
||||
4. **Design the smallest general correction.** Name the desired user behavior,
|
||||
the authoritative state/transaction or provider boundary that owns it, the
|
||||
affected callers, and the existing guarantees that must survive. Check it
|
||||
against `PRODUCT.md` and `SPEC-implementation.md`. A change to an intentional
|
||||
against `PRODUCT.md` and the existing code and tests. A change to an intentional
|
||||
product rule is a contract change, not an excuse to delete its guard. Avoid
|
||||
case-name branches, phrase-specific prompts, unconditional retries, or
|
||||
weakening approval, ownership, cancellation, and budget gates to get green.
|
||||
|
||||
@@ -6,7 +6,7 @@ Audience: Product and engineering
|
||||
|
||||
This document explains how Paperclip interprets issue assignment, issue status, execution runs, wakeups, parent/sub-issue structure, and blocker relationships.
|
||||
|
||||
`doc/SPEC-implementation.md` remains the V1 contract. This document is the detailed execution model behind that contract.
|
||||
The code and its tests are the source of truth. This document is the detailed execution model behind them.
|
||||
|
||||
## 1. Core Model
|
||||
|
||||
@@ -536,7 +536,7 @@ and the user need not certify infrastructure state in a reconciliation form.
|
||||
|
||||
Repeated automatic signals for an unchanged gate share one durable skipped-wake diagnostic, scoped to company, agent, issue, gate code, and condition identity. The diagnostic retains the first request and counts later observations. This applies to execution reconciliation, dependencies, pause holds, company and agent availability, budget blocks, and disabled heartbeats. These diagnostics do not consume provider attempts and are never proof that a future wake was delivered. All current gates are checked again on the next wake, including the periodic dependency reconciliation sweep. Clearing one gate does not bypass another.
|
||||
|
||||
Another run's unfinished accounting or cleanup never refuses new work (see `doc/SPEC-implementation.md`, "Admission is independent of cleanup and accounting"). A new task whose first assignment wake is refused by a temporary condition (an explicit pause) stays `todo`. Stranded-work recovery does not move a task with no run to `blocked` for such a condition. The task shows what it waits for, and the assigned-task liveness sweep admits it once the condition clears, through normal admission and with one run. A reached hard stop or blocked unpriced usage remains a board decision. Removed assignees and cancelled tasks still do not wake.
|
||||
Another run's unfinished accounting or cleanup never refuses new work. Only a hard stop (spend at the limit, or reported unpriced usage under a blocking policy), an explicit pause of the company, project or agent, or an inactive company refuses admission. A new task whose first assignment wake is refused by a temporary condition (an explicit pause) stays `todo`. Stranded-work recovery does not move a task with no run to `blocked` for such a condition. The task shows what it waits for, and the assigned-task liveness sweep admits it once the condition clears, through normal admission and with one run. A reached hard stop or blocked unpriced usage remains a board decision. Removed assignees and cancelled tasks still do not wake.
|
||||
|
||||
A user's message refused by a pause (a paused agent, a paused company, or a budget pause that is not a reached hard stop) is saved as a deferred intent that names the refusal and its release trigger; it is never written as a terminal skip. The pause's own stop keeps it. Lifting the pause is the operator's explicit authorization to send what the pause refused, as Send is after a Stop: when the pause stopped the task's run, the lifted pause issues the task's next explicit wake, which adopts the saved message once. A task that never ran keeps the message in the task, and stranded-work recovery starts it.
|
||||
|
||||
@@ -2217,11 +2217,10 @@ Automatic productivity reviews are retired. Run counts, missing comments, and el
|
||||
### Issue-thread interaction resolution
|
||||
|
||||
Every issue-thread interaction kind inherits resolver policy `anyone` when the
|
||||
creator omits a policy. `anyone` includes the creator agent and creating run.
|
||||
Callers opt into independent review with `not_creator` or human resolution with
|
||||
`human_only`; a named addressee and company cap may narrow the effective audience.
|
||||
The legacy input aliases `board_or_agents` and `board_only` normalize to `anyone`
|
||||
and `human_only` for new writes.
|
||||
creator omits a policy. Restrictions are opt-in; the canonical policies, addressee
|
||||
rules, and company caps are listed below. The legacy input aliases
|
||||
`board_or_agents` and `board_only` normalize to `anyone` and `human_only` for new
|
||||
writes.
|
||||
|
||||
Resolver policy is snapshotted with explicit/inherited provenance and an effective
|
||||
source (`requested`, `company_cap`, or `governed_action`). Existing ambiguous
|
||||
@@ -2236,6 +2235,51 @@ the outcome commits. Resolution records an answer; every continuation, task
|
||||
creation, tool/provider call, execution-policy transition, spend, deployment, or
|
||||
other effect independently re-runs its own authorization and approval gates.
|
||||
|
||||
Question, confirmation, checkbox confirmation, and item verdict cards stay pending
|
||||
when a user sends an ordinary task comment. Their `supersedeOnUserComment` flag
|
||||
defaults to `false`. A creator may set it to `true` when a comment should replace
|
||||
the pending request, as the opening onboarding question does.
|
||||
|
||||
Canonical resolver policies are:
|
||||
|
||||
- `anyone`: any authenticated actor in the interaction's company who can read the
|
||||
issue and use the normal resolution route. For agents this includes the creator
|
||||
agent and the creating/source run.
|
||||
- `not_creator`: the explicit independent-review policy. It excludes the creator
|
||||
agent and creating/source run while otherwise using the ordinary agent resolver
|
||||
path.
|
||||
- `human_only`: only an authorized human/board actor may resolve the interaction.
|
||||
|
||||
An explicit named agent or user addressee and a company-configured cap may narrow
|
||||
the effective audience. Only the exact named addressee may resolve an addressed
|
||||
interaction; a human does not override a user addressee. Explicit user recipients
|
||||
must exist and be authorized to respond in the issue's company before creation.
|
||||
Ordinary Agent Chat questions derive their user recipient from the persisted
|
||||
conversation owner. A conflicting explicit user recipient is rejected; IDs are
|
||||
never guessed or repaired. Ordinary task questions keep optional addressing.
|
||||
A cap never widens the requested audience. Tool-action confirmations and
|
||||
other hard-governed action cards remain `human_only` (or move to the formal approval
|
||||
system) regardless of a requested open audience.
|
||||
|
||||
Surfaces that offer a resolution must state the effective audience before the
|
||||
operator acts, from server metadata rather than a client-side policy inference.
|
||||
Issue-thread cards read it from the interaction snapshot; attention rows read it
|
||||
from the feed item's `resolverAudience` (canonical requested/effective policy,
|
||||
effective-policy source, provenance, and the addressee/creator identities the
|
||||
evaluator compares against), because a collapsed row carries decision verbs
|
||||
before the interaction itself is fetched. A failed resolution keeps the server's
|
||||
denial reason in visible, assertively announced feedback and names who may
|
||||
respond; an audience denial is permanent, so it must not degrade to a retry
|
||||
prompt. Neither surface may enable or disable a control on its own authority.
|
||||
|
||||
An open audience is not an uncapped one: when an agent run resolves an interaction
|
||||
on an issue other than its own source issue, the resolution is a cross-issue
|
||||
mutation and consumes the per-run cross-issue influence budget in
|
||||
[shared default-open issue writes](agent-permission-defaults.md#shared-default-open-issue-writes), charged
|
||||
after audience authorization and before the interaction mutation, child tasks,
|
||||
continuation, tool action, or wake. Same-issue resolutions and board/user
|
||||
resolutions are outside that counter.
|
||||
|
||||
A native continuation may replay the same plain confirmation or checkbox key
|
||||
after receiving its accepted response. Only the run's persisted, identity-bound
|
||||
response can nominate that replay. The interaction service returns the original
|
||||
@@ -2296,7 +2340,7 @@ When the source issue is non-terminal and has no other live path, the product sh
|
||||
|
||||
### Watchdog authority during execution
|
||||
|
||||
The watchdog agent acts in a scoped capacity, not as the original deliverable worker and not as the board. The server must enforce the authority contract in `doc/SPEC-implementation.md` from persisted watchdog context. Prompt text and custom instructions may guide the watchdog's judgment, but they cannot grant authority outside the watched subtree or widen an interaction's ordinary effective audience.
|
||||
The watchdog agent acts in a scoped capacity, not as the original deliverable worker and not as the board. The server must enforce the [authority contract](TASK-WATCHDOG.md#authority-contract) from persisted watchdog context. Prompt text and custom instructions may guide the watchdog's judgment, but they cannot grant authority outside the watched subtree or widen an interaction's ordinary effective audience.
|
||||
|
||||
Watchdogs must not create visible probe issues, comments, or throwaway tasks to discover capability boundaries. They should rely on the wake capability metadata and explicit API denials, then record any denied operation as evidence in the reusable watchdog issue.
|
||||
|
||||
|
||||
@@ -3,9 +3,9 @@
|
||||
Status: proposed complete spec for the post-V1 plugin system
|
||||
|
||||
This document is the complete specification for Paperclip's plugin and extension architecture.
|
||||
It expands the brief plugin notes in [doc/SPEC.md](../SPEC.md) and should be read alongside the comparative analysis in [doc/plugins/ideas-from-opencode.md](./ideas-from-opencode.md).
|
||||
It should be read alongside the comparative analysis in [doc/plugins/ideas-from-opencode.md](./ideas-from-opencode.md).
|
||||
|
||||
This is not part of the V1 implementation contract in [doc/SPEC-implementation.md](../SPEC-implementation.md).
|
||||
This is not part of the V1 implementation contract.
|
||||
It is the full target architecture for the plugin system that should follow V1.
|
||||
|
||||
## Current implementation caveats
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
Status: design report, not a V1 commitment
|
||||
|
||||
Paperclip V1 explicitly excludes a plugin framework in [doc/SPEC-implementation.md](../SPEC-implementation.md), but the long-horizon spec says the architecture should leave room for extensions. This report studies the `opencode` plugin system and translates the useful patterns into a Paperclip-shaped design.
|
||||
Paperclip V1 originally excluded a plugin framework, but the long-horizon plan left room for extensions. This report studies the `opencode` plugin system and translates the useful patterns into a Paperclip-shaped design.
|
||||
|
||||
Assumption for this document: Paperclip is a single-tenant operator-controlled instance. Plugin installation should therefore be global across the instance. "Companies" are still first-class Paperclip objects, but they are organizational records, not tenant-isolation boundaries for plugin trust or installation.
|
||||
|
||||
@@ -62,8 +62,6 @@ Relevant Paperclip files reviewed for current extension seams:
|
||||
- [server/src/secrets/provider-registry.ts](../../server/src/secrets/provider-registry.ts)
|
||||
- [server/src/services/run-log-store.ts](../../server/src/services/run-log-store.ts)
|
||||
- [server/src/services/activity-log.ts](../../server/src/services/activity-log.ts)
|
||||
- [doc/SPEC.md](../SPEC.md)
|
||||
- [doc/SPEC-implementation.md](../SPEC-implementation.md)
|
||||
|
||||
## What OpenCode Actually Implements
|
||||
|
||||
|
||||
@@ -9,7 +9,6 @@ Scope: Agent execution runtime, adapter protocol, wakeup orchestration, and live
|
||||
|
||||
This spec defines how Paperclip actually runs agents while staying runtime-agnostic.
|
||||
|
||||
- `doc/SPEC-implementation.md` remains the V1 baseline contract.
|
||||
- This document adds concrete subsystem detail for agent execution, including local CLI adapters, runtime state persistence, wakeup scheduling, and browser live updates.
|
||||
- If this doc conflicts with current runtime behavior in code, this doc is the target behavior for upcoming implementation.
|
||||
|
||||
|
||||
+2
-2
@@ -15,8 +15,8 @@ reference is neither a registered execution nor evidence that a journey passed.
|
||||
These are sibling directories under `maps/`. Each feature file has a same-named
|
||||
agent access companion. Reuse the product map's sub-feature IDs, so `tasks/create`
|
||||
identifies the same capability in both maps. Product behavior remains governed by
|
||||
[the implementation spec](../doc/SPEC-implementation.md); a map cannot grant
|
||||
authority or redefine a permission denial as success.
|
||||
the code and its tests; a map cannot grant authority or redefine a permission
|
||||
denial as success.
|
||||
|
||||
## Capability identifiers
|
||||
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
Start here when reproducing a user-facing bug, verifying a change, or deciding
|
||||
which surfaces a fix must cover. Each recipe describes what a person can do,
|
||||
where they can do it, the expected result, and the evidence needed to verify it.
|
||||
Product behavior is still governed by [the implementation spec](../../doc/SPEC-implementation.md).
|
||||
Product behavior is still governed by the code and its tests.
|
||||
|
||||
The sibling [agent access map](../agent-access-map/README.md) records APIs,
|
||||
agent entry points and permission boundaries for the same capability IDs.
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
Browse the [published feature guide](https://d1p6rlowie26tp.cloudfront.net/storybook/branches/master/?path=/story/overview-storybook-guide--coverage-guide),
|
||||
or run `pnpm storybook` for the current checkout. The feature and capability IDs
|
||||
come from the [feature recipes](../feature-map/README.md). Product behavior and
|
||||
permissions remain governed by the implementation spec and access companions.
|
||||
permissions remain governed by the code, its tests, and access companions.
|
||||
|
||||
## Authored sources
|
||||
|
||||
|
||||
@@ -2,7 +2,8 @@
|
||||
* Copy contract for denied issue writes (open cross-task writes: failure UX).
|
||||
*
|
||||
* Cross-issue issue writes are default-open for standard-trust agents on issues
|
||||
* they can already read (see SPEC-implementation §9.3). The remaining walls are
|
||||
* they can already read (see `doc/agent-permission-defaults.md`, "Shared
|
||||
* default-open issue writes"). The remaining walls are
|
||||
* rare — but a real incident burned a full detour discovering a workaround
|
||||
* behind an opaque 403, so every one of them must say three things:
|
||||
*
|
||||
|
||||
@@ -5822,7 +5822,7 @@ export function issueRoutes(
|
||||
// watched subtree. This must be evaluated before the base assignee-ownership
|
||||
// boundary below: that boundary denies an agent mutating an issue owned by a
|
||||
// different agent, which is exactly the watchdog's primary job
|
||||
// (SPEC-implementation §9.9 — comment, transition, reassign within the
|
||||
// (`doc/TASK-WATCHDOG.md`, "Authority contract" — comment, transition, reassign within the
|
||||
// watched subtree). The watchdog scope can only widen access to the watched
|
||||
// subtree; downstream status-transition, assignment, recovery, and budget
|
||||
// guards in the route handlers still apply.
|
||||
@@ -6247,9 +6247,10 @@ export function issueRoutes(
|
||||
});
|
||||
}
|
||||
// Resolving an interaction on another run's issue is a cross-issue mutation
|
||||
// like a comment or a PATCH, so it consumes the same per-run budget (§9.3,
|
||||
// §9.8.1). This runs last: company/resource access, run attribution,
|
||||
// containment, and the audience decision have all already passed, and the
|
||||
// like a comment or a PATCH, so it consumes the same per-run budget (see
|
||||
// `doc/agent-permission-defaults.md`). This runs last: company/resource
|
||||
// access, run attribution, containment, and the audience decision have all
|
||||
// already passed, and the
|
||||
// terminal interaction mutation plus every child-task, continuation,
|
||||
// activity, tool, and wake side effect is still downstream. Same-issue
|
||||
// resolutions short-circuit inside the counter transaction and are not
|
||||
|
||||
@@ -585,7 +585,7 @@ async function checkVisibleNextAction(db: Db, now: Date, limit: number): Promise
|
||||
const page = await db.select({ id: issues.id, companyId: issues.companyId, executionRunId: issues.executionRunId,
|
||||
updatedAt: issues.updatedAt })
|
||||
.from(issues).where(and(eq(issues.status, "in_progress"), isNotNull(issues.assigneeAgentId),
|
||||
// A saved monitor deadline is a first-class wait path (SPEC-implementation).
|
||||
// A saved monitor deadline is a first-class wait path (doc/execution-semantics.md §8).
|
||||
or(isNull(issues.monitorNextCheckAt), lt(issues.monitorNextCheckAt, now)),
|
||||
notExists(db.select({ one: sql`1` }).from(heartbeatRuns).where(and(
|
||||
eq(heartbeatRuns.companyId, issues.companyId), inArray(heartbeatRuns.status, ACTIVE_RUN_STATUSES),
|
||||
|
||||
@@ -276,7 +276,7 @@
|
||||
"packages/shared/src/issue-references.ts": "bfdd2126fb12797f2c8177113285b2c3233aecef",
|
||||
"packages/shared/src/issue-thread-interactions.test.ts": "6f516055744fcedd2e0c06ce82c6a1a019120762",
|
||||
"packages/shared/src/issue-write-denial.test.ts": "e21b93aa79e6635c019ac338eff954ec618a98ed",
|
||||
"packages/shared/src/issue-write-denial.ts": "7844fa576492d53e064fc6326c9d94af827ce157",
|
||||
"packages/shared/src/issue-write-denial.ts": "e6b4d72a83f6e4e76e85e34a80f88d1d69b7dfe4",
|
||||
"packages/shared/src/markdown-work-products.test.ts": "7293d14ad45ec2b11b5deaab4ce070c36f7c9010",
|
||||
"packages/shared/src/markdown-work-products.ts": "16a88cfb717f325c247a516e78b47d53871b52ed",
|
||||
"packages/shared/src/mcp-config-help-prompt.ts": "fa58effb7cd995198909315d9ba2a93dedde0552",
|
||||
|
||||
@@ -223,7 +223,8 @@ function GovernanceSelect({
|
||||
* The open default is the headline — interactions are resolvable by anyone in
|
||||
* the company unless a row here narrows them — so the panel only offers
|
||||
* narrowing choices and never presents an unrestricted card as board-required
|
||||
* (PAP-17280, contract in `doc/SPEC-implementation.md` §9.8.1).
|
||||
* (PAP-17280, contract in `doc/execution-semantics.md`, "Issue-thread
|
||||
* interaction resolution").
|
||||
*/
|
||||
export function InteractionGovernancePanel({
|
||||
governance,
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
/**
|
||||
* Plain-language presentation of *who may resolve* an issue-thread interaction
|
||||
* (PAP-17280, Phase 3 of the open-default resolver contract in
|
||||
* `doc/SPEC-implementation.md` §9.8.1).
|
||||
* `doc/execution-semantics.md`, "Issue-thread interaction resolution").
|
||||
*
|
||||
* The product default is open: an interaction created without an explicit
|
||||
* `resolverPolicy` is resolvable by `anyone` in the company — the board or any
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
/**
|
||||
* @fileoverview Classifies a failed skill mutation into the four visual states
|
||||
* from the Phase 3 UX spec (PAP-13865 / §9.10 Company Skill Policy Contract).
|
||||
* from the Phase 3 UX spec (PAP-13865 / `doc/company-skill-policy.md`).
|
||||
*
|
||||
* The contract inverts the old model: **skill permissions are opt-in
|
||||
* restrictions, not opt-in capabilities.** Under the open default there is no
|
||||
@@ -22,7 +22,7 @@ import { ApiError } from "../api/client";
|
||||
export const SKILL_POLICY_DENIAL_CODE = "skill_policy_denied";
|
||||
|
||||
/**
|
||||
* Non-configurable platform-invariant failure codes (§9.10). Policy can never
|
||||
* Non-configurable platform-invariant failure codes (`doc/company-skill-policy.md`). Policy can never
|
||||
* loosen these — the remediation is always to fix the artifact/source/input,
|
||||
* never to change a permission.
|
||||
*/
|
||||
@@ -50,7 +50,7 @@ export interface SkillDenial {
|
||||
state: SkillDenialState;
|
||||
/** Machine-readable error code from the server, when present. */
|
||||
code: string | null;
|
||||
/** §9.10 decision `reason`, when the server surfaced the decision shape. */
|
||||
/** Skill-policy decision `reason`, when the server surfaced the decision shape. */
|
||||
reason: string | null;
|
||||
/** Plain-language title for the banner. */
|
||||
title: string;
|
||||
|
||||
@@ -4035,7 +4035,7 @@ export function CompanySkills() {
|
||||
// Route a failed skill mutation to the persistent policy banner when it is an
|
||||
// explicit-policy (State B) or platform-safety (State C) denial; otherwise keep
|
||||
// the existing transient error toast. This is the core "actionable denial only
|
||||
// for real restrictions" behavior from §9.10 (PAP-13865).
|
||||
// for real restrictions" behavior from `doc/company-skill-policy.md` (PAP-13865).
|
||||
const reportSkillError = (error: unknown, title: string, fallbackBody: string, actionLabel?: string) => {
|
||||
if (policyDenial.capture(error, actionLabel)) return;
|
||||
pushToast({
|
||||
|
||||
@@ -3958,7 +3958,7 @@ export function CompanySkills({ collectionView }: { collectionView?: "authored"
|
||||
// Route a failed skill mutation to the persistent policy banner when it is an
|
||||
// explicit-policy (State B) or platform-safety (State C) denial; otherwise keep
|
||||
// the existing transient error toast. This is the core "actionable denial only
|
||||
// for real restrictions" behavior from §9.10 (PAP-13865).
|
||||
// for real restrictions" behavior from `doc/company-skill-policy.md` (PAP-13865).
|
||||
const reportSkillError = (error: unknown, title: string, fallbackBody: string, actionLabel?: string) => {
|
||||
if (policyDenial.capture(error, actionLabel)) return;
|
||||
pushToast({
|
||||
|
||||
@@ -198,7 +198,7 @@ function useMutationErrorToast() {
|
||||
// Under the open default there is no permission chrome. When an action is
|
||||
// actually denied — by an explicit company policy (State B) or a platform
|
||||
// safety invariant (State C) — show the actionable denial title/remediation
|
||||
// instead of a generic "try again" error (§9.10, PAP-13865). Transient
|
||||
// instead of a generic "try again" error (`doc/company-skill-policy.md`, PAP-13865). Transient
|
||||
// failures keep the plain error toast.
|
||||
const denial = classifySkillDenial(error);
|
||||
if (denial) {
|
||||
|
||||
Reference in new issue
Block a user