feat: a trigger may attach a standing instruction to its prompt (issue #60)

`run.instructions` is one line of operator text on a forge trigger, rendered
into the USER prompt's envelope: above the fenced data region, below the
harness's own numbered steps, and BEFORE the never-merge paragraph.

Label, comment and pull_request triggers carried no prompt text at all, so "for
this trigger specifically: the tests run with X, this repo's convention is Y"
had to be committed into the repo's SKILL.md or pushed into the deployment-wide
persona, which applies it to every job everywhere.

PLACEMENT IS ARGUED, NOT ASSUMED, because it is the whole of the change.

CONST-ISSUE-TEXT-IS-DATA governs event PAYLOADS. This is operator text from a
reviewed, git-tracked file, which passes the same mutability test
DES-FLOWS-ARE-DATA-PERSONA-IS-CODE already applies to the overlay persona:
"Mutability, not the persona/flow label, is the boundary."

Inside the fenced data region it would be DOCUMENTED TO BE IGNORED, since
dataRegion tells the model everything below its heading must be reported rather
than obeyed. In the system prompt it would work and be marginally cheaper per
turn, and is still refused: every other member of that layer is read from a
fixed file path once at loader build, which is the shape
CONST-PERSONA-IN-CACHED-PREFIX's acceptance leans on, and run.task is already
contracted user-prompt-only, so two operator text fields with two placements
would be an incoherence.

It sits BEFORE the never-merge paragraph because later text reads as more
specific, and the harness's non-negotiables must be the last thing before the
data region rather than something an operator instruction appears to qualify.
That costs nothing and forecloses the argument.

CONST-ISSUE-TEXT-IS-DATA gains one clause for the region it never described, in
the shape of the replay clause run.resume added, written as four checkable parts
rather than as a permission. This widens WHO may write an instruction, from the
flow author and the deploy-time operator to the same operator per trigger, and
not WHAT may become one.

dataRegion is UNCHANGED, which is the point: because the text lands in the
envelope, the shared export keeps its signature and the new-parameters-go-last
rule is honoured with no hole threaded through three sibling forges. They are
still edited, all three, because a gitlab trigger whose instruction was silently
dropped is the no-op this project refuses.

Refused on cron, naming run.task: a local job's prompt IS run.task, with no
envelope, no data heading and no fence, so there is no standing region distinct
from the task for a second field to occupy, and two fields writing one region
with an undefined order would both appear to work.

Capped at 2000 characters, refused rather than truncated. The caching argument
does NOT justify this and the spec says so: the text is written once,
session.prompt() is called once, and at the pin pi-ai attaches cache_control to
the LAST USER MESSAGE as well as the system prompt. What justifies it is a
context overflow inside a PAID container with no pre-spend signal, and keeping
the field in its lane, since anything longer belongs in the flow's SKILL.md or
the overlay persona. The refusal names both. Surrounding whitespace is NOT
refused, unlike run.image, because whitespace changes what an image REFERENCE
means and does not change what prose means; whitespace-only is.

No content filtering, and a comment says why: placement is the boundary and the
delimiter is defence in depth, so an operator who writes a fake data heading
into their own text has forged nothing -- the real heading is emitted after
theirs and still opens the real region. There is a test for exactly that.

No model-callable path: dispatch_trigger_add/_edit gain no parameter, on
run.resume's test rather than f.forge's, because standing text reaching every
future job of a trigger is a self-influence channel one confirm dialog does not
bound.

CONST-ISSUE-TEXT-IS-DATA AMENDED. NEW REQ-PER-TRIGGER-INSTRUCTION and
DES-TRIGGER-INSTRUCTION-IN-THE-ENVELOPE (five rejected placements recorded).
INT-TRIGGERS-FILE-CONTRACT, INT-CONTAINER-JOB-INPUTS: AMENDED.

CONST-PERSONA-IN-CACHED-PREFIX UNCHANGED, checked, and it records WHY the
obvious reading is wrong rather than borrowing an argument that does not apply.
CONST-TRIGGER-AUTHOR-GATE UNCHANGED, checked: the field changes how a job is
prompted, never whether it starts. CONST-ISOLATION-CONTAINER-PER-JOB,
INT-CONTAINER-RUNTIME-CONTRACT, CONST-BUDGET-BEFORE-TOKENS,
CONST-RETRY-INFRA-ONLY, INT-WEBHOOK-PAYLOAD-SUBSET, REQ-PER-TRIGGER-SKILLS,
DES-FLOWS-ARE-DATA-PERSONA-IS-CODE: UNCHANGED, checked.

Mutation-checked: moving the block below the never-merge paragraph turns the
last-word test red, and fencing it turns the not-fenced test red.

2069 tests, 0 failures, 0 skipped in the CI posture.

Signed-off-by: Rob Boerman <robboerman@live.nl>

Author: edgehero

README.md

@@ -180,6 +180,11 @@ or what it costs):
   ([`docs/global-pi-overlay.md`](docs/global-pi-overlay.md)).
 - `"replicas": 2` (GitHub only) races independent sandboxes on the same event and opens one PR per
   replica. Each replica spends its own budget slot ([`docs/replicas.md`](docs/replicas.md)).
