agent-bios 0.15.0 → 0.16.0

package/claude/guides/slide-writing/scripts/render.mjs

@@ -0,0 +1,82 @@
+// Render only the sealed HTML and its sealed local assets. No slide styles are injected.
+import {readFile, writeFile, mkdir, realpath} from 'node:fs/promises';
+import {resolve, relative, isAbsolute, sep} from 'node:path';
+import {pathToFileURL, fileURLToPath} from 'node:url';
+import {createRequire} from 'node:module';
+
+const [htmlArg, outArg, sealedArg] = process.argv.slice(2);
+if (!htmlArg || !outArg || !sealedArg) throw new Error('Usage: render.mjs SEALED_HTML OUTPUT_DIR SEALED_ROOT');
+const modulePath = process.env.SLIDE_PLAYWRIGHT_MODULE;
+const browserPath = process.env.SLIDE_BROWSER_EXECUTABLE;
+if (!modulePath || !browserPath) throw new Error('SLIDE_PLAYWRIGHT_MODULE and SLIDE_BROWSER_EXECUTABLE are required');
+const {chromium} = await import(pathToFileURL(resolve(modulePath)).href);
+const require = createRequire(resolve(modulePath));
+const {PDFDocument} = require('pdf-lib');
+const html = await realpath(htmlArg), sealed = await realpath(sealedArg), out = resolve(outArg);
+const inside = path => { const r = relative(sealed, path); return r !== '..' && !r.startsWith('..' + sep) && !isAbsolute(r); };
+if (!inside(html)) throw new Error('HTML is outside sealed input root');
+await mkdir(out, {recursive:true});
+const browser = await chromium.launch({headless:true, executablePath:resolve(browserPath)});
+try {
+  const page = await browser.newPage({viewport:{width:1400,height:1000}, deviceScaleFactor:1});
+  const blocked = [], errors = [];
+  page.on('pageerror', e => errors.push(e.message));
+  await page.route('**/*', async route => {
+    const u = route.request().url();
+    if (u.startsWith('data:') || u.startsWith('about:')) return route.continue();
+    if (u.startsWith('file:')) {
+      try { if (inside(await realpath(fileURLToPath(u)))) return route.continue(); } catch {}
+    }
+    blocked.push(u); return route.abort();
+  });
+  await page.emulateMedia({media:'print'});
+  await page.goto(pathToFileURL(html).href, {waitUntil:'networkidle'});
+  await page.evaluate(() => document.fonts.ready);
+  const pages = await page.evaluate(() => [...document.querySelectorAll('section.slide')].map((slide,i) => {
+    const rect = slide.getBoundingClientRect(), texts = [], outside = [];
+    const walker = document.createTreeWalker(slide, NodeFilter.SHOW_TEXT);
+    let node;
+    while ((node = walker.nextNode())) {
+      const value = node.textContent.trim(); if (!value) continue;
+      const parent = node.parentElement, style = getComputedStyle(parent);
+      if (style.visibility === 'hidden' || style.display === 'none') continue;
+      const range = document.createRange(); range.selectNodeContents(node);
+      const bounds = range.getBoundingClientRect(); if (!bounds.width || !bounds.height) continue;
+      const transforms = [];
+      for (let p=parent; p && p!==slide.parentElement; p=p.parentElement) {
+        const transform = getComputedStyle(p).transform;
+        if (transform !== 'none') transforms.push(transform);
+      }
+      const item = {text:value, font_px:parseFloat(style.fontSize), x:bounds.x-rect.x, y:bounds.y-rect.y,
+        width:bounds.width, height:bounds.height, alignment:style.textAlign,
+        declared_level:parent.closest('[data-level]')?.getAttribute('data-level') ?? null,
+        font_family:style.fontFamily, font_weight:style.fontWeight, transforms};
+      texts.push(item);
+      if (item.x < -1 || item.y < -1 || item.x+item.width > rect.width+1 || item.y+item.height > rect.height+1) outside.push(item);
+    }
+    const regions = [...slide.querySelectorAll('[data-role]')].map(n => {
+      const r=n.getBoundingClientRect(); return {role:n.dataset.role,x:r.x-rect.x,y:r.y-rect.y,width:r.width,height:r.height};
+    });
+    return {id:'p'+String(i+1).padStart(4,'0'), source_page:slide.dataset.sourcePage ?? '',
+      title:slide.querySelector('[data-role="title"],h1,h2')?.textContent.trim() ?? '',
+      width:rect.width,height:rect.height,text:texts,outside,regions};
+  }));
+  if (!pages.length) throw new Error('No section.slide pages were rendered');
+  for (const p of pages) {
+    if (!(Number.isFinite(p.width) && Number.isFinite(p.height) && p.width>0 && p.height>0)) throw new Error('Invalid page geometry');
+    if (Math.abs(p.width-pages[0].width)>1 || Math.abs(p.height-pages[0].height)>1) throw new Error('Pages have different dimensions');
+  }
+  const slides = page.locator('section.slide');
+  for (let i=0; i<pages.length; i++) await slides.nth(i).screenshot({path:resolve(out,`page-${String(i+1).padStart(4,'0')}.png`),animations:'disabled'});
+  await page.pdf({path:resolve(out,'deck.pdf'),width:pages[0].width+'px',height:pages[0].height+'px',
+    printBackground:true,preferCSSPageSize:false,margin:{top:0,right:0,bottom:0,left:0}});
+  const pdf = await PDFDocument.load(await readFile(resolve(out,'deck.pdf')));
+  if (pdf.getPageCount() !== pages.length) throw new Error(`PDF page count ${pdf.getPageCount()} differs from HTML page count ${pages.length}`);
+  const pdfSizes=pdf.getPages().map(p=>p.getSize());
+  for (const size of pdfSizes) if (Math.abs(size.width-pages[0].width*.75)>1 || Math.abs(size.height-pages[0].height*.75)>1) throw new Error('PDF dimensions differ from measured slide dimensions');
+  const report={pages, pdf_page_count:pdf.getPageCount(), pdf_sizes_points:pdfSizes,
+    font_metric:'font_px is computed CSS size; inspect glyph rectangles, transforms, font loading and actual image separately',
+    blocked_requests:blocked, script_errors:errors};
+  await writeFile(resolve(out,'measurements.json'),JSON.stringify(report,null,2)+'\n');
+  process.stdout.write(JSON.stringify({pages:pages.length,pdf_pages:pdf.getPageCount(),blocked_requests:blocked.length,script_errors:errors.length})+'\n');
+} finally { await browser.close(); }

