docs: reconcile LESSONS.md and VISION.md with what the branch removed

- LESSONS.md's 2026-06-22 test-placement entry told authors to put test
  files directly in scripts/ with a README row. The file-structure contract
  the repo now enforces permits tests/ as one of four directories, requires
  a tests/README.md when it exists, and FAILs test files in scripts/.
- LESSONS.md's 2026-08-16 entry described a dispatch chain ending at
  skill-author/references/retrofit.md in the present tense. This branch
  deleted that file. Sibling entries whose referents the branch removed
  were marked historical; this one was not.
- VISION.md's Phase 1 now puts stack, framework and deployment choices out
  of scope for this repo, while Phase 3 still named React Native and Tauri.

README.md was checked and needed no change: its offline guarantee already
carries the populated-apm_modules condition from 8cfd54f and agrees with
gates.md and AGENTS.md.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NwD8Egs5r4ndqeFLmhusX2
This commit is contained in:
2026-09-20 18:38:21 +00:00
parent 9b6f2b1583
commit 4e22c4920a
2 changed files with 5 additions and 5 deletions

View File

@@ -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

View File

@@ -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.