+- `"instructions"` attaches one line of standing text to that trigger (forge triggers only, up to 2000
+  characters). It reaches the job's prompt above the issue or PR text, labelled as coming from you rather
+  than from the issue, so "the tests run with pnpm here" applies to every run of that trigger without
+  being committed to the repo or pushed into the deployment wide persona. Cron triggers use `task`
+  instead, which is the same text in the same place.
 - `"resume": true` continues the session that opened the PR ([`docs/sessions.md`](docs/sessions.md)).
 - `"github": true` on a cron trigger mints the same per-job GitHub token the webhook path gets, so a
   scheduled flow can use `gh`.

admin/src/read-model.mjs

@@ -696,6 +696,10 @@ export function normalizeTriggerForDisplay(entry) {
   // `image`, and shown for the same reason: which skills a job loads IS what the agent can do. `null` is
   // the none sentinel, matching this function's own convention.
   const skillsDir = typeof run.skillsDir === "string" && run.skillsDir.trim() !== "" ? run.skillsDir : null;
+  // Whether this trigger attaches operator standing text (REQ-PER-TRIGGER-INSTRUCTION). A BOOLEAN, not
+  // the text: the panel line must say that a trigger carries one, and the text itself may be 2000
+  // characters. The detail view is where the words belong.
+  const instructions = typeof run.instructions === "string" && run.instructions.trim() !== "";
   // An opt-IN, so `=== true` and not `!== false` -- the opposite test from `packages` directly above, and
   // the difference is the whole point. Getting this polarity wrong is the defect 0.1.4 shipped a fix for:
   // the riskiest triggers rendered with no badge and no warning, quiet exactly where the risk was.
@@ -721,12 +725,13 @@ export function normalizeTriggerForDisplay(entry) {
         packages,
         image,
         skillsDir,
+        instructions,
         resume,
       };
     case "label":
-      return { type: "label", any: normalizeSelector(on.any), all: normalizeSelector(on.all), none: normalizeSelector(on.none), flow, packages, image, skillsDir, resume, replicas, forge };
+      return { type: "label", any: normalizeSelector(on.any), all: normalizeSelector(on.all), none: normalizeSelector(on.none), flow, packages, image, skillsDir, instructions, resume, replicas, forge };
     case "comment":
-      return { type: "comment", phrase: typeof on.phrase === "string" ? on.phrase : null, flow, packages, image, skillsDir, resume, replicas, forge };
+      return { type: "comment", phrase: typeof on.phrase === "string" ? on.phrase : null, flow, packages, image, skillsDir, instructions, resume, replicas, forge };
     case "pull_request":
       return {
         type: "pull_request",
@@ -738,6 +743,7 @@ export function normalizeTriggerForDisplay(entry) {
         packages,
         image,
         skillsDir,
+        instructions,
         resume,
         replicas,
         forge,

admin/src/render.mjs

@@ -181,22 +181,25 @@ function triggerLine(t) {
   // the full path lives in the trigger detail view, where the panel is the operator's own session on their
   // own host and a path discloses nothing new.
   const skl = t?.skillsDir ? `  [skills ${String(t.skillsDir).split(/[\\/]/).filter(Boolean).pop()}]` : "";
+  // A trigger that puts operator standing text into every job's prompt says so. Same doctrine as the
+  // badges above: a trigger that changes what the agent is told must never render like one that does not.
+  const ins = t?.instructions === true ? "  [instructions]" : "";
   const res = t?.resume === true ? "  [resume]" : "";
   // A trigger that turns one delivery into N paid runs says so (REQ-REPLICA-RUNS). Same class of badge as
   // [resume]: not a preference an operator can skim past, but the field that multiplies the bill. Absent on
   // an unreplicated trigger, appended last, so every existing line is byte-identical.
   const rep = t?.replicas > 1 ? `  [x${t.replicas}]` : "";
   switch (t?.type) {
     case "cron":
-      return `cron  ${t.id ?? "-"}  ${t.pattern ?? "-"} → ${t.folder ?? "-"}/${flow}${forge}${pkgs}${img}${skl}${res}${rep}`;
+      return `cron  ${t.id ?? "-"}  ${t.pattern ?? "-"} → ${t.folder ?? "-"}/${flow}${forge}${pkgs}${img}${skl}${ins}${res}${rep}`;
     case "label":
-      return `label  ${ruleClauses(t) || "(no selector)"} → ${flow}${forge}${pkgs}${img}${skl}${res}${rep}`;
+      return `label  ${ruleClauses(t) || "(no selector)"} → ${flow}${forge}${pkgs}${img}${skl}${ins}${res}${rep}`;
     case "comment":
-      return `comment  "${t.phrase ?? "-"}" → ${flow}${forge}${pkgs}${img}${skl}${res}${rep}`;
+      return `comment  "${t.phrase ?? "-"}" → ${flow}${forge}${pkgs}${img}${skl}${ins}${res}${rep}`;
     case "pull_request": {
       const clauses = ruleClauses(t);
       const action = `action[${(t.action ?? []).join(",")}]`;
-      return `pull_request  ${action}${clauses ? ` ${clauses}` : ""} → ${flow}${forge}${pkgs}${img}${skl}${res}${rep}`;
+      return `pull_request  ${action}${clauses ? ` ${clauses}` : ""} → ${flow}${forge}${pkgs}${img}${skl}${ins}${res}${rep}`;
     }
     default:
       return "(unknown trigger)";

admin/test/read-model.test.mjs

@@ -448,10 +448,10 @@ test("readTriggers normalizes each on.type into its discriminated display record
   const res = readTriggers({ triggersPath: "/x/triggers.json", fs: fakeFs(files) });
   // Every entry omits `run.packages`, and packages is an OPT-OUT -- so all four normalize to `true`.
   assert.deepEqual(res.triggers, [
-    { type: "cron", id: "nightly", pattern: "0 3 * * *", folder: "/srv/p", flow: "tidy", model: null, packages: true, image: null, skillsDir: null, resume: false },
-    { type: "label", any: ["pi:frontend"], all: [], none: ["wontfix"], flow: "frontend-fix", packages: true, image: null, skillsDir: null, resume: false, replicas: null, forge: "github" },
-    { type: "comment", phrase: "@pi", flow: "fix", packages: true, image: null, skillsDir: null, resume: false, replicas: null, forge: "github" },
-    { type: "pull_request", action: ["labeled"], any: ["pi:review"], all: [], none: [], flow: "review", packages: true, image: null, skillsDir: null, resume: false, replicas: null, forge: "github" },
+    { type: "cron", id: "nightly", pattern: "0 3 * * *", folder: "/srv/p", flow: "tidy", model: null, packages: true, image: null, skillsDir: null, instructions: false, resume: false },
+    { type: "label", any: ["pi:frontend"], all: [], none: ["wontfix"], flow: "frontend-fix", packages: true, image: null, skillsDir: null, instructions: false, resume: false, replicas: null, forge: "github" },
+    { type: "comment", phrase: "@pi", flow: "fix", packages: true, image: null, skillsDir: null, instructions: false, resume: false, replicas: null, forge: "github" },
+    { type: "pull_request", action: ["labeled"], any: ["pi:review"], all: [], none: [], flow: "review", packages: true, image: null, skillsDir: null, instructions: false, resume: false, replicas: null, forge: "github" },
   ]);
 });
 
@@ -516,7 +516,7 @@ test("readTriggers skips an entry that is not a usable { on, run } object (viewe
     }),
   };
   const res = readTriggers({ triggersPath: "/x/triggers.json", fs: fakeFs(files) });
-  assert.deepEqual(res.triggers, [{ type: "label", any: ["pi:frontend"], all: [], none: [], flow: "frontend-fix", packages: true, image: null, skillsDir: null, resume: false, replicas: null, forge: "github" }]);
+  assert.deepEqual(res.triggers, [{ type: "label", any: ["pi:frontend"], all: [], none: [], flow: "frontend-fix", packages: true, image: null, skillsDir: null, instructions: false, resume: false, replicas: null, forge: "github" }]);
 });
 
 test("readTriggers returns { invalid } when there is no triggers array", () => {

docs/workflows.md

@@ -89,6 +89,27 @@ copied at all, because pi would register no skill for it. A skill past the size
 refuses the job with the cap named, which is deliberate: a partly copied skill is a skill whose
 instructions point at files that are not there.
 
+## A standing instruction, and what it is not
+
+`run.instructions` on a forge trigger attaches one line of your own text to every job that trigger
+starts. It reaches the prompt above the issue or pull request text, labelled as coming from you, so the
+agent can tell it apart from whatever a stranger wrote in the issue.
+
+It is the smallest of three places instructions can live, and picking the right one matters more than the
+feature does:
+
+| Where | Scope | Reviewed by | Reach for it when |
+|---|---|---|---|
+| `run.instructions` | one trigger | your edit to `triggers.json` | a sentence or two, specific to this pairing of event and flow |
+| the flow's `SKILL.md` | every job that runs that flow, on that repo | a merge on the target repo | the instructions ARE the procedure |
+| the overlay's `APPEND_SYSTEM.md` | every job, every repo, every flow | `import-pi`, at deploy time | house style that outlives any one trigger |
+
+The 2000 character cap is there to keep the first row from quietly becoming the second. If your standing
+text no longer fits on a screen, it is a flow, and it belongs in a file someone reviews.
+
+Cron triggers do not take it, and use `task` instead. That is not an omission: a scheduled job's whole
+prompt IS its `task`, so a second field would write the same region with no defined order between them.
+
 ## The structured case: stage a workflow extension
 
 **Nothing installs at job time.** Job containers run with `PI_OFFLINE=1` and, on the shipped image, no

receiver/src/config.mjs

@@ -275,13 +275,13 @@ function loadTriggers(env, readFile, fileExists) {
 		knownFlows.add(run.flow);
 		const group = groups[run.kind];
 		if (on.type === "label") {
-			group.label.push({ index, predicate: { any: on.any, all: on.all, none: on.none }, flow: run.flow, packages: run.packages, image: run.image, skillsDir: run.skillsDir, resume: run.resume, replicas: run.replicas, repository: run.repository });
+			group.label.push({ index, predicate: { any: on.any, all: on.all, none: on.none }, flow: run.flow, packages: run.packages, image: run.image, skillsDir: run.skillsDir, instructions: run.instructions, resume: run.resume, replicas: run.replicas, repository: run.repository });
 		} else if (on.type === "comment") {
-			group.comment = { index, phrase: on.phrase, defaultFlow: run.flow, packages: run.packages, image: run.image, skillsDir: run.skillsDir, resume: run.resume, replicas: run.replicas, repository: run.repository }; // parseTriggers guarantees at most one per forge
+			group.comment = { index, phrase: on.phrase, defaultFlow: run.flow, packages: run.packages, image: run.image, skillsDir: run.skillsDir, instructions: run.instructions, resume: run.resume, replicas: run.replicas, repository: run.repository }; // parseTriggers guarantees at most one per forge
 		} else if (on.type === "pull_request") {
 			// `reviewStates` is null rather than an empty Set when unnarrowed: the filter tests it for
 			// presence, and an empty Set would read as "no verdict matches" and silently refuse everything.
-			group.pullRequest.push({ index, actions: new Set(on.action), reviewStates: on.reviewState ? new Set(on.reviewState) : null, predicate: { any: on.any, all: on.all, none: on.none }, flow: run.flow, packages: run.packages, image: run.image, skillsDir: run.skillsDir, resume: run.resume, replicas: run.replicas });
+			group.pullRequest.push({ index, actions: new Set(on.action), reviewStates: on.reviewState ? new Set(on.reviewState) : null, predicate: { any: on.any, all: on.all, none: on.none }, flow: run.flow, packages: run.packages, image: run.image, skillsDir: run.skillsDir, instructions: run.instructions, resume: run.resume, replicas: run.replicas });
 		}
 	}
 

receiver/src/filter-azure.mjs

@@ -110,6 +110,7 @@ export function filterAzure(subset, triggers, knownFlows, selfId, authorized, de
 		// /job/event.json, and a worker-host path in an agent-readable file is the leak prepare-local's
 		// basename(folder) restraint already exists to prevent.
 		...(resolved.skillsDir !== undefined ? { skillsDir: resolved.skillsDir } : {}),
+		...(resolved.instructions !== undefined ? { instructions: resolved.instructions } : {}),
 		...(resolved.resume !== undefined ? { resume: resolved.resume } : {}),
 		trigger: {
 			event,
@@ -171,6 +172,7 @@ function matchLabelRules(subset, triggers, labels, action) {
 		packages: rule.packages,
 		image: rule.image,
 		skillsDir: rule.skillsDir,
+		instructions: rule.instructions,
 		resume: rule.resume,
 		matched: { index: rule.index, type: "label", label: matchedLabel(L, rule.predicate) },
 		target: { type: "issue", number: subset.target?.number, title: subset.target?.title, body: subset.target?.body },
@@ -200,6 +202,7 @@ function routeComment(subset, triggers, knownFlows, targetType) {
 		packages: triggers.comment.packages,
 		image: triggers.comment.image,
 		skillsDir: triggers.comment.skillsDir,
+		instructions: triggers.comment.instructions,
 		resume: triggers.comment.resume,
 		matched: { index: triggers.comment.index, type: "comment", phrase },
 		// No author_association: Azure has none, and the authority that admitted this comment was resolved
@@ -227,6 +230,7 @@ function routePullRequest(subset, triggers, action) {
 			packages: rule.packages,
 			image: rule.image,
 			skillsDir: rule.skillsDir,
+			instructions: rule.instructions,
 			resume: rule.resume,
 			matched: { index: rule.index, type: "pull_request", action },
 			target: {

receiver/src/filter-forgejo.mjs

@@ -112,6 +112,7 @@ export function filterForgejo(eventName, subset, triggers, knownFlows, selfId, a
 		// /job/event.json, and a worker-host path in an agent-readable file is the leak prepare-local's
 		// basename(folder) restraint already exists to prevent.
 		...(resolved.skillsDir !== undefined ? { skillsDir: resolved.skillsDir } : {}),
+		...(resolved.instructions !== undefined ? { instructions: resolved.instructions } : {}),
 		...(resolved.resume !== undefined ? { resume: resolved.resume } : {}),
 		trigger: {
 			event: eventName,
@@ -139,6 +140,7 @@ function routeIssueLabel(subset, triggers) {
 		packages: rule.packages, // the MATCHED rule's fields -- rules in one file may differ on them
 		image: rule.image,
 		skillsDir: rule.skillsDir,
+		instructions: rule.instructions,
 		resume: rule.resume,
 		matched: { index: rule.index, type: "label", label: matchedLabel(L, rule.predicate) },
 		target: { type: "issue", number: subset.issue?.number, title: subset.issue?.title, body: subset.issue?.body },
@@ -173,6 +175,7 @@ function routeComment(subset, triggers, knownFlows) {
 		packages: triggers.comment.packages,
 		image: triggers.comment.image,
 		skillsDir: triggers.comment.skillsDir,
+		instructions: triggers.comment.instructions,
 		resume: triggers.comment.resume,
 		matched: { index: triggers.comment.index, type: "comment", phrase },
 		// The invoking comment rides on the trigger. No author_association: Forgejo has none, and the
@@ -198,6 +201,7 @@ function routePullRequest(subset, triggers, action) {
 			packages: rule.packages,
 			image: rule.image,
 			skillsDir: rule.skillsDir,
+			instructions: rule.instructions,
 			resume: rule.resume,
 			matched: { index: rule.index, type: "pull_request", action },
 			target: {

receiver/src/filter-gitlab.mjs

@@ -103,6 +103,7 @@ export function filterGitLab(subset, triggers, knownFlows, selfId, authorized, d
 		// /job/event.json, and a worker-host path in an agent-readable file is the leak prepare-local's
 		// basename(folder) restraint already exists to prevent.
 		...(resolved.skillsDir !== undefined ? { skillsDir: resolved.skillsDir } : {}),
+		...(resolved.instructions !== undefined ? { instructions: resolved.instructions } : {}),
 		// Conditional like packages/image, and for the same reason: an unflagged job's data must stay
 		// byte-identical to today's, so the key is absent rather than present-and-undefined.
 		...(resolved.resume !== undefined ? { resume: resolved.resume } : {}),
@@ -137,6 +138,7 @@ function routeLabel(subset, triggers, targetType) {
 		packages: rule.packages,
 		image: rule.image,
 		skillsDir: rule.skillsDir,
+		instructions: rule.instructions,
 		resume: rule.resume,
 		matched: { index: rule.index, type: "label", label: matchedLabel(added, rule.predicate) },
 		target: buildTarget(subset, targetType),
@@ -195,6 +197,7 @@ function mrResult(subset, rule, matched) {
 		packages: rule.packages,
 		image: rule.image,
 		skillsDir: rule.skillsDir,
+		instructions: rule.instructions,
 		resume: rule.resume,
 		matched,
 		target: buildTarget(subset, "pull_request"),
@@ -230,6 +233,7 @@ function routeNote(subset, triggers, knownFlows) {
 		packages: triggers.comment.packages,
 		image: triggers.comment.image,
 		skillsDir: triggers.comment.skillsDir,
+		instructions: triggers.comment.instructions,
 		resume: triggers.comment.resume,
 		matched: { index: triggers.comment.index, type: "comment", phrase },
 		target: buildTarget(subset, targetType),

receiver/src/filter.mjs

@@ -116,6 +116,7 @@ export function filter(eventName, subset, cfg, selfId, deliveryId) {
 		// /job/event.json, and a worker-host path in an agent-readable file is the leak prepare-local's
 		// basename(folder) restraint already exists to prevent.
 		...(resolved.skillsDir !== undefined ? { skillsDir: resolved.skillsDir } : {}),
+		...(resolved.instructions !== undefined ? { instructions: resolved.instructions } : {}),
 		// Conditional like packages/image, and for the same reason: an unflagged job's data must stay
 		// byte-identical to today's, so the key is absent rather than present-and-undefined.
 		...(resolved.resume !== undefined ? { resume: resolved.resume } : {}),
@@ -159,6 +160,7 @@ function routeIssueLabel(subset, triggers) {
 		packages: rule.packages, // the MATCHED rule's fields -- rules in one file may differ on them
 		image: rule.image,
 		skillsDir: rule.skillsDir,
+		instructions: rule.instructions,
 		resume: rule.resume,
 		replicas: rule.replicas,
 		matched: { index: rule.index, type: "label", label: matchedLabel(L, rule.predicate) },
@@ -204,6 +206,7 @@ function routeComment(subset, triggers, knownFlows) {
 		packages: triggers.comment.packages,
 		image: triggers.comment.image,
 		skillsDir: triggers.comment.skillsDir,
+		instructions: triggers.comment.instructions,
 		resume: triggers.comment.resume,
 		replicas: triggers.comment.replicas,
 		matched: { index: triggers.comment.index, type: "comment", phrase },
@@ -297,6 +300,7 @@ function routePullRequest(subset, triggers, action) {
 			packages: rule.packages, // the MATCHED rule's fields -- rules in one file may differ on them
 			image: rule.image,
 			skillsDir: rule.skillsDir,
+			instructions: rule.instructions,
 			resume: rule.resume,
 			replicas: rule.replicas,
 			matched: { index: rule.index, type: "pull_request", action },