package/claude/guides/slide-writing.md

@@ -0,0 +1,195 @@
+---
+guide_id: slide-writing
+language: en
+status: active
+description: Apply shared source-fidelity, meaning, structure, and layout criteria when creating, revising, or reviewing slides, in any presentation format.
+use_when:
+  - creating, revising, or reviewing slides and presentation materials
+  - deciding slide headlines, logical relationships, body hierarchy, spacing, or alignment
+resources:
+  - Read `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/guides/slide-writing/RUNBOOK.md` only when using the paired static HTML/PDF execution and review path.
+core_rules:
+  - Read this primary guide for every slide or presentation task; it is the shared semantic source.
+  - Use the companion runbook and scripts only for an explicitly applicable static HTML/PDF job.
+---
+
+<!-- criterion:c0000 -->
+# Principles for Writing Slides
+
+Structure slides so the reader first understands the central judgment, then can verify on the same screen the evidence and conditions supporting it. Visualizations express logical relationships between concepts through position, shape, size, grouping, and connections. The relationship stated by the wording must match the relationship read from the screen.
+
+After deciding which meaning from the source must be preserved, design the groupings and relationships, body hierarchy, space, and reading order. Set specific values for presentation specifications for each task. When preserving meaning, readability, and use of space conflict, first reconsider the arrangement and content composition. Do not conceal a space problem by combining independent concepts or by making only a particular body level smaller.
+<!-- /criterion -->
+
+<!-- criterion:c0001 -->
+## 1. Define the central judgment of each slide and the role of its body
+
+Each slide answers what the reader needs to understand or judge. Groupings in the body connect the evidence, comparisons, processes, and conditions that explain that answer. When independent questions are mixed together, split the slide or define the higher-level question that explains why they belong together.
+
+A slide may contain multiple facts. Each fact's role in the central judgment and its relationship to the others must be clear. Make the key relationships findable on the screen before the reader must assemble the content and infer them. Rather than connect every detailed condition with lines, reveal first the relationships needed to understand the central judgment.
+<!-- /criterion -->
+
+<!-- criterion:c0002 -->
+## 2. Write headlines so the subject and conclusion are clear even when only the headlines are read
+
+For a slide that explains content, state the subject and central judgment in its headline. Replace with a concrete sentence any reference that requires the preceding slide to understand, a title that only previews a count, or wording that omits the subject or predicate excessively. State the judgment within the scope and degree of certainty that the evidence supports.
+
+Slides for overview, definition, or transition use a title that reveals their role and the content they convey. Do not force a claim onto a slide that has no conclusion. The sequence of problem framing and judgments must also connect when all headlines are read in order.
+
+Headline line breaks follow units of meaning such as phrases and clauses. If only one final character or grammatical ending remains on the next line, adjust the headline width, phrasing, or line break. Distinguish a deliberately short line containing an independent word from a line that remains because a word was split off.
+<!-- /criterion -->
+
+<!-- criterion:c0003 -->
+## 3. Preserve the names and distinctions of key concepts
+
+Use the same name for the same concept. Explain a technical concept where needed, and do not alternate synonyms merely to vary the writing style. Even when shortening an explanation, retain each item's name and its difference from other items.
+
+Before summarizing, identify the concepts, indicators, and conditions that must be read, recorded, or judged independently. An item defined separately in the source must remain findable in the result under its own name and definition. If distinct items are collapsed into one combined name, restore the distinction. Multiple items may appear in the same box; confirm their independence through the correspondence of names, definitions, and values rather than through the number of boxes.
+
+Distinguish subjects, roles, activities, outputs, outcomes, and evaluation criteria. Distinguish examples from selection results, hypotheses from confirmed facts, and temporal order from causality. Also retain the conditions, exceptions, and applicable scope under which a relationship holds. When comparing numbers, align units, periods, subjects, and denominators; if the bases differ, state that difference.
+
+If the source does not establish a relationship or scope, retain that uncertainty. Do not add an unsupported cause, sequence, or superiority merely to create a connection needed for visualization.
+<!-- /criterion -->
+
+<!-- criterion:c0004 -->
+## 4. Create a reading order from conclusion to evidence
+
+Arrange information on one screen according to the following roles. Use the roles needed for the slide's purpose, and do not repeat the same content in multiple locations.
+
+| Information role | What the reader confirms |
+|---|---|
+| Headline | The subject and central judgment of this slide |
+| Introduction | The judgment's scope and premise, and how to read the body |
+| Current-position indicator | The discussion this slide belongs to in the overall document |
+| Body | The evidence and relationships supporting the judgment |
+| Conclusion or implication | An additional judgment or action derived from the body |
+| Source | The material and location for verifying the evidence |
+
+In the body, make visible where reading begins, what is compared together, and where to move next. Put information compared on the same basis in corresponding positions, and reveal any branch or convergence point. If two flows mix, divide the space or redefine the higher-level grouping.
+
+Separate conclusions that only hold after reading the body's explanation from source indicators. Make conditions, exceptions, and responsibility scope that change the interpretation readable in the body close to the relevant claim. Set the order of emphasis so decorative position indicators or repeated titles do not draw attention away from the body.
+<!-- /criterion -->
+
+<!-- criterion:c0005 -->
+## 5. Design both the composition within groupings and the relationships between them
+
+Group the body into units with connected meaning, such as comparison targets, processes, responsibilities by subject, use of results, or common conditions. Arrange them so relationships within a grouping appear closer than relationships between groupings. Elements grouped by the same box, background, or boundary need a reason to be read together.
+
+Boxes, background contrast, dividing lines, and whitespace are means to reveal grouping boundaries. A box is unnecessary when alignment, a common axis, connections, or continuity of shape make one object clear. Tables retain the comparison basis and the correspondence of rows and columns. A process may use boxes by step or be divided within one area; either way, the overall flow must read as continuous.
+
+Set the unit for dividing boxes according to concepts or steps that must be read independently. Before putting every sentence in a separate box or gathering distinct judgments in one large box, check what distinction the reader gains. If the relationship between boxes must be left only to sentence interpretation, reinforce the arrangement, containment, or connections.
+<!-- /criterion -->
+
+<!-- criterion:c0006 -->
+## 6. Express logical relationships through space, shape, and connections
+
+First determine what is related to what, and how. Confirm the direction, conditions for holding, and applicable scope of the relationship, then select an expression that makes it readable. A relationship may have several valid arrangements.
+
+| Relationship to show | Expressions that can be used | Meaning to preserve |
+|---|---|---|
+| Causality | Directional arrangement and connections among cause, action, and result | What affects what, and the strength and conditions of the evidence |
+| Hierarchy or classification | A composition that divides branches or stages beneath a higher-level concept | What is classified according to which criteria |
+| Containment or composition | Nested boxes, common boundaries, and the arrangement of component elements | What is part of what, and the scope of containment |
+| Dependency or reliance | Layers of foundation and dependent elements, and connections showing prerequisites | What requires what; do not turn dependency into causality or containment |
+| Equivalence or parallelism | Same-level columns, rows, comparison tables, or matrices | Independent alternatives or parallel evidence, and the common comparison basis |
+| Equality or correspondence | An equals sign or a correspondence indicator between objects | The scope of the same meaning or value and its distinction from simple correspondence; use equals signs for equality |
+| Correlation | A connection that explicitly states the association, or a chart using actual data | The fact that things vary together or are associated, and its distinction from a causal claim |
+| Sequence or transition | Connected boxes, wedges, flowcharts, or timelines | Direction of progress, branching or convergence, and transition conditions; if using a time axis, periods and points in time |
+| Roles or handoffs | Areas or lanes by subject, and handoff points | Boundaries of execution responsibility and what is handed over |
+| Numeric magnitude, change, or distribution | A chart appropriate to the data and comparison purpose | Actual values and units, axes, and comparison basis |
+
+The table's composition is a set of options, not a fixed symbol dictionary. Use visual markers with the same role consistently within a document. If a symbol's meaning could be confused, place a short relationship explanation near the connected objects. When position and connecting lines alone do not settle the meaning, make the wording readable with them.
+
+Use nesting and layering to reveal containment, dependency, or differences in level. Do not treat a simple shadow or overlap as evidence of a logical relationship. Adjust the arrangement if boundaries or content are obscured. Make equivalent elements recognizable as being at the same level, but differing amounts of content do not require every box to have the same area. Check that a difference cannot be mistaken for superiority or quantity.
+
+### Selection order for directional expressions
+
+For a relationship that must show direction, secure both the spacing between boxes and room for their content.
+
+1. First check whether changing the box's end or boundary can express the content and direction together. The width for text and the distinction between concepts must remain intact.
+2. If a modified box is unnatural, connect the flow with a short wedge within the standard spacing.
+3. If a wedge cannot make the relationship and connected objects clear, use an arrow. Within the readable range, reduce the connection length and space reserved solely for it.
+
+An arrow may be selected directly when it ensures visibility while also minimizing empty space. It is unnecessary to produce every alternative in sequence. Judge appropriateness by the actual screen's relationships, spacing, and readability rather than by the reason a symbol was selected. Do not apply this order to a relationship that does not need direction.
+
+It must be clear what arrows, wedges, and pointed ends of boxes point from and to. When connecting lines obscure content or several lines overlap so the target becomes ambiguous, first redesign box positions, groupings, and the branch structure.
+
+A step guide that states periods may use equal widths. If using a quantitative axis where length represents time, represent actual periods. Do not use axes, area, or height that makes a concept map appear to be a measured result; if confusion is possible, indicate near the diagram that it is a concept map. Retain the units, axes, and legends necessary to interpret numeric charts.
+<!-- /criterion -->
+
+<!-- criterion:c0007 -->
+## 7. Allocate space to the body area and within groupings
+
+First determine the area the body will use between the headline and introduction, and the conclusion and source. Allocate area to each grouping according to the amount of information needed to explain the central judgment, the reading order, and the relationship structure. Content slides should align the outer boundaries of higher-level groupings and use the entire body area.
+
+Apply consistent horizontal and vertical spacing between groupings at the same level. For areas compared side by side, align their starting points and comparison baselines, and preserve row and column correspondence. Distinguish the internal whitespace of nested groupings from the spacing between higher-level groupings because their roles differ. When spacing differs, check the relationship that the difference conveys.
+
+Space allocation must continue from outer boxes to internal titles, tables, rows, and text. If a box with a short explanation is largely empty while another box concentrates essential evidence in small text, reconsider the area allocation. Do not treat the space problem as solved merely because all boxes have the same size or text was moved to vertical center.
+
+Check separately the space between the body boundary and the final grouping, and the space between the end of a grouping and its actual content. Also examine the space occupied by connecting symbols. Retain whitespace that distinguishes groupings and supports reading order. Reduce unnecessary empty areas by adjusting the arrangement, content amount, or line breaks, rather than filling them by only expanding spacing between sentences.
+
+Cover, transition, or closing slides, and slides focused on one visual object, may use whitespace for attention and distinction. Judge its appropriateness by the slide's reading purpose and actual content arrangement. Do not make one empty-space ratio the passing threshold for every slide.
+<!-- /criterion -->
+
+<!-- criterion:c0008 -->
+## 8. Adjust content volume and text arrangement together
+
+Information density is achieved when the evidence and conditions needed for a judgment are included faithfully and can be read. In a presentation, the key point and relationships appear first; when read alone, definitions, interpretation, and conditions can be followed.
+
+When space is lacking, remove redundant wording and adjust column widths, paragraph divisions, row heights, internal whitespace, and the area of each grouping. Place sentences with different roles separately, as with definitions and interpretations in a comparison table. Do not hide essential evidence by shrinking type or moving it to footnotes.
+
+When space remains, first check whether necessary explanation is missing, then adjust grouping proportions, line arrangement, and actual content size. Do not add claims or figures absent from the source, or pad with the same statement. Line breaks in sentences and names follow units of meaning, and related units and conditions must not be read separately from the body.
+
+When adjusting size, apply the document-wide criteria for each body level. Do not enlarge or reduce only the same level in a particular slide or box. If a common size changes, check every slide that uses that level.
+
+When it is difficult to maintain semantic distinction and readability, simplify the structure or divide the slides at units where meaning is complete. If slide-count or output constraints make resolution impossible, state the conflicting constraints and remaining issue. Confirm readability at the actual delivery size.
+<!-- /criterion -->
+
+<!-- criterion:c0009 -->
+## 9. Connect semantic levels within a slide to document-wide text sizes
+
+Determine semantic hierarchy within each slide's body. First distinguish what is the higher-level concept and which items and explanations belong below it. Do not determine body text sizes by constructing a hierarchy among concepts across the whole document or by judging which slide's topic is more important.
+
+Connect the levels determined on each slide to sizes shared across the document. Within a slide, express a higher level larger than a lower level, and make the difference between levels discernible on the actual screen. Text at the same level uses the same size even when it is on a different slide or in a different box. The number of levels and actual size values are set in the task specification; do not force a level that a slide does not need. If values have not been set, the author selects them based on delivery purpose, screen size, and content volume, then records them as the application standard.
+
+| Situation | Basis for setting size |
+|---|---|
+| Different concepts on different slides occupy the same body level | Apply the same size without comparing the concepts' relationship or importance. |
+| The same concept is used as a higher-level grouping on one slide and a detailed explanation on another | Apply the size appropriate to its level within each slide. |
+| Text at the same level is long or differs only in form, such as a sentence versus a word | Keep the same size and adjust through width, line breaks, alignment, and arrangement. |
+
+Do not determine a semantic level merely from the form of being a table header or bold. Base it on the actual role it plays in that slide's body. Classify table values and units by their meaning and reading role as well; do not rename a level as lower merely to fit content in smaller type. Manage size criteria for headlines, introductions, and sources separately from body levels.
+
+Make the roles of higher-level area titles, column titles, lower-level titles, and body values visible. Distinguish them by adding background contrast, dividing lines, or boldness to size based on semantic level, while using the same emphasis treatment consistently for the same role within the document. Distinguish table headers from the first data row, and do not layer further emphasis when the distinction is already sufficient. Do not rely only on differences in a specific color.
+
+Adjust if hierarchy is reversed or blurred on the actual screen even when level names or style settings are correct. Check size consistency and the validity of semantic-level classification separately.
+<!-- /criterion -->
+
+<!-- criterion:c0010 -->
+## 10. Align text according to its form and reading purpose
+
+Choose alignment according to the content form of the relevant block and the reading or comparison the reader performs. Even at the same semantic level, sentences and short labels may use different alignment.
+
+| Content and reading mode | Basis for choosing alignment |
+|---|---|
+| Continuous sentences, long explanations, or multi-line evidence | Use alignment that makes it easy to read from the beginning of each line. Left alignment is usually appropriate. |
+| Short labels, independent words, or a list of similarly sized words | Consider whether center alignment enables faster recognition of the grouping and comparison targets. Do not require it merely because the content is words. |
+| Numbers whose magnitude is compared | Align the baseline needed for comparison, such as digit places or decimal points. Standardize units and notation. |
+| Titles and explanations, table headers and values | Choose alignment appropriate to each role while preserving the correspondence between titles and content. |
+
+Choose horizontal and vertical alignment separately. Centering a short label within a cell and aligning the starting line of a long explanation to the top may suit different reading tasks. Within the same comparison, standardize the alignment basis for items with the same role, form, and reading purpose.
+
+Vertical centering is a choice that changes position within a cell. It does not justify excessive box height. When line breaks or content volume changes, recheck alignment and row-column correspondence.
+<!-- /criterion -->
+
+<!-- criterion:c0011 -->
+## 11. Verify the source, wording, and visual expression separately
+
+When comparing against the source, check that key concepts, figures, conditions, subjects, and relationships are preserved. On the screen, read separately the relationship stated by the actual wording and the relationship indicated by the arrangement, shape, and symbols, then check that they agree. Correct the expression if wording states correlation but a symbol implies causality, or if independent alternatives appear to be consecutive stages.
+
+First verify the composition method on representative slides, then review the entire document after expansion. Titles, groupings, hierarchy, and flow must be readable without the author's explanation. When changing a common size or style, recheck every affected slide type.
+
+In the final delivery format, inspect line breaks, contrast, dividing lines, backgrounds, connection targets, and page breaks. Check versions that omit some elements so they do not leave an empty space or broken reference. Also check whether the screen actually reviewed and the document to be delivered represent the same content.
+
+Successful rendering, no overflow beyond the page, and the author's declaration of completion do not replace quality review. Retain evidence from source comparison and screen review, and distinguish items that were not verified from items whose judgment is ambiguous. After correcting remaining issues, recheck, or deliver with unresolved limitations stated.
+<!-- /criterion -->

