Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

docs: guard AGENTS.md file references and send the documentation audit after stale instruction names

[._.]/ Adam Eivy045945234da2
diff --git a/client/src/AGENTS.md b/client/src/AGENTS.md
index e5b341943c..7c0e241279 100644
--- a/client/src/AGENTS.md
+++ b/client/src/AGENTS.md
@@ -56,7 +56,7 @@ For the full "adding a new page" checklist (nav manifest entry shape, palette ac
- **Mobile collapse + `TabPills`.** The tab bar is `client/src/components/ui/TabPills.jsx` (`mobileCompact` collapses it under `sm`) — **reuse it, never roll a new tab bar.** The `Drawer tabs` layout wires TabPills for you; a surface hosted in *both* a drawer and a page (like `ImageGenTab`) renders its own internal `<TabPills variant="pills" mobileCompact>` instead so the same grouping works in either host. See the sub-nav rule below for what `mobileCompact` renders.
- **Deep-linkable active tab.** Drive `activeTab` from a URL search param via `useDrawerTab(paramName, defaultTab, tabIds)` (`client/src/hooks/useDrawerTab.js`) so the open section is shareable/bookmarkable/reload-safe — the same "URL is the source of truth for what's open" rule as routed views. The caller owns the param name (`appTab`, `mediaTab`, …) so a page can host more than one drawer; pass the id list so a stale deep link degrades to `defaultTab` instead of a blank panel.
- **Long-lived forms** opt out of accidental dismissal with `closeOnEsc={false}` / `closeOnBackdrop={false}` so an Esc keystroke mid-edit doesn't discard the form.
- - **The overlay is always portaled to `<body>` — never re-nest it.** The backdrop and panel are both `position:fixed`, and a `filter` / `backdrop-filter` / `transform` ancestor becomes their containing block; on the "glass" themes `index.css` gives every bordered/rounded `.bg-port-card` a `backdrop-filter`, so an inline drawer nested under a card was sized to the *card*, not the viewport (issue #4150). Portaling is unconditional rather than an opt-in flag, so no call site has to remember it — React still routes events and context through the React tree. The one thing the portal leaves behind is a **page-scoped CSS theming root written as descendant selectors** (`.openworld-themed` in `index.css`): a caller inside one must pass that class as `portalClassName` (see `OpenWorldSettingsDrawer.jsx`). Same trap, same fix, for any new hand-rolled `fixed inset-0` overlay — portal it (`Modal`'s `usePortal`, `GalleryImagePicker.jsx`).
+ - **The overlay is always portaled to `<body>` — never re-nest it.** The backdrop and panel are both `position:fixed`, and a `filter` / `backdrop-filter` / `transform` ancestor becomes their containing block; on the "glass" themes `index.css` gives every bordered/rounded `.bg-port-card` a `backdrop-filter`, so an inline drawer nested under a card was sized to the *card*, not the viewport (issue #4150). Portaling is unconditional rather than an opt-in flag, so no call site has to remember it — React still routes events and context through the React tree. The one thing the portal leaves behind is a **page-scoped CSS theming root written as descendant selectors** (`.openworld-themed` in `index.css`): a caller inside one must pass that class as `portalClassName` (the prop is documented on `Drawer.jsx`). Same trap, same fix, for any new hand-rolled `fixed inset-0` overlay — portal it (`Modal`'s `usePortal`, `GalleryImagePicker.jsx`).
- **Worked examples:** `client/src/components/apps/EditAppDrawer.jsx` (built-in `tabs` layout, `size="lg"`, `useDrawerTab('appTab', …)`) and `client/src/components/settings/ImageGenTab.jsx` (internal `TabPills variant="pills"` sub-tabs, `useDrawerTab('mediaTab', …)`). The primitive is `Drawer.jsx`; the design record is `docs/plans/2026-07-01-drawer-ux-redesign.md`.
## Large collections and incremental loading
diff --git a/client/src/components/dashboard/AGENTS.md b/client/src/components/dashboard/AGENTS.md
index ed3706e857..16069b603e 100644
--- a/client/src/components/dashboard/AGENTS.md
+++ b/client/src/components/dashboard/AGENTS.md
@@ -1,6 +1,6 @@
# Dashboard Widgets & Layouts (`client/src/components/dashboard/`)
-Dashboard widgets are registered in `widgetRegistry.jsx` — each entry has `{ id, label, Component, width, defaultH?, gate? }`. The Dashboard page renders the active layout's widget list from this registry; named layouts persist in `data/dashboard-layouts.json` and are managed via `GET/PUT/DELETE /api/dashboard/layouts`. Built-in layouts (`default`, `focus`, `morning-review`, `ops`) are seeded on first read and cannot be deleted.
+Dashboard widgets are registered in `widgetRegistry.jsx` — each entry has `{ id, label, Component, width, defaultH?, gate? }`. The Dashboard page renders the active layout's widget list from this registry; named layouts persist in `data/dashboard-layouts.json` (owned by `server/services/dashboardLayouts.js`) and are managed via `GET/PUT/DELETE /api/dashboard/layouts`. Built-in layouts (`default`, `focus`, `morning-review`, `ops`) are seeded on first read and cannot be deleted.
**Grid positions:** layouts also carry a `grid: [{ id, x, w, order, h?, fixedH? }]` array — column placement on a 12-column grid plus a reading/packing sequence. When `grid` is empty (legacy/unmigrated layouts) the renderer auto-flows widgets using `synthesizeGrid` based on each widget's `width` keyword and `defaultH`. The "Arrange" button on the Dashboard enters edit mode where every widget exposes a move (top-right) and resize (bottom-right) handle; a move snaps horizontally to columns and re-inserts the cell into the sequence at the rank its dropped pixel position implies (`rankAtPixel` → `insertAtOrder`), renumbering `order` densely. Save persists to the active layout's `grid`. The grid renderer collapses to a single-column stack below 640px container width, rendered in reading order (`order`, then `x` as a tiebreak) — never grid-array order, which nothing keeps sorted.
diff --git a/scripts/ci-test-plan.js b/scripts/ci-test-plan.js
index a316d1d2fe..0a3807faab 100644
--- a/scripts/ci-test-plan.js
+++ b/scripts/ci-test-plan.js
@@ -308,6 +308,9 @@ export const ALWAYS_RUN_TESTS = [
// Whole-tree scanner: any server file can add a `process.env` read, and
// `.env.example` itself is not a scope the selector routes to a runner.
'server/envExampleDrift.test.js',
+ // Whole-tree scanner (#12093): any rename or deletion can strand a backticked
+ // file name in an AGENTS.md, which is documentation-only to the planner.
+ 'server/instructionFileReferences.test.js',
// Whole-tree scanners over the shared collectServerSources/collectClientSources
// walkers (#8723): the offending file is never imported by the guard, so
// impact selection only reaches them when the guard itself changes.
diff --git a/server/AGENTS.md b/server/AGENTS.md
index 3d71359df0..962aa9314a 100644
--- a/server/AGENTS.md
+++ b/server/AGENTS.md
@@ -44,7 +44,7 @@ These apply to Express/service/model code. Universal constraints (no try/catch o
## Generated manifests
-- **Derive at first use before committing a manifest.** A source-derived inventory that is deterministic, cheap, and reads only files every install ships belongs in memory behind a per-process cache, not in git: `server/lib/apiRouteGraph.js` scans the mounted route graph in ~50 ms on the first `/api/api-docs/*` request, and `socketEventInventory.js` does the same for Socket.IO events. The route catalog used to be `apiRouteCatalog.generated.json`; even content-keyed, its `stats` counts conflicted on every pair of branches that each added a route, `main` carried a stale `stats.declarations` over a byte-identical route graph, and it took 14 regeneration-only commits in 90 days. A committed copy is justified only when derivation is slow, nondeterministic, or needs inputs an install lacks (`promptStageCallSites.generated.json` reads every `git ls-files`-tracked `server/` source once per stage key, which no request handler should pay for).
+- **Derive at first use before committing a manifest.** A source-derived inventory that is deterministic, cheap, and reads only files every install ships belongs in memory behind a per-process cache, not in git: `server/lib/apiRouteGraph.js` scans the mounted route graph in ~50 ms on the first `/api/api-docs/*` request, and `socketEventInventory.js` does the same for Socket.IO events. The route catalog used to be a committed `apiRouteCatalog.generated.json` (retired — it no longer exists in the tree); even content-keyed, its `stats` counts conflicted on every pair of branches that each added a route, `main` carried a stale `stats.declarations` over a byte-identical route graph, and it took 14 regeneration-only commits in 90 days. A committed copy is justified only when derivation is slow, nondeterministic, or needs inputs an install lacks (`promptStageCallSites.generated.json` reads every `git ls-files`-tracked `server/` source once per stage key, which no request handler should pay for).
- **A checked-in generated manifest is addressed by CONTENT, never by POSITION.** `server/lib/*.generated.json` files are derived from source and kept honest by a drift test that regenerates and compares. That only works if the manifest changes when the thing it describes changes — and *only* then. A record that says "declared at `foo.js:412`" is rewritten by any edit that inserts a line above 412 (a rename, a comment, an unrelated handler), so the drift test fires on commits that change no route/stage/event at all, each parallel branch regenerates the file differently, and every rebase conflicts on it.
- **Key each record by the declaring file plus the semantic identity of what it declares** — the stage key plus file paths for `promptStageCallSites.generated.json`. Positional detail may stay **in memory**: the route-graph coverage guard in `server/lib/apiRouteGraph.test.js` compares two fresh in-memory scans (`scanRouteGraph()` vs `parseRouteModule()`, keyed `file#routerId METHOD /path` by `routeDeclarationKey`), so nothing committed ever points back into the source it was derived from.
- **Prove it with a property test, not a name list.** `shiftSourceText` (`scripts/lib/positionInvariance.js`) prepends a comment header to each source the generator reads; regenerate from the shifted sources and demand byte-identical output — asserting the rule directly, so it catches a position recorded as `at`, `span`, `row`, a `loc: [412, 8]` tuple, or a `foo.js#L412` anchor. The prompt-stage generator carries that test. `server/lib/generatedManifests.test.js` is the cheap tree-wide backstop: it scans every git-tracked `*.generated.json` for `line`/`column`/`offset`-style keys and `path/to/file.js:412` strings, catching a manifest whose generator never adopted the property test. It matches key names, so it is a net, not a proof — write both. That same file also enforces adoption structurally: it lists every git-tracked `scripts/*.js` that writes a `.generated.json` and fails when one has no sibling `.test.js` importing `positionInvariance.js`, so a new generator cannot ship without the property test.
@@ -52,5 +52,5 @@ These apply to Express/service/model code. Universal constraints (no try/catch o
## Prompt templates
- **Stage-prompt template changes need a migration.** `scripts/setup-data.js` only copies *missing* prompt files to `data/prompts/stages/` — existing installs keep their old templates. When you add a `{{template.variable}}` reference to a `data.reference/prompts/stages/*.md` file, also add an entry to `scripts/migrations/NNN-…js` that updates the corresponding installed prompt when its hash still matches the pre-change shipped version. Normalize line endings (`\r\n` → `\n`, bare `\r` → `\n`) before hashing so the comparison is correct on Windows checkouts. Build it with `makePromptReplaceMigration` and export `ACCEPTED_OLD_MD5` / `NEW_SHIPPED_MD5` — **never hand-mirror a hash table into `scripts/setup-data.js`**, which sweeps those exports itself via `buildPromptDriftTables`. Worked example: `scripts/migrations/394-factual-extraction-lens-prompts.js`. A `makeSeedMigration` only copies MISSING files and will NOT upgrade an installed template. Re-point every earlier migration naming the same file at the new hash (`_shippedHashDrift.test.js` fails otherwise) and keep the superseded hash in the new migration's accepted-old set. Migration scripts live in `scripts/migrations/`; the per-install applied-list is `data/migrations.applied.json` (gitignored runtime state). See `scripts/migrations/003-update-pipeline-stage-prompts.js`.
-- **A `PROMPT_VERSIONS` bump for a scheduled-task prompt (`server/services/taskPromptDefaults.js`) needs NO migration** — its second step is `node scripts/regen-prompt-integrity-snapshot.js`, which retires the outgoing hash (root `AGENTS.md` "Distribution model"). `readSchedule()` in `server/services/taskScheduleStore.js` already upgrades every uncustomized stored prompt to the shipped default on the next `loadSchedule()` and persists the result — the first schedule read after the update converges the install regardless of whether a migration ran. Six migrations re-implemented that same loop against `data/task-schedule.json` (a path the store never reads — it reads `data/cos/task-schedule.json`) before this was written down: `281-reconcile-missing-releases-prompt.js`, `293-agents-md-prompt-rename.js`, `297-release-check-slashdo-review-prompt.js`, `308-release-check-advisory-review-prompt.js`, `332-release-check-fix-blockers-prompt.js`, `338-claim-issue-volunteer-claim-contract.js`. They stay — the distribution model forbids deleting applied migrations — but they are closed precedent, not a pattern to repeat. `scripts/migrations/promptBumpMigrations.guard.test.js` fails if a seventh copy imports `taskPromptDefaults.js` and writes `task-schedule.json`.
+- **A `PROMPT_VERSIONS` bump for a scheduled-task prompt (`server/services/taskPromptDefaults.js`) needs NO migration** — its second step is `node scripts/regen-prompt-integrity-snapshot.js`, which retires the outgoing hash (root `AGENTS.md` "Distribution model"). `readSchedule()` in `server/services/taskScheduleStore.js` already upgrades every uncustomized stored prompt to the shipped default on the next `loadSchedule()` and persists the result — the first schedule read after the update converges the install regardless of whether a migration ran. Six migrations re-implemented that same loop against a `task-schedule.json` at the data root — a path the store never reads; `readSchedule()` reads `data/cos/task-schedule.json` — before this was written down: `281-reconcile-missing-releases-prompt.js`, `293-agents-md-prompt-rename.js`, `297-release-check-slashdo-review-prompt.js`, `308-release-check-advisory-review-prompt.js`, `332-release-check-fix-blockers-prompt.js`, `338-claim-issue-volunteer-claim-contract.js`. They stay — the distribution model forbids deleting applied migrations — but they are closed precedent, not a pattern to repeat. `scripts/migrations/promptBumpMigrations.guard.test.js` fails if a seventh copy imports `taskPromptDefaults.js` and writes `task-schedule.json`.
- **Creative prompts carry the IP-latitude clause automatically — classify the stage or source rather than wrapping a call site.** PortOS is a professional artist's tool; a model that silently renames, genericizes, or disclaimers a deliberate reference to existing IP produces defective output, and rights/clearance is the operator's responsibility, not the model's. `server/lib/creativeLatitude.js` owns the clause and the single table that classifies what gets it, applied at each of the three LLM transports: `promptService.buildPrompt` (stage templates, keyed on the stage name — fails SAFE, so a stage the tables never saw is stamped), `promptRunner.runPromptThroughProvider` (every hand-rolled prompt, keyed on the run `source` tag it already requires — an allowlist, since ops calls dominate there), and `aiProvider.callProviderAISimple` (its own fetch, so creative callers pass `creative: true`). So **a new creative stage or LLM-calling service is covered only once its stage name / `source` is classified in that module** — add the prefix or exact name there rather than wrapping a call site. Two guard tests force the decision: `creativeLatitude.test.js` walks `data.reference/prompts/stage-config.json`, and `creativeLatitude.sources.test.js` scans every `source:` literal handed to the shared runners — both fail on an unclassified entry. A caller that budgets a context window before the stamp lands (the inline editorial check) must reserve `CREATIVE_LATITUDE_TOKENS`. **The clause is shown, never hidden (#11317):** where the user typed the text the LLM receives (prompt Enhance/Refine, Music Designer, series review notes, mood board Generate more), the service stamps with `withCreativeLatitude` itself (idempotent, so the transport passes it through once) and returns the exact sent text plus `CREATIVE_LATITUDE_ADDITION` and its instructions as `promptAdditions`, which the client lists with `SentPromptPanel`. `services/mediaPromptRefiner.js` is the worked example.
diff --git a/server/instructionFileReferences.test.js b/server/instructionFileReferences.test.js
new file mode 100644
index 0000000000..f41537edba
--- /dev/null
+++ b/server/instructionFileReferences.test.js
@@ -0,0 +1,139 @@
+import { describe, it, expect } from 'vitest';
+import { execFileSync } from 'child_process';
+import { readFileSync } from 'fs';
+import { basename, dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+
+/**
+ * Tree-wide guard (#12093): every backticked file name in a tracked AGENTS.md
+ * resolves to a file that exists.
+ *
+ * The AGENTS.md tree is spliced into every API-provider agent prompt, so a
+ * stale name there sends every agent hunting for a file that was renamed,
+ * retired, or never existed, and nothing else notices: the instruction files
+ * are documentation-only to CI's planner, and no code imports them. A rename
+ * or deletion anywhere in the tree can strand a reference with no import edge
+ * back to this guard, which is why it rides `ALWAYS_RUN_TESTS`.
+ *
+ * Scope is deliberately narrow and cheap: the basename of each backticked
+ * `*.js|jsx|cjs|mjs|md|json|yml|yaml` token must match a tracked file. Runtime
+ * files (`data/…`, `~/…`) are never tracked, so a basename no tracked file
+ * carries is verified by searching the tracked source for it instead: a
+ * runtime file nothing reads or writes is as stale as a deleted module.
+ */
+
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+
+const git = (...args) => execFileSync('git', args, { cwd: REPO_ROOT, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+const gitLines = (...args) => git(...args).split('\n').filter(Boolean);
+
+/**
+ * Names that are intentionally cited as history: the prose says they are gone
+ * and names them so a reader recognizes the retired file in old commits. This
+ * list may only shrink — a new stale name gets fixed in the prose, not parked
+ * here — and `pins the retired allowlist` below enforces that.
+ */
+export const RETIRED_NAMES = Object.freeze([
+ 'apiRouteCatalog.generated.json', // server/AGENTS.md: derive-at-first-use rationale names the manifest it replaced
+]);
+
+const FILE_TOKEN = /^(?:\.\/|~\/|<repo-root>\/)?([\w.][\w./-]*\.(?:jsx?|[cm]js|md|json|ya?ml))$/;
+/** Example names the prose uses as stand-ins (`foo.js:412`), never real files. */
+const PLACEHOLDER_STEM = /^(?:foo|bar|baz|qux|x|y|example)$/;
+
+/**
+ * Backticked file names in `text`, each with the line it sits on. A token is
+ * taken up to the first `:` or `#` (`file.js:412`, `routes/x.js#schema`);
+ * placeholders, globs, and example stems (`<x>`, `*`, `{…}`, `foo.js`) are
+ * not file names.
+ */
+export const extractFileTokens = (text) => {
+ const tokens = [];
+ text.split('\n').forEach((line, i) => {
+ for (const m of line.matchAll(/`([^`\n]+)`/g)) {
+ const raw = m[1].split(/[:#]/)[0].trim();
+ if (/[<>*{}\s]/.test(raw)) continue;
+ const match = raw.match(FILE_TOKEN);
+ const stem = match ? basename(match[1]).replace(/\.[^.]+$/, '') : '';
+ // A bare suffix (`.generated.json`, `.test.js`) names a convention, not a file.
+ if (!match || !stem || stem.startsWith('.') || PLACEHOLDER_STEM.test(stem)) continue;
+ tokens.push({ line: i + 1, path: match[1] });
+ }
+ });
+ return tokens;
+};
+
+const trackedAgentsFiles = () => gitLines('ls-files', '--', 'AGENTS.md', '*/AGENTS.md');
+
+const trackedBasenames = () => new Set(gitLines('ls-files').map((p) => basename(p)));
+
+/** True when some tracked, non-test source names `name` as a string. */
+const sourceMentions = (name) => {
+ try {
+ return git('grep', '-lF', name, '--', '*.js', '*.cjs', '*.mjs', ':!*.test.js', ':!*.md').trim().length > 0;
+ } catch (err) {
+ if (err.status === 1) return false; // git grep: no match
+ throw err;
+ }
+};
+
+export const findStaleReferences = ({ files, tracked, mentions = sourceMentions, retired = RETIRED_NAMES }) => {
+ const stale = [];
+ for (const file of files) {
+ const text = readFileSync(join(REPO_ROOT, file), 'utf8');
+ for (const { line, path } of extractFileTokens(text)) {
+ const name = basename(path);
+ if (retired.includes(name) || tracked.has(name) || mentions(name)) continue;
+ stale.push(`${file}:${line} \`${path}\` (no tracked file has this basename and no tracked source names it)`);
+ }
+ }
+ return stale;
+};
+
+describe('instruction file references', () => {
+ const files = trackedAgentsFiles();
+ const tracked = trackedBasenames();
+
+ it('scans every tracked AGENTS.md', () => {
+ expect(files).toContain('AGENTS.md');
+ expect(files).toContain('server/AGENTS.md');
+ expect(files).toContain('client/src/AGENTS.md');
+ });
+
+ it('every backticked file name in an AGENTS.md matches a tracked file', () => {
+ expect(findStaleReferences({ files, tracked })).toEqual([]);
+ });
+
+ it('pins the retired allowlist: still absent, still cited, never growing', () => {
+ expect(RETIRED_NAMES.length).toBeLessThanOrEqual(1);
+ const cited = new Set(files.flatMap((f) => extractFileTokens(readFileSync(join(REPO_ROOT, f), 'utf8')).map((t) => basename(t.path))));
+ for (const name of RETIRED_NAMES) {
+ expect(tracked.has(name), `${name} is tracked again — drop it from RETIRED_NAMES`).toBe(false);
+ expect(cited.has(name), `${name} is no longer cited by any AGENTS.md — drop it from RETIRED_NAMES`).toBe(true);
+ }
+ });
+
+ it('extracts file tokens and skips placeholders, globs, and anchors', () => {
+ const text = [
+ 'Read `server/lib/real.js` and `routes/other.js#schema` at `third.jsx:412`, `./docs/X.md`.',
+ 'Not files: `data/<x>`, `*.test.js`, `.generated.json`, `.changelog/v{version}.md`, `npm run x`, `foo.js:412`, `@AGENTS.md`.',
+ 'Runtime: `data/cos/task-schedule.json` and `~/.portos/agent-key.json`.',
+ ].join('\n');
+ expect(extractFileTokens(text)).toEqual([
+ { line: 1, path: 'server/lib/real.js' },
+ { line: 1, path: 'routes/other.js' },
+ { line: 1, path: 'third.jsx' },
+ { line: 1, path: 'docs/X.md' },
+ { line: 3, path: 'data/cos/task-schedule.json' },
+ { line: 3, path: '.portos/agent-key.json' },
+ ]);
+ });
+
+ it('reports a stale name with file:line, and a source mention or the retired list clears it', () => {
+ const noSource = findStaleReferences({ files: ['server/AGENTS.md'], tracked: new Set(), mentions: () => false, retired: [] });
+ expect(noSource.length).toBeGreaterThan(0);
+ expect(noSource.every((s) => /^server\/AGENTS\.md:\d+ `[^`]+` \(no tracked file has this basename and no tracked source names it\)$/.test(s))).toBe(true);
+ expect(noSource.some((s) => s.includes('`apiRouteCatalog.generated.json`'))).toBe(true);
+ expect(findStaleReferences({ files: ['server/AGENTS.md'], tracked: new Set(), mentions: () => true, retired: [] })).toEqual([]);
+ });
+});
diff --git a/server/services/taskPromptDefaults/integrity.snapshot.json b/server/services/taskPromptDefaults/integrity.snapshot.json
index 842f44004f..ba7d74712d 100644
--- a/server/services/taskPromptDefaults/integrity.snapshot.json
+++ b/server/services/taskPromptDefaults/integrity.snapshot.json
@@ -26,7 +26,7 @@
"dependency-updates": "2d94021c979a86a349e125f5c15665d8",
"do-release": "0ee9c504bad68f4a73be15f0b955a796",
"do-replan": "35660eb7b43e4259a6a9253ed288a1db",
- "documentation": "1a89cf4a93e57746b68a1ce496b73305",
+ "documentation": "c94797b4bd3a0d554e225888ed48b76b",
"error-handling": "416b4e9aa2c1fcc3bfea7a2d38814ae5",
"feature-completeness": "00d8916cc6032e74817657375375115b",
"feature-ideas": "804f62f1dadadbfa8a0bcd4aff16b2e8",
@@ -90,7 +90,7 @@
"dependency-updates": 7,
"do-release": 17,
"do-replan": 2,
- "documentation": 8,
+ "documentation": 9,
"error-handling": 4,
"feature-completeness": 1,
"feature-ideas": 11,
@@ -337,7 +337,8 @@
"74aa8433896647e7815f9d6d9e4a56c8",
"b375f95ae2274f03d06ba5ceff5705d8",
"246be4932c277fa0ec0ab365beb3baad",
- "a30e3bfba8cd13369ccaf806a3534a79"
+ "a30e3bfba8cd13369ccaf806a3534a79",
+ "1a89cf4a93e57746b68a1ce496b73305"
],
"error-handling": [
"26225ac04f2f35feb61151b2e6474465",
diff --git a/server/services/taskPromptDefaults/prompts.js b/server/services/taskPromptDefaults/prompts.js
index 019c125166..a6d81c078f 100644
--- a/server/services/taskPromptDefaults/prompts.js
+++ b/server/services/taskPromptDefaults/prompts.js
@@ -712,6 +712,10 @@ who finds nothing.
a destructive side effect, an ordering requirement, an upgrade step.
- **Stale references** — links to moved or deleted files, examples using retired
APIs, screenshots of interfaces that no longer exist.
+- **Instruction and prompt files that name things that do not exist** — a file,
+ function, flag, tool, or command named in AGENTS.md, nested instruction
+ files, skills, or the shipped task prompts that is absent from the tree.
+ Verify each by search; one finding per file with the list.
- **Missing "why" on non-obvious decisions** — a constraint, workaround, or
deliberate trade-off that reads as arbitrary and invites someone to "fix" it.
- **Comments that lie** — an inline comment describing behavior the function no
diff --git a/server/services/taskPromptDefaults/versions.js b/server/services/taskPromptDefaults/versions.js
index 3e44c86dd7..a82e8c20b8 100644
--- a/server/services/taskPromptDefaults/versions.js
+++ b/server/services/taskPromptDefaults/versions.js
@@ -44,7 +44,7 @@ export const PROMPT_VERSIONS = {
'error-handling': 4, // v4: cedes sensitive detail in an error path to privacy and partial writes to data-integrity (#12086). v3: carries {modeInstructions} and covers resilience (timeouts, retry ceilings, degraded-dependency fallback, cleanup on the error path, actionable user-facing text) while handing swallowed errors and log context to observability. Previously v2: unified `[Improvement: {appName}]` body (older default used the `[App Improvement: {appName}]` header)
'typing': 3, // v3: carries {modeInstructions}, exits cleanly on an untyped project, and targets boundary escape hatches and validator/type disagreement instead of a mechanical annotation sweep. Previously v2: unified `[Improvement: {appName}]` body (older default used the `[App Improvement: {appName}]` header)
'dependency-updates': 7, // v7: dependency-update worktrees keep package-manager writes out of the source checkout's shared node_modules. v6: the throwaway bot-PR worktree is `dep-{appSlug}-pr-<n>` — the app NAME alone did not isolate two managed apps sharing a name, and {appSlug} is rendered server-side rather than slugified by the agent (`appWorktreeSlug`, server/lib/worktreeOwnership.js). v5: inventory all Dependabot alerts and ecosystems, verify actual upstream fixes, and track unpatched mitigations separately from alert closure. v4: the Phase 1 GitLab MR listing gains `--output json` — without it glab answers with the human table, which carries the head branch but NOT the author, while the classification right below it reads both. The same bump drops `--state` from the MR-list recipes — that flag does not exist (MR state is selected by presence flags `--merged`/`--closed`/`--all`, and OPEN is the default), so `--state opened` exited 1 with `Unknown flag: --state` and Phase 1 skipped its bot-PR triage entirely on GitLab repos. v3: Phase 1 triages open Dependabot/Renovate PRs first (evidence → MERGE / FIX-THEN-MERGE / CLOSE / LEAVE, including conflict + CI-failure repair on the bot branch) before Phase 2 updates anything the bots didn't cover — an agent that bumped packages itself was duplicating and conflicting with open bot PRs. v2: generic {appName} body (older default hardcoded "PortOS")
- 'documentation': 8, // v8: drops the read-instruction-files restatement the mode banners own (#12080). v7: carries {modeInstructions} and ranks wrong documentation above missing documentation, verifying instructions against the code rather than trusting the prose. Previously v6: the changelog step names `AGENTS.md` (or `CLAUDE.md`) as the file carrying the repo's documented convention — #4852 made AGENTS.md the canonical cross-vendor agent-instructions filename, and a managed app that adopted it would otherwise be told to read a file it no longer has. v5: the changelog step defers to the convention the repo documents (some repos collect per-branch fragments in a directory so parallel agents don't conflict) instead of prescribing an append to `.changelog/NEXT.md`. v4: generic {appName} body (v1 hardcoded "PortOS"; v2/v3 retired DONE.md wording)
+ 'documentation': 9, // v9: hunts instruction files, skills, and shipped task prompts for named files/functions/flags/tools/commands absent from the tree, one finding per file (#12093). v8: drops the read-instruction-files restatement the mode banners own (#12080). v7: carries {modeInstructions} and ranks wrong documentation above missing documentation, verifying instructions against the code rather than trusting the prose. Previously v6: the changelog step names `AGENTS.md` (or `CLAUDE.md`) as the file carrying the repo's documented convention — #4852 made AGENTS.md the canonical cross-vendor agent-instructions filename, and a managed app that adopted it would otherwise be told to read a file it no longer has. v5: the changelog step defers to the convention the repo documents (some repos collect per-branch fragments in a directory so parallel agents don't conflict) instead of prescribing an append to `.changelog/NEXT.md`. v4: generic {appName} body (v1 hardcoded "PortOS"; v2/v3 retired DONE.md wording)
'ui-bugs': 4, // v4: hunts the unhappy branch of each primary action and statically provable crashes (a call to a member the imported module lacks), which no longer count as speculative; cedes stranded workflows to workflow-recovery and unfinished controls to feature-completeness. Previous version: v3: carries {modeInstructions}, exits cleanly when the interface is unreachable instead of filing from imagination, and cedes layout/a11y/UX/copy to their owners. Previously v2: generic {appName} + the app UI (older default hardcoded "PortOS" + http://localhost:5555)
'mobile-responsive': 4, // v4: owns every layout defect at viewport width ≤1024 plus touch; narrow containers on a desktop viewport stay with ux (#12084). v3: carries {modeInstructions} and requires the viewport width plus what a user cannot do there, rather than flagging any layout that merely looks different. Previously v2: generic {appName} app-UI body (older default hardcoded "PortOS" + http://localhost:5555)
'ux': 7, // v7: walks routes with whatever browser automation the run has (no Playwright MCP tool names), three viewport classes instead of six exact sizes, and item 8 restricted to a narrow container on a desktop viewport — phone/tablet widths belong to mobile-responsive (#12077, #12084). v6: route selection reaches record detail/editor routes partway through their workflow with tracker-driven rotation, and adds checklist items 12 (a record page says where it stands, the next action, and how to open its output) and 13 (same page family, same shell — provable from layout config). Previous version: v5: adds checklist items 9–11 (instruction text that over-explains, duplicate controls for one action, information hidden when the current state needs it) plus a per-route action/text/state inventory; previous runs only filed what items 1–8 named and treated verbosity as aesthetic. v4: forge issues use plain human-readable titles and tracker-defined IDs; filing syntax/identity comes from {trackerInstructions}. v3: audits narrow monitors and widget containers, including clipped overflow and sidebar/zoom states.