@owlmeans/create-app 0.1.14 → 0.1.16-rc.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/create-app",
-  "version": "0.1.14",
+  "version": "0.1.16-rc.0",
   "license": "MIT",
   "description": "Scaffold a minimal fullstack OwlMeans Common app — common + api + web workspaces, shadcn UI navigation/layout, no auth, and a session-scoped in-memory resource. Deploys agent skills via @owlmeans/agent-skills by default.",
   "type": "module",
@@ -29,7 +29,7 @@
     "template"
   ],
   "dependencies": {
-    "@owlmeans/agent-skills": "^0.1.14"
+    "@owlmeans/agent-skills": "^0.1.16-rc.0"
   },
   "devDependencies": {
     "@owlmeans/dep-config": "workspace:*",

package/template/CLAUDE.md

@@ -47,7 +47,8 @@ Single shared agent memory store: `.agents/memory/` — a graph of subsystem nod
   scope matches the task.
 - Every write merges into the matching subsystem node and compacts — record reusable knowledge,
   never session events.
-- Procedure-shaped or repeatedly-touched memory must become a skill — `memory-promotion`.
+- Procedure-shaped or repeatedly-touched memory must be **distilled into** a skill as short
+  general rules — never pasted in as memory text (`memory-promotion`).
 - If the store degrades (event logs, oversized nodes, bloated index) — `memory-recompact`.
 - Never write memory to `.claude/memory/`, `.github/memory/`, `~/.claude/`, or anywhere outside
   this repository.
@@ -57,10 +58,11 @@ Single shared agent memory store: `.agents/memory/` — a graph of subsystem nod
 ## Self-Education (mandatory)
 
 Whenever development started from a plan agreed with the agent, the work is not complete until
-the `self-education` skill has been applied: update the project skills/instructions the change
-touched, record external-doc findings (URL + gist) in the governing skill, or add a
-skill/instruction for a new subsystem or technology. The completion report must include the
-self-education outcome — or state why none was needed.
+the `self-education` skill has been applied: rewrite the project skills/instructions the change
+touched so they state current rules (never a note about what changed), record external-doc
+findings (URL + gist) in the governing skill, or add a skill/instruction for a new subsystem or
+technology. The completion report must include the self-education outcome — or state why none
+was needed.
 
 ## What this is
 

package/template/_claude/skills/agent-memory/SKILL.md

@@ -136,3 +136,7 @@ each repo — fan every fix out to all copies; verify with `diff`. Correct re-ru
 Fact-shaped ("what is true") stays here. Procedure-shaped ("to do X, do Y") becomes a skill —
 follow `memory-promotion` where present, otherwise `skill-authoring`. Repeated use of a node to
 *perform* tasks, and over-cap nodes full of steps, are promotion triggers.
+
+Promotion is a **rewrite, never a move**: never paste node text into a skill. "Record the rule,
+not the story" and the size caps above bind skill bodies at least as tightly as they bind nodes
+(`memory-promotion` → Distillation).

package/template/_claude/skills/memory-promotion/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: memory-promotion
-description: Transform procedure-shaped or repeatedly-used memory into skills and instructions — the procedure-shape test, promote? repeated-touch flags, over-cap trigger, update-vs-create decision, and the post-promotion pointer state. Use when memory content reads as "how to", when a promote? flag is encountered again, or during recompaction.
+description: Transform procedure-shaped or repeatedly-used memory into skills and instructions — the procedure-shape test, the mandatory distillation rewrite, promote? repeated-touch flags, over-cap trigger, update-vs-create decision, and the post-promotion pointer state. Use when memory content reads as "how to", when a promote? flag is encountered again, when writing memory-derived content into a skill, or during recompaction.
 user-invocable: true
 scope: general
 ---
@@ -12,6 +12,9 @@ Memory holds **facts**; **procedures** belong in skills/instructions, where they
 stop consuming memory-read cycles. Promotion is how the store stays compact and the harness
 teaches itself.
 
+Promotion is a **rewrite, never a move**. Memory text pasted into a skill is the single most
+common way this harness degrades — see Distillation below.
+
 ## Triggers
 
 - **Procedure shape**: the content answers *how to do X* — ordered steps, imperative verbs,
@@ -28,7 +31,44 @@ teaches itself.
 
 Procedure-shaped answers *how to do X*: ordered steps, imperative verbs, commands, action tables.
 Fact-shaped answers *what is true*: declarative structure, invariants, symptom→cause pairs.
-Mixed entries split — the fact stays in the node, the "then do" moves out.
+Mixed entries split — the fact stays in the node, the "then do" is distilled into a rule in the
+skill.
+
+## Distillation (mandatory)
+
+**Never paste memory text into a skill.** A promoted line leaves the node as prose about a past
+occurrence and enters the skill as **one general rule**: *when this applies → do this → or this
+breaks*, stated so it holds next time rather than describing last time.
+
+| Strip | Keep |
+|---|---|
+| dates, phase/status markers, "COMPLETE", "landed" | the condition that makes the rule apply |
+| versions, image tags, SHAs — unless the rule turns on the version | the step to take |
+| "was X, now Y", "the former X was removed" | the failure it prevents |
+| who did it, attempt sequences, incident narrative | the recognition fingerprint (symptom) |
+| point-in-time inventories, counts, snapshots | |
+
+Before (memory): "2026-07-05 — the control-board git card was removed; the dialog now owns all
+git actions."
+After (rule): "Git actions live in the git dialog; the control board holds none."
+
+Before (memory): "Phase 3 (COMPLETE, 2026-06-13): added the init-container build, publisher
+`src/build.ts`, kephemeral v0.1.5."
+After (rule): "Production images build in an init container driven by `publisher/src/build.ts`."
+
+**If the rule cannot be stated without saying when it happened, it is not promotable** — it stays
+a memory fact, or it is dropped.
+
+### Budget
+
+A promotion normally adds **1–5 lines** to an existing skill, and a single rule is ≤ 3 lines. A
+whole new section, or more text added than the node lost, means the content was moved rather than
+distilled — redo it.
+
+A skill may legitimately run long when it maps a large subsystem, so length alone is not the test:
+**every line must be a rule, a contract, or a pointer.** A section that reads as the story of how
+the code got there is pollution at any length. "Record the rule, not the story" (`agent-memory`)
+binds skill bodies at least as tightly as it binds nodes.
 
 ## Flagging (how content earns promotion)
 
@@ -46,17 +86,21 @@ even partially; keep both twins in sync. Create a NEW pair only when:
   re-encountered ` → promote?` flag);
 - (c) an external technology required internet docs and has no governing skill.
 