package/claude/guides/svg-visualization-guide.md

@@ -36,6 +36,15 @@ For `IMPLEMENTATION_MAP.html`, include one self-contained SVG service blueprint
 that shows the whole service or implemented system at the right level of
 abstraction.
 
+## Slide And Presentation Work
+
+When creating, revising, or reviewing slides or presentation materials, read the
+normal guide at `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/guides/slide-writing.md` for
+the semantic criteria before choosing a visual expression. Read its companion
+runbook only for an explicitly applicable static HTML/PDF job path. This guide
+helps make logical relationships visually readable; it does not replace the
+that guide's source-fidelity, hierarchy, spacing, or review criteria.
+
 ## When To Use SVG
 
 Prefer SVG when the visual needs any of these:

package/claude/guides/verification-discipline.md

@@ -175,7 +175,11 @@ produce a green with no evidence behind it:
   healed downstream or coinciding with a default. The runner must report build failure,
   unreachable, and equivalent distinctly from KILLED and SURVIVED, and halt on a moved anchor.
   More tests red than the mutation should touch indicts it; classify a survivor (rebuild,
-  discard, genuine gap) before writing a test.
+  discard, genuine gap) before writing a test. **Equivalent is a verdict about the probe as
+  much as the mutant**: a probe that is dead or returns a constant reports every mutant as
+  equivalent, and one aimed at an input the mutant does not affect reports the same. Refuse
+  the verdict unless the probe is shown to discriminate on UNMUTATED code and to exercise the
+  input the mutant targets — an unusable probe is its own outcome, not an equivalent mutant.
 - **The probe that measured the original.** A copied script that derives its root or targets from
   its own location (`$0`, `BASH_SOURCE`, a `cd` to its parent) scans the original tree, not the
   copy, so its verdict says nothing about the mutation you planted. Pin the subject in the copy,

