From 5756503c301b816e86b9640e801f151c43171daa Mon Sep 17 00:00:00 2001 From: thePR0M3TH3AN <53631862+PR0M3TH3AN@users.noreply.github.com> Date: Fri, 13 Feb 2026 12:02:02 -0500 Subject: [PATCH] docs(agents): enforce deterministic PR agent extraction --- docs/agents/prompts/META_PROMPTS.md | 32 ++++++++++++++++++++----- docs/agents/prompts/daily-scheduler.md | 19 +++++++++++---- docs/agents/prompts/weekly-scheduler.md | 19 +++++++++++---- 3 files changed, 56 insertions(+), 14 deletions(-) diff --git a/docs/agents/prompts/META_PROMPTS.md b/docs/agents/prompts/META_PROMPTS.md index 6a52005e..ed656341 100644 --- a/docs/agents/prompts/META_PROMPTS.md +++ b/docs/agents/prompts/META_PROMPTS.md @@ -14,9 +14,18 @@ before choosing a task — is to run these two commands. Not later. NOW. COMMAND 1 — Check for open daily agent PRs: - curl -s "https://api.github.com/repos/PR0M3TH3AN/bitvid/pulls?state=open&per_page=100" | jq '{count: length, titles: [.[].title]}' + curl -s "https://api.github.com/repos/PR0M3TH3AN/bitvid/pulls?state=open&per_page=100" | jq '{count: length, prs: [.[] | {number, title, draft, created_at, head: {ref: .head.ref}, labels: [.labels[].name]}]}' - Review the output. Any title containing "[daily]" means that agent is OFF LIMITS. + Normalize each PR to an agent name using this deterministic rule: + 1) Preferred: parse `head.ref` as `agents/daily//...` + 2) Fallback: parse agent name from title only if branch parsing fails + 3) If agent cannot be derived from metadata, treat as GLOBAL LOCK warning and do not schedule daily tasks until manually resolved + + OFF LIMITS rule: any PR that maps to a daily-cadence agent is excluded, regardless of title tag format. + + Valid daily claim branch examples: + - agents/daily/docs-agent/2026-02-13-claim + - agents/daily/test-audit-agent/run-2026-02-13 COMMAND 2 — Check for in-progress task logs: @@ -31,7 +40,8 @@ STOP HERE. Do not proceed until both outputs are pasted. --- Now analyze the output: -- Any agent name that appears in an open PR title is EXCLUDED. +- Any PR that maps to a daily-cadence agent is EXCLUDED (branch parsing first, title fallback second). +- If any PR agent cannot be derived from metadata, treat as GLOBAL LOCK warning and do not schedule this cadence. - Any agent with a "_started.md" log file that has no matching "_completed.md" or "_failed.md" from the same agent at a later timestamp is EXCLUDED (unless the started file is more than 24 hours old). @@ -62,9 +72,18 @@ before choosing a task — is to run these two commands. Not later. NOW. COMMAND 1 — Check for open weekly agent PRs: - curl -s "https://api.github.com/repos/PR0M3TH3AN/bitvid/pulls?state=open&per_page=100" | jq '{count: length, titles: [.[].title]}' + curl -s "https://api.github.com/repos/PR0M3TH3AN/bitvid/pulls?state=open&per_page=100" | jq '{count: length, prs: [.[] | {number, title, draft, created_at, head: {ref: .head.ref}, labels: [.labels[].name]}]}' - Review the output. Any title containing "[weekly]" means that agent is OFF LIMITS. + Normalize each PR to an agent name using this deterministic rule: + 1) Preferred: parse `head.ref` as `agents/weekly//...` + 2) Fallback: parse agent name from title only if branch parsing fails + 3) If agent cannot be derived from metadata, treat as GLOBAL LOCK warning and do not schedule weekly tasks until manually resolved + + OFF LIMITS rule: any PR that maps to a weekly-cadence agent is excluded, regardless of title tag format. + + Valid weekly claim branch examples: + - agents/weekly/ci-health-agent/2026-02-weekly-run + - agents/weekly/weekly-synthesis-agent/sprint-07 COMMAND 2 — Check for in-progress task logs: @@ -79,7 +98,8 @@ STOP HERE. Do not proceed until both outputs are pasted. --- Now analyze the output: -- Any agent name that appears in an open PR title is EXCLUDED. +- Any PR that maps to a weekly-cadence agent is EXCLUDED (branch parsing first, title fallback second). +- If any PR agent cannot be derived from metadata, treat as GLOBAL LOCK warning and do not schedule this cadence. - Any agent with a "_started.md" log file that has no matching "_completed.md" or "_failed.md" from the same agent at a later timestamp is EXCLUDED (unless the started file is more than 24 hours old). diff --git a/docs/agents/prompts/daily-scheduler.md b/docs/agents/prompts/daily-scheduler.md index ff4fa509..efb7d1d6 100644 --- a/docs/agents/prompts/daily-scheduler.md +++ b/docs/agents/prompts/daily-scheduler.md @@ -76,12 +76,22 @@ If you arrived here from the meta prompt and already ran these commands and past Run this command: ```bash -curl -s "https://api.github.com/repos/PR0M3TH3AN/bitvid/pulls?state=open&per_page=100" | jq '{count: length, titles: [.[].title]}' +curl -s "https://api.github.com/repos/PR0M3TH3AN/bitvid/pulls?state=open&per_page=100" | jq '{count: length, prs: [.[] | {number, title, draft, created_at, head: {ref: .head.ref}, labels: [.labels[].name]}]}' ``` **Paste the complete raw output.** If the command returns nothing or errors, write: `OUTPUT: (empty — no results)` -Review the titles in the output. Every agent name that appears in a PR title containing `[daily]` is **OFF LIMITS** — do not select it. +Normalize each PR to an agent name using this deterministic rule: +1. **Preferred:** parse the branch name from `head.ref` with the convention `agents/daily//...`. +2. **Fallback:** only if branch parsing fails, parse `` from the PR title. +3. If an agent cannot be derived from PR metadata, treat that PR as a **global lock warning** and do not schedule any daily agent until manually resolved. + +Examples of valid daily claim branch names (all parseable): +- `agents/daily/docs-agent/2026-02-13-claim` +- `agents/daily/test-audit-agent/run-2026-02-13` +- `agents/daily/prompt-curator-agent/task-rotation-fix` + +**OFF LIMITS rule:** any PR that maps to an agent in the **daily cadence** is excluded, regardless of title tag format. ### COMMAND 2 — Check the task log for incomplete runs @@ -98,6 +108,7 @@ Look for any `_started.md` files that do NOT have a corresponding `_completed.md Combine results from Commands 1 and 2: - Agents with open/draft PRs → EXCLUDED +- PRs whose agent cannot be derived from metadata → GLOBAL LOCK (stop scheduling this cadence) - Agents with `started` status less than 24 hours old (no matching `completed`/`failed`) → EXCLUDED Write your exclusion list explicitly: @@ -169,7 +180,7 @@ You must create a visible claim before doing any work. This claim is a **distrib After pushing, re-check for competing claims: ```bash -curl -s "https://api.github.com/repos/PR0M3TH3AN/bitvid/pulls?state=open&per_page=100" | jq '{count: length, titles: [.[].title]}' +curl -s "https://api.github.com/repos/PR0M3TH3AN/bitvid/pulls?state=open&per_page=100" | jq '{count: length, prs: [.[] | {number, title, draft, created_at, head: {ref: .head.ref}, labels: [.labels[].name]}]}' ``` If you see another PR for this agent that was created *before* yours, abandon your branch and go back to Step 1 to select the next agent. @@ -276,7 +287,7 @@ Use the current UTC timestamp (which will be later than the `started` file). The | Layer | Mechanism | Catches | |-------|-----------|---------| -| **Pre-flight gate** | Scan ALL open `[daily]` PRs via `curl` | Agents claimed by any platform | +| **Pre-flight gate** | Scan ALL open PR metadata via `curl` + deterministic agent mapping | Agents claimed by any platform | | **Pre-flight gate** | Check task log dir for `started` files | Agents in progress (even without PR) | | **Step 2a** | Push branch with claim commit | Cross-platform visibility | | **Step 2b** | Race condition re-check | Simultaneous claims | diff --git a/docs/agents/prompts/weekly-scheduler.md b/docs/agents/prompts/weekly-scheduler.md index a0b7a718..04aae5d1 100644 --- a/docs/agents/prompts/weekly-scheduler.md +++ b/docs/agents/prompts/weekly-scheduler.md @@ -76,12 +76,22 @@ If you arrived here from the meta prompt and already ran these commands and past Run this command: ```bash -curl -s "https://api.github.com/repos/PR0M3TH3AN/bitvid/pulls?state=open&per_page=100" | jq '{count: length, titles: [.[].title]}' +curl -s "https://api.github.com/repos/PR0M3TH3AN/bitvid/pulls?state=open&per_page=100" | jq '{count: length, prs: [.[] | {number, title, draft, created_at, head: {ref: .head.ref}, labels: [.labels[].name]}]}' ``` **Paste the complete raw output.** If the command returns nothing or errors, write: `OUTPUT: (empty — no results)` -Review the titles in the output. Every agent name that appears in a PR title containing `[weekly]` is **OFF LIMITS** — do not select it. +Normalize each PR to an agent name using this deterministic rule: +1. **Preferred:** parse the branch name from `head.ref` with the convention `agents/weekly//...`. +2. **Fallback:** only if branch parsing fails, parse `` from the PR title. +3. If an agent cannot be derived from PR metadata, treat that PR as a **global lock warning** and do not schedule any weekly agent until manually resolved. + +Examples of valid weekly claim branch names (all parseable): +- `agents/weekly/ci-health-agent/2026-02-weekly-run` +- `agents/weekly/telemetry-agent/report-refresh` +- `agents/weekly/weekly-synthesis-agent/sprint-07` + +**OFF LIMITS rule:** any PR that maps to an agent in the **weekly cadence** is excluded, regardless of title tag format. ### COMMAND 2 — Check the task log for incomplete runs @@ -98,6 +108,7 @@ Look for any `_started.md` files that do NOT have a corresponding `_completed.md Combine results from Commands 1 and 2: - Agents with open/draft PRs → EXCLUDED +- PRs whose agent cannot be derived from metadata → GLOBAL LOCK (stop scheduling this cadence) - Agents with `started` status less than 24 hours old (no matching `completed`/`failed`) → EXCLUDED Write your exclusion list explicitly: @@ -164,7 +175,7 @@ You must create a visible claim before doing any work. This claim is a **distrib After pushing, re-check for competing claims: ```bash -curl -s "https://api.github.com/repos/PR0M3TH3AN/bitvid/pulls?state=open&per_page=100" | jq '{count: length, titles: [.[].title]}' +curl -s "https://api.github.com/repos/PR0M3TH3AN/bitvid/pulls?state=open&per_page=100" | jq '{count: length, prs: [.[] | {number, title, draft, created_at, head: {ref: .head.ref}, labels: [.labels[].name]}]}' ``` If you see another PR for this agent that was created *before* yours, abandon your branch and go back to Step 1 to select the next agent. @@ -273,7 +284,7 @@ Use the current UTC timestamp (which will be later than the `started` file). The | Layer | Mechanism | Catches | |-------|-----------|---------| -| **Pre-flight gate** | Scan ALL open `[weekly]` PRs via `curl` | Agents claimed by any platform | +| **Pre-flight gate** | Scan ALL open PR metadata via `curl` + deterministic agent mapping | Agents claimed by any platform | | **Pre-flight gate** | Check task log dir for `started` files | Agents in progress (even without PR) | | **Step 2a** | Push branch with claim commit | Cross-platform visibility | | **Step 2b** | Race condition re-check | Simultaneous claims |