From 0419534100d667475226cb07301a43a8428f4f03 Mon Sep 17 00:00:00 2001 From: Alex J Lennon Date: Thu, 15 Oct 2026 23:11:18 +0100 Subject: [PATCH] Clarify Briar guidance and improve the first-hour path Assisted-by: Briar --- .github/workflows/ci.yml | 6 +- AGENTS.md | 25 +++--- content/capabilities.json | 14 ++- content/clocks.json | 2 +- content/glossary.json | 2 +- content/hour.json | 84 ++++++++---------- content/learning.json | 13 +-- content/measure.json | 17 ++-- content/patterns.json | 6 +- content/playbook.json | 16 ++-- content/runtime.json | 11 +-- content/stack.json | 12 +-- content/starters.json | 6 +- content/stats.json | 2 +- content/timeline.json | 2 +- docs/agents.html | 16 ++-- docs/app.js | 12 ++- docs/content/capabilities.json | 14 ++- docs/content/clocks.json | 2 +- docs/content/glossary.json | 2 +- docs/content/hour.json | 84 ++++++++---------- docs/content/learning.json | 13 +-- docs/content/measure.json | 17 ++-- docs/content/patterns.json | 6 +- docs/content/playbook.json | 16 ++-- docs/content/runtime.json | 11 +-- docs/content/stack.json | 12 +-- docs/content/starters.json | 6 +- docs/content/stats.json | 2 +- docs/content/timeline.json | 2 +- docs/index.html | 22 ++++- docs/packs/codex-hour-starter.zip | Bin 5902 -> 7799 bytes docs/packs/codex-hour/AGENTS.md | 25 ++++-- docs/packs/codex-hour/CHECKLIST.md | 61 ++++++++++--- docs/packs/codex-hour/README.md | 69 ++++++-------- docs/packs/codex-hour/clocks.json | 4 +- .../codex-hour/patterns/WORKING-PATTERNS.md | 4 + docs/packs/cursor-hour-starter.zip | Bin 6334 -> 9206 bytes .../rules/p0-human-gate-irreversible.mdc | 7 +- .../.cursor/rules/p0-no-secrets-in-chat.mdc | 2 +- .../.cursor/rules/working-agreements.mdc | 22 +++++ docs/packs/cursor-hour/CHECKLIST.md | 64 ++++++++++--- docs/packs/cursor-hour/README.md | 44 +++++---- docs/packs/cursor-hour/clocks.json | 2 +- .../cursor-hour/patterns/WORKING-PATTERNS.md | 4 + docs/starters/rule.template.md | 7 +- docs/styles.css | 16 ++++ package-lock.json | 13 ++- package.json | 3 +- packs/codex-hour/AGENTS.md | 25 ++++-- packs/codex-hour/CHECKLIST.md | 61 ++++++++++--- packs/codex-hour/README.md | 69 ++++++-------- packs/codex-hour/clocks.json | 4 +- packs/codex-hour/patterns/WORKING-PATTERNS.md | 4 + .../rules/p0-human-gate-irreversible.mdc | 7 +- .../.cursor/rules/p0-no-secrets-in-chat.mdc | 2 +- .../.cursor/rules/working-agreements.mdc | 22 +++++ packs/cursor-hour/CHECKLIST.md | 64 ++++++++++--- packs/cursor-hour/README.md | 44 +++++---- packs/cursor-hour/clocks.json | 2 +- .../cursor-hour/patterns/WORKING-PATTERNS.md | 4 + starters/rule.template.md | 7 +- tests/accessibility.spec.js | 82 +++++++++++++++++ tests/smoke.spec.js | 6 +- 64 files changed, 781 insertions(+), 424 deletions(-) create mode 100644 docs/packs/cursor-hour/.cursor/rules/working-agreements.mdc create mode 100644 packs/cursor-hour/.cursor/rules/working-agreements.mdc create mode 100644 tests/accessibility.spec.js diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 0d0e116..63f1eb8 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -9,10 +9,10 @@ jobs: privacy-and-ux: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v4 - - uses: actions/setup-node@v4 + - uses: actions/checkout@v6 + - uses: actions/setup-node@v6 with: - node-version: "20" + node-version: "24" cache: npm - run: npm ci - run: npx playwright install --with-deps chromium diff --git a/AGENTS.md b/AGENTS.md index bf22455..5af241c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -10,17 +10,20 @@ This notebook is for humans **and** coding agents. Do not invent policy from the 2. Download the Codex pack: (or browse ; the original Cursor pack remains available at ) -3. Copy the pack’s `AGENTS.md` and `.agents/` into the **project** root. Start a - new Codex task so guidance loads from the beginning. -4. Rename the example skill to the human’s real recurring job. -5. Keep both fail-closed boundaries: `no secrets in chat` and `human decision - for consequential writes`. Codex guidance, sandboxing and permissions are - separate layers; one does not replace another. -6. Sign off **one** pattern in `patterns/WORKING-PATTERNS.md` with a real failure line. -7. Set `harness.start` in `clocks.json` to today (ISO). -8. Run one real task with the skill’s proof checklist — not a plan alone. - -Done when those eight are true. Then stop for the day. +3. Merge the pack’s `AGENTS.md` and `.agents/` into existing project guidance; + never overwrite it. For Cursor use `.cursor/rules/` and `.cursor/skills/`. + Start a new task and check which guidance and skills the host can read. +4. Check the secrets boundary and the human decision for consequential actions. + Written guidance does not enforce controls: test host permissions separately. +5. Run one small read-only task now, such as explaining a failing test with file + references and a suggested check. Verify the result against the source. +6. Adapt the host’s example skill only if the job recurs. +7. Keep a pattern only for an observed problem. A signed-off row is editorial + agreement, not a cryptographic capability or action permission. +8. Set optional dates honestly: both packs have `harness.start`; only Codex has + `codex.start`. Unknown dates can stay unset. + +Done when one useful task has a checked result. No routine reflection record is required. ## While you work diff --git a/content/capabilities.json b/content/capabilities.json index 401d9f3..33ce891 100644 --- a/content/capabilities.json +++ b/content/capabilities.json @@ -1,6 +1,6 @@ { "schema": "durable-agent-harness/capabilities/v1", - "intro": "Productivity here is mostly scope: work that was uneconomic or impossible solo becomes routine — with proof and review still required.", + "intro": "These bands are Alex’s qualitative personal estimates of scope and effort, not benchmark results or measured productivity multipliers. The linked accounts show particular experiences and their limits; they do not validate every row. Where no public evidence is linked, support is not available here.", "scale": [ { "id": "solo-easy", @@ -57,14 +57,22 @@ "before": "impossible", "now": "solo-hard", "note": "Skills and signed patterns beat “we talked about this once”.", - "band": "Team knowledge base" + "band": "Team knowledge base", + "evidence": { + "url": "notes/the-token-bonfire.html", + "label": "Token Bonfire: failures and limits" + } }, { "outcome": "Move the working relationship between agent hosts", "before": "impossible", "now": "solo-hard", "note": "Portable Agent Skills moved; project guidance and permissions stayed host-native; a drift sensor guards the boundary.", - "band": "Platform engineering" + "band": "Platform engineering", + "evidence": { + "url": "notes/the-cockpit-changed-the-work-did-not.html", + "label": "Host migration account" + } }, { "outcome": "Parallel repository tasks with isolated state", diff --git a/content/clocks.json b/content/clocks.json index 73562ca..e07f149 100644 --- a/content/clocks.json +++ b/content/clocks.json @@ -1,7 +1,7 @@ { "schema": "durable-agent-harness/clocks/v1", "as_of": "2026-09-05", - "note": "Public tenure clocks for the engineering story. The start dates are intentional; they’re not a claim about the first time I ever touched an LLM.", + "note": "Snapshot calculated as of 5 September 2026, not today. Original start dates are preserved; these ages describe that date.", "clocks": [ { "id": "serious_ai", diff --git a/content/glossary.json b/content/glossary.json index b4e39c8..7a895b9 100644 --- a/content/glossary.json +++ b/content/glossary.json @@ -120,7 +120,7 @@ }, { "term": "Briar", - "def": "A WhatsApp personal-assistant channel for monitor/triage and tiered replies, with the same fail-closed outbound rules as the cockpit." + "def": "Alex’s agent setup: project guidance, skills, tools, memory and runtime controls used across hosts. Messaging is one surface; Briar is not a particular editor or model." }, { "term": "Token lean", diff --git a/content/hour.json b/content/hour.json index 0a1c236..6fa7069 100644 --- a/content/hour.json +++ b/content/hour.json @@ -1,8 +1,8 @@ { "schema": "durable-agent-harness/hour/v1", "title": "Start in 60 minutes", - "intro": "Don’t read the whole notebook. Get a thin working relationship into Codex in about an hour — or take the original Cursor pack if that is still your cockpit.", - "promise": "When you finish you have: two fail-closed boundaries, one on-demand skill, one signed pattern, and two tenure clocks. That’s enough to stop the next stupid burn.", + "intro": "Start with a small piece of work in a project you control. Use Codex or Cursor; the packs share the same boundaries but use different project paths.", + "promise": "Within the first 35 minutes, aim for one useful, checked result. The rest of the hour is for keeping only the guidance and records you need.", "pack": { "zip": "packs/codex-hour-starter.zip", "browse": "packs/codex-hour/README.md", @@ -23,78 +23,68 @@ { "id": "1", "minutes": 5, - "title": "Download the pack", - "why": "Empty templates invite dithering. This pack is already named and filled with boring defaults you can rename.", - "do": "Download the zip (or browse the files). Unzip next to a scratch project — or into a small git repo you control.", - "proof": "You can see README.md, AGENTS.md and a .agents/skills tree on disk." + "title": "Choose a small task and your host", + "why": "Use a project you control and a task whose result you can check.", + "do": "Download the Codex or Cursor pack. Start with a read-only job: explain one failing test, naming the file, likely cause and one way to check it.", + "proof": "A task with a clear finish, and the selected pack unpacked beside the project." }, { "id": "2", "minutes": 10, - "title": "Drop files where Codex loads them", - "why": "A harness that lives only in chat dies when the chat dies.", - "do": "Copy `AGENTS.md` and `.agents/` into your project root. Start a new Codex task so project guidance is read from the beginning and the skill is discovered.", - "proof": "Codex can name the project guidance and the example-domain-task skill." + "title": "Merge guidance and check the boundaries", + "why": "Keep the project’s existing instructions.", + "do": "Codex: merge AGENTS.md and .agents/ into the project root. Cursor: merge .cursor/rules/ and .cursor/skills/. Compare conflicts before changing existing files. Keep secrets out of chat; agree the exact scope before consequential actions. Start a new task and ask which guidance and skill paths it can read. Check host permissions separately.", + "proof": "You can distinguish the instructions it read from controls the host actually enforces." }, { "id": "3", - "minutes": 10, - "title": "Rename the skill to your real job", - "why": "Generic skills don’t fire. Trigger nouns must match how you talk.", - "do": "Edit skills/example-domain-task/SKILL.md: change the name, description triggers, When/Do steps, and Proof of done to one task you do weekly.", - "proof": "You can say the trigger phrase out loud and it matches the description." + "minutes": 20, + "title": "Do useful work", + "why": "A result tells you more than a completed setup checklist.", + "do": "Run the small task now. For example: “Read this failing test and its implementation. Explain the likely cause and suggest a focused check. Do not edit files.” Require file references and the limits of the diagnosis.", + "proof": "A useful answer checked against the source, with no unrequested edits." }, { "id": "4", "minutes": 10, - "title": "Keep two fail-closed boundaries", - "why": "Secrets in chat and silent consequential writes are the burns that don’t forgive. The host mechanism may change; the boundary must not.", - "do": "Read the two boundaries in AGENTS.md: secrets stay out of chat, and consequential writes need a visible human decision. Keep the file short. Use Codex sandboxing and permissions as separate host controls.", - "proof": "You can explain each boundary, its decision point, and what the host enforces separately." + "title": "Adapt a skill if the job will recur", + "why": "Keep a procedure only when it helps repeat the work.", + "do": "Codex: edit .agents/skills/example-domain-task/SKILL.md. Cursor: edit .cursor/skills/example-domain-task/SKILL.md. Rename it for your recurring job, with matching triggers and proof of done. Try that job with the skill.", + "proof": "The skill describes your job and its result can be checked. Skip it for a one-off task." }, { "id": "5", - "minutes": 10, - "title": "Sign off one pattern", - "why": "Unsigned patterns are just opinions. Sign-off is what makes Kaizen real.", - "do": "Open patterns/WORKING-PATTERNS.md. Keep a signed-off row that matches a real failure (the pack ships lean-tool-sessions and trash-instead-of-hard-delete as examples), or replace with one of yours. Write the problem in one line.", - "proof": "The table has at least one signed-off row that matches a real incident." + "minutes": 5, + "title": "Record a pattern only if there is a lesson", + "why": "An example row is not your own approval.", + "do": "Read patterns/WORKING-PATTERNS.md. Codex examples include one-writer-per-tree and one-bounded-diagnostic-pass; Cursor examples include lean-tool-sessions and trash-instead-of-hard-delete. Keep or adapt one only if it matches an observed problem. A signed-off row records editorial agreement, not permission to execute an action.", + "proof": "Any retained pattern names a real problem; otherwise leave it proposed." }, { "id": "6", "minutes": 5, - "title": "Freeze a tenure clock", - "why": "Without a start date, every demo invents a heroic timeline.", - "do": "Edit clocks.json: set harness.start to today and codex.start to the first day you used Codex on real project work.", - "proof": "Two dates you trust are on disk — not only in a slide." + "title": "Set dates if you want to track tenure", + "why": "Preserve history rather than making the setup look older.", + "do": "Both packs have clocks.json: set harness.start to today. The Codex pack also has codex.start: use the first day you used Codex on real project work, or leave it unset if unknown. Do not add a Codex date to the Cursor stub.", + "proof": "Any dates you keep are honest; clocks are optional records." }, { "id": "7", "minutes": 5, - "title": "Run one real task", - "why": "The harness is only real under load.", - "do": "Ask the agent to do the skill’s task. Require the proof checklist. If it skips a gate, stop and tighten the rule — don’t shrug.", - "proof": "You have a short note of what changed and how you verified it." - }, - { - "id": "8", - "minutes": 5, - "title": "Schedule a tiny Hansei", - "why": "Without reflection the pack becomes folklore in a week.", - "do": "Put a 15-minute calendar block in seven days: keep / amend / retire on the pattern and skill. Link this site’s Learning section if you want the longer loop.", - "proof": "The calendar (or ticket) exists. You are done for today." + "title": "Finish with the result", + "why": "Short tasks can finish in chat.", + "do": "Report what you found or changed, how you checked it and anything unresolved. If something failed, diagnose the mechanism before adding a rule: a smaller task, clearer instruction or runtime restriction may help. Review later only when requested or an observed problem warrants it.", + "proof": "One checked result. No routine reflection note or calendar appointment required." } ], "done": { "title": "Done when", "checks": [ - "Pack installed where Codex loads it", - "Skill renamed to your domain", - "Two fail-closed boundaries understood (secrets; consequential writes)", - "At least one signed-off pattern with a real problem line", - "Two frozen clock dates", - "One task run with proof — not a plan alone" + "Existing project instructions preserved and selected host paths checked", + "Secrets boundary understood; human decisions and host enforcement kept separate", + "One useful task completed with evidence and limits", + "Any skill, pattern or dates retained serve a real need" ] }, - "next": "When this feels boring (good), read the Codex migration note, Playbook or Learning sections. Skip what you don’t need." + "next": "Read the Playbook or Learning sections when a problem calls for them. The Token Bonfire describes what happened when improving the process became more work than the task." } diff --git a/content/learning.json b/content/learning.json index db19327..3b50e51 100644 --- a/content/learning.json +++ b/content/learning.json @@ -1,7 +1,7 @@ { "schema": "durable-agent-harness/learning/v1", "title": "Kaizen → Hansei → Toyota Way Practices", - "intro": "Tools alone aren’t the harness. We improve on purpose (Kaizen), reflect on what actually happened (Hansei), and keep a named practice cluster (Toyota Way Practices) so agents load the right lens for the live pain — not the whole philosophy every turn.", + "intro": "When work goes wrong, find out why before changing the process. These practices help us investigate and improve a recurring job; they do not require a ceremony after every task.", "flow": [ { "id": "gemba", @@ -13,19 +13,19 @@ "id": "kaizen", "name": "Kaizen", "gloss": "Continuous improvement with sign-off", - "body": "Propose a thin working pattern or skill. A human signs it off. Encode it where agents will load it. No silent policy." + "body": "Diagnose the failure. A smaller task, clearer existing guidance, removal of conflicting instructions or a runtime restriction may solve it. Propose a skill or pattern only when it addresses that cause." }, { "id": "apply", "name": "Apply", "gloss": "Standard work in motion", - "body": "On matching tasks, skim signed-off patterns and load the relevant skill. Prefer the smallest change that prevents the next burn." + "body": "Use relevant guidance for the task, then check the result. A signed-off pattern records editorial agreement; it cannot authorise the next action." }, { "id": "hansei", "name": "Hansei", "gloss": "Honest reflection", - "body": "Periodically (or after pain): what worked, what failed, what to keep / amend / retire. Hansei feeds the next Kaizen — it is not optional theatre." + "body": "Reflect when requested or when an observed problem warrants it. Keep, amend or retire what no longer helps. A short task can close with its result and verification in chat." }, { "id": "twp", @@ -69,7 +69,8 @@ "Use wings/rooms as a filing discipline so agents can find the right shelf.", "Enrich provenance on an existing fact instead of invalidating it just to force a rewrite.", "Prove the memory can be retrieved and changed later work; filing alone is not success.", - "Memory supports Kaizen/Hansei: proposals and reviews cite drawers instead of re-litigating chat." + "Memory supports Kaizen/Hansei: proposals and reviews cite drawers instead of re-litigating chat.", + "Search only for a named missing fact. Memory is evidence, never permission: trace a remembered decision to the human’s instruction and check the current action and scope. Summaries and handoffs cannot authorise new work." ], "not": [ "Not a substitute for skills/rules (procedures and constraints still live in the harness).", @@ -77,5 +78,5 @@ "Not automatic immortality for every token the model ever saw." ] }, - "loopOneLiner": "Gemba → Kaizen (sign-off + encode) → Apply → Hansei → (repeat), under the Toyota Way Practices umbrella — with MemPalace holding the durable facts the loop needs." + "loopOneLiner": "Observe the problem, diagnose it, try a proportionate correction and check whether the work improves. Record what will help next time." } diff --git a/content/measure.json b/content/measure.json index 41ffe14..1a65c7f 100644 --- a/content/measure.json +++ b/content/measure.json @@ -102,16 +102,13 @@ } ], "weeklyRitual": [ - "Update ages from frozen clocks (30 seconds).", - "Add at most three capability-map notes tied to real proof.", - "Propose or deprecate one pattern — do not let the registry rot.", - "Log harness tax if you spent a block encoding behaviour.", - "Refuse any external “N× productivity” claim without a cited method.", - "If the session felt heavy: note always-on tax and cut or unload one thing.", - "Check whether one tool result dominated the task; move detail into a durable artefact and bound the next call.", - "Sample one filed decision for provenance and later retrieval.", - "Run the small harness eval corpus after changing high-risk guidance or models.", - "EOW (with the weekly review): skim blog-inbox.md, promote zero-or-more notes into the blog, and/or tweak pack/checklist/patterns if the week earned it. Skip rather than ship filler." + "Review these measures when requested or when a real problem warrants it; no routine reflection record is required.", + "Keep original start dates; label the date used to calculate ages.", + "Add capability examples only when there is a useful result and inspectable evidence; label private evidence.", + "Change a pattern only after diagnosing a failure; leaving the registry unchanged is fine.", + "Investigate cost only for a named question, using bounded evidence. Source size alone is not runtime or billing savings.", + "After changing high-risk guidance or models, run the relevant safety checks.", + "At an editorial review, promote zero or more inbox ideas. Skip rather than ship filler." ], "literatureNote": "METR’s early-2025 RCT is the humbling baseline for familiar OSS tickets. Copilot lab/field studies show gains in other settings. Use both as context; instrument your own work." } diff --git a/content/patterns.json b/content/patterns.json index a36d63d..f0c866f 100644 --- a/content/patterns.json +++ b/content/patterns.json @@ -1,6 +1,6 @@ { "schema": "durable-agent-harness/patterns/v1", - "intro": "Portable patterns worth stealing — named moves we signed off because they earned their place.", + "intro": "Patterns we found useful after specific failures. A signed-off entry records editorial agreement with guidance, not a cryptographic capability or permission for a future action.", "patterns": [ { "name": "Lean tool sessions", @@ -79,7 +79,7 @@ { "name": "MemPalace with purpose", "problem": "Transcript sludge and contradictory “facts” make agents confidently wrong.", - "move": "File curated drawers; search before re-deciding; invalidate stale cards. Memory supports the Kaizen/Hansei loop — it is not a chat landfill.", + "move": "File curated drawers; search before re-deciding; invalidate stale cards. Memory supports the Kaizen/Hansei loop — it is not a chat landfill. Search for a named missing fact. Memory is evidence, never permission; check the human instruction and its current scope.", "signals": [ "Re-litigating settled decisions", "Duplicate contradictory notes" @@ -208,7 +208,7 @@ { "name": "Encode the second burn", "problem": "Teams re-pay for the same mistake because the fix lived only in a chat.", - "move": "When a failure repeats once, write or update a skill before moving on.", + "move": "Diagnose the repeated failure before changing guidance. Consider a smaller task, a runtime restriction, clarifying an existing rule or removing a conflict. Add a skill only if a repeatable procedure will help.", "signals": [ "“We hit this last month”", "Tribal knowledge in one person’s head" diff --git a/content/playbook.json b/content/playbook.json index 350b47d..d756950 100644 --- a/content/playbook.json +++ b/content/playbook.json @@ -5,7 +5,7 @@ "principles": [ "Start thinner than you think. A fat always-on prompt is a tax on every turn.", "Encode pain, not aspirations. A skill earns its place by preventing a real failure.", - "Irreversible actions stay human. Draft freely; send/publish/destroy only with an explicit gate.", + "The human decides consequential actions. An agent may execute an authorised action within its exact scope after the required checks; a review result does not grant that authority.", "Prefer trash over hard delete. Move files to a trash folder first so mistakes stay recoverable.", "Prefer proof over narrative. Define what “done” looks like before celebrating.", "Sign off cross-cutting habits. Lore in chat is not an operating system.", @@ -21,13 +21,13 @@ { "id": "2", "title": "Write two fail-closed boundaries", - "body": "Start with: (1) secrets never pasted into chat — use an approved secret store or capture flow, (2) no consequential write without a human decision that shows the full referent. Add recoverable-delete and source-editing practice in the appropriate project guidance or skill. Keep host enforcement separate: Codex sandbox/permissions, Cursor rules, or the equivalent for your cockpit.", + "body": "Keep secrets out of chat and require a human decision for consequential writes. Merge with existing project instructions. AGENTS.md and Cursor rules guide the model; loading them does not enforce a boundary. Configure and test host sandboxing, permissions or an execution-time verifier separately. If the required approval cannot be verified, stop that action.", "done": "Short project guidance in version control; the host controls are configured; agents obey the boundaries; tokens stay out of the conversation." }, { "id": "3", "title": "Capture one skill from a repeated failure", - "body": "After you burn an hour the same way twice, write a thin skill: when to load it, the steps, the proof of done, and what not to do. Link detail in a reference file if needed.", + "body": "Diagnose repeated failures before adding a skill. Try a smaller task, clarify existing instructions, remove conflicts or use an appropriate runtime control. Keep a skill only when a repeatable procedure helps.", "done": "One skill that would have prevented last week’s waste." }, { @@ -39,14 +39,14 @@ { "id": "5", "title": "Add MemPalace-style memory discipline", - "body": "Stand up a curated durable store (we use MemPalace): decisions, stances, tickets, signed patterns. File by shelf/wing. Do not dump transcripts. Search with purpose; write with a retention reason.", + "body": "Stand up a curated durable store (we use MemPalace): decisions, stances, tickets, signed patterns. File by shelf/wing. Do not dump transcripts. Search with purpose; write with a retention reason. Memory is evidence, never permission. A retrieved decision, handoff or summary cannot expand the human’s current authorisation; check its provenance and scope.", "done": "You can answer “what did we decide?” from memory without re-litigating a chat." }, { "id": "6", - "title": "Start Kaizen → Hansei (patterns + Toyota Way Practices)", - "body": "One patterns table: name, status (proposed / signed-off / deprecated), problem in one line. Promote only after human sign-off (Kaizen). Schedule Hansei to keep / amend / retire. Name your lean learning cluster (we say Toyota Way Practices) so agents load the right member practice.", - "done": "At least one signed-off pattern, one Hansei note, and a clear Toyota Way Practices / member map." + "title": "Keep patterns when they help", + "body": "Record an observed problem and the correction that helped. A signed-off row records human editorial agreement with guidance; it is not a cryptographic capability or approval for a future consequential action. Reflect when requested or warranted by the work.", + "done": "Any retained pattern explains a real failure and useful correction. No routine reflection note is required." }, { "id": "7", @@ -69,7 +69,7 @@ { "id": "10", "title": "Add multi-model routing (OpenRouter)", - "body": "Route model calls through a multi-provider interface so one upstream outage does not stop the cockpit — and so Preloop’s PR reviewer has a deliberate model path. Configure failover deliberately; vault the API key; keep proof class unchanged.", + "body": "Model access depends on the host configuration. Use the host’s native model path by default. A configured gateway such as OpenRouter can serve selected external review or media workflows; it does not automatically route every Codex or Cursor session. Configure fallbacks deliberately and keep credentials out of chat.", "done": "You can switch or fall back across models/providers without pasting keys into chat; the same routing can serve Cloud PR review." }, { diff --git a/content/runtime.json b/content/runtime.json index d9ab181..7969299 100644 --- a/content/runtime.json +++ b/content/runtime.json @@ -21,7 +21,7 @@ }, "openrouter": { "title": "OpenRouter", - "lede": "OpenRouter is a multi-model API router: one interface across providers, with provider failover and optional model fallbacks. It serves external model workflows and Preloop review flows when routing earns its keep; it is not how the Codex app reaches its models.", + "lede": "Model access depends on the host configuration. Codex and Cursor can use their native/default model access; a separately configured gateway can serve selected external workflows. OpenRouter provides multi-provider routing and fallbacks where deliberately configured, including some review workflows. It is not a universal path for the cockpit.", "docs": "https://openrouter.ai/docs", "verified": "2026-09-15", "preloopReviewRoute": { @@ -38,7 +38,7 @@ ], "not": [ "Not a replacement for skills/rules/memory — it is transport for model calls.", - "Not the model path for the Codex app.", + "Not proof that a host session uses this route; check that host’s configuration.", "Not “set and forget” for data-retention or ZDR choices; configure deliberately when it matters.", "Not a productivity multiplier claim by itself." ] @@ -49,7 +49,7 @@ "steps": [ { "title": "Push the PR commit", - "body": "Ordinary git push. No special local ritual — the check lives in Cloud + GitHub, not in a fat always-on prompt." + "body": "Before a push, confirm the human has authorised that repository, content and action and that required checks pass. Where action-bound verification is required, the executor must verify it at execution time. A review pass alone is not permission." }, { "title": "Preloop reviewer runs", @@ -65,7 +65,7 @@ } ], "practices": [ - "Treat the Preloop status as a review signal, not as merge authority — humans still merge.", + "The human owns the merge decision. An agent can execute a specifically authorised merge within scope after the required checks. A Preloop status supplies review evidence, not merge authority.", "Keep OpenRouter keys in Bitwarden Secrets Manager (or the vault Preloop Cloud uses); never in workflow YAML or chat.", "Prefer async review by default; make CI wait only when runner time is scarce or the failure mode is expensive.", "When the gate is on, fix or skip with an explicit, rare bypass — do not normalise “ignore Preloop”.", @@ -77,5 +77,6 @@ "Not the same thing as Preloop’s desktop MCP approvals in Cursor." ] }, - "together": "The durable harness — portable skills, explicit policy, memory, signed patterns, gates and proof — supports the working relationship. Codex owns its model path, sandbox and permissions; those host-native mechanisms are dependencies and adapters, not portable assets. Preloop can audit selected tool flows and review PR commits; OpenRouter routes external model capacity for those workflows. CI may wait on the review signal. Humans still own consequential actions and merges." + "together": "The durable harness — portable skills, explicit policy, memory, signed patterns, gates and proof — supports the working relationship. Codex owns its model path, sandbox and permissions; those host-native mechanisms are dependencies and adapters, not portable assets. Preloop can audit selected tool flows and review PR commits; OpenRouter routes external model capacity for those workflows. CI may wait on the review signal. Humans still own consequential actions and merges.", + "summary": "The harness supports the work through procedures, evidence and controls. Guidance files do not install enforcement. Host configuration determines model access and permissions; optional services cover only their configured flows. Human decisions remain necessary for consequential actions, even when an agent performs the authorised execution." } diff --git a/content/stack.json b/content/stack.json index a10aa4c..bc66e58 100644 --- a/content/stack.json +++ b/content/stack.json @@ -1,6 +1,6 @@ { "schema": "durable-agent-harness/stack/v1", - "intro": "The working relationship is the human experience. The harness is the versioned and tested mechanism that makes it repeatable: portable procedures, explicit policy, memory, tools, human gates and feedback. Codex and Cursor are cockpits; product-specific mechanisms are host adapters.", + "intro": "Briar is the name of my agent setup across editors, models and messaging surfaces. This notebook describes what we tried, where it failed and what helped us finish useful work. Skills and project instructions guide the agent; host permissions and runtime controls enforce only the boundaries they are configured to cover.", "layers": [ { "id": "cockpit", @@ -63,12 +63,12 @@ "id": "patterns", "title": "Patterns", "subtitle": "Kaizen → Hansei → Toyota Way Practices", - "body": "Cross-cutting ways of working: propose → human sign-off → encode → apply → periodic Hansei. The learning core is named Toyota Way Practices; patterns are the registry that makes Kaizen real.", + "body": "Keep guidance that addresses an observed problem. A human can agree a correction, then test it on real work. Review it when requested or when it stops helping; a signed-off entry is not action permission.", "tips": [ "No silent promotion to signed-off", - "Hansei keeps / amends / retires — on a cadence", - "Toyota Way Practices names the cluster; load the member practice for the live pain", - "Encode into skills/rules where agents will load them" + "Review when requested or warranted by a problem", + "Load the practice that helps with the actual failure", + "Guidance needs separate runtime controls where enforcement matters" ] }, { @@ -87,7 +87,7 @@ "id": "runtime", "title": "Runtime + routing", "subtitle": "Preloop · OpenRouter", - "body": "Preloop adds a durable policy/audit plane on tool use — and a Cloud PR reviewer that posts a `preloop` commit status. OpenRouter routes models for the cockpit and that reviewer. Both serve the harness; neither is the harness.", + "body": "Preloop adds a durable policy/audit plane on tool use — and a Cloud PR reviewer that posts a `preloop` commit status. Model routing depends on host configuration: native/default access for the host, or a deliberately configured gateway for selected external workflows and reviews. Both serve the harness; neither is the harness.", "tips": [ "Keep keys in a vault", "Document methods, not enrollment secrets", diff --git a/content/starters.json b/content/starters.json index 5e91525..6ad9ebe 100644 --- a/content/starters.json +++ b/content/starters.json @@ -1,6 +1,6 @@ { "schema": "durable-agent-harness/starters/v1", - "intro": "Copy these into your own versioned config. They’re deliberately generic — rename them and put your proof classes in.", + "intro": "Merge examples into your existing project guidance. Skills describe procedures; the rule starter uses Cursor metadata. Neither installs runtime enforcement.", "templates": [ { "id": "skill", @@ -10,9 +10,9 @@ }, { "id": "rule", - "title": "Rule template", + "title": "Cursor rule template", "filename": "rule.template.md", - "blurb": "Fail-closed constraint. Prefer requestable; always-on only for true P0s." + "blurb": "Save as .cursor/rules/.mdc in Cursor. alwaysApply controls requested loading, not enforcement. Codex users: use concise AGENTS.md guidance and native permissions." }, { "id": "pattern", diff --git a/content/stats.json b/content/stats.json index c1d9dcb..42e1ca0 100644 --- a/content/stats.json +++ b/content/stats.json @@ -1,7 +1,7 @@ { "schema": "durable-agent-harness/stats/v1", "as_of": "2026-09-05", - "disclaimer": "Aggregates only — proxies for harness size, not quality.", + "disclaimer": "Snapshot as of 5 September 2026. These historical counts have not been recounted; they describe size, not quality.", "metrics": [ { "id": "skills", diff --git a/content/timeline.json b/content/timeline.json index fbd76e3..2a42433 100644 --- a/content/timeline.json +++ b/content/timeline.json @@ -143,7 +143,7 @@ "title": "One skill source for Cursor and Codex", "body": "Shipped a fail-closed shared-skill projector: reviewed manifest, symlink support, drift checks, secret-shaped-file rejection, and Harness Gauntlet coverage.", "link": { - "label": "Implementation PR #169", + "label": "Private implementation PR #169 (repository access required)", "href": "https://github.com/DynamicDevices/cursor-config/pull/169" } }, diff --git a/docs/agents.html b/docs/agents.html index 16e29f7..9c6114a 100644 --- a/docs/agents.html +++ b/docs/agents.html @@ -99,13 +99,13 @@