package/claude/hooks/tooling-gotchas-hook.py

@@ -14,8 +14,9 @@ GUIDE = "guides/tooling-gotchas.md"
 
 # (name, compiled trigger, one-line reminder, guide anchor). Priority order; max 2 injected.
 #
-# The anchor is the heading in tooling-gotchas.md this rule compresses. It exists because the
-# hook is Claude-only and the guide is what a Codex reader gets instead: a rule admitted here
+# The anchor is the heading in tooling-gotchas.md this rule compresses. It exists because
+# agent-bios registers this hook on Claude only — Codex has hooks of its own, they are simply
+# not wired here — so the guide is what a Codex reader gets instead: a rule admitted here
 # with no counterpart there would silently give the two hosts different guidance. The mapping
 # is declared rather than matched, because a rule name and a guide heading do not share a
 # string. --self-test checks every anchor against the guide AND its codex mirror.
@@ -224,11 +225,12 @@ def main() -> int:
 
 
 def self_test() -> int:
-    """Two halves, because this hook serves two hosts differently.
+    """Two halves, because this hook reaches the two hosts differently.
 
     Claude gets the injection, so the first half runs the real entry point over real stdin and
-    requires the message out. Codex gets nothing from a hook, so its equivalent is the guide —
-    and the second half is the only thing that keeps the two hosts saying the same thing.
+    requires the message out. Nothing registers this hook on Codex, so its equivalent is the
+    guide — and the second half is the only thing that keeps the two hosts saying the same
+    thing. Codex does have hooks; wiring them is open work, not a host limitation.
     """
     import pathlib, subprocess
 

package/codex/AGENTS.md

@@ -85,8 +85,8 @@
 ## Multi-Model Workflow
 
 - Codex-only standing authorization: on root/main local tasks, ordinary subagent dispatch is authorized when the `When To Spawn` gates fire. Explicit no-fan-out wins. Delegated agents may re-delegate only when their role allows. This grants no destructive, remote, credential, install, OAuth, push, live-network-expanding, or broader-sandbox authority.
-- Standing spawn policy: check the spawn gates at every work-unit boundary — judgment latitude applies inside a gate, never to whether the gates are checked. Independence: verifying or reviewing your own work always spawns, and you raise it yourself — before presenting a load-bearing conclusion or taking an irreversible step, propose the cross-check unprompted; the user should never have to ask for it. Parallelism: two or more independent items spawn in parallel — SWEEP when each item applies one explicit rule and returns ambiguity as an exception, else WORKHORSE. Residual context: work whose log dwarfs the conclusion the main needs spawns with a bounded report contract. Escalation: an irreversible or authority-changing action ahead, two failed attempts, or two persisting design alternatives spawns a bounded FRONTIER judgment with a blind packet (evidence, constraints, rubric, neutral alternatives — never your draft conclusion) and a pre-noted change condition. Specifiability/de-minimis: work needing your live context, or whose verification would repeat the reasoning, or whose packet outweighs the work, stays inline.
-- Down-spawns carry a machine-checkable done-when on decision-complete work with staged output (no external irreversible actions) and briefing-plus-verifying clearly cheaper than doing. Record one line per gate decision — `SpawnGate: <gate> <tier> spawn|inline — <why>` — and for FRONTIER record the disposition afterward (what changed, or why nothing did). A launch contract's `Delegation=off` lifts the spawn obligation, not the records; explicit user no-fan-out always wins.
+- Standing spawn policy: check the spawn gates at every work-unit boundary — judgment latitude applies inside a gate, never to whether the gates are checked. Independence: before presenting a load-bearing conclusion or taking an irreversible step, propose the cross-check unprompted; the user should never have to ask for it. Independence comes from the seat you dispatch to, so name it. Parallelism: two or more independent items spawn in parallel — SWEEP when each item applies one explicit rule and returns ambiguity as an exception, else WORKHORSE. Residual context: work whose log dwarfs the conclusion the main needs spawns with a bounded report contract. Escalation: an irreversible or authority-changing action ahead, two failed attempts, or two persisting design alternatives spawns a bounded FRONTIER judgment with a blind packet (evidence, constraints, rubric, neutral alternatives — never your draft conclusion) and a pre-noted change condition. Specifiability/de-minimis: work needing your live context, or whose verification would repeat the reasoning, or whose packet outweighs the work, stays inline.
+- Down-spawns carry a machine-checkable done-when on decision-complete work with staged output (no external irreversible actions) and a tier pinned before dispatch. Record one line per gate decision — `SpawnGate: <gate> <tier> spawn|inline — <why>` — and for FRONTIER record the disposition afterward (what changed, or why nothing did). A launch contract's `Delegation=off` lifts the spawn obligation, not the records; explicit user no-fan-out always wins.
 - For work spanning multiple models or CLI agents, context resets and handoffs, unattended LLM batches (including orchestrated subagent fleets), or parallel worktree branches, read and use `${CODEX_HOME:-$HOME/.codex}/guides/cli-multi-model-workflow.md` as a scoped extension of this section.
 - For composing a prompt, packet, or tool description aimed at a specific model family — including cross-family review dispatch, porting a prompt written for an older model, or choosing a reasoning-effort level for a model family — read and use `${CODEX_HOME:-$HOME/.codex}/guides/gpt-prompting.md` for gpt-family targets and `${CODEX_HOME:-$HOME/.codex}/guides/claude-prompting.md` for claude-family targets as scoped extensions of this section.
 - Allocate models by difficulty × blast radius, not phase name; when implementation ran on a cheaper tier, compensate by raising reviewer effort or adding a reviewer kind — never economize on implementation and verification at once.

package/codex/agents/frontier.toml

@@ -1,6 +1,7 @@
 name = "frontier"
 description = "Bounded hardest decisions, first-of-kind design, triage, and final verdicts."
-model = "gpt-5.6-sol"
+model = "gpt-6-astra"
+model_reasoning_effort = "max"
 sandbox_mode = "read-only"
 
 developer_instructions = """