-New skills multiply lookup cost — compactness applies to the skill population too.
+New skills multiply lookup cost — compactness applies to the skill population *and* to each
+skill's body.
 
 ## Procedure
 
 1. Collect the flagged / procedure-shaped memory lines.
-2. Author or extend the SKILL.md and its `.github/instructions/<name>.instructions.md` twin,
-   following the repo's `skill-authoring` or `create-skill` conventions.
-3. Shrink the node: delete the promoted prose; leave one pointer line (format below).
-4. Remove the ` → promote?` flags.
-5. Update the node's index hook if its main value moved; bump `updated:`.
-6. Report per the Reporting rule.
+2. **Distill** each into a general rule (section above). Not optional — skipping it is the
+   failure mode this skill exists to prevent.
+3. Author or extend the SKILL.md and its `.github/instructions/<name>.instructions.md` twin,
+   following the repo's `skill-authoring` or `create-skill` conventions. Where an existing rule
+   already covers the ground, **rewrite that rule in place**; append only when nothing covers it.
+4. Shrink the node: delete the source lines; leave one pointer line (format below).
+5. Remove the ` → promote?` flags.
+6. Update the node's index hook if its main value moved; bump `updated:`.
+7. Report per the Reporting rule.
 
 ## Post-promotion state
 

package/template/_claude/skills/memory-recompact/SKILL.md

@@ -39,7 +39,8 @@ For each old file or section:
    genuinely in-flight state → `Status`, dated).
 3. On conflict between records, the version consistent with **current code** wins — check the
    code, don't average.
-4. Procedure-shaped survivors do not enter nodes — route them to `memory-promotion`.
+4. Procedure-shaped survivors do not enter nodes — route them to `memory-promotion`. Routing
+   means distilling them into general rules, never handing the text over verbatim.
 
 ## Legacy-store merge (migration)
 

