Files
PaperClipAI/ui/src/lib/interaction-audience.ts
T
DottaandClaude Opus 5.5 11b09b7234 refactor: remove doc/execution-semantics.md and its references (#21699)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Contributors and agents read the docs under `doc/` for background on
run execution
> - `doc/execution-semantics.md` grew to 6,310 lines of per-PR notes
> - It was hard to read and it drifted from the code
> - The code and tests are the source of truth for execution behavior
> - This pull request removes the file and every reference to it
> - The benefit is one less stale document that readers can mistake for
a requirement

## Linked Issues or Issue Description

**Issue type**

Outdated or unclear documentation.

**Where is the issue?**

`doc/execution-semantics.md`, and the docs, rules, skills, maps, code
comments and log text that link to it.

**What's wrong?**

The file is 6,310 lines of notes added one PR at a time. Much of it
repeats or contradicts the code. Readers and agents treat it as a
contract, but the code and tests decide the behavior.

**Suggested fix**

Delete the file. Remove each link to it. Keep the documents that link to
it. Point at code where a pointer is still useful. Do not move the
content to another doc.

Refs #10664 (an open docs PR that edits this file; it becomes obsolete).

## What Changed

- Delete `doc/execution-semantics.md`.
- Remove links and pointers in `doc/PRODUCT.md`,
`doc/LOW-TRUST-PRESETS.md`, `doc/TASK-WATCHDOG.md`,
`doc/composer-stop.md`, `doc/native-workspace-finalization-recovery.md`,
`doc/run-log-events.md`, `doc/runner-internals.md` and
`doc/workspace-repositories.md`.
- `doc/TASK-WATCHDOG.md` now points at
`server/src/modules/active-run-watchdog/` for the silent active-run
watchdog.
- Remove the link in `rules/upgrade-safe-run-state.mdc` and
`maps/feature-map/recovery.md`.
- Update the skills `diagnose-why-work-stopped`,
`fix-failed-paperclip-run` and `terminal-bench-loop`. The
`fix-failed-paperclip-run` skill now points at
`server/src/services/heartbeat/` and `server/src/services/recovery/`.
- Remove the file from the source anchors in `.devin/wiki.json`.
- Remove the doc name from four code comments in `server/` and `ui/`.
- The failed-attachment log message no longer ends with a link to the
removed doc. Two tests now check the message text instead of the link.
- Leave two dated plan files under `doc/plans/` unchanged. They are
history.

## Verification

- `git grep -i execution-semantics` finds no hits outside `doc/plans/`.
- Every relative Markdown link in the changed files resolves.
- `node scripts/check-maps.mjs` passes.
- `node --test .github/scripts/tests/*.test.mjs` passes (808 tests).
- `pnpm verify` was not run locally. The worktree has no `node_modules`.
CI runs the changed Vitest files.

## Risks

- Low risk. Most changes are docs and comments.
- One runtime log line is shorter. It no longer has a link. No logic
changes.
- Open PRs that edit the deleted file, such as #10664, will conflict.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use and
shell access.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-14 20:29:25 -06:00

282 lines
12 KiB
TypeScript

/**
* Plain-language presentation of *who may resolve* an issue-thread interaction.
*
* The product default is open: an interaction created without an explicit
* `resolverPolicy` is resolvable by `anyone` in the company — the board or any
* agent, including the agent that created it. `not_creator`, `human_only`, and a
* named addressee are *narrowing* controls that a requester asks for on purpose.
*
* This module is presentation only. It never decides authority: the server
* evaluator owns that, and every downstream effect re-runs its own
* authorization (see the Phase 1S security verdict on PAP-17278). Everything
* here is derived from the server-provided snapshot fields
* (`requestedResolverPolicy`, `effectiveResolverPolicy`,
* `effectiveResolverPolicySource`, `resolverPolicyProvenance`) so the copy a
* reader sees agrees with the policy the server will apply.
*/
import {
ISSUE_THREAD_INTERACTION_CANONICAL_RESOLVER_POLICIES,
normalizeIssueThreadInteractionResolverPolicy,
type AttentionItem,
type AttentionResolverAudience,
type IssueThreadInteractionCanonicalResolverPolicy,
type IssueThreadInteractionEffectiveResolverPolicySource,
type IssueThreadInteractionResolverPolicy,
type IssueThreadInteractionResolverPolicyProvenance,
} from "@paperclipai/shared";
import type { IssueThreadInteraction } from "./issue-thread-interactions";
/**
* The open default. Creation surfaces present this first and requesters omit
* `resolverPolicy` to get it.
*/
export const DEFAULT_RESOLVER_POLICY: IssueThreadInteractionCanonicalResolverPolicy = "anyone";
/** Short label for a resolver audience — badges, select options, table cells. */
const RESOLVER_POLICY_LABELS: Record<IssueThreadInteractionCanonicalResolverPolicy, string> = {
anyone: "Anyone",
not_creator: "Anyone except creator",
human_only: "Human only",
};
/**
* Plain-language preview of what a policy *does*, phrased for a surface that is
* choosing it for future cards (company defaults and caps). Card-specific copy
* that names the real creator/addressee comes from
* {@link describeInteractionAudience}.
*/
const RESOLVER_POLICY_EFFECTS: Record<IssueThreadInteractionCanonicalResolverPolicy, string> = {
anyone:
"Anyone in the organization can respond — the board or any agent, including the one that asked.",
not_creator:
"Anyone in the organization except the agent that created the card, and its run. Use this when the answer has to come from someone else.",
human_only: "Only a person on the board can respond. Agents are turned away.",
};
/** Accepts canonical values and the deprecated `board_*` compatibility aliases. */
export function resolverPolicyLabel(policy: IssueThreadInteractionResolverPolicy): string {
return RESOLVER_POLICY_LABELS[normalizeIssueThreadInteractionResolverPolicy(policy)];
}
/** Accepts canonical values and the deprecated `board_*` compatibility aliases. */
export function resolverPolicyEffect(policy: IssueThreadInteractionResolverPolicy): string {
return RESOLVER_POLICY_EFFECTS[normalizeIssueThreadInteractionResolverPolicy(policy)];
}
/**
* Ordered choice list for every surface that picks a resolver audience. `anyone`
* is first and marked as the default so the open option reads as the normal
* path rather than a permission grant.
*/
export const RESOLVER_POLICY_CHOICES: readonly {
value: IssueThreadInteractionCanonicalResolverPolicy;
label: string;
effect: string;
isDefault: boolean;
}[] = ISSUE_THREAD_INTERACTION_CANONICAL_RESOLVER_POLICIES.map((value) => ({
value,
label: RESOLVER_POLICY_LABELS[value],
effect: RESOLVER_POLICY_EFFECTS[value],
isDefault: value === DEFAULT_RESOLVER_POLICY,
}));
/** Why an effective audience ended up narrower than the requested one. */
export type InteractionAudienceNarrowing =
| "requested"
| "company_cap"
| "governed_action"
| "addressee"
| "legacy_restriction";
export interface InteractionAudienceDescription {
/** Effective canonical policy the server will enforce. */
policy: IssueThreadInteractionCanonicalResolverPolicy;
/** Canonical policy the creator asked for (before caps/clamps). */
requestedPolicy: IssueThreadInteractionCanonicalResolverPolicy;
/** Short badge label for the effective audience. */
label: string;
/** One sentence naming exactly who can respond to *this* card. */
summary: string;
/**
* The same fact in a glanceable clause, for a dense surface that shows the
* audience beside compact decision buttons (collapsed attention rows).
*/
shortSummary: string;
/** True when the card is open to the whole company with no addressee. */
isOpen: boolean;
/** Set when something narrows the audience below the open default. */
narrowedBy: InteractionAudienceNarrowing | null;
/** Extra sentence explaining a narrowing the requester did not ask for. */
narrowedNote: string | null;
}
/**
* The server-evaluated facts an audience description is derived from. Both the
* full interaction snapshot (issue thread) and the attention feed's
* `resolverAudience` (collapsed queue rows) reduce to this shape, so one copy
* table serves both surfaces and they cannot drift.
*/
export interface InteractionAudienceFacts {
effectiveResolverPolicy: IssueThreadInteractionCanonicalResolverPolicy;
requestedResolverPolicy: IssueThreadInteractionCanonicalResolverPolicy;
effectiveResolverPolicySource: IssueThreadInteractionEffectiveResolverPolicySource;
resolverPolicyProvenance: IssueThreadInteractionResolverPolicyProvenance;
hasAddressee: boolean;
isUserAddressee?: boolean;
}
/**
* Describe the effective audience of one interaction.
*
* Precedence mirrors the server evaluator's *narrowing* order so the copy can
* never promise a wider audience than the API allows: `human_only` (including a
* governed-action clamp) beats a named addressee, which beats `not_creator`,
* which beats the open default.
*/
export function describeInteractionAudience({
interaction,
creatorLabel,
addresseeLabel,
}: {
interaction: IssueThreadInteraction;
/** Display label of the creating actor, when known. */
creatorLabel?: string | null;
/** Display label of the named addressee, when the card has one. */
addresseeLabel?: string | null;
}): InteractionAudienceDescription {
return describeResolverAudience({
facts: {
effectiveResolverPolicy: interaction.effectiveResolverPolicy,
requestedResolverPolicy: interaction.requestedResolverPolicy,
effectiveResolverPolicySource: interaction.effectiveResolverPolicySource,
resolverPolicyProvenance: interaction.resolverPolicyProvenance,
hasAddressee: Boolean(interaction.addresseeAgentId || interaction.addresseeUserId),
isUserAddressee: Boolean(interaction.addresseeUserId),
},
creatorLabel,
addresseeLabel,
});
}
/**
* Describe an effective audience from the server-evaluated facts alone — used
* where the full interaction is not loaded, such as a collapsed attention row
* (PAP-17287).
*/
export function describeResolverAudience({
facts,
creatorLabel,
addresseeLabel,
}: {
facts: InteractionAudienceFacts;
creatorLabel?: string | null;
addresseeLabel?: string | null;
}): InteractionAudienceDescription {
const policy = facts.effectiveResolverPolicy;
const requestedPolicy = facts.requestedResolverPolicy;
const hasAddressee = facts.hasAddressee;
const isUserAddressee = facts.isUserAddressee === true;
// `formatAssigneeUserLabel` returns the display-cased "You" for the signed-in
// reader, which is right for a badge and wrong mid-sentence ("Only You can
// respond."). Every use below is inside a sentence.
const midSentence = (label: string) => (label === "You" ? "you" : label);
const addressee = midSentence(
addresseeLabel?.trim() || (isUserAddressee ? "the addressed user" : "the addressed agent"),
);
const creator = midSentence(creatorLabel?.trim() || "the agent that created it");
const summary = isUserAddressee
? `Only ${addressee} can respond.`
: policy === "human_only"
? `${hasAddressee ? `Assigned to ${addressee}. ` : ""}Only a person on the board can respond — agents cannot resolve this card.`
: hasAddressee
? `Only ${addressee} or a person on the board can respond.`
: policy === "not_creator"
? `Anyone in the organization except ${creator} can respond.`
: "Anyone in the organization can respond — the board or any agent, including the one that asked.";
// Same fact, fewer words: a collapsed row has to answer "is this mine to
// decide?" in one glance, next to the buttons that act on the answer.
const shortSummary = isUserAddressee
? `Only ${addressee} can respond`
: policy === "human_only"
? hasAddressee
? `Assigned to ${addressee} · board only`
: "Only the board can respond"
: hasAddressee
? `Only ${addressee} or the board can respond`
: policy === "not_creator"
? `Anyone except ${creator} can respond`
: "Anyone can respond";
const source = facts.effectiveResolverPolicySource;
const provenance = facts.resolverPolicyProvenance;
// Narrowing the requester did *not* ask for is the only thing worth an extra
// sentence: a governed-action clamp, a company cap, or a card created before
// open resolution existed. An explicitly requested restriction is already
// fully described by `summary`.
const narrowedNote = source === "governed_action"
? "This card runs a governed action, so it stays human-only whatever audience was requested."
: source === "company_cap"
? `Organization interaction governance narrowed this from ${RESOLVER_POLICY_LABELS[requestedPolicy]} to ${RESOLVER_POLICY_LABELS[policy]}.`
: provenance === "legacy_inherited_restriction"
? "Created before Anyone became the default, so it stays restricted. A new card would be open."
: null;
const narrowedBy: InteractionAudienceNarrowing | null = source === "governed_action"
? "governed_action"
: source === "company_cap"
? "company_cap"
: provenance === "legacy_inherited_restriction"
? "legacy_restriction"
: policy !== "anyone"
? "requested"
: hasAddressee
? "addressee"
: null;
return {
policy,
requestedPolicy,
// A named addressee owns the response, so the label must not read "Anyone"
// while the sentence next to it names one actor. `human_only` wins for an
// agent addressee, while a user addressee is the narrower human audience.
label: (policy !== "human_only" || isUserAddressee) && hasAddressee
? "Addressed"
: RESOLVER_POLICY_LABELS[policy],
summary,
shortSummary,
isOpen: policy === "anyone" && !hasAddressee,
narrowedBy,
narrowedNote,
};
}
/**
* Audience of an `issue_thread_interaction` attention row, from the server
* metadata the feed ships with the item (PAP-17287). Returns `null` for every
* other source kind and for a feed built before the metadata existed, so a
* caller renders nothing rather than guessing a policy client-side.
*/
export function describeAttentionResolverAudience(
item: Pick<AttentionItem, "sourceKind" | "resolverAudience">,
): InteractionAudienceDescription | null {
if (item.sourceKind !== "issue_thread_interaction") return null;
const audience: AttentionResolverAudience | null | undefined = item.resolverAudience;
if (!audience) return null;
return describeResolverAudience({
facts: {
effectiveResolverPolicy: audience.effectiveResolverPolicy,
requestedResolverPolicy: audience.requestedResolverPolicy,
effectiveResolverPolicySource: audience.effectiveResolverPolicySource,
resolverPolicyProvenance: audience.resolverPolicyProvenance,
hasAddressee: Boolean(audience.addresseeAgentId || audience.addresseeUserId),
isUserAddressee: Boolean(audience.addresseeUserId),
},
creatorLabel: audience.createdByAgentName,
addresseeLabel: audience.addresseeName,
});
}