package/codex/agents/reviewer.toml

@@ -1,7 +1,7 @@
 name = "reviewer"
 description = "Adversarial review focused on correctness, regressions, security, and missing tests."
 model = "gpt-5.6-terra"
-model_reasoning_effort = "high"
+model_reasoning_effort = "xhigh"
 sandbox_mode = "read-only"
 
 developer_instructions = """

package/codex/agents/sweep.toml

@@ -1,9 +1,9 @@
 name = "sweep"
-description = "Cheap read-heavy scans, candidate finding, mechanical checks, and closed-form summaries."
+description = "Read-only checks applying one explicit rule to each item; report ambiguity as an exception."
 model = "gpt-5.6-luna"
-model_reasoning_effort = "low"
+model_reasoning_effort = "max"
 sandbox_mode = "read-only"
 
 developer_instructions = """
-Run one clear repeatable scan, candidate pass, mechanical check, or closed summary over exact inputs/rules/stop/output. Read-only: do not edit, broaden scope, choose architecture, or seek authority. Use relevant tools, parallelize independent reads, and surface ambiguity instead of inferring intent. Return status, the non-empty items_checked, findings, proving evidence/command, and risks_or_escalations.
+Apply one explicit rule to each item in the supplied inputs and stop at the declared boundary. Read-only: do not edit, broaden scope, choose architecture, or seek authority. Use relevant tools, parallelize independent reads, and surface ambiguity instead of inferring intent. Return status, the non-empty items_checked, findings, proving evidence/command, and risks_or_escalations.
 """

package/codex/agents/workhorse.toml

@@ -1,7 +1,7 @@
 name = "workhorse"
 description = "Bounded implementation, fixes, and per-item judgment for delegated Codex work."
 model = "gpt-5.6-terra"
-model_reasoning_effort = "high"
+model_reasoning_effort = "xhigh"
 
 developer_instructions = """
 Complete one bounded implementation, fix, or per-item judgment from a packet naming objective, frozen scope/inputs, allowed actions, output, done-when, and verification. Preserve out-of-scope behavior, batch independent reads, and escalate missing decisions/authority. Inherit sandbox; dangerous, remote, credential, install, OAuth, push, or live-network-expanding actions require exact original-user authorization. Run the narrowest reliable changed-path check and report status, files_or_items_touched, evidence, verification or gap, and risks_or_escalations.