package/template/_claude/skills/self-education/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: self-education
-description: Mandatory post-development guidance updating — after functionality is added or changed, update the project skills/instructions the work touched, record external-doc findings (URL + gist) in the governing skill, or add skills/instructions for new subsystems and technologies. Required before the completion report whenever development started from a plan agreed with the agent.
+description: Mandatory post-development guidance updating — after functionality is added or changed, rewrite the project skills/instructions the work touched as current rules (never as change notes), record external-doc findings (URL + gist) in the governing skill, or add skills/instructions for new subsystems and technologies. Required before the completion report whenever development started from a plan agreed with the agent.
 user-invocable: true
 scope: general
 ---
@@ -29,7 +29,22 @@ For each area the work touched:
 1. Which existing skill/instruction covers it? (Check `.claude/skills/` +
    `.github/instructions/`.)
 2. Do its commands, paths, APIs, and behavior claims still hold after the change?
-3. Fix in place — and keep the skill and its instruction twin in sync.
+3. Fix in place — rewrite the affected lines so they describe current behavior; never append a
+   note about what this change did. Keep the skill and its instruction twin in sync.
+
+## Shape of an update
+
+Skills and instructions state **current rules, not what changed**. Every edit is a rewrite in
+place of the affected lines.
+
+Never write into a skill or instruction: dated bulletins ("2026-07-05 — …"), phase or migration
+status ("Phase 3 complete", "migration done", "landed"), "formerly X, now Y", incident
+narratives, fixed-bug logs, or point-in-time inventories. If a line only makes sense to someone
+who watched the change happen, it does not belong in guidance — the rule it taught does, stated
+timelessly. Facts too specific to generalize go to `.agents/memory/` (`agent-memory`); the
+rewrite recipe is `memory-promotion` → Distillation.
+
+Test: a finished skill reads as though the feature was always this way.
 
 ## Non-project skills
 

package/template/_claude/skills/skill-authoring/SKILL.md

@@ -71,10 +71,14 @@ skill").
 If you find yourself writing "last time we…", that is memory. If you are writing "to do X, do Y",
 that is a skill.
 
+Never paste memory text into a skill. Memory content enters guidance only as a restated general
+rule — trigger, step, and the failure it prevents, with dates, phase/status markers, versions and
+incident narrative stripped (`memory-promotion` → Distillation).
+
 ## After adding a skill
 
 1. If it replaces an ad-hoc `.claude/<topic>.md`, remove that file.
-2. If it absorbed memory content, shrink the source `.agents/memory/` node to a pointer line
-   (`memory-promotion`) — the memory index does not list skills.
+2. If it distilled memory content into rules, shrink the source `.agents/memory/` node to a
+   pointer line (`memory-promotion`) — the memory index does not list skills.
 3. Reference it from `CLAUDE.md` / `.github/copilot-instructions.md` if it should be discoverable
    every session.

package/template/_github/copilot-instructions.md

@@ -48,7 +48,8 @@ Single shared agent memory store: `.agents/memory/` — a graph of subsystem nod
   scope matches the task.
 - Every write merges into the matching subsystem node and compacts — record reusable knowledge,
   never session events.
-- Procedure-shaped or repeatedly-touched memory must become an instruction/skill — follow
+- Procedure-shaped or repeatedly-touched memory must be **distilled into** an instruction/skill
+  as short general rules — never pasted in as memory text — follow
   `.github/instructions/memory-promotion.instructions.md`.
 - If the store degrades (event logs, oversized nodes, bloated index) — follow
   `.github/instructions/memory-recompact.instructions.md`.
@@ -61,10 +62,10 @@ Single shared agent memory store: `.agents/memory/` — a graph of subsystem nod
 
 Whenever development started from a plan agreed with the agent, the work is not complete until
 [.github/instructions/self-education.instructions.md](.github/instructions/self-education.instructions.md)
-has been applied: update the project instructions/skills the change touched, record external-doc
-findings (URL + gist) in the governing instruction, or add an instruction/skill for a new
-subsystem or technology. The completion report must include the self-education outcome — or
-state why none was needed.
+has been applied: rewrite the project instructions/skills the change touched so they state
+current rules (never a note about what changed), record external-doc findings (URL + gist)
+in the governing instruction, or add an instruction/skill for a new subsystem or technology.
+The completion report must include the self-education outcome — or state why none was needed.
 
 ## What this is
 

package/template/_github/instructions/agent-memory.instructions.md

@@ -137,3 +137,7 @@ Fact-shaped ("what is true") stays here. Procedure-shaped ("to do X, do Y") beco
 instruction/skill — follow `.github/instructions/memory-promotion.instructions.md` where present,
 otherwise the skill-authoring guidance. Repeated use of a node to *perform* tasks, and over-cap
 nodes full of steps, are promotion triggers.
