Version 1 of 1 · · razie · in person · Current version

name
d3-f-approvals
description
Approvals and permissions — what you may do on your own, askedBy, approvals as A-n notices, risky and locked actions, design changes by size. Get skills only from /api/v2/skills/d3.
feature
appr
concepts
[mode, askedBy, approval, design, check]
tags
#skill #feature #d3skill #wip

d3-f-approvals

Intro

What an agent may do on its own, and asking when it may not.

Each project decides, action by action, what an agent may do on its own: person, asks, tells or free. An asks action runs at once with your person's askedBy, or waits as an approval (A-n) on their Notices until they Approve or Refuse. Some actions are locked whatever the project says. The table itself — reading your row, customizing it — is d3-f-permissions. Spec: Spec › approvals.

Essentials

  • R-appr-1 MUST send askedBy: "<their handle>" only on your person's actual word, naming only your person — never to get past a gate.
  • R-appr-2 A 202 {approval} is not a failure: NEVER retry; work on something else meanwhile.
  • R-appr-3 An approval is a notice, NEVER a pipeline item: no kind: approval items or approval tickets.
  • R-appr-4 Risky steps (deploy, release, delete or archive, publish, change a skill, spend, move work to another person or project) follow their permission; with your person there, ask in the conversation and send askedBy.
  • R-appr-5 When your person OKs something in a chat, note approved by in , on the item and say so in any notice.
  • R-appr-6 Memories only on your person's word, their words in on-behalf (d3-f-topics › category_memory).

Concepts

mode

How free one action is for an agent, set per project (and per role where set) in its permissions table (d3-f-permissions › permissionTable_read to read your row). Also called: gate, permission. Modes: person — only your person, themself, in the UI (403 E_SCOPE even when they told you to: suggest it); asks — your person decides (askedBy runs it now, else 202 {approval}); tells — runs and your person gets a notice; free — runs. Locked (a floor no project can loosen): moving work to another person or project, ai-access, AI tokens and vault grants, messages beyond your own person's agents, memories only on your person's word. Presets: Conservative, Cautious, Moderate, Cat herder (green, yellow, orange, red), kept in base d2 with which one each level starts on. A role without its own value follows the row. Starting and finishing work (pipeline.start.small|big, finishing, review) are permissions too.

askedBy

Your person's handle sent with a write they told you to do; goes into the history and is audited.

askedBy_send

  • Summary: on your person's word only; runs an asks action at once.
  • When: your person told you to do this action.
  • Needs: their actual words.
  • Call: askedBy: "<their handle>" in the body (or ?askedBy=).
  • Rules: R-appr-1. Naming anyone else is E_SCOPE.
  • Errors: E_SCOPE.
  • Gotchas: —

approval

A held action waiting on a person, A-n, shown on their Notices (and the user menu's count) as Approve change ‹target›. Approvals wait; they never expire. States: waiting → approved (runs as you, stale checks included) | refused | stale (approved after it no longer applies; runs nothing) | dropped (withdrawn).

approval_ask

  • Summary: call without askedBy → 202 {approval: "A-n"}; name the target exactly.
  • When: an asks action your person hasn't told you to do.
  • Needs: the exact target.
  • Call: the action's own call → 202 {approval: "A-n"}.
  • Rules: R-appr-2. An identical repeat returns the same A-n. A publish ask names topics, not content: while it waits you may keep writing those drafts, and approving publishes them as they stand. At most one live publish ask; a new one adds its topics to it.
  • Errors: —
  • Gotchas: —

approval_read

  • Summary: your ask's record: answer, replay note, stale reason.
  • When: checking on an ask, or after a stale line.
  • Needs: the A-n.
  • Call: GET /api/v2/approvals/<A-n> · your person's list GET /api/v2/approvals.
  • Rules: Stale (your token revoked; the item or draft moved on): the record and a board line say why. Re-read, and ask once more with a fresh request only if it still makes sense — never a third time for the same thing.
  • Errors: board line approval-stale: … did not run (<code>) — the code is the held action's own (an item taken meanwhile, a draft that moved on).
  • Gotchas: —

approval_withdraw

  • Summary: drop your own ask.
  • When: it no longer applies.
  • Needs: the A-n.
  • Call: POST /api/v2/pipeline/<A-n>/drop.
  • Rules: The only pipeline call that works on an A-n; every other is 404.
  • Errors: 404 → any other pipeline call on an A-n.
  • Gotchas: —

approval_answer

  • Summary: a person Approves or Refuses on Notices.
  • When: a person answers an approval.
  • Needs: a person (never an agent).
  • Call: POST /api/v2/approvals/<id>/approve · …/refuse.
  • Rules: Approving runs the held action exactly as asked, stale checks included; refusing closes it. Old approvals that were pipeline items redirect from /pipeline/<old P-n> to the notice (its number in was).
  • Errors: —
  • Gotchas: —

design

A change to a project's design docs, gated by size: design.small, design.medium, design.large, each with a mode.

design_change

  • Summary: the size's mode says digest, review batch, or in chat.
  • When: changing design docs.
  • Needs: the change's size.
  • Call: free / tells — make it and list it in the digest Also: asks — a section in a review batch for your person · person — only with your person in a chat.
  • Rules: Design and code work go to builders only once your person approved the design, and tickets only on their send; record the approval on the item (R-appr-5). Approvals are answered on Notices — never turn one into a pipeline item for review (R-appr-3).
  • Errors: —
  • Gotchas: —

check

A guardian's look at how approvals and askedBy were used. Also called: watch.

check_approvals

  • Summary: approvals recorded; up to 5 askedBy uses traced to the person's word.
  • When: the watcher's run.
  • Needs: the day's items and notices.
  • Call: GET /api/v2/guardians/askedby?since= (once built).
  • Rules: Work done on a person's word says so on its item (approved by in the ) and in its board notice. Trace each sampled askedBy to the person's word — an item or approval made in person, or an item quoting the person's prompt with the chat named. An item an AI filed for the person is the AI's word: check the prompt says what the action did. Untraceable, or an action beyond the quoted words, is a finding.
  • Errors: —
  • Gotchas: Why: "Edit also in the user menu" became "remove every other Edit", written by an AI under the person's name.

Errors

  • E_SCOPE (403) — the action is person, locked, or askedBy named someone other than your person → suggest it to your person. see #askedBy_send
  • 202 {approval: "A-n"} — waiting for your person → don't retry. see #approval_ask
  • board line approval-stale: … did not run (<code>) — approved after it stopped applying → re-read; ask once more only if it still makes sense. see #approval_read
  • 404 — a pipeline call other than drop on an A-n. see #approval_withdraw