From 213de22f7414bfd6cfec76d261ac1879aef8bd54 Mon Sep 17 00:00:00 2001 From: anoopkansupada Date: Sun, 24 May 2026 00:07:31 -0400 Subject: [PATCH] docs(local-patches): triage doc for carried local commits (#1) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * feat(plan-eng-review): add Step 0.5 — existing-capability check before new substrate code When a plan touches a knowledge-graph or agent-runtime substrate (gbrain, OpenClaw, Hermes), run a 60-second check before designing new infrastructure: ssh 'gbrain integrations list && launchctl list | grep -i gbrain' Most recipe-driven substrates already ship a senses + reflexes system that IS the signal-detector / autopilot / ingest pattern. Configure or extend existing recipes (markdown files) instead of building parallel ops/ infrastructure. Why: 2026-05-17 in hash-lemma, /plan-eng-review accepted a plan to extract a JSONL queue lib + producer + consumer bin + LaunchAgent + OAuth-DCR migration to wire "signal-detector on every Slack message" — when gbrain's `integrations` system already shipped the pattern (11 senses + 1 reflex, recipe-based). The 60-second check would have flagged the wrong-buildout at scope-lock, saving ~3-5 days of misdirected code. Substrates with no equivalent capability surface (pure web apps, libraries, CLIs) skip the step. Co-Authored-By: Claude Opus 4.7 (1M context) * docs(local-patches): triage doc for carried local commits LOCAL_PATCHES.md - living audit of every patch on top of upstream/main. Current state: 1 commit ahead, 8 behind upstream. The single carried patch (aff14a72 plan-eng-review Step 0.5) is flagged for upstream PR. Codifies rules: default to extension points, PR within 7 days if touching upstream skills, /gstack-upgrade is canonical. Co-Authored-By: Claude Opus 4.7 (1M context) --------- Co-authored-by: Claude Opus 4.7 (1M context) --- LOCAL_PATCHES.md | 40 +++++++++++++++++++++++++++++++++++ plan-eng-review/SKILL.md | 17 ++++++++++++++- plan-eng-review/SKILL.md.tmpl | 17 ++++++++++++++- 3 files changed, 72 insertions(+), 2 deletions(-) create mode 100644 LOCAL_PATCHES.md diff --git a/LOCAL_PATCHES.md b/LOCAL_PATCHES.md new file mode 100644 index 000000000..7cd656817 --- /dev/null +++ b/LOCAL_PATCHES.md @@ -0,0 +1,40 @@ +# Local Patches — Triage & Upstream Plan + +Living document. Every patch carried on top of `upstream/main` belongs here, with +a triage decision: **PR upstream**, **keep local (extension point)**, or **delete**. + +Audit cadence: every upgrade (`/gstack-upgrade`). If a patch sits here for >30 days +without a PR filed or a justification, delete it or land it. + +Last audit: 2026-05-23 + +--- + +## Patches that touch core / shared skills + +### 1. `aff14a72` — `plan-eng-review`: Step 0.5 existing-capability check +- **Files:** `skills/plan-eng-review/SKILL.md` +- **What it does:** adds a 60-second pre-design check for plans touching gbrain / OpenClaw / Hermes substrates — surfaces existing integrations / launchd jobs before greenlighting new infra code. +- **Why it exists:** memory `feedback_probe_mini_integrations_first` — caught a 2,200-page redundant ingestion design 2026-05-20. +- **Triage: PR UPSTREAM.** Generalizes well — any operator with a substrate-style integration system benefits from a pre-build capability check. Likely fast review. +- **PR action:** open against `garrytan/gstack` titled `feat(plan-eng-review): Step 0.5 existing-capability check before substrate code`. +- **Owner:** Anoop +- **Status:** not yet filed + +--- + +## Patches in extension points (never conflict) + +None currently — gstack repo is clean in this regard. + +--- + +## Rules for future patches + +1. **Default to extension points.** Before touching `skills//SKILL.md`, ask: can this be a *new* skill (`skills/my-skill/`) or a `references/` addition? Modifying upstream skills generates rebase conflicts every gstack-upgrade. + +2. **If you must touch an upstream-skill SKILL.md, file the upstream PR within 7 days.** Carrying core-skill patches without upstreaming is interest-bearing debt. + +3. **Don't commit scratch.** Local debugging files belong outside the repo or in `/scratch/` (gitignored). + +4. **`/gstack-upgrade` is the canonical upgrade flow.** Don't hand-roll. If it breaks, fix the skill, not the workaround. diff --git a/plan-eng-review/SKILL.md b/plan-eng-review/SKILL.md index 5557a33fa..46c68b5e3 100644 --- a/plan-eng-review/SKILL.md +++ b/plan-eng-review/SKILL.md @@ -1006,7 +1006,22 @@ If the complexity check triggers (8+ files or 2+ new classes/services), STOP bef **STOP.** Do NOT proceed to Section 1 (Architecture review), edit the plan file with a proposed scope reduction, or call ExitPlanMode until the user responds. Naming the 80% solution in chat prose and continuing — or loading the AskUserQuestion schema via ToolSearch and then never invoking it — is the failure mode this gate exists to prevent. -If the complexity check does not trigger, present your Step 0 findings and proceed directly to Section 1. +If the complexity check does not trigger, present your Step 0 findings and proceed directly to Step 0.5. + +### Step 0.5: Existing-capability check (gbrain / autopilot / integration recipes) + +If the plan touches a knowledge-graph or agent-runtime substrate (gbrain, OpenClaw, Hermes, a similar recipe-driven system), run this 60-second check BEFORE designing new code under `ops//`: + +```bash +# gbrain example — substitute the substrate's equivalent CLI / launchd label +ssh 'gbrain integrations list && launchctl list | grep -i gbrain' +``` + +The recipe-driven substrates (gbrain especially) ship a senses + reflexes system that IS the signal-detector / autopilot / ingest pattern. Most "wire X into the flow" plans should be **configuring an existing recipe** (or writing a markdown recipe modeled on an existing one), NOT building new infrastructure. If a recipe exists `AVAILABLE` → configure it. If a recipe is `CONFIGURED` but dormant → investigate why. If no recipe exists → write a markdown recipe modeled on a sibling recipe (e.g. `imessage-to-brain`), submit upstream. Only propose new ops/ code if all three branches fail. + +This step exists because the failure mode is real: a 2026-05-17 hash-lemma plan proposed extracting a JSONL queue lib + producer + consumer bin + LaunchAgent + OAuth-DCR migration to wire "signal-detector on every Slack message" — when the gbrain `integrations` system already shipped the pattern. The 60-second check would have flagged the wrong-buildout at scope-lock. + +For substrates with no equivalent capability surface (pure web apps, libraries, CLIs), skip this step. Always work through the full interactive review: one section at a time (Architecture → Code Quality → Tests → Performance) with at most 8 top issues per section. diff --git a/plan-eng-review/SKILL.md.tmpl b/plan-eng-review/SKILL.md.tmpl index 1d5be0e6f..9196e755b 100644 --- a/plan-eng-review/SKILL.md.tmpl +++ b/plan-eng-review/SKILL.md.tmpl @@ -142,7 +142,22 @@ If the complexity check triggers (8+ files or 2+ new classes/services), STOP bef **STOP.** Do NOT proceed to Section 1 (Architecture review), edit the plan file with a proposed scope reduction, or call ExitPlanMode until the user responds. Naming the 80% solution in chat prose and continuing — or loading the AskUserQuestion schema via ToolSearch and then never invoking it — is the failure mode this gate exists to prevent. -If the complexity check does not trigger, present your Step 0 findings and proceed directly to Section 1. +If the complexity check does not trigger, present your Step 0 findings and proceed directly to Step 0.5. + +### Step 0.5: Existing-capability check (gbrain / autopilot / integration recipes) + +If the plan touches a knowledge-graph or agent-runtime substrate (gbrain, OpenClaw, Hermes, a similar recipe-driven system), run this 60-second check BEFORE designing new code under `ops//`: + +```bash +# gbrain example — substitute the substrate's equivalent CLI / launchd label +ssh 'gbrain integrations list && launchctl list | grep -i gbrain' +``` + +The recipe-driven substrates (gbrain especially) ship a senses + reflexes system that IS the signal-detector / autopilot / ingest pattern. Most "wire X into the flow" plans should be **configuring an existing recipe** (or writing a markdown recipe modeled on an existing one), NOT building new infrastructure. If a recipe exists `AVAILABLE` → configure it. If a recipe is `CONFIGURED` but dormant → investigate why. If no recipe exists → write a markdown recipe modeled on a sibling recipe (e.g. `imessage-to-brain`), submit upstream. Only propose new ops/ code if all three branches fail. + +This step exists because the failure mode is real: a 2026-05-17 hash-lemma plan proposed extracting a JSONL queue lib + producer + consumer bin + LaunchAgent + OAuth-DCR migration to wire "signal-detector on every Slack message" — when the gbrain `integrations` system already shipped the pattern. The 60-second check would have flagged the wrong-buildout at scope-lock. + +For substrates with no equivalent capability surface (pure web apps, libraries, CLIs), skip this step. Always work through the full interactive review: one section at a time (Architecture → Code Quality → Tests → Performance) with at most 8 top issues per section.