diff --git a/LESSONS.md b/LESSONS.md index db12749..136131a 100644 --- a/LESSONS.md +++ b/LESSONS.md @@ -56,9 +56,9 @@ Skills sharing a resource (e.g. `validate.sh`) via a `shared/` directory and rel `skill-audit`'s (now `factory-audit`'s skill flow, per ADR-0025: `references/skill-description-quality.md` and `references/skill-body-discipline.md`) description and body-discipline rubrics were derived from `skill-write`'s own conventions — circular, so drift in one silently propagated to the other. Fix: extract condensed reference files directly from the upstream spec (agentskills.io) into the audit skill, so the rubric is independent of in-repo convention drift. -## 2026-06-22 — Test files in scripts/ are dev tooling; document them in README as non-spec +## 2026-06-22 — Test files in scripts/ are dev tooling; document them in README as non-spec (historical) -The agentskills.io spec defines `scripts/` for bundled executables, not test infrastructure — bats files placed there are invisible to spec-following auditors and cause README drift. Fix: place test files directly in `scripts/` (no subdirectory), and add a README row noting each as "dev tooling, not shipped." +Superseded — the fix below is now itself a FAIL. `factory-audit`'s `references/skill-file-structure.md:14` permits `tests/` as one of the four allowed directories, `:21-22` fails a test file found in `scripts/`, and `:58-60` requires a `tests/README.md` when `tests/` exists. Skill-root READMEs are gone too, so there is no table left to add a row to. What survives is the reason: test infrastructure is dev tooling, not shipped content, and has to be declared where an auditor reads — which is now `tests/README.md`. Kept for reference: the agentskills.io spec defines `scripts/` for bundled executables, not test infrastructure — bats files placed there are invisible to spec-following auditors and cause README drift. Fix: place test files directly in `scripts/` (no subdirectory), and add a README row noting each as "dev tooling, not shipped." ## 2026-06-27 — Clean-context audit catches what biased forks miss @@ -130,9 +130,9 @@ Widening a description-opener rule to also catch mid-sentence text looked like a `apm audit --ci` failed on `.claude/settings.json` with an empty `git diff` — `pretty-format-json --autofix` silently re-sorts JSON keys, and this generated file was missing from its exclude list, so every commit re-sorted apm's insertion-ordered output before apm compared against it. Separately, a defect introduced 3 hours earlier on the same branch was first mis-described as "pre-existing," an unverified claim about history. Fix: add tool-owned paths to every autofixing hook's exclude the moment ownership is declared, and verify "pre-existing" claims with `git log -S` or `git branch --contains` before writing them down. -## 2026-08-16 — A rule reversed inside a retrofit leaves no trace unless someone writes it down +## 2026-08-16 — A rule reversed inside a retrofit leaves no trace unless someone writes it down (historical) -A retrofit replaced "keep reference chains one level deep" with "two hops, never three" — the opposite rule, needed because the new dispatch pattern requires `SKILL.md` → `improve.md` → `retrofit.md`. The ADR never mentioned chain depth, so the reversal was carried entirely by the diff with no sign a contradicting rule ever existed. Fix: when a change inverts a standing rule, record the inversion where the rule's rationale lives, or it reads as forgotten rather than overturned. +The chain named below no longer exists — `plugins/kyberforge/.apm/skills/skill-author/references/retrofit.md` was deleted, so the dispatch ends at `improve.md`. The reversed rule itself survives, in `skill-author/references/create.md:150`. Kept for reference: a retrofit replaced "keep reference chains one level deep" with "two hops, never three" — the opposite rule, needed because the new dispatch pattern requires `SKILL.md` → `improve.md` → `retrofit.md`. The ADR never mentioned chain depth, so the reversal was carried entirely by the diff with no sign a contradicting rule ever existed. Fix: when a change inverts a standing rule, record the inversion where the rule's rationale lives, or it reads as forgotten rather than overturned. ## 2026-09-15 — A rare flake in a pipefail suite is a race until proven otherwise diff --git a/docs/VISION.md b/docs/VISION.md index 4025d2c..4adc120 100644 --- a/docs/VISION.md +++ b/docs/VISION.md @@ -60,4 +60,4 @@ Runtime orchestration: push config updates to machines, see running agents, mana ### Phase 3 — Native Apps -Mobile (React Native) and desktop (Tauri) wrappers over the Phase 1/2 web app. Deferred until the web app is mature. +Mobile and desktop wrappers over the Phase 1/2 web app. Deferred until the web app is mature; the wrapper technology is that product's own choice, on the same terms as the rest of its stack.