+
+Promotion is a **rewrite, never a move**: never paste node text into an instruction. "Record the
+rule, not the story" and the size caps above bind instruction bodies at least as tightly as they
+bind nodes (memory-promotion instruction → Distillation).

package/template/_github/instructions/memory-promotion.instructions.md

@@ -1,5 +1,5 @@
 ---
-description: "Promote procedure-shaped or hot memory into skills/instructions — triggers (procedure test, promote? flags, over-cap), update-vs-create rule, post-promotion pointer state. Apply when converting memory content into guidance files or when a promote? flag appears in a memory node."
+description: "Promote procedure-shaped or hot memory into skills/instructions — triggers (procedure test, promote? flags, over-cap), the mandatory distillation rewrite, update-vs-create rule, post-promotion pointer state. Apply when converting memory content into guidance files or when a promote? flag appears in a memory node."
 applyTo: "**/.agents/memory/**, **/.claude/skills/**, **/.github/instructions/**"
 scope: general
 ---
@@ -11,6 +11,9 @@ Memory holds **facts**; **procedures** belong in instructions/skills, where they
 stop consuming memory-read cycles. Promotion is how the store stays compact and the harness
 teaches itself.
 
+Promotion is a **rewrite, never a move**. Memory text pasted into an instruction is the single
+most common way this harness degrades — see Distillation below.
+
 ## Triggers
 
 - **Procedure shape**: the content answers *how to do X* — ordered steps, imperative verbs,
@@ -27,7 +30,44 @@ teaches itself.
 
 Procedure-shaped answers *how to do X*: ordered steps, imperative verbs, commands, action tables.
 Fact-shaped answers *what is true*: declarative structure, invariants, symptom→cause pairs.
-Mixed entries split — the fact stays in the node, the "then do" moves out.
+Mixed entries split — the fact stays in the node, the "then do" is distilled into a rule in the
+instruction.
+
+## Distillation (mandatory)
+
+**Never paste memory text into an instruction.** A promoted line leaves the node as prose about a
+past occurrence and enters the instruction as **one general rule**: *when this applies → do this
+→ or this breaks*, stated so it holds next time rather than describing last time.
+
+| Strip | Keep |
+|---|---|
+| dates, phase/status markers, "COMPLETE", "landed" | the condition that makes the rule apply |
+| versions, image tags, SHAs — unless the rule turns on the version | the step to take |
+| "was X, now Y", "the former X was removed" | the failure it prevents |
+| who did it, attempt sequences, incident narrative | the recognition fingerprint (symptom) |
+| point-in-time inventories, counts, snapshots | |
+
+Before (memory): "2026-07-05 — the control-board git card was removed; the dialog now owns all
+git actions."
+After (rule): "Git actions live in the git dialog; the control board holds none."
+
+Before (memory): "Phase 3 (COMPLETE, 2026-06-13): added the init-container build, publisher
+`src/build.ts`, kephemeral v0.1.5."
+After (rule): "Production images build in an init container driven by `publisher/src/build.ts`."
+
+**If the rule cannot be stated without saying when it happened, it is not promotable** — it stays
+a memory fact, or it is dropped.
+
+### Budget
+
+A promotion normally adds **1–5 lines** to an existing instruction, and a single rule is ≤ 3 lines.
+A whole new section, or more text added than the node lost, means the content was moved rather than
+distilled — redo it.
+
+An instruction may legitimately run long when it maps a large subsystem, so length alone is not the
+test: **every line must be a rule, a contract, or a pointer.** A section that reads as the story of
+how the code got there is pollution at any length. "Record the rule, not the story"
+(`agent-memory.instructions.md`) binds instruction bodies at least as tightly as it binds nodes.
 
 ## Flagging (how content earns promotion)
 
@@ -45,18 +85,22 @@ even partially; keep both twins in sync. Create a NEW pair only when:
   re-encountered ` → promote?` flag);
 - (c) an external technology required internet docs and has no governing instruction.
 
-New instructions multiply lookup cost — compactness applies to the guidance population too.
+New instructions multiply lookup cost — compactness applies to the guidance population *and* to
+each instruction's body.
 
 ## Procedure
 
 1. Collect the flagged / procedure-shaped memory lines.