package/codex/config-additions.toml

@@ -18,5 +18,5 @@ description = "Bounded implementation, fixes, and per-item judgment for delegate
 config_file = "${CODEX_HOME}/agents/workhorse.toml"
 
 [agents.sweep]
-description = "Cheap read-heavy scans, candidate finding, mechanical checks, and closed-form summaries."
+description = "Read-only checks applying one explicit rule to each item; report ambiguity as an exception."
 config_file = "${CODEX_HOME}/agents/sweep.toml"

package/codex/guides/claude-prompting.md

@@ -9,21 +9,26 @@ use_when:
   - porting a prompt written for an older claude model
   - deciding a reasoning-effort level for claude work
 core_rules:
+  - choose guidance by the actual target model — Fable 5.1 and Opus 5 need different progress, delegation, and verification tuning
   - state the goal, the constraints, and the reason behind the request; let the model choose the route
-  - de-prescribe ported prompts — step-by-step scaffolding written for older models reduces output quality on this tier
+  - compare inherited process scaffolding on the target model before keeping or removing it
   - put the full task specification in the first turn for long-horizon work rather than revealing it across turns
   - make tool descriptions prescriptive about when to call, not only what the tool does
   - require progress claims to be audited against a tool result from the same session
   - name the boundary explicitly — what to do without asking, and what to stop and ask about
