From 3c18035299613bac22f0227951c493f9ef13508f Mon Sep 17 00:00:00 2001 From: Paul Keen <125715+pftg@users.noreply.github.com> Date: Sat, 22 Aug 2026 13:22:26 +0200 Subject: [PATCH 1/2] AI-ops audit P0s + decisions: re-tier agents, live gates, one rule source Executes docs/70-79-ai-intelligence/70.12 P0 list + Paul's four decisions (2026-08-22): - Agents: core/coder, core/reviewer, ruby-reviewer, ruby-coder, content-creator -> model: opus (routing-rule compliance; root cause of the recurring reviewer Fable-quota deaths). - Gates: bin/validate-course added to publish.yml unit job (its only caller was an uninstalled pre-push hook); the config test that green-covered that dead hook is DELETED per the enforcement lens's dissent (fix by deletion). test.yml continue-on-error removed - the visual PR gate is BLOCKING again (22-day soak over, motivating defects fixed). - One rule source: docs/workflows/BASE_HANDBOOK.md deleted (3 rules drifted behind CLAUDE.md while 16 agents cited it); full reference sweep across CLAUDE.md, AGENTS.md, QWEN/GEMINI.md, docs/README, ai-config, ruby.md, agents.md, the OKF ownership concept, and all agent files - agents now cite CLAUDE.md + flow-router. - Docs-CI contradiction resolved in all three homes (no CI fires on docs-only PRs; none is waited for - Paul 2026-08-22). - okf-maintainer built as a real agent (the ENFORCED rule's executor); phantom "weekly maintain pass" claim removed from both rule copies. - mem0 dropped from the memory stack (fallback = memoria); plugin disabled machine-side alongside the MCP dedup (~100k schema tokens/session). - Ruflo retrieval wired into SessionStart (keyword CORRECTION recall, unredirected stdout) - the 30-day read measurement that decides the memory architecture. - OKF: ruflo-runtime concept updated + dated log entry ride this commit. Gates: rake test:unit 286 runs 0 failures; bin/validate-course all 8 pass; OKF validator 0 ERRORS; settings.json jq-valid. Co-Authored-By: Claude Fable 5 --- .claude/agents/build-monitor.md | 2 +- .claude/agents/content-creator.md | 4 +- .claude/agents/core/analyst.md | 2 +- .claude/agents/core/coder.md | 6 +-- .claude/agents/core/planner.md | 2 +- .claude/agents/core/researcher.md | 2 +- .claude/agents/core/reviewer.md | 4 +- .claude/agents/core/screenshot-guardian.md | 2 +- .claude/agents/core/tester.md | 2 +- .claude/agents/hugo-expert.md | 2 +- .claude/agents/okf-maintainer.md | 42 ++++++++++++++++ .claude/agents/ruby/ruby-coder.md | 4 +- .claude/agents/ruby/ruby-reviewer.md | 4 +- .claude/agents/seo-specialist.md | 2 +- .../agents/validation/qa-browser-tester.md | 2 +- .../ui-problem-diagnosis-specialist.md | 2 +- .../agents/validation/ux-browser-validator.md | 2 +- .claude/settings.json | 5 ++ .github/workflows/publish.yml | 8 +++ .github/workflows/test.yml | 11 ++-- .okf/log.md | 18 +++++++ .okf/workflows/company-layer-ownership.md | 2 +- .okf/workflows/ruflo-runtime.md | 13 +++++ AGENTS.md | 6 +-- CLAUDE.md | 6 +-- GEMINI.md | 2 +- QWEN.md | 2 +- docs/README.md | 4 +- docs/workflows/BASE_HANDBOOK.md | 50 ------------------- docs/workflows/agents.md | 2 +- docs/workflows/ai-config.md | 2 +- docs/workflows/autonomous-delivery-prompt.md | 3 +- docs/workflows/ruby.md | 2 +- test/unit/bin_scripts_test.rb | 19 +++---- 34 files changed, 136 insertions(+), 105 deletions(-) create mode 100644 .claude/agents/okf-maintainer.md delete mode 100644 docs/workflows/BASE_HANDBOOK.md diff --git a/.claude/agents/build-monitor.md b/.claude/agents/build-monitor.md index 508bb15fb..988217772 100644 --- a/.claude/agents/build-monitor.md +++ b/.claude/agents/build-monitor.md @@ -12,4 +12,4 @@ Use skills (minimal subset): - `best-practices` Rules: -- Follow `docs/workflows/BASE_HANDBOOK.md` +- Follow `CLAUDE.md` (repo root — the canonical rules) and `docs/workflows/flow-router.md` diff --git a/.claude/agents/content-creator.md b/.claude/agents/content-creator.md index e98112c65..e9be55b92 100644 --- a/.claude/agents/content-creator.md +++ b/.claude/agents/content-creator.md @@ -1,7 +1,7 @@ --- name: content-creator description: Creates or edits site/course content under the JT voice guide, canon, and anti-AI-pattern gates. Voice-sensitive judgment work. -model: fable +model: opus --- # Content Creator (Canonical) @@ -15,6 +15,6 @@ Use skills (minimal subset): - `copywriting-core` Rules: -- Follow `docs/workflows/BASE_HANDBOOK.md` +- Follow `CLAUDE.md` (repo root — the canonical rules) and `docs/workflows/flow-router.md` - For full blog workflow, see `docs/workflows/blog-pipeline.md` - For cover images, follow `docs/workflows/cover-images.md` and `.stitch/design.md` diff --git a/.claude/agents/core/analyst.md b/.claude/agents/core/analyst.md index 166155362..ac81e2911 100644 --- a/.claude/agents/core/analyst.md +++ b/.claude/agents/core/analyst.md @@ -13,4 +13,4 @@ Use skills (minimal subset): - `six-thinking-hats` Rules: -- Follow `docs/workflows/BASE_HANDBOOK.md` +- Follow `CLAUDE.md` (repo root — the canonical rules) and `docs/workflows/flow-router.md` diff --git a/.claude/agents/core/coder.md b/.claude/agents/core/coder.md index 13e8b50b6..85a051247 100644 --- a/.claude/agents/core/coder.md +++ b/.claude/agents/core/coder.md @@ -1,7 +1,7 @@ --- name: core-coder -description: Implements changes with minimal context - thin wrapper over the incremental-implementation skill set and BASE_HANDBOOK rules. -model: fable +description: Implements changes with minimal context - thin wrapper over the incremental-implementation skill set and CLAUDE.md rules. +model: opus --- # Core Coder (Critical) @@ -13,7 +13,7 @@ Use skills (minimal subset): - `best-practices` Rules: -- Follow `docs/workflows/BASE_HANDBOOK.md` +- Follow `CLAUDE.md` (repo root — the canonical rules) and `docs/workflows/flow-router.md` - If a task is domain-specific (SEO/Hugo/content), defer to the canonical agent or skill ## Methodology stance (XP / lean) diff --git a/.claude/agents/core/planner.md b/.claude/agents/core/planner.md index 8e00e1406..4349bc064 100644 --- a/.claude/agents/core/planner.md +++ b/.claude/agents/core/planner.md @@ -13,7 +13,7 @@ Use skills (minimal subset): - `incremental-implementation` Rules: -- Follow `docs/workflows/BASE_HANDBOOK.md` +- Follow `CLAUDE.md` (repo root — the canonical rules) and `docs/workflows/flow-router.md` ## Methodology stance (Shape Up / lean) diff --git a/.claude/agents/core/researcher.md b/.claude/agents/core/researcher.md index 49e553730..f4196d5be 100644 --- a/.claude/agents/core/researcher.md +++ b/.claude/agents/core/researcher.md @@ -13,7 +13,7 @@ Use skills (minimal subset): - `knowledge-synthesis` Rules: -- Follow `docs/workflows/BASE_HANDBOOK.md` +- Follow `CLAUDE.md` (repo root — the canonical rules) and `docs/workflows/flow-router.md` - Obey the Research Protocol for claude-context searches ## Methodology stance (lean) diff --git a/.claude/agents/core/reviewer.md b/.claude/agents/core/reviewer.md index 343a653a3..d175c4e25 100644 --- a/.claude/agents/core/reviewer.md +++ b/.claude/agents/core/reviewer.md @@ -1,7 +1,7 @@ --- name: core-reviewer description: Reviews changes for correctness and risk across the repo - the general 4-eyes gate. Judgment role, findings with file:line evidence. -model: fable +model: opus --- # Core Reviewer (Critical) @@ -13,7 +13,7 @@ Use skills (minimal subset): - `code-review-quality` Rules: -- Follow `docs/workflows/BASE_HANDBOOK.md` +- Follow `CLAUDE.md` (repo root — the canonical rules) and `docs/workflows/flow-router.md` ## Methodology stance (XP / lean) diff --git a/.claude/agents/core/screenshot-guardian.md b/.claude/agents/core/screenshot-guardian.md index 95c9a333a..ab8cc5476 100644 --- a/.claude/agents/core/screenshot-guardian.md +++ b/.claude/agents/core/screenshot-guardian.md @@ -13,4 +13,4 @@ Use skills (minimal subset): - `pagespeed-insights` Rules: -- Follow `docs/workflows/BASE_HANDBOOK.md` +- Follow `CLAUDE.md` (repo root — the canonical rules) and `docs/workflows/flow-router.md` diff --git a/.claude/agents/core/tester.md b/.claude/agents/core/tester.md index ae891d220..721ab6209 100644 --- a/.claude/agents/core/tester.md +++ b/.claude/agents/core/tester.md @@ -14,7 +14,7 @@ Use skills (minimal subset): - `tdd-fix-tests` Rules: -- Follow `docs/workflows/BASE_HANDBOOK.md` +- Follow `CLAUDE.md` (repo root — the canonical rules) and `docs/workflows/flow-router.md` ## Methodology stance (XP) diff --git a/.claude/agents/hugo-expert.md b/.claude/agents/hugo-expert.md index 2e4388f05..efe489ab0 100644 --- a/.claude/agents/hugo-expert.md +++ b/.claude/agents/hugo-expert.md @@ -14,5 +14,5 @@ Use skills (minimal subset): - `postcss-best-practices` Rules: -- Follow `docs/workflows/BASE_HANDBOOK.md` +- Follow `CLAUDE.md` (repo root — the canonical rules) and `docs/workflows/flow-router.md` - For CSS rules see `docs/workflows/css-consolidation.md` diff --git a/.claude/agents/okf-maintainer.md b/.claude/agents/okf-maintainer.md new file mode 100644 index 000000000..0b2dbb621 --- /dev/null +++ b/.claude/agents/okf-maintainer.md @@ -0,0 +1,42 @@ +--- +name: okf-maintainer +description: Maintains the .okf/ knowledge bundle - distills a durable learning into its concept file + section index + a dated log.md entry, riding the SAME commit/branch as the change that produced it. Dispatch in parallel with the main work per the ENFORCED CLAUDE.md OKF rule. Also upserts the concept's okf-* mirror entry in ruflo memory (namespace okf) per the sync rule. +model: opus +--- + +# OKF Maintainer + +You maintain `.okf/` — the Open Knowledge Format bundle. You are dispatched +with (a) the durable learning (root cause, gotcha, decision, canon change) and +(b) the branch/commit it must ride with. + +- Follow `CLAUDE.md` (repo root — the canonical rules) and `docs/workflows/flow-router.md` +- Consume the bundle via the `okf:okf` skill; never hand-edit the bundle FORMAT + from memory — the skill carries the spec. + +## The job, every time + +1. **Consolidate before creating**: find the existing concept the learning + belongs to (`.okf/*/index.md` first). A new concept file is the exception + and needs a matching index row. +2. Update the concept + its section `index.md` row if the description changed. +3. Append a dated `## YYYY-MM-DD - ` entry to `.okf/log.md` + (newest first) — what changed, why, and the pointer. +4. **Ruflo mirror (sync rule)**: if a concept's title/description changed, + upsert its memory entry: + `npx @claude-flow/cli@latest memory store -n okf -k okf-- -v ": Details: "` + (prefixes: okf-build- / okf-content- / okf-wf- / okf-design- / okf-arch- / okf-cs-). +5. Validate: run the `okf:validate` skill's checker with `--strict`; the gate + is **0 ERRORS** (warnings are a known-red state — check the error count, + not the exit code or the checkmark). +6. Commit on the SAME branch as the main work (or hand the staged files back + to the coordinator if it owns the commit) — the bundle update rides the + same commit as the change. Never a separate cleanup PR. + +## Boundaries + +- You edit `.okf/` and the ruflo okf namespace only. Never the change under + documentation, never CLAUDE.md, never STATUS.md — flag mismatches back to + the coordinator instead. +- One learning per dispatch; if you find a second stale thing while working, + report it, don't fix it silently. diff --git a/.claude/agents/ruby/ruby-coder.md b/.claude/agents/ruby/ruby-coder.md index 34a1d3c29..47e9db24e 100644 --- a/.claude/agents/ruby/ruby-coder.md +++ b/.claude/agents/ruby/ruby-coder.md @@ -1,7 +1,7 @@ --- name: ruby-coder description: Ruby/test-suite changes with minimal context - Minitest, Rake tasks, bin/ scripts. Follows 37signals/DHH style and the repo's TDD gates. -model: sonnet +model: opus --- # Ruby Coder (Critical) @@ -14,4 +14,4 @@ Use skills (minimal subset): - `minitest` Rules: -- Follow `docs/workflows/BASE_HANDBOOK.md` +- Follow `CLAUDE.md` (repo root — the canonical rules) and `docs/workflows/flow-router.md` diff --git a/.claude/agents/ruby/ruby-reviewer.md b/.claude/agents/ruby/ruby-reviewer.md index 93b5098ef..b4f523677 100644 --- a/.claude/agents/ruby/ruby-reviewer.md +++ b/.claude/agents/ruby/ruby-reviewer.md @@ -1,7 +1,7 @@ --- name: ruby-reviewer description: Reviews Ruby/test-suite changes for correctness, risk, and repo-convention fit. The 4-eyes gate for Ruby work - judgment role, evidence-cited findings. -model: fable +model: opus --- # Ruby Reviewer (Critical) @@ -13,4 +13,4 @@ Use skills (minimal subset): - `rails-expert` Rules: -- Follow `docs/workflows/BASE_HANDBOOK.md` +- Follow `CLAUDE.md` (repo root — the canonical rules) and `docs/workflows/flow-router.md` diff --git a/.claude/agents/seo-specialist.md b/.claude/agents/seo-specialist.md index 2f0c03f8b..adaf95a27 100644 --- a/.claude/agents/seo-specialist.md +++ b/.claude/agents/seo-specialist.md @@ -15,5 +15,5 @@ Use skills (minimal subset): - `pagespeed-insights` Rules: -- Follow `docs/workflows/BASE_HANDBOOK.md` +- Follow `CLAUDE.md` (repo root — the canonical rules) and `docs/workflows/flow-router.md` - If the task is not SEO-related, defer to the appropriate skill or agent diff --git a/.claude/agents/validation/qa-browser-tester.md b/.claude/agents/validation/qa-browser-tester.md index b768055b8..1baf59050 100644 --- a/.claude/agents/validation/qa-browser-tester.md +++ b/.claude/agents/validation/qa-browser-tester.md @@ -13,4 +13,4 @@ Use skills (minimal subset): - `web-design-reviewer` Rules: -- Follow `docs/workflows/BASE_HANDBOOK.md` +- Follow `CLAUDE.md` (repo root — the canonical rules) and `docs/workflows/flow-router.md` diff --git a/.claude/agents/validation/ui-problem-diagnosis-specialist.md b/.claude/agents/validation/ui-problem-diagnosis-specialist.md index 0c0e06796..748aba492 100644 --- a/.claude/agents/validation/ui-problem-diagnosis-specialist.md +++ b/.claude/agents/validation/ui-problem-diagnosis-specialist.md @@ -13,4 +13,4 @@ Use skills (minimal subset): - `ux-principles` Rules: -- Follow `docs/workflows/BASE_HANDBOOK.md` +- Follow `CLAUDE.md` (repo root — the canonical rules) and `docs/workflows/flow-router.md` diff --git a/.claude/agents/validation/ux-browser-validator.md b/.claude/agents/validation/ux-browser-validator.md index 126192a45..e9cf8be8f 100644 --- a/.claude/agents/validation/ux-browser-validator.md +++ b/.claude/agents/validation/ux-browser-validator.md @@ -13,4 +13,4 @@ Use skills (minimal subset): - `ux-principles` Rules: -- Follow `docs/workflows/BASE_HANDBOOK.md` +- Follow `CLAUDE.md` (repo root — the canonical rules) and `docs/workflows/flow-router.md` diff --git a/.claude/settings.json b/.claude/settings.json index 1119c3db7..58558aca3 100644 --- a/.claude/settings.json +++ b/.claude/settings.json @@ -8,6 +8,11 @@ "type": "command", "command": "bin/agent-bootstrap > /tmp/agent-bootstrap.log 2>&1 || true", "timeout": 600 + }, + { + "type": "command", + "command": "npx @claude-flow/cli@latest memory search -q CORRECTION --type keyword --limit 5 2>/dev/null || true", + "timeout": 45 } ] } diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 3cd567eb5..805bbffc0 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -89,6 +89,14 @@ jobs: PRECOMPILED_ASSETS: '1' HUGO_DEFAULT_PATH: _dest/public-test + # Course content validators (chapter numbering, links, em-dash, + # year-stamp...). Previously only wired to an uninstalled pre-push hook — + # a green config test stood in front of a gate that never ran + # (docs/70-79-ai-intelligence/70.12, P0). CI is where it cannot be + # uninstalled. + - name: Course validators + run: bin/validate-course + # Asset-pipeline integration: dev vs prod branching in css-processor, # css-inline, and js-processor (fingerprint/integrity/minify/crossorigin). # Previously ran only inside `rake test` on push-to-master, so a PR could diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 5800d9fdb..ed0302b20 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -9,8 +9,8 @@ name: Screenshot Tests # PR #386) - and record mode would silently overwrite the canonical # baselines with unpinned renders. # -# PR runs are REPORT-ONLY during the soak period (continue-on-error) - -# flip that flag off to make the gate blocking. +# PR runs are BLOCKING (2026-08-22): the report-only soak that started +# 2026-07-31 ended after its motivating defects were fixed. on: workflow_dispatch: @@ -67,9 +67,10 @@ jobs: if: ${{ github.event_name == 'pull_request' || inputs.screenshots || inputs.update-baselines }} runs-on: ubuntu-latest timeout-minutes: 20 - # Report-only soak for the PR gate: failures upload the diff report and - # comment on the PR but do not block merging. Remove after the soak. - continue-on-error: ${{ github.event_name == 'pull_request' }} + # BLOCKING since 2026-08-22: the report-only soak (2026-07-31, #413) ended — + # its motivating defects were fixed (#560 tolerance, #566 baselines, #570 + # per-page pins) and 22 days report-only meant nothing blocking checked + # Linux pixels (dtest-from-worktree is vacuous). steps: # PR events use the default checkout (the PR *merge* commit): testing diff --git a/.okf/log.md b/.okf/log.md index 13f2331b0..16c141b2b 100644 --- a/.okf/log.md +++ b/.okf/log.md @@ -111,6 +111,24 @@ Also corrected: the ~1e-6 noise figure in test-gates and in the code comment was macOS-local and read as universal. Same overclaim shape the #566 reviewer caught one layer down. +## 2026-08-22 - audit P0s executed: re-tiered agents, live gates, one rule source + +All 70.12 P0s landed the same day. Five agents re-tiered off fable/sonnet to +opus (core coder+reviewer, ruby pair, content-creator) - the reviewer +quota-death root cause. bin/validate-course now runs in CI's unit job and the +config test that green-covered its uninstalled pre-push hook is DELETED (the +enforcement lens's own dissent: fix by deletion, not elaboration). The CI +visual gate's 22-day report-only soak ended - continue-on-error removed. +BASE_HANDBOOK.md deleted with a full reference sweep; CLAUDE.md is the one +rule source and all 20 agents now cite it. okf-maintainer exists as a real +agent (the ENFORCED rule's phantom executor, built); the phantom "weekly +maintain pass" claim removed from both rule copies. Docs-CI three-way +contradiction resolved (no CI fires on docs-only; none is waited for). mem0 +dropped (plugin off, fallback = memoria); machine config deduped (~100k +schema tokens/session: ruflo-core plugin MCP, chrome-devtools x2, github, +serena, context7 x2, notebooklm). Ruflo retrieval wired into SessionStart +for the 30-day read measurement. Full audit: docs/70-79-ai-intelligence/70.12. + ## 2026-08-22 - six-lens AI-ops audit: the failure mode is silent no-ops, not missing rules A /swarm panel (six read-only lenses, mandatory dissents) audited the AI diff --git a/.okf/workflows/company-layer-ownership.md b/.okf/workflows/company-layer-ownership.md index 4035e0e6c..a29939238 100644 --- a/.okf/workflows/company-layer-ownership.md +++ b/.okf/workflows/company-layer-ownership.md @@ -58,7 +58,7 @@ the OKF same-commit wording is the pattern that has held). # Where the routers point -Aligned 2026-08-17: `AGENTS.md`, `docs/workflows/BASE_HANDBOOK.md`, +Aligned 2026-08-17: `AGENTS.md`, `docs/workflows/flow-router.md` (split into two routes), `CLAUDE.md`, `docs/projects/2607-vibe-code-rescue/strategy.md`, and `.agents/skills/async-first-communication/SKILL.md`. If a new doc tells an diff --git a/.okf/workflows/ruflo-runtime.md b/.okf/workflows/ruflo-runtime.md index 4ca0d5584..28c1ceb1f 100644 --- a/.okf/workflows/ruflo-runtime.md +++ b/.okf/workflows/ruflo-runtime.md @@ -55,6 +55,19 @@ per concept from its frontmatter title/description, exactly as above. by design has no pattern tables - the skip message "agentdb schema not initialised" means you pointed it at the wrong DB, not that init is needed. - 12 background workers exist (`hooks worker list`); the daemon runs them. +- **Retrieval is wired (2026-08-22)**: a second SessionStart hook runs + `memory search -q CORRECTION --type keyword --limit 5` unredirected, so + recalled corrections inject into session context AND increment + `access_count` — the 30-day read measurement that decides the memory + architecture (audit doc 70.12). Do not remove it before the measurement. +- **ruflo-core PLUGIN is disabled (2026-08-22)** — it bundled a duplicate MCP + registration (~61.5k schema tokens/session); the project-level `ruflo` + entry in `~/.claude.json` is the ONE registration (CLAUDE.md hardcodes its + `mcp__ruflo__*` prefix). Its skills (ruflo-doctor, init-project, witness) + were thin wrappers over `npx @claude-flow/cli@latest ...` — call the CLI + directly (doctor / init upgrade / etc.). Other ruflo-* plugins stay enabled. +- **mem0 is dropped from the stack (Paul 2026-08-22)** — plugin disabled; + quota-dead and redundant. Fallback chain is ruflo → memoria. # CLI bugs observed 2026-08-22 (ruflo v3.38.16) - do not re-fight these diff --git a/AGENTS.md b/AGENTS.md index 9382f4b64..95b735393 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,15 +1,15 @@ # AGENTS.md — JetThoughts Blog Canonical instructions live in `CLAUDE.md`. Read that first. -Session start: always read `@docs/workflows/BASE_HANDBOOK.md` and `@docs/workflows/flow-router.md`. +Session start: always read `@docs/workflows/flow-router.md` (rules live in `CLAUDE.md`). **Async-first communication (SOP for ALL agents):** written, discoverable artifacts are the default for every decision, finding, status change, and handoff — sync interaction is the exception and its outcome gets written back same-day. Full rules + canonical surfaces table: `.agents/skills/async-first-communication/SKILL.md`. A task is not done until its state is readable asynchronously. **Cold-start surface: `STATUS.md` at repo root** (goals + WIP + blockers, links only) — a session that changed what's in flight updates it in the same commit/PR, or the session is not done. -**Four eyes on every stage, author != verifier (SOP for ALL agents):** the point is agents collaborating to find the TRUTH — a single agent cannot find its own blind spot, because it checks the thing it MEANT to build. Every change is **written by one sub-agent and verified by a different one**; the author never produces the evidence for its own claim. The review lands before the artifact leaves the workshop: a plan is peer-reviewed BEFORE the user is asked, a diff BEFORE commit, a finding is reproduced before it is reported, a measurement re-derived before it is quoted. Brief reviewers with the goal and the artifact, never your conclusions; ask for measurements, not verdicts. Routing: internal sub-agents for every per-stage review, `/codex:review` ONCE at the final verify before merge for USER-FACING changes (it is slow — never in the inner loop); docs-only and instruction-layer changes ship on internal review + CI and apply its findings as a follow-up. No reviewer tooling in this runtime? Fall back agent → external → peer session → human, and mark the change UNREVIEWED if none is reachable. Full protocol: the `jt-delivery:contract` skill (plugin `jt-delivery@jetthoughts`); repo bindings: `docs/workflows/autonomous-delivery-prompt.md`. +**Four eyes on every stage, author != verifier (SOP for ALL agents):** the point is agents collaborating to find the TRUTH — a single agent cannot find its own blind spot, because it checks the thing it MEANT to build. Every change is **written by one sub-agent and verified by a different one**; the author never produces the evidence for its own claim. The review lands before the artifact leaves the workshop: a plan is peer-reviewed BEFORE the user is asked, a diff BEFORE commit, a finding is reproduced before it is reported, a measurement re-derived before it is quoted. Brief reviewers with the goal and the artifact, never your conclusions; ask for measurements, not verdicts. Routing: internal sub-agents for every per-stage review, `/codex:review` ONCE at the final verify before merge for USER-FACING changes (it is slow — never in the inner loop); docs-only and instruction-layer changes ship on internal review + local gates — no CI fires on them (path filters) and none is waited for (Paul 2026-08-22); findings apply as a follow-up. No reviewer tooling in this runtime? Fall back agent → external → peer session → human, and mark the change UNREVIEWED if none is reachable. Full protocol: the `jt-delivery:contract` skill (plugin `jt-delivery@jetthoughts`); repo bindings: `docs/workflows/autonomous-delivery-prompt.md`. **Session memory (ruflo-first, SOP for ALL agents):** search ruflo memory (`mcp__ruflo__memory_search`, MCP path) before non-obvious decisions; store decisions/corrections via `mcp__ruflo__memory_store` as they land. Details + prefix conventions: `CLAUDE.md` §Memory. -**OKF maintenance (ENFORCED, parallel by default):** durable learnings (canon numbers, root causes, workflow gotchas) go into `.okf/` — dispatch an okf-maintainer in parallel with the main work, not after it; the bundle update rides the same commit as the change. Weekly scheduled maintain pass back-fills misses. See CLAUDE.md OKF section for the full rule. +**OKF maintenance (ENFORCED, parallel by default):** durable learnings (canon numbers, root causes, workflow gotchas) go into `.okf/` — dispatch the `okf-maintainer` agent in parallel with the main work, not after it; the bundle update rides the same commit as the change. No scheduled back-fill exists; the same-commit rule is the only mechanism. See CLAUDE.md OKF section for the full rule. - `.agents/skills/async-first-communication/SKILL.md` — async-first knowledge sharing SOP (default for ALL work) diff --git a/CLAUDE.md b/CLAUDE.md index 581634432..8a430286c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -40,15 +40,15 @@ Operational knowledge lives in `.okf/` (`build/`, `content/`, `design/`, `workflows/` — one concept per file). Consume via progressive disclosure: `/okf:okf` (consume) at session start; never hand-read or hand-edit the bundle format — the skills carry the spec. Validate with `/okf:validate .okf --strict` before committing bundle changes. -**Maintain as you work (ENFORCED)**: a durable learning updates its concept + section index + a dated `.okf/log.md` entry, riding the SAME commit as the change — dispatch a background okf-maintainer in parallel, or inline for tiny fixes; a weekly maintain pass back-fills misses. A session that shipped durable knowledge without an OKF entry is not done. **Ruflo mirror**: a concept title/description change also upserts its `okf-
-` entry in ruflo memory namespace `okf` (backfilled 2026-08-22, one entry per concept; runtime map: `.okf/workflows/ruflo-runtime.md`). +**Maintain as you work (ENFORCED)**: a durable learning updates its concept + section index + a dated `.okf/log.md` entry, riding the SAME commit as the change — dispatch the `okf-maintainer` agent (`.claude/agents/okf-maintainer.md`, built 2026-08-22) in parallel, or inline for tiny fixes. No scheduled back-fill exists — the same-commit rule is the only mechanism, which is why it is ENFORCED. A session that shipped durable knowledge without an OKF entry is not done. **Ruflo mirror**: a concept title/description change also upserts its `okf-
-` entry in ruflo memory namespace `okf` (backfilled 2026-08-22, one entry per concept; runtime map: `.okf/workflows/ruflo-runtime.md`). --- ## 🔍 Research Protocol -**Session start**: read `@docs/workflows/BASE_HANDBOOK.md` + `@docs/workflows/flow-router.md`, run `/okf:okf` consume. Prefer skills over agents unless the workflow requires them. +**Session start**: read `@docs/workflows/flow-router.md`, run `/okf:okf` consume. Prefer skills over agents unless the workflow requires them. (BASE_HANDBOOK.md deleted 2026-08-22 — it had drifted three rules behind this file while 16 agents cited it as their source; THIS file is the single rule source.) -**Memory — search before deciding, store as you learn (ruflo-first, Paul 2026-08-21)**: at session start and before any non-obvious decision, `mcp__ruflo__memory_search` with a semantic query from the task's actual words — a past 🔧 CORRECTION outranks fresh reasoning. Store cross-session decisions/corrections/state the moment they land via `mcp__ruflo__memory_store` (one fact per entry; 🎯 GOAL / 📋 PLAN / 🔄 RETRO / 💡 LESSON / 🔧 CORRECTION / ⚠️ ANTIPATTERN prefixes; corrections upsert the existing key — never a second copy). This is IN ADDITION to the ENFORCED OKF rule above — `.okf/` owns repo-canonical knowledge, ruflo memory owns what a future session must recall before deciding. Terminal gotcha: CLI `memory search --type semantic` returns empty (needs @ruvector/core) and hybrid degrades to its keyword leg — use `--type keyword` in terminals; real semantic search works only via the MCP tools. Fallback when ruflo is down: memoria / mem0. +**Memory — search before deciding, store as you learn (ruflo-first, Paul 2026-08-21)**: at session start and before any non-obvious decision, `mcp__ruflo__memory_search` with a semantic query from the task's actual words — a past 🔧 CORRECTION outranks fresh reasoning. Store cross-session decisions/corrections/state the moment they land via `mcp__ruflo__memory_store` (one fact per entry; 🎯 GOAL / 📋 PLAN / 🔄 RETRO / 💡 LESSON / 🔧 CORRECTION / ⚠️ ANTIPATTERN prefixes; corrections upsert the existing key — never a second copy). This is IN ADDITION to the ENFORCED OKF rule above — `.okf/` owns repo-canonical knowledge, ruflo memory owns what a future session must recall before deciding. Terminal gotcha: CLI `memory search --type semantic` returns empty (needs @ruvector/core) and hybrid degrades to its keyword leg — use `--type keyword` in terminals; real semantic search works only via the MCP tools. Fallback when ruflo is down: memoria (mem0 dropped 2026-08-22 — quota-dead and redundant; its plugin is disabled). **Markdown search (docs/, content/, .okf/) — `qmd` FIRST** (Paul 2026-08-01; collection `jt-site`; `qmd embed` after big doc batches): known terms → `qmd search "..." -c jt-site -n 5`; conceptual → `qmd query` with lex/vec/hyde fields; then `qmd get`/`multi-get` — never answer from snippets. **Code** (templates/CSS/Ruby): claude-context MCP (`Search the codebase at for: "[pattern]"`, root via `git rev-parse --show-toplevel`) or grepai/tokensave; DeepWiki `ask_question` on `jetthoughts/jetthoughts.github.io` for repo-level questions; `rg`/`ls` after, for exact names. `knowledge/` is a host-only symlink — never depend on it in container/CI sessions. diff --git a/GEMINI.md b/GEMINI.md index 6c32986a2..4b0684a38 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -1,7 +1,7 @@ # GEMINI.md — JetThoughts Blog Canonical instructions live in `CLAUDE.md`. Read that first. -Session start: always read `@docs/workflows/BASE_HANDBOOK.md` and `@docs/workflows/flow-router.md`. +Session start: always read `@docs/workflows/flow-router.md` (rules live in `CLAUDE.md`). **ICP (MANDATORY for content/design/marketing):** Read `docs/90-99-content-strategy/strategy-analysis/90.10-icp-primary-website-target.md` before any content or design work. Target: non-technical founder burned by a devshop. diff --git a/QWEN.md b/QWEN.md index cfe2f7a3b..0e73ce211 100644 --- a/QWEN.md +++ b/QWEN.md @@ -2,7 +2,7 @@ Canonical instructions live in `CLAUDE.md`. Read that first. -Session start: always read `@docs/workflows/BASE_HANDBOOK.md` and `@docs/workflows/flow-router.md`. +Session start: always read `@docs/workflows/flow-router.md` (rules live in `CLAUDE.md`). **ICP (MANDATORY for content/design/marketing):** Read `docs/90-99-content-strategy/strategy-analysis/90.10-icp-primary-website-target.md` before any content or design work. Target: non-technical founder burned by a devshop. diff --git a/docs/README.md b/docs/README.md index e4dddc974..ca589ba10 100644 --- a/docs/README.md +++ b/docs/README.md @@ -8,7 +8,7 @@ | `adr/` · `incidents/` · `design-system/` | Decisions · postmortems · design tokens | | `business/` | Company OS, vision, opportunity portfolio — the company layer ([`business/index.md`](business/index.md)) | | `projects//` | One folder per initiative (own JD sub-tree; superseded material under its `70-79-archives/`) | -| `workflows/` | ONLY cross-cutting pipeline how-tos (blog/linkedin pipelines, flow-router, BASE_HANDBOOK) — not a catch-all | +| `workflows/` | ONLY cross-cutting pipeline how-tos (blog/linkedin pipelines, flow-router) — not a catch-all | New docs go into the matching area with `NN.NN-name-{reference|tutorial|how-to}.md` naming — never loose at `docs/` root. @@ -37,7 +37,7 @@ Hugo static site (`bin/hugo-build`) · PostCSS pipeline · vanilla JS (minimal) ## 🚀 Fresh-session entry points -- **Any task**: `docs/workflows/BASE_HANDBOOK.md` + `docs/workflows/flow-router.md` +- **Any task**: `CLAUDE.md` + `docs/workflows/flow-router.md` - **Outbound/sales/pipeline**: vault `~/Documents/pkm/jt-vcr-runbook.md` ▶ START HERE (moved 2026-08-20; campaign artifacts stay in `docs/projects/2607-vibe-code-rescue/`) - **Company numbers**: vault `~/Documents/pkm/jt-operations.md` §1 (host-only) - **Content**: `docs/projects/2510-seo-content-strategy/20-29-strategy/20.09-content-plan-revision-aug-2026.md` (check its P0 gate first) diff --git a/docs/workflows/BASE_HANDBOOK.md b/docs/workflows/BASE_HANDBOOK.md deleted file mode 100644 index e57ff4daf..000000000 --- a/docs/workflows/BASE_HANDBOOK.md +++ /dev/null @@ -1,50 +0,0 @@ -# Base Handbook (Shared Rules) - -Use this as the shared boilerplate for agents and skills. Keep agent/skill files thin and reference this. - -## Non-Negotiables -- Zero generic AI language -- Zero unsupported claims (cite sources) -- Zero Hugo build breaks (`bin/hugo-build` required for content changes) -- No custom test scripts (use `bin/rake test:critical`) -- Avoid Python scripts for analysis; prefer `rg`, `sed`, `awk`, and shell tools -- No duplicate throwaway files (`*_refactored.*`, `*_new.*`, `*_backup.*`) -- New docs are allowed only under `docs/workflows/` (else edit existing files) -- If user says “code is bad” or “over-engineered”: HALT, perform 5-Why analysis, fix config, then proceed - -## Research Protocol (Mandatory) -1. `Search the codebase at for: "[pattern]"` (use the current checkout root — `git rev-parse --show-toplevel`; do not hardcode a machine-specific path) -2. `Search the codebase at /knowledge for: "[topic]"` -3. `Get library docs for "[framework]"` - -## Current WIP + goals (repo state) -**Read `STATUS.md` at the repo root at session start** — the cross-project cold-start surface (goals, WIP, blocked-on-Paul, links only). Any session that changes what's in flight updates it in the same commit/PR. - -## Business layer (company state) -**All operations live in the vault** (`~/Documents/pkm`, host-only; Paul 2026-08-20): goal/OKR/rocks/weekly numbers in `jt-operations.md`, identity/positioning/bet status in `jt-business-os.md`, the bet's execution entry point in `jt-vcr-runbook.md` **▶ START HERE**. This repo carries growth/marketing campaigns only; `docs/business/` holds pointer stubs. - -Use claude-context MCP semantic search first for code and content patterns. Use `rg`/`ls` for exact filenames, slugs, and fallback searches after semantic search. - -## Flow Router (Mandatory) -Always follow `@docs/workflows/flow-router.md` to route tasks to the correct workflow. - -## Content Work (Mandatory) -If the task involves creating or editing LinkedIn content, read `@docs/workflows/linkedin-post-pipeline.md` first. -If the task involves creating or editing blog content, read `@docs/workflows/blog-pipeline.md`. -If a cover image is required, also read `@docs/workflows/cover-images.md` and `@.stitch/design.md`. - -## Code Support (Mandatory) -For code changes, follow the router and relevant flow: -- `@docs/workflows/flow-router.md` -- `@docs/workflows/css-consolidation.md` for HTML/CSS -- `@docs/workflows/ruby.md` for Ruby/Rails - -## Testing -- TDD: RED → GREEN → REFACTOR (see `/knowledge/20.01-*`, `/knowledge/20.11-*`) -- Test quality: behavior-focused only (see `/knowledge/25.04-*`) -- Minitest only; never create ad hoc `*.sh` test scripts -- Run `bin/rake test:critical` after every micro-change (<10 lines) - -## Visual Validation (CSS/HTML/JS changes) -- Tolerance: 0.0 for refactors, ≤0.03 for new features -- Use Chrome DevTools to verify console/network are clean (zero errors, zero 404s) diff --git a/docs/workflows/agents.md b/docs/workflows/agents.md index a59f2ebd5..1e1572d12 100644 --- a/docs/workflows/agents.md +++ b/docs/workflows/agents.md @@ -1,6 +1,6 @@ # Agent Strategy -Goal: replace most agents with skills, keep a minimal critical set of agents. All agents should be thin wrappers pointing to skills and `docs/workflows/BASE_HANDBOOK.md`. +Goal: replace most agents with skills, keep a minimal critical set of agents. All agents should be thin wrappers pointing to skills and `CLAUDE.md`. ## Critical Agents (keep) - `core/coder` diff --git a/docs/workflows/ai-config.md b/docs/workflows/ai-config.md index af5957b52..9b24c8ed3 100644 --- a/docs/workflows/ai-config.md +++ b/docs/workflows/ai-config.md @@ -2,7 +2,7 @@ Use this flow for agents, skills, and CLI configuration. -1. Read `@docs/workflows/BASE_HANDBOOK.md` +1. Read `CLAUDE.md` (repo root) 2. Prefer skills over agents; keep agents thin 3. Sync skills with `bin/skillshare-sync` when changing skills or targets 4. Keep instruction files compact and refer to workflows via `@` pointers diff --git a/docs/workflows/autonomous-delivery-prompt.md b/docs/workflows/autonomous-delivery-prompt.md index d51a69022..95abc4069 100644 --- a/docs/workflows/autonomous-delivery-prompt.md +++ b/docs/workflows/autonomous-delivery-prompt.md @@ -51,7 +51,8 @@ without the `dtest` leg. Internal sub-agents (distinct lens per call) for every per-stage review; **`/codex:review` ONCE at the final verify before merge, for user-facing changes only** — never in the inner loop. Docs/instruction-layer changes ship -on internal review + CI. +on internal review + local gates; no CI fires on them (path filters — see the +gate table above) and none is waited for (Paul 2026-08-22). ### Where everything else is diff --git a/docs/workflows/ruby.md b/docs/workflows/ruby.md index d2ac4a0bd..1430ad862 100644 --- a/docs/workflows/ruby.md +++ b/docs/workflows/ruby.md @@ -2,7 +2,7 @@ Use this flow for any Ruby/Rails changes. -1. Read `@docs/workflows/BASE_HANDBOOK.md` +1. Read `CLAUDE.md` (repo root) 2. Use skills: `37signals-rails`, `rails-expert`, `minitest` 3. Run `bin/rake test:critical` after every micro-change 4. For HTML/CSS changes triggered by Rails views, also read `@docs/workflows/css-consolidation.md` diff --git a/test/unit/bin_scripts_test.rb b/test/unit/bin_scripts_test.rb index 243b312eb..278958a77 100644 --- a/test/unit/bin_scripts_test.rb +++ b/test/unit/bin_scripts_test.rb @@ -58,19 +58,12 @@ def test_no_bare_production_hugo_builds_outside_hugo_build "bin/ scripts invoking bare `hugo --environment production` - route through bin/hugo-build (or bin/build-if-stale)" end - # `ruby file1.rb file2.rb` executes ONLY file1 (file2 becomes ARGV) - - # this silently disabled these very guards in the pre-push hook once. - # The hook must run them through the rake entrypoint, and must not fall - # back to the multi-file ruby pattern. - def test_pre_push_hook_runs_guards_via_rake_entrypoint - hook = File.expand_path("../../.githooks/pre-push", __dir__) - assert File.file?(hook), ".githooks/pre-push missing - the .gitignore `.*` rule swallowed it once" - body = File.read(hook, encoding: "bom|utf-8") - assert_match(%r{bin/rake test:guards}, body, - "pre-push must run the guard tests via `bin/rake test:guards`") - refute_match(/ruby\s+(?:-\S+\s+)*\S+_test\.rb\s+\S+_test\.rb/, body, - "pre-push passes multiple test files to one ruby invocation - only the first runs") - end + # (Deleted 2026-08-22: test_pre_push_hook_runs_guards_via_rake_entrypoint. + # It asserted the pre-push hook's TEXT while the hook was not installed + # anywhere - core.hooksPath unset, .git/hooks empty - a green config test + # covering a gate that never ran. What it pretended to guarantee now runs + # in CI: bin/validate-course is a publish.yml unit-job step, and the guard + # tests run via rake test:unit there regardless of hook installation.) # bin/test must honor a caller-provided HUGO_DEFAULT_PATH (bin/dtest points # the container at _dest/public-dtest) - a hardcoded DEST silently tests From c4928f5cede28d0732e133ee71f45a7d01d91e7d Mon Sep 17 00:00:00 2001 From: Paul Keen <125715+pftg@users.noreply.github.com> Date: Sat, 22 Aug 2026 13:31:12 +0200 Subject: [PATCH 2/2] ruflo-runtime: memory_import_claude workaround found - corpus IS mirrored The path-encoding bug has a working workaround (pass a pre-dashed projectPath); the 48-file auto-memory corpus imported with embeddings into namespace claude-memories, semantic recall verified (0.72-0.76 similarity on a stale-tracker query). Supersedes the "deliberately NOT mirrored" note. Co-Authored-By: Claude Fable 5 --- .okf/workflows/ruflo-runtime.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/.okf/workflows/ruflo-runtime.md b/.okf/workflows/ruflo-runtime.md index 28c1ceb1f..5b18281c8 100644 --- a/.okf/workflows/ruflo-runtime.md +++ b/.okf/workflows/ruflo-runtime.md @@ -77,10 +77,13 @@ or still present. - `config init` generates a config the loader rejects ("reading 'map'" warning on every call). Run on defaults; delete any generated config. -- `memory export` fails ("Exported to undefined"); `memory_import_claude` - finds 0 files even with `allProjects: true` (path-encoding). The auto-memory - corpus is deliberately NOT mirrored into ruflo - `MEMORY.md` already loads - every session. +- `memory export` fails ("Exported to undefined"). `memory_import_claude` + has a path-encoding bug (replaces only slashes, but Claude's memory dir + name also dashes the dots) — WORKAROUND: pass a pre-dashed projectPath, + e.g. `/Users/pftg/dev/jetthoughts-github-io`, and it imports. The + auto-memory corpus (48 files) IS mirrored via that workaround since + 2026-08-22, namespace `claude-memories`, semantic recall verified — + re-import after big memory-file batches (idempotent, dedups). - CLI `memory search --type semantic` returns empty in terminals (needs @ruvector/core); single-term `--type keyword` works; real semantic search is MCP-only. (Also in CLAUDE.md research protocol.)