-2. Author or extend the `.github/instructions/<name>.instructions.md` and its
+2. **Distill** each into a general rule (section above). Not optional — skipping it is the
+   failure mode this instruction exists to prevent.
+3. Author or extend the `.github/instructions/<name>.instructions.md` and its
    `.claude/skills/<name>/SKILL.md` twin, following the repo's skill-authoring / create-skill
-   conventions.
-3. Shrink the node: delete the promoted prose; leave one pointer line (format below).
-4. Remove the ` → promote?` flags.
-5. Update the node's index hook if its main value moved; bump `updated:`.
-6. Report per the Reporting rule.
+   conventions. Where an existing rule already covers the ground, **rewrite that rule in place**;
+   append only when nothing covers it.
+4. Shrink the node: delete the source lines; leave one pointer line (format below).
+5. Remove the ` → promote?` flags.
+6. Update the node's index hook if its main value moved; bump `updated:`.
+7. Report per the Reporting rule.
 
 ## Post-promotion state
 

package/template/_github/instructions/memory-recompact.instructions.md

@@ -40,7 +40,8 @@ For each old file or section:
 3. On conflict between records, the version consistent with **current code** wins — check the
    code, don't average.
 4. Procedure-shaped survivors do not enter nodes — route them to
-   `.github/instructions/memory-promotion.instructions.md`.
+   `.github/instructions/memory-promotion.instructions.md`. Routing means distilling them into
+   general rules, never handing the text over verbatim.
 
 ## Legacy-store merge (migration)
 

package/template/_github/instructions/self-education.instructions.md

@@ -1,5 +1,5 @@
 ---
-description: "Mandatory post-development skill/instruction updating — after adding or changing functionality, update touched project guidance, note external-doc findings in the governing instruction, or add instructions for new subsystems/technologies; required before the completion report when development started from an agreed plan. Apply when editing skills or instruction files after development."
+description: "Mandatory post-development skill/instruction updating — after adding or changing functionality, rewrite touched project guidance as current rules (never as change notes), note external-doc findings in the governing instruction, or add instructions for new subsystems/technologies; required before the completion report when development started from an agreed plan. Apply when editing skills or instruction files after development."
 applyTo: "**/.claude/skills/**, **/.github/instructions/**"
 scope: general
 ---
@@ -28,7 +28,23 @@ For each area the work touched:
 1. Which existing instruction/skill covers it? (Check `.github/instructions/` +
    `.claude/skills/`.)
 2. Do its commands, paths, APIs, and behavior claims still hold after the change?
-3. Fix in place — and keep the instruction and its skill twin in sync.
+3. Fix in place — rewrite the affected lines so they describe current behavior; never append a
+   note about what this change did. Keep the instruction and its skill twin in sync.
+
+## Shape of an update
+
+Instructions and skills state **current rules, not what changed**. Every edit is a rewrite in
+place of the affected lines.
+
+Never write into an instruction or skill: dated bulletins ("2026-07-05 — …"), phase or migration
+status ("Phase 3 complete", "migration done", "landed"), "formerly X, now Y", incident
+narratives, fixed-bug logs, or point-in-time inventories. If a line only makes sense to someone
+who watched the change happen, it does not belong in guidance — the rule it taught does, stated
+timelessly. Facts too specific to generalize go to `.agents/memory/`
+(`.github/instructions/agent-memory.instructions.md`); the rewrite recipe is
+`.github/instructions/memory-promotion.instructions.md` → Distillation.
+
+Test: a finished instruction reads as though the feature was always this way.
 
 ## Non-project instructions
 

package/template/_github/instructions/skill-authoring.instructions.md

@@ -55,8 +55,12 @@ Cross-reference related guidance by name.
   specific to this project's history. See the agent-memory instruction; promotion triggers live
   in the memory-promotion instruction.
 
+Never paste memory text into guidance. Memory content enters an instruction or skill only as a
+restated general rule — trigger, step, and the failure it prevents, with dates, phase/status
+markers, versions and incident narrative stripped (memory-promotion instruction → Distillation).
+
 ## After adding a skill
 
-If it absorbed memory content, shrink the source `.agents/memory/` node to a pointer line
+If it distilled memory content into rules, shrink the source `.agents/memory/` node to a pointer line
 (memory-promotion instruction) — the memory index does not list skills. Reference it from
 `.github/copilot-instructions.md` / `CLAUDE.md` if it should be discoverable every session.