docs: stop the preloaded instruction set asserting machine state
Why: four defects in the files every session pays for, all introduced or left behind by the trim. AGENTS.md told agents the `<plugin>:` form still resolves "because user-scope native installs were left enabled on purpose", and that a working namespaced call "is not something to fix". That premise is false on this machine: installed_plugins.json is empty, no enabledPlugins key exists in ~/.claude.json, and ~/.apm/marketplaces.json is empty. ADR-0018 already reversed itself once on this exact claim (Correction 2026-08-14) using that same enablement as its evidence, so flipping the assertion again would be the third revision in three. Both files now assert nothing about install state at all, which removes the flip-flop surface instead of re-aiming it. The other three are guard-rails whose instruction survived the trim while the caveat that made it safe did not: - The run-tests.sh line omitted --strict, so it named the one invocation that reports SKIPPED rather than failed when a dependency is missing. gates.md records this gate going green having verified 15 of 17 suites on a vale-less PATH. .pre-commit-config.yaml:70 already uses --strict for that reason. - The .claude/settings.json prohibition lost its ADR-0019 exception, so an agent applying it literally would strip apm's own merged SessionStart entry and create the drift the rule exists to prevent. - LESSONS.md still routed graduated rules to CONTEXT.md's Principles section, which this branch deleted. Implementation notes: the six terms the trim dropped while AGENTS.md still claimed CONTEXT.md glosses everything -- authoring root, content mirror, apm package, output profile, near-miss, vacuous green -- are restored as one-line entries per CONTEXT-FORMAT.md, sourced from architecture.md, gates.md and skill-audit's description-quality.md rather than reworded. ADR-0018 gets a third dated note recording the observation and the fact that the state has now been described two ways, and its stale user-scope inventory is replaced by a pointer to it; the decision it records is untouched. LESSONS.md:3 carried the identical stale claim as :5 and is fixed with it. Impact: preloaded context is now free of assertions about machine state. Refs: #105 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TmFqzpuExLJv3m114XVE9w
This commit is contained in:
@@ -1,8 +1,8 @@
|
||||
# Lessons
|
||||
|
||||
Patterns observed during development of this repo. Three or more entries on the same pattern → promote to CONTEXT.md (or the relevant instruction file) as a standing rule.
|
||||
Patterns observed during development of this repo. Three or more entries on the same pattern → promote to `docs/spec/architecture.md` (or the relevant instruction file) as a standing rule.
|
||||
|
||||
**Graduation rule:** When three or more entries cover the same pattern, the human reviews and promotes it to the appropriate standing location: `CONTEXT.md` for domain-level principles, `core/instructions/coding.md` for coding conventions, `core/instructions/testing.md` for testing conventions, or `core/instructions/subagent-orchestration.md` for delegation conventions. Those four are the whole set — `core/instructions/` holds `coding.md`, `governance.md`, `subagent-orchestration.md` and `testing.md`, and nothing else. Git conventions have no standing file of their own: promote them to `core/instructions/coding.md`, or create a new instruction file deliberately rather than assuming one exists. The graduated entries are marked `[graduated → target file]` rather than deleted (audit trail).
|
||||
**Graduation rule:** When three or more entries cover the same pattern, the human reviews and promotes it to the appropriate standing location: `docs/spec/architecture.md` for structural and domain-level principles — `CONTEXT.md` is not a destination, its `## Principles` section was deleted and what was there now sits under that file's "AGENTS.md pattern" and "Reference conventions" headings — `core/instructions/coding.md` for coding conventions, `core/instructions/testing.md` for testing conventions, or `core/instructions/subagent-orchestration.md` for delegation conventions. Those four are the whole set — `core/instructions/` holds `coding.md`, `governance.md`, `subagent-orchestration.md` and `testing.md`, and nothing else. Git conventions have no standing file of their own: promote them to `core/instructions/coding.md`, or create a new instruction file deliberately rather than assuming one exists. The graduated entries are marked `[graduated → target file]` rather than deleted (audit trail).
|
||||
|
||||
**Who writes here:** The session-handoff skill (Chunk 3) prompts LESSONS.md extraction before closing a session. The human may also write directly.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user