|
10 | 10 | # KNOWLEDGE (8sync managed — append-only) |
11 | 11 |
|
12 | 12 | ## Learnings (append-only — ghi DƯỚI đây; KHÔNG sửa block `8sync:harness` ở trên) |
13 | | -_(consolidated → agents/archive/KNOWLEDGE-1782879675.md · agents/archive/KNOWLEDGE-1782951662.md)_ |
14 | | -- **validated: anti-forget is a 4-layer stack that *declares + reminds* but |
15 | | - never *checks* — the missing 5th layer is a live per-turn reviewer.** Layers: |
16 | | - (1) `APPEND_SYSTEM.md` always-on rules (never compacts), (2) `8sync-recall.ts` |
17 | | - hook injecting skill-index + STATE at `agent-start`/`compacting`, (3) Mnemopi |
18 | | - `retain`/`recall` + `<memories>` per-turn inject ("remind"), (4) |
19 | | - `capabilities.md` exact tool catalog. None verify the turn just taken. omp's |
20 | | - `--advisor` (valueless boolean flag, confirmed in omp 16.2.x `--help`) is that |
21 | | - reviewer → now default-ON in `models.rs` `omp_flags()`/`resume_flags()`, |
22 | | - gated off for `TaskClass::Trivial`, opt-out `8sync ai --no-advisor` / |
23 | | - `advisor=false`. "remind" the user asked for = layer 3 (already wired), NOT a |
24 | | - distinct omp tool (`todo` is the closest built-in). |
25 | | -- **validated: rust-embed uses `compression` feature here** → embedded assets |
26 | | - (`models.toml`, `APPEND_SYSTEM.md`) are compressed blobs, so `strings binary` |
27 | | - will NOT find their text. Verify asset edits via the edit-tool output / source, |
28 | | - and verify *flag/struct* strings (`--advisor`, `no_advisor`) which live in the |
29 | | - code section and DO show up. |
30 | | -- **failure→fixed: `8sync skill update`'s git-collection loop treated "no |
31 | | - filter" as "install every sub-skill found in the repo", not "only refresh |
32 | | - what's already registered".** Registering ONE skill from a 20-skill |
33 | | - collection (`agents/skills.toml`'s `alpha-research` → feynman) silently |
34 | | - installed all 19 others too, and re-added them on every bulk |
35 | | - `8sync harness` run even after being deliberately removed from the |
36 | | - manifest (`contributing` kept reappearing). Root cause: `want(name)` is |
37 | | - `filter.is_none_or(|f| f == name)` — vacuously true whenever `filter` is |
38 | | - `None`, so `url_matches || want(sname)` was always true in the bulk path. |
39 | | - Fixed in `update.rs`'s git-source loop: a sub-skill installs only when the |
40 | | - URL/repo-segment was explicitly targeted, its own name was explicitly |
41 | | - filtered, OR (bulk run, filter=None) it already has a registry key. |
42 | | - Lesson: any "install-all-from-collection" loop MUST distinguish "user |
43 | | - explicitly asked for this whole collection" from "no filter given" — |
44 | | - they are NOT the same thing, and conflating them lets any single |
45 | | - registered skill from a collection silently expand into arbitrary, |
46 | | - unrequested skills on every idempotent re-run. |
47 | | -- **validated: 18 of feynman's 20 skills were installed as text with zero |
48 | | - chance of running** — 14 pointed to feynman's OWN slash-commands |
49 | | - (`prompts/*.md`, only registered inside feynman's own pi-coding-agent |
50 | | - runtime via `extensions/research-tools.ts`), which don't exist in omp. |
51 | | - Ported all 14 (+ 4 more with just cosmetic "Feynman" naming) to |
52 | | - self-contained `assets/skills/<name>/SKILL.md` using omp's real tool |
53 | | - names (`task` for feynman's `subagent`, `web_search`/`read` for |
54 | | - `fetch_content`, `ask` for `ask_user_question`). Lesson: NEVER trust a |
55 | | - skill's line count or presence in a registry as a proxy for it actually |
56 | | - working in the host runtime — a skill that only makes sense inside its |
57 | | - origin tool's own slash-command system is dead weight anywhere else. |
58 | | - Always open the actual prompt/extension source before assuming a ported |
59 | | - skill "just works". |
60 | | -- **validated: Phase C/D/E loop-eng v2 (full) shipped → v0.19.0.** (C) loop section + generated |
61 | | - block: `task` implementer↔independent verifier (verify-gate before commit, objective/boundaries/ |
62 | | - output per subagent, share-trace for dependent, parallel only independent); FAIL → `failure:` in |
63 | | - KNOWLEDGE seed prefix, read first at session start. (D) `memory.rs` `PLAYBOOKS_TEMPLATE` → |
64 | | - `agents/PLAYBOOKS.md` (Voyager procedural memory, index by `When:`); memory tiering KNOWLEDGE/ |
65 | | - PLAYBOOKS/DECISIONS; bench spine now 6 files. (E) L1→L3 + guardrails (no auto push/PR at L3); |
66 | | - `up.rs` per-tick job documented. Verified: PLAYBOOKS.md seeded on `harness up`, generated AGENTS.md |
67 | | - carries Loop-discipline invariant; final bench upfront ~7,095 tok, A2 saved 81% (abs 32,308 tok), |
68 | | - A1 PASS. Grounding: Anthropic orchestrator + Cognition share-trace + Voyager + Reflexion. |
69 | | -- **validated: `/gs` one-command team loop shipped → v0.20.0.** New omp slash command |
70 | | - `assets/commands/gs.md` (arg-routed: `<goal>` plan+run · bare resume · `auto` L3 · `status|next|stop`) |
71 | | - driving the A–E loop off `agents/STATE.md`; token-lean (codegraph/cbm/headroom mandatory) + |
72 | | - guardrails (verify-gate before commit, worktree + no push/PR at L3, hard-stop `.gs/STOP`). Modeled on |
73 | | - gsd-pi `/gsd auto`. `deploy::ensure_gs_command(home, root?)` writes `~/.omp/agent/commands/gs.md` |
74 | | - (global) + `<repo>/.omp/commands/gs.md` (team, committed); wired into harness auto/init/up. On-demand |
75 | | - `gs` skill (bundled #15) documents protocol. **Key facts:** omp discovers commands at |
76 | | - `~/.omp/agent/commands/*.md` + `<cwd>/.omp/commands/*.md` (`omp://slash-command-internals.md`), |
77 | | - native precedence 100, body is a prompt template with `$ARGUMENTS`. Verified: `/gs` deploys both |
78 | | - paths, valid frontmatter, gs skill on-demand (not in upfront); bench A1 PASS, upfront ~7,322 tok, |
79 | | - A2 saved 81%. failure: gstack tool-backed roles (qa/ship) still need gstack `bin/` + deps installed. |
80 | | -- **validated: `/gs` autonomy + hint + QA + reference submodules → v0.20.1.** (1) `/gs auto` wasn't |
81 | | - unattended because the agent kept calling `ask` — added an **Autonomy contract** (NEVER ask in |
82 | | - `auto`; research → assume → log under `## Assumptions` in STATE → proceed; "blocker" = only |
83 | | - credential/external-approval/destructive). omp default `tools.approvalMode: yolo` already auto-approves |
84 | | - tools, so the stalls were `ask`/clarifying, NOT the approval gate — a slash command can't bypass that |
85 | | - gate anyway. (2) Hint: omp shows per-arg hints only for BUILTINS; file commands surface only their |
86 | | - `description` — so front-loaded modes into description + added `argument-hint` frontmatter (YAML must |
87 | | - be quoted/clean: a value starting with `[` or containing `: ` breaks the parser). (3) QA/test made |
88 | | - first-class: per-slice verify-gate runs tests+QA, plus a mandatory **Closeout** (full suite + e2e QA + |
89 | | - independent re-review vs DoD + handoff summary) before reporting done. (4) Added `reference/gstack` + |
90 | | - `reference/gsd-pi` submodules. **failure: codegraph honors NO exclude — not `.gitignore` (even |
91 | | - `index -f`), no flag, no ignore-file; populating reference/ ballooned the index to ~3k files/110MB.** |
92 | | - Fix: commit submodule pointers but `git submodule deinit -f` the working trees (lean by default, |
93 | | - fetch on demand); cbm DOES respect `.gitignore` (it excludes `agents/skills`), so `reference/` is |
94 | | - gitignored as a cbm guard. Verified bare `8sync harness` = full auto-setup (MCP + skills + `/gs` + |
95 | | - memory + inject + index) in one command; bench A1 PASS, ~7.6k upfront, A2 80%. |
96 | | -- **validated: doc-hygiene + AI-engine health + loop correctness → v0.22.0.** (1) `harness/audit.rs` |
97 | | - `harness_audit` + `stale_summary`: hand-rolled path scanner (no regex crate) flags STALE repo-relative |
98 | | - doc paths, oversized docs (>400 lines / >120-line force-load block), 30d churn hotspots. **Heuristic |
99 | | - rules that matter:** trim only TRAILING sentence punctuation (leading `.`/`/` are meaningful); SKIP |
100 | | - absolute (`/home/…`), `~`-rooted/`<placeholder>`-derived `/…` fragments, URLs, and dotdir first-segs |
101 | | - (`github.com`, `.cargo`) — else the harness's own machine-generated CORE paths false-positive. Wired |
102 | | - into `doctor` (one-line summary) + `/gs` doc-hygiene. Verified: scratch repo flags only the planted |
103 | | - `src/gone.rs`; su-code 30→4 after the skip rules. (2) `doctor::check_ai_engines(home)` enforces the |
104 | | - token-optimization stack is installed AND registered in `~/.omp/agent/mcp.json`: codegraph 0.9.6 + |
105 | | - codebase-memory-mcp 0.8.1 + headroom 0.27.0 (all green here). (3) **failure: codegraph STEP 0 verbs |
106 | | - were wrong** — force-load/index/breadcrumb taught `codegraph search/deps/defs`, NONE exist; real CLI |
107 | | - (0.9.6) = `query/callers/callees/impact/context/files/affected/sync/status`. Fixed all 3 strings. |
108 | | - (4) **failure: a stale `~/.omp/skills/karpathy` dir beside canonical `karpathy-guidelines` (identical |
109 | | - frontmatter `name`) double-listed the skill** (CORE + a redundant on-demand). `build_force_load` now |
110 | | - dedups by frontmatter `name` after the rank-sort (keeps higher-ranked dir) — each logical skill once; |
111 | | - future-proof. Note: bundled `assets/skills/karpathy/` deploys to target `karpathy-guidelines` via the |
112 | | - explicit (asset,target) map in `deploy.rs`/`setup.rs` — dir name ≠ skill name is fine. (5) **failure: |
113 | | - bundled `impeccable` referenced `.agents/skills/impeccable/scripts/*.mjs` (leading dot) but 8sync |
| 13 | +_(consolidated 101 dòng cũ → agents/archive/KNOWLEDGE-1783170628.md)_ |
| 14 | +- **validated: "read images to save 90% tokens" is TRUE only with a dedicated optical |
| 15 | + encoder (DeepSeek-OCR arXiv 2510.18234: 10× @97%), NOT by sending a PNG to |
| 16 | + Opus/GLM.** Claude bills images per 28×28 patch = `⌈W/28⌉×⌈H/28⌉` (pay-per-pixel; |
| 17 | + Opus 4.7+ dropped the cheap ~1.15MP cap, ~3× pricier). MEASURED on this repo: |
| 18 | + STATE.md (7502 chars ≈ 1875 text tok) rendered 1200×1400 = 2150 vision tok = **0.87× |
| 19 | + (image LOSES for text)**; the 12388-edge codegraph as 1400×2200 image = 3950 vision tok |
| 20 | + vs ~99k text = **~25× (structure WINS)**. ⇒ gate: STRUCTURE (graph/diagram/dashboard/ |
| 21 | + PDF/UI) → image; code/exact-config/line-data → text. Wired into APPEND_SYSTEM + |
| 22 | + image-routing skill + capabilities.md + `--advisor` enforcement. Correct memory pattern |
| 23 | + = OCR-Memory (arXiv 2604.26622): image to LOCATE, exact text to READ (never OCR precise |
| 24 | + content back out of a picture). |
| 25 | +- **validated: `8sync shot` was a no-op STUB** (like `diff-img`); made real via headless |
| 26 | + Chromium — system first, else omp's bundled `~/.omp/puppeteer/chrome/<ver>/chrome-linux64/chrome` |
| 27 | + (verified: valid PNG in 0.44s). `--virtual-time-budget=<ms>` lets SPA content render before |
| 28 | + capture (confirmed: the Vite dashboard rendered fully). |
| 29 | +- **validated: dashboard deep-link fixed** — nav was in-memory (button, no URL), so |
| 30 | + headless shot always rendered State. Added `pageFromUrl()` + `history.replaceState` |
| 31 | + in `web/src/App.tsx`: `?page=<id>` (or `/<id>`) selects the initial page. `build.rs` |
| 32 | + already rebuilds the Vite FE when `web/src` changes (`web_src_newer`) → plain `cargo |
| 33 | + build` re-embeds; server SPA-fallback serves index.html for any path so the query |
| 34 | + works headless. VERIFIED: `8sync shot .../?page=codegraph` renders the real graph |
| 35 | + (4.8k nodes/12.4k edges, 12 Leiden clusters) — flagship "shot the memory graph" live. |
114 | 36 | mirrors to `agents/skills/`** — its setup scripts couldn't run; fixed 28 refs across SKILL.md + 4 |
115 | 37 | reference docs. Note: headroom's router PROTECTS code/recent content (`router:protected:recent_code`) |
116 | 38 | → won't compress small code samples (0 saved); it compresses genuine large logs. |
|
0 commit comments