Take the pack

  • 2
    -

    Drop AGENTS.md and .agents/ into the project

    -

    Project-local. Start a new Codex task so guidance and skills load from the beginning.

    +

    Merge AGENTS.md and .agents/ into the project

    +

    Preserve existing instructions. For Cursor merge .cursor/rules/ and .cursor/skills/. Start a new task and check which guidance and skills it can read; loading is not enforcement.

  • 3
    -

    Rename the skill

    -

    Change example-domain-task triggers and proof to the human’s real weekly job.

    +

    Run one small task

    +

    Try a read-only diagnosis of one failing test. Ask for file references and a suggested check, then verify the answer against the source. Adapt the host’s example skill if this job recurs.

  • 4
    @@ -114,13 +114,13 @@

    Keep two fail-closed boundaries

  • 5
    -

    Sign off one pattern

    -

    One signed-off row with a real failure line in patterns/WORKING-PATTERNS.md.

    +

    Keep a pattern if it helps

    +

    Record an observed problem only if a reusable correction helps. A signed-off row records editorial agreement; it is not permission for future actions.

  • 6
    -

    Freeze a clock + run one task

    -

    Set harness.start to today. Run the skill with its proof checklist — not a plan alone.

    +

    Finish with evidence

    +

    Report the checked result and anything unresolved. Dates are optional: both packs have harness.start; only Codex has codex.start. No routine reflection note is required.

    • diff --git a/docs/app.js b/docs/app.js index c834d72..9305680 100644 --- a/docs/app.js +++ b/docs/app.js @@ -415,6 +415,7 @@ function renderCapabilities(data) { el("span", { className: "pill now", text: scale[row.now] || row.now }), el("span", {}, [ row.note, + row.evidence ? el("a", { className: "text-link", href: row.evidence.url, text: row.evidence.label }) : null, row.band ? el("div", { className: "band", text: row.band }) : null, ]), ]), @@ -615,7 +616,7 @@ async function renderStarters(data) { for (const t of data.templates) { const body = await loadText(new URL(t.filename, STARTER_BASE)); - const pre = el("pre", { className: "starter-body" }, [body]); + const pre = el("pre", { className: "starter-body", tabindex: "0", role: "region", "aria-label": `${t.title} code sample` }, [body]); const btn = el("button", { type: "button", className: "copy-btn", text: "Copy" }); btn.addEventListener("click", async () => { try { @@ -746,3 +747,12 @@ main().catch((err) => { console.error(err); document.body.dataset.ready = "error"; }); + + document.querySelectorAll('.mobile-contents a').forEach((link) => { + link.addEventListener('click', () => { + const contents = link.closest('details'); + contents.open = false; + const target = link.hash && document.getElementById(link.hash.slice(1)); + if (target) { target.setAttribute('tabindex', '-1'); target.focus({ preventScroll: true }); } + }); +}); diff --git a/docs/content/capabilities.json b/docs/content/capabilities.json index 401d9f3..33ce891 100644 --- a/docs/content/capabilities.json +++ b/docs/content/capabilities.json @@ -1,6 +1,6 @@ { "schema": "durable-agent-harness/capabilities/v1", - "intro": "Productivity here is mostly scope: work that was uneconomic or impossible solo becomes routine — with proof and review still required.", + "intro": "These bands are Alex’s qualitative personal estimates of scope and effort, not benchmark results or measured productivity multipliers. The linked accounts show particular experiences and their limits; they do not validate every row. Where no public evidence is linked, support is not available here.", "scale": [ { "id": "solo-easy", @@ -57,14 +57,22 @@ "before": "impossible", "now": "solo-hard", "note": "Skills and signed patterns beat “we talked about this once”.", - "band": "Team knowledge base" + "band": "Team knowledge base", + "evidence": { + "url": "notes/the-token-bonfire.html", + "label": "Token Bonfire: failures and limits" + } }, { "outcome": "Move the working relationship between agent hosts", "before": "impossible", "now": "solo-hard", "note": "Portable Agent Skills moved; project guidance and permissions stayed host-native; a drift sensor guards the boundary.", - "band": "Platform engineering" + "band": "Platform engineering", + "evidence": { + "url": "notes/the-cockpit-changed-the-work-did-not.html", + "label": "Host migration account" + } }, { "outcome": "Parallel repository tasks with isolated state", diff --git a/docs/content/clocks.json b/docs/content/clocks.json index 73562ca..e07f149 100644 --- a/docs/content/clocks.json +++ b/docs/content/clocks.json @@ -1,7 +1,7 @@ { "schema": "durable-agent-harness/clocks/v1", "as_of": "2026-09-05", - "note": "Public tenure clocks for the engineering story. The start dates are intentional; they’re not a claim about the first time I ever touched an LLM.", + "note": "Snapshot calculated as of 5 September 2026, not today. Original start dates are preserved; these ages describe that date.", "clocks": [ { "id": "serious_ai", diff --git a/docs/content/glossary.json b/docs/content/glossary.json index b4e39c8..7a895b9 100644 --- a/docs/content/glossary.json +++ b/docs/content/glossary.json @@ -120,7 +120,7 @@ }, { "term": "Briar", - "def": "A WhatsApp personal-assistant channel for monitor/triage and tiered replies, with the same fail-closed outbound rules as the cockpit." + "def": "Alex’s agent setup: project guidance, skills, tools, memory and runtime controls used across hosts. Messaging is one surface; Briar is not a particular editor or model." }, { "term": "Token lean", diff --git a/docs/content/hour.json b/docs/content/hour.json index 0a1c236..6fa7069 100644 --- a/docs/content/hour.json +++ b/docs/content/hour.json @@ -1,8 +1,8 @@ { "schema": "durable-agent-harness/hour/v1", "title": "Start in 60 minutes", - "intro": "Don’t read the whole notebook. Get a thin working relationship into Codex in about an hour — or take the original Cursor pack if that is still your cockpit.", - "promise": "When you finish you have: two fail-closed boundaries, one on-demand skill, one signed pattern, and two tenure clocks. That’s enough to stop the next stupid burn.", + "intro": "Start with a small piece of work in a project you control. Use Codex or Cursor; the packs share the same boundaries but use different project paths.", + "promise": "Within the first 35 minutes, aim for one useful, checked result. The rest of the hour is for keeping only the guidance and records you need.", "pack": { "zip": "packs/codex-hour-starter.zip", "browse": "packs/codex-hour/README.md", @@ -23,78 +23,68 @@ { "id": "1", "minutes": 5, - "title": "Download the pack", - "why": "Empty templates invite dithering. This pack is already named and filled with boring defaults you can rename.", - "do": "Download the zip (or browse the files). Unzip next to a scratch project — or into a small git repo you control.", - "proof": "You can see README.md, AGENTS.md and a .agents/skills tree on disk." + "title": "Choose a small task and your host", + "why": "Use a project you control and a task whose result you can check.", + "do": "Download the Codex or Cursor pack. Start with a read-only job: explain one failing test, naming the file, likely cause and one way to check it.", + "proof": "A task with a clear finish, and the selected pack unpacked beside the project." }, { "id": "2", "minutes": 10, - "title": "Drop files where Codex loads them", - "why": "A harness that lives only in chat dies when the chat dies.", - "do": "Copy `AGENTS.md` and `.agents/` into your project root. Start a new Codex task so project guidance is read from the beginning and the skill is discovered.", - "proof": "Codex can name the project guidance and the example-domain-task skill." + "title": "Merge guidance and check the boundaries", + "why": "Keep the project’s existing instructions.", + "do": "Codex: merge AGENTS.md and .agents/ into the project root. Cursor: merge .cursor/rules/ and .cursor/skills/. Compare conflicts before changing existing files. Keep secrets out of chat; agree the exact scope before consequential actions. Start a new task and ask which guidance and skill paths it can read. Check host permissions separately.", + "proof": "You can distinguish the instructions it read from controls the host actually enforces." }, { "id": "3", - "minutes": 10, - "title": "Rename the skill to your real job", - "why": "Generic skills don’t fire. Trigger nouns must match how you talk.", - "do": "Edit skills/example-domain-task/SKILL.md: change the name, description triggers, When/Do steps, and Proof of done to one task you do weekly.", - "proof": "You can say the trigger phrase out loud and it matches the description." + "minutes": 20, + "title": "Do useful work", + "why": "A result tells you more than a completed setup checklist.", + "do": "Run the small task now. For example: “Read this failing test and its implementation. Explain the likely cause and suggest a focused check. Do not edit files.” Require file references and the limits of the diagnosis.", + "proof": "A useful answer checked against the source, with no unrequested edits." }, { "id": "4", "minutes": 10, - "title": "Keep two fail-closed boundaries", - "why": "Secrets in chat and silent consequential writes are the burns that don’t forgive. The host mechanism may change; the boundary must not.", - "do": "Read the two boundaries in AGENTS.md: secrets stay out of chat, and consequential writes need a visible human decision. Keep the file short. Use Codex sandboxing and permissions as separate host controls.", - "proof": "You can explain each boundary, its decision point, and what the host enforces separately." + "title": "Adapt a skill if the job will recur", + "why": "Keep a procedure only when it helps repeat the work.", + "do": "Codex: edit .agents/skills/example-domain-task/SKILL.md. Cursor: edit .cursor/skills/example-domain-task/SKILL.md. Rename it for your recurring job, with matching triggers and proof of done. Try that job with the skill.", + "proof": "The skill describes your job and its result can be checked. Skip it for a one-off task." }, { "id": "5", - "minutes": 10, - "title": "Sign off one pattern", - "why": "Unsigned patterns are just opinions. Sign-off is what makes Kaizen real.", - "do": "Open patterns/WORKING-PATTERNS.md. Keep a signed-off row that matches a real failure (the pack ships lean-tool-sessions and trash-instead-of-hard-delete as examples), or replace with one of yours. Write the problem in one line.", - "proof": "The table has at least one signed-off row that matches a real incident." + "minutes": 5, + "title": "Record a pattern only if there is a lesson", + "why": "An example row is not your own approval.", + "do": "Read patterns/WORKING-PATTERNS.md. Codex examples include one-writer-per-tree and one-bounded-diagnostic-pass; Cursor examples include lean-tool-sessions and trash-instead-of-hard-delete. Keep or adapt one only if it matches an observed problem. A signed-off row records editorial agreement, not permission to execute an action.", + "proof": "Any retained pattern names a real problem; otherwise leave it proposed." }, { "id": "6", "minutes": 5, - "title": "Freeze a tenure clock", - "why": "Without a start date, every demo invents a heroic timeline.", - "do": "Edit clocks.json: set harness.start to today and codex.start to the first day you used Codex on real project work.", - "proof": "Two dates you trust are on disk — not only in a slide." + "title": "Set dates if you want to track tenure", + "why": "Preserve history rather than making the setup look older.", + "do": "Both packs have clocks.json: set harness.start to today. The Codex pack also has codex.start: use the first day you used Codex on real project work, or leave it unset if unknown. Do not add a Codex date to the Cursor stub.", + "proof": "Any dates you keep are honest; clocks are optional records." }, { "id": "7", "minutes": 5, - "title": "Run one real task", - "why": "The harness is only real under load.", - "do": "Ask the agent to do the skill’s task. Require the proof checklist. If it skips a gate, stop and tighten the rule — don’t shrug.", - "proof": "You have a short note of what changed and how you verified it." - }, - { - "id": "8", - "minutes": 5, - "title": "Schedule a tiny Hansei", - "why": "Without reflection the pack becomes folklore in a week.", - "do": "Put a 15-minute calendar block in seven days: keep / amend / retire on the pattern and skill. Link this site’s Learning section if you want the longer loop.", - "proof": "The calendar (or ticket) exists. You are done for today." + "title": "Finish with the result", + "why": "Short tasks can finish in chat.", + "do": "Report what you found or changed, how you checked it and anything unresolved. If something failed, diagnose the mechanism before adding a rule: a smaller task, clearer instruction or runtime restriction may help. Review later only when requested or an observed problem warrants it.", + "proof": "One checked result. No routine reflection note or calendar appointment required." } ], "done": { "title": "Done when", "checks": [ - "Pack installed where Codex loads it", - "Skill renamed to your domain", - "Two fail-closed boundaries understood (secrets; consequential writes)", - "At least one signed-off pattern with a real problem line", - "Two frozen clock dates", - "One task run with proof — not a plan alone" + "Existing project instructions preserved and selected host paths checked", + "Secrets boundary understood; human decisions and host enforcement kept separate", + "One useful task completed with evidence and limits", + "Any skill, pattern or dates retained serve a real need" ] }, - "next": "When this feels boring (good), read the Codex migration note, Playbook or Learning sections. Skip what you don’t need." + "next": "Read the Playbook or Learning sections when a problem calls for them. The Token Bonfire describes what happened when improving the process became more work than the task." } diff --git a/docs/content/learning.json b/docs/content/learning.json index db19327..3b50e51 100644 --- a/docs/content/learning.json +++ b/docs/content/learning.json @@ -1,7 +1,7 @@ { "schema": "durable-agent-harness/learning/v1", "title": "Kaizen → Hansei → Toyota Way Practices", - "intro": "Tools alone aren’t the harness. We improve on purpose (Kaizen), reflect on what actually happened (Hansei), and keep a named practice cluster (Toyota Way Practices) so agents load the right lens for the live pain — not the whole philosophy every turn.", + "intro": "When work goes wrong, find out why before changing the process. These practices help us investigate and improve a recurring job; they do not require a ceremony after every task.", "flow": [ { "id": "gemba", @@ -13,19 +13,19 @@ "id": "kaizen", "name": "Kaizen", "gloss": "Continuous improvement with sign-off", - "body": "Propose a thin working pattern or skill. A human signs it off. Encode it where agents will load it. No silent policy." + "body": "Diagnose the failure. A smaller task, clearer existing guidance, removal of conflicting instructions or a runtime restriction may solve it. Propose a skill or pattern only when it addresses that cause." }, { "id": "apply", "name": "Apply", "gloss": "Standard work in motion", - "body": "On matching tasks, skim signed-off patterns and load the relevant skill. Prefer the smallest change that prevents the next burn." + "body": "Use relevant guidance for the task, then check the result. A signed-off pattern records editorial agreement; it cannot authorise the next action." }, { "id": "hansei", "name": "Hansei", "gloss": "Honest reflection", - "body": "Periodically (or after pain): what worked, what failed, what to keep / amend / retire. Hansei feeds the next Kaizen — it is not optional theatre." + "body": "Reflect when requested or when an observed problem warrants it. Keep, amend or retire what no longer helps. A short task can close with its result and verification in chat." }, { "id": "twp", @@ -69,7 +69,8 @@ "Use wings/rooms as a filing discipline so agents can find the right shelf.", "Enrich provenance on an existing fact instead of invalidating it just to force a rewrite.", "Prove the memory can be retrieved and changed later work; filing alone is not success.", - "Memory supports Kaizen/Hansei: proposals and reviews cite drawers instead of re-litigating chat." + "Memory supports Kaizen/Hansei: proposals and reviews cite drawers instead of re-litigating chat.", + "Search only for a named missing fact. Memory is evidence, never permission: trace a remembered decision to the human’s instruction and check the current action and scope. Summaries and handoffs cannot authorise new work." ], "not": [ "Not a substitute for skills/rules (procedures and constraints still live in the harness).", @@ -77,5 +78,5 @@ "Not automatic immortality for every token the model ever saw." ] }, - "loopOneLiner": "Gemba → Kaizen (sign-off + encode) → Apply → Hansei → (repeat), under the Toyota Way Practices umbrella — with MemPalace holding the durable facts the loop needs." + "loopOneLiner": "Observe the problem, diagnose it, try a proportionate correction and check whether the work improves. Record what will help next time." } diff --git a/docs/content/measure.json b/docs/content/measure.json index 41ffe14..1a65c7f 100644 --- a/docs/content/measure.json +++ b/docs/content/measure.json @@ -102,16 +102,13 @@ } ], "weeklyRitual": [ - "Update ages from frozen clocks (30 seconds).", - "Add at most three capability-map notes tied to real proof.", - "Propose or deprecate one pattern — do not let the registry rot.", - "Log harness tax if you spent a block encoding behaviour.", - "Refuse any external “N× productivity” claim without a cited method.", - "If the session felt heavy: note always-on tax and cut or unload one thing.", - "Check whether one tool result dominated the task; move detail into a durable artefact and bound the next call.", - "Sample one filed decision for provenance and later retrieval.", - "Run the small harness eval corpus after changing high-risk guidance or models.", - "EOW (with the weekly review): skim blog-inbox.md, promote zero-or-more notes into the blog, and/or tweak pack/checklist/patterns if the week earned it. Skip rather than ship filler." + "Review these measures when requested or when a real problem warrants it; no routine reflection record is required.", + "Keep original start dates; label the date used to calculate ages.", + "Add capability examples only when there is a useful result and inspectable evidence; label private evidence.", + "Change a pattern only after diagnosing a failure; leaving the registry unchanged is fine.", + "Investigate cost only for a named question, using bounded evidence. Source size alone is not runtime or billing savings.", + "After changing high-risk guidance or models, run the relevant safety checks.", + "At an editorial review, promote zero or more inbox ideas. Skip rather than ship filler." ], "literatureNote": "METR’s early-2025 RCT is the humbling baseline for familiar OSS tickets. Copilot lab/field studies show gains in other settings. Use both as context; instrument your own work." } diff --git a/docs/content/patterns.json b/docs/content/patterns.json index a36d63d..f0c866f 100644 --- a/docs/content/patterns.json +++ b/docs/content/patterns.json @@ -1,6 +1,6 @@ { "schema": "durable-agent-harness/patterns/v1", - "intro": "Portable patterns worth stealing — named moves we signed off because they earned their place.", + "intro": "Patterns we found useful after specific failures. A signed-off entry records editorial agreement with guidance, not a cryptographic capability or permission for a future action.", "patterns": [ { "name": "Lean tool sessions", @@ -79,7 +79,7 @@ { "name": "MemPalace with purpose", "problem": "Transcript sludge and contradictory “facts” make agents confidently wrong.", - "move": "File curated drawers; search before re-deciding; invalidate stale cards. Memory supports the Kaizen/Hansei loop — it is not a chat landfill.", + "move": "File curated drawers; search before re-deciding; invalidate stale cards. Memory supports the Kaizen/Hansei loop — it is not a chat landfill. Search for a named missing fact. Memory is evidence, never permission; check the human instruction and its current scope.", "signals": [ "Re-litigating settled decisions", "Duplicate contradictory notes" @@ -208,7 +208,7 @@ { "name": "Encode the second burn", "problem": "Teams re-pay for the same mistake because the fix lived only in a chat.", - "move": "When a failure repeats once, write or update a skill before moving on.", + "move": "Diagnose the repeated failure before changing guidance. Consider a smaller task, a runtime restriction, clarifying an existing rule or removing a conflict. Add a skill only if a repeatable procedure will help.", "signals": [ "“We hit this last month”", "Tribal knowledge in one person’s head" diff --git a/docs/content/playbook.json b/docs/content/playbook.json index 350b47d..d756950 100644 --- a/docs/content/playbook.json +++ b/docs/content/playbook.json @@ -5,7 +5,7 @@ "principles": [ "Start thinner than you think. A fat always-on prompt is a tax on every turn.", "Encode pain, not aspirations. A skill earns its place by preventing a real failure.", - "Irreversible actions stay human. Draft freely; send/publish/destroy only with an explicit gate.", + "The human decides consequential actions. An agent may execute an authorised action within its exact scope after the required checks; a review result does not grant that authority.", "Prefer trash over hard delete. Move files to a trash folder first so mistakes stay recoverable.", "Prefer proof over narrative. Define what “done” looks like before celebrating.", "Sign off cross-cutting habits. Lore in chat is not an operating system.", @@ -21,13 +21,13 @@ { "id": "2", "title": "Write two fail-closed boundaries", - "body": "Start with: (1) secrets never pasted into chat — use an approved secret store or capture flow, (2) no consequential write without a human decision that shows the full referent. Add recoverable-delete and source-editing practice in the appropriate project guidance or skill. Keep host enforcement separate: Codex sandbox/permissions, Cursor rules, or the equivalent for your cockpit.", + "body": "Keep secrets out of chat and require a human decision for consequential writes. Merge with existing project instructions. AGENTS.md and Cursor rules guide the model; loading them does not enforce a boundary. Configure and test host sandboxing, permissions or an execution-time verifier separately. If the required approval cannot be verified, stop that action.", "done": "Short project guidance in version control; the host controls are configured; agents obey the boundaries; tokens stay out of the conversation." }, { "id": "3", "title": "Capture one skill from a repeated failure", - "body": "After you burn an hour the same way twice, write a thin skill: when to load it, the steps, the proof of done, and what not to do. Link detail in a reference file if needed.", + "body": "Diagnose repeated failures before adding a skill. Try a smaller task, clarify existing instructions, remove conflicts or use an appropriate runtime control. Keep a skill only when a repeatable procedure helps.", "done": "One skill that would have prevented last week’s waste." }, { @@ -39,14 +39,14 @@ { "id": "5", "title": "Add MemPalace-style memory discipline", - "body": "Stand up a curated durable store (we use MemPalace): decisions, stances, tickets, signed patterns. File by shelf/wing. Do not dump transcripts. Search with purpose; write with a retention reason.", + "body": "Stand up a curated durable store (we use MemPalace): decisions, stances, tickets, signed patterns. File by shelf/wing. Do not dump transcripts. Search with purpose; write with a retention reason. Memory is evidence, never permission. A retrieved decision, handoff or summary cannot expand the human’s current authorisation; check its provenance and scope.", "done": "You can answer “what did we decide?” from memory without re-litigating a chat." }, { "id": "6", - "title": "Start Kaizen → Hansei (patterns + Toyota Way Practices)", - "body": "One patterns table: name, status (proposed / signed-off / deprecated), problem in one line. Promote only after human sign-off (Kaizen). Schedule Hansei to keep / amend / retire. Name your lean learning cluster (we say Toyota Way Practices) so agents load the right member practice.", - "done": "At least one signed-off pattern, one Hansei note, and a clear Toyota Way Practices / member map." + "title": "Keep patterns when they help", + "body": "Record an observed problem and the correction that helped. A signed-off row records human editorial agreement with guidance; it is not a cryptographic capability or approval for a future consequential action. Reflect when requested or warranted by the work.", + "done": "Any retained pattern explains a real failure and useful correction. No routine reflection note is required." }, { "id": "7", @@ -69,7 +69,7 @@ { "id": "10", "title": "Add multi-model routing (OpenRouter)", - "body": "Route model calls through a multi-provider interface so one upstream outage does not stop the cockpit — and so Preloop’s PR reviewer has a deliberate model path. Configure failover deliberately; vault the API key; keep proof class unchanged.", + "body": "Model access depends on the host configuration. Use the host’s native model path by default. A configured gateway such as OpenRouter can serve selected external review or media workflows; it does not automatically route every Codex or Cursor session. Configure fallbacks deliberately and keep credentials out of chat.", "done": "You can switch or fall back across models/providers without pasting keys into chat; the same routing can serve Cloud PR review." }, { diff --git a/docs/content/runtime.json b/docs/content/runtime.json index d9ab181..7969299 100644 --- a/docs/content/runtime.json +++ b/docs/content/runtime.json @@ -21,7 +21,7 @@ }, "openrouter": { "title": "OpenRouter", - "lede": "OpenRouter is a multi-model API router: one interface across providers, with provider failover and optional model fallbacks. It serves external model workflows and Preloop review flows when routing earns its keep; it is not how the Codex app reaches its models.", + "lede": "Model access depends on the host configuration. Codex and Cursor can use their native/default model access; a separately configured gateway can serve selected external workflows. OpenRouter provides multi-provider routing and fallbacks where deliberately configured, including some review workflows. It is not a universal path for the cockpit.", "docs": "https://openrouter.ai/docs", "verified": "2026-09-15", "preloopReviewRoute": { @@ -38,7 +38,7 @@ ], "not": [ "Not a replacement for skills/rules/memory — it is transport for model calls.", - "Not the model path for the Codex app.", + "Not proof that a host session uses this route; check that host’s configuration.", "Not “set and forget” for data-retention or ZDR choices; configure deliberately when it matters.", "Not a productivity multiplier claim by itself." ] @@ -49,7 +49,7 @@ "steps": [ { "title": "Push the PR commit", - "body": "Ordinary git push. No special local ritual — the check lives in Cloud + GitHub, not in a fat always-on prompt." + "body": "Before a push, confirm the human has authorised that repository, content and action and that required checks pass. Where action-bound verification is required, the executor must verify it at execution time. A review pass alone is not permission." }, { "title": "Preloop reviewer runs", @@ -65,7 +65,7 @@ } ], "practices": [ - "Treat the Preloop status as a review signal, not as merge authority — humans still merge.", + "The human owns the merge decision. An agent can execute a specifically authorised merge within scope after the required checks. A Preloop status supplies review evidence, not merge authority.", "Keep OpenRouter keys in Bitwarden Secrets Manager (or the vault Preloop Cloud uses); never in workflow YAML or chat.", "Prefer async review by default; make CI wait only when runner time is scarce or the failure mode is expensive.", "When the gate is on, fix or skip with an explicit, rare bypass — do not normalise “ignore Preloop”.", @@ -77,5 +77,6 @@ "Not the same thing as Preloop’s desktop MCP approvals in Cursor." ] }, - "together": "The durable harness — portable skills, explicit policy, memory, signed patterns, gates and proof — supports the working relationship. Codex owns its model path, sandbox and permissions; those host-native mechanisms are dependencies and adapters, not portable assets. Preloop can audit selected tool flows and review PR commits; OpenRouter routes external model capacity for those workflows. CI may wait on the review signal. Humans still own consequential actions and merges." + "together": "The durable harness — portable skills, explicit policy, memory, signed patterns, gates and proof — supports the working relationship. Codex owns its model path, sandbox and permissions; those host-native mechanisms are dependencies and adapters, not portable assets. Preloop can audit selected tool flows and review PR commits; OpenRouter routes external model capacity for those workflows. CI may wait on the review signal. Humans still own consequential actions and merges.", + "summary": "The harness supports the work through procedures, evidence and controls. Guidance files do not install enforcement. Host configuration determines model access and permissions; optional services cover only their configured flows. Human decisions remain necessary for consequential actions, even when an agent performs the authorised execution." } diff --git a/docs/content/stack.json b/docs/content/stack.json index a10aa4c..bc66e58 100644 --- a/docs/content/stack.json +++ b/docs/content/stack.json @@ -1,6 +1,6 @@ { "schema": "durable-agent-harness/stack/v1", - "intro": "The working relationship is the human experience. The harness is the versioned and tested mechanism that makes it repeatable: portable procedures, explicit policy, memory, tools, human gates and feedback. Codex and Cursor are cockpits; product-specific mechanisms are host adapters.", + "intro": "Briar is the name of my agent setup across editors, models and messaging surfaces. This notebook describes what we tried, where it failed and what helped us finish useful work. Skills and project instructions guide the agent; host permissions and runtime controls enforce only the boundaries they are configured to cover.", "layers": [ { "id": "cockpit", @@ -63,12 +63,12 @@ "id": "patterns", "title": "Patterns", "subtitle": "Kaizen → Hansei → Toyota Way Practices", - "body": "Cross-cutting ways of working: propose → human sign-off → encode → apply → periodic Hansei. The learning core is named Toyota Way Practices; patterns are the registry that makes Kaizen real.", + "body": "Keep guidance that addresses an observed problem. A human can agree a correction, then test it on real work. Review it when requested or when it stops helping; a signed-off entry is not action permission.", "tips": [ "No silent promotion to signed-off", - "Hansei keeps / amends / retires — on a cadence", - "Toyota Way Practices names the cluster; load the member practice for the live pain", - "Encode into skills/rules where agents will load them" + "Review when requested or warranted by a problem", + "Load the practice that helps with the actual failure", + "Guidance needs separate runtime controls where enforcement matters" ] }, { @@ -87,7 +87,7 @@ "id": "runtime", "title": "Runtime + routing", "subtitle": "Preloop · OpenRouter", - "body": "Preloop adds a durable policy/audit plane on tool use — and a Cloud PR reviewer that posts a `preloop` commit status. OpenRouter routes models for the cockpit and that reviewer. Both serve the harness; neither is the harness.", + "body": "Preloop adds a durable policy/audit plane on tool use — and a Cloud PR reviewer that posts a `preloop` commit status. Model routing depends on host configuration: native/default access for the host, or a deliberately configured gateway for selected external workflows and reviews. Both serve the harness; neither is the harness.", "tips": [ "Keep keys in a vault", "Document methods, not enrollment secrets", diff --git a/docs/content/starters.json b/docs/content/starters.json index 5e91525..6ad9ebe 100644 --- a/docs/content/starters.json +++ b/docs/content/starters.json @@ -1,6 +1,6 @@ { "schema": "durable-agent-harness/starters/v1", - "intro": "Copy these into your own versioned config. They’re deliberately generic — rename them and put your proof classes in.", + "intro": "Merge examples into your existing project guidance. Skills describe procedures; the rule starter uses Cursor metadata. Neither installs runtime enforcement.", "templates": [ { "id": "skill", @@ -10,9 +10,9 @@ }, { "id": "rule", - "title": "Rule template", + "title": "Cursor rule template", "filename": "rule.template.md", - "blurb": "Fail-closed constraint. Prefer requestable; always-on only for true P0s." + "blurb": "Save as .cursor/rules/.mdc in Cursor. alwaysApply controls requested loading, not enforcement. Codex users: use concise AGENTS.md guidance and native permissions." }, { "id": "pattern", diff --git a/docs/content/stats.json b/docs/content/stats.json index c1d9dcb..42e1ca0 100644 --- a/docs/content/stats.json +++ b/docs/content/stats.json @@ -1,7 +1,7 @@ { "schema": "durable-agent-harness/stats/v1", "as_of": "2026-09-05", - "disclaimer": "Aggregates only — proxies for harness size, not quality.", + "disclaimer": "Snapshot as of 5 September 2026. These historical counts have not been recounted; they describe size, not quality.", "metrics": [ { "id": "skills", diff --git a/docs/content/timeline.json b/docs/content/timeline.json index fbd76e3..2a42433 100644 --- a/docs/content/timeline.json +++ b/docs/content/timeline.json @@ -143,7 +143,7 @@ "title": "One skill source for Cursor and Codex", "body": "Shipped a fail-closed shared-skill projector: reviewed manifest, symlink support, drift checks, secret-shaped-file rejection, and Harness Gauntlet coverage.", "link": { - "label": "Implementation PR #169", + "label": "Private implementation PR #169 (repository access required)", "href": "https://github.com/DynamicDevices/cursor-config/pull/169" } }, diff --git a/docs/index.html b/docs/index.html index cfd09cb..fc977d4 100644 --- a/docs/index.html +++ b/docs/index.html @@ -175,6 +175,24 @@ Starters About +
    + Contents + +