-derived_at: 2026-09-01
+derived_at: 2026-09-07
 source_pins:
   - doc: prompting-claude-opus-5
     sha256: 65be3e0b437cbe23cc41bb4f9b7a5031c5a71cd49ab91ec4d19c62738762b086
-    pinned_at: 2026-09-01
+    pinned_at: 2026-09-07
   - doc: claude-prompting-best-practices
-    sha256: 476ddc2744812dced0b520c8f628aecb52df52babdaf82ee5a0b10f25f5bcbdb
-    pinned_at: 2026-09-01
+    sha256: f98aa130a7974b2edf98f8c3babe806ab140d5cdd3933a506f5211335b431c5f
+    pinned_at: 2026-09-07
+  - doc: prompting-claude-fable-5-1
+    sha256: 4aa645dd26fe9efebdaaff7462563bfac1f27782ce2d71dd5afffeaf02a80c62
+    pinned_at: 2026-09-07
 targets:
+  - claude-fable-5-1
   - claude-fable-5
   - claude-opus-5
   - claude-sonnet-5
@@ -32,6 +37,7 @@ verification_focus:
   - prompt changes are A/B'd against the prior scaffolding rather than assumed
   - effort changes are swept across levels on a real eval set, not chosen by reputation
   - per-model constraints are confirmed against the live surface before use
+  - model-specific advice stays within its named section, including after assembly
 ---
 
 # Claude Prompting Guide
@@ -41,26 +47,56 @@ composing a prompt for a claude-tier model — a review packet dispatched
 cross-family, a subagent brief, or the main's own instructions when the main is
 Claude.
 
-The central shift: this tier is more autonomous and more literal than its
-predecessors, and prompts written for older models are often too prescriptive —
-they measurably reduce output quality. Porting a prompt means removing
-scaffolding, not adding to it. State the goal and the constraints; let the model
-pick the path.
+Use the shared recipe and checklist together with the section for the model being
+prompted, even when a subagent uses a different model from the main. Model-specific
+tuning preserves the corpus's permission boundaries and required verification.
+
+| Target | Apply |
+| --- | --- |
+| `claude-fable-5-1` | Shared recipe and Claude Fable 5.1 |
+| `claude-opus-5` | Shared recipe and Claude Opus 5 |
+| `claude-fable-5`, `claude-sonnet-5`, `claude-haiku-4-5` | Shared recipe; consult the target's own guidance before borrowing another model's tuning |
 
 ## Default prompt recipe
 
-- `Goal` and the **reason behind it** — this tier connects a task to relevant
-  context when it knows the intent, instead of inferring intent on its own.
-  "I'm doing X for Y, who needs Z; with that in mind: …" outperforms the bare
-  request, most of all for long-running agents holding several workstreams.
+- `Goal` and the **reason behind it** — provide the audience, purpose, and relevant
+  context so the model does not have to infer the intent.
 - `Success criteria` — what done means and how it is checked.
-- `Constraints and boundaries` — say what not to do. This tier sometimes takes
-  unrequested-but-adjacent actions; naming the boundary is the fix.
+- `Constraints and boundaries` — state the permitted scope and approval conditions.
 - `Tools` — each description states **when to call it**, not only what it does.
-  Prescriptive trigger conditions give measurable lift here.
+  Name prerequisite retrieval and validation when correctness depends on them.
 - `Output` — the artifact shape and the register.
 
-## When to add blocks
+## Claude Fable 5.1
+
+- Begin effort experiments at `high`; compare supported levels afresh. Identical
+  effort names need not have identical costs across models.
+- Request brief start, progress, and final updates; first verify the client renders
+  updates and remove conflicting silence instructions.
+- Batch independent tool calls. Let the lead do independent work while subagents run.
+- Complete authorized requests, including promised next steps. State genuine approval
+  boundaries and whether a person is available; avoid unnecessary pauses.
+- Ask for literal prose and useful formatting. Demonstrate how retrieved quotations
+  should be marked and attributed.
+- Keep edits targeted and tests proportional to the requested behavior; report
+  unrelated issues separately.
+- At `low`, explicitly trigger retrieval for current facts instead of trusting name
+  recognition. Compare higher effort when retrieval still fails.
+- Preserve decisions, constraints, open work, and exact details in compaction summaries.
+- Append API history unchanged; use supported compaction instead of replaying thinking
+  against an edited prefix.
+- At `xhigh`/`max`, budget tokens for thinking and the deliverable; compare `high` for
+  long outputs.
+- Give dense-image work crop and zoom tools.
+
+These are prompt and harness tuning choices, not changes to the configured seat's
+effort or permissions. The Opus-specific advice below does not apply to this model.
+
+## Claude Opus 5
+
+The following behavior claims and tuning recommendations apply to `claude-opus-5`.
+
+### When to add blocks
 
 - Long-horizon or autonomous work: give the full spec up front in one
   well-specified turn and run at a high effort. Do **not** add a self-check
@@ -90,21 +126,18 @@ pick the path.
 - Progress reporting: require each claim to be traceable to a tool result from
   the session, and unverified work to be labeled as such.
 
-## How to choose prompt shape
+### How to choose prompt shape
 
 - One bounded question with a self-contained packet → a single run. Default for
   review.
 - Independent workstreams → delegate, and prefer asynchronous subagents over
   spawn-and-block: long-lived agents keep their context instead of rebuilding it
   per subtask, and the orchestrator is not pinned to the slowest one.
-- Effort ladder — `low`, `medium`, `high`, `xhigh`, `max` on the frontier, helm,
-  and workhorse bindings; `xhigh` is the best setting for most coding and
-  agentic work, `high` a sound default, `low` for cheap subagent scans. Start
-  there and sweep *down* on a real eval set rather than reaching for the top: the
-  lower rungs are unusually strong on the helm binding, higher effort up front
-  often *reduces* turn count and total cost on agentic work, and some tasks land
-  equally well a level down. Effort does not control response length — see
-  Working rules.
+- Start effort experiments at `high`; compare lower settings on representative
+  tasks and step up to `xhigh` for demanding coding or agentic work when quality
+  improves. Re-test inherited defaults. The configured seat's effort remains an
+  explicit workload choice. Effort does not control response length — see Working
+  rules.
 - Per-model constraints differ across the `targets` bindings — thinking
   configuration, sampling parameters, and effort support are not uniform, and
   the sweep binding is the most restricted. On the helm binding, for instance,
@@ -113,7 +146,7 @@ pick the path.
   live surface before relying on it in a dispatch; do not assume the frontier
   binding's rules apply to the sweep one.
 
-## Working rules
+### Working rules
 
 - Expect long turns. A single request on a hard task at high effort can run for
   minutes; plan timeouts, streaming, and progress UX around that rather than
@@ -143,7 +176,7 @@ pick the path.
 - Instruction following stays consistent across the full context window, so a
   rule does not need restating near the end to survive a long session.
 
-## Running with thinking disabled
+### Running with thinking disabled
 
 Disabling thinking is accepted only at `high` effort or below, and it is usually
 the wrong lever: thinking on at `low` effort generally beats thinking off at
@@ -173,20 +206,20 @@ delete it: that instruction increases tag leakage rather than suppressing it.
 2. Name the boundaries — what to do freely, what to stop and ask about.
 3. Give each tool a when-to-call description.
 4. Say how progress claims must be grounded, and how the deliverable should read.
-5. Delete the step-by-step scaffolding inherited from older models — including
-   any verify-your-work step and any encouragement to delegate — then A/B the
-   prompt with it removed before keeping either version.
+5. Apply the target model's section and check for contradictions. Compare changes
+   on the same tasks; remove inherited scaffolding only when the target benefits,
+   keeping required repository checks and permission boundaries intact.
 
 ## Sources
 
-Derived from the vendor's `prompting-claude-opus-5` and
-`claude-prompting-best-practices` documents, at the exact bytes whose hashes are
-recorded in `source_pins` above. The pin is what makes a later vendor edit
-detectable rather than remembered.
+The shared recipe is derived from `claude-prompting-best-practices`; the Fable 5.1
+section from `prompting-claude-fable-5-1`; and the Opus 5 section from
+`prompting-claude-opus-5`. `source_pins` records the exact bytes used for this
+derivation. Fable 5.1 has its own prompting document; model names in `targets` do
+not extend the Opus-specific behavior claims to other models.
 
-Prompting guidance is version-bound — this generation inverted advice the last one
-gave — so when a `targets` model changes, re-derive from the current documents
-rather than editing around the old rules.
+When a `targets` model changes, re-derive its advice from its own current document
+and check the shared recipe for conflicts.
 `launch/check-prompting-targets.sh` fails when the launch config binds a model
 this guide does not list; that check is about **naming**, and a model added to
 `targets:` satisfies it forever. Whether the guidance was actually re-derived is