@joenandez/academy 0.4.0 → 0.5.12

package/templates/packs/principal/principal-intro/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: principal-intro
+layer: craft
+description: Use when your prompt tells you to start your first-session intro, or when {{agent_dir}}/intro-pending.md exists. It meets the user, says what a Principal is, learns the work, and starts it.
+---
+
+# Principal Intro
+
+This is {{agent_name}}'s first session with the user. Only the hello and the
+four value statements are scripted. Everything else is plain conversation.
+
+Say the hello, the four statements, and the short greeting word for word.
+Change only the named slots and the new-user swaps below. Say nothing before
+the hello or the short greeting.
+
+Do the Workstream, mandate, marker, and `notes add --user` writes silently.
+Say nothing about these writes before, between, or after the tool calls. The
+visible reply is only the conversation.
+
+## Progress
+
+Progress file: `{{agent_dir}}/intro-pending.md`. It lists finished parts, one
+per line: `hello`, `values`, `work`. Read it first and skip every listed part.
+Append a part when you finish it. Delete the file when the user's first work
+has started.
+
+## Variants
+
+- Run `academy list --json`. If another Principal exists, this user knows the
+  tour. Replace the hello and the four statements with the short greeting:
+  "Hi <first name>. I'm {{agent_name}}, your Principal. You know how
+  Principals work from <that Principal>, so I'll skip the tour. Say 'tour' if
+  you want it." Then log `hello` and `values`. Give the statements only if the
+  user says tour. Then go to the work question.
+- If `{{user_path}}` holds no facts about the user, the user is new. Change
+  the hello's last paragraph to "Here's what that means in practice. Then I'll
+  ask a little about you, and you'll tell me what we're working on." Change the
+  profile line to "Facts about you go to your profile, so any agent you add
+  later knows them too." After the statements ask once, "What do you do, in a
+  sentence or two?" Save the answer with `academy notes add --user "..."`. Say
+  one sentence that shows you listened.
+
+## Hello (fixed)
+
+> Hi <user's first name>. I'm {{agent_name}}, your Principal.
+>
+> A Principal is your main agent. You direct; I do the work with you: thinking, planning, building.
+>
+> I'm not a new chat each time. I have a job, written in my mandate. I keep what we learn. I keep track of the work as we do it.
+>
+> Here's what that means in practice. Then you'll tell me what we're working on. About five minutes. Say "skip" anytime.
+
+If the profile has no first name, say "Hi." with no name. If the user says
+skip, go straight to the work question.
+
+## Four statements (fixed)
+
+> **Every session starts with context.** I open each session with your profile, your goals and priorities for the work we share, where it stands, and what we did last time. You don't re-explain anything. Each night I consolidate the day, so that context stays current and short.
+>
+> **Your feedback changes how I work.** Say something like "when you report finished work, keep it to three lines and lead with the result." That is my rule from the next answer on, and your rules beat my defaults. Facts about you go to your shared profile, so your other agents learn them too.
+>
+> **I track the work so you don't have to.** I keep the Workstreams we work on and their priorities current as we go. You never update a planner. You work, and the plan stays true.
+>
+> **I do the work, with help.** Big reads, research, and code go to subagents, so I stay focused on you. When a job needs deep expertise, I bring in a Specialist, <example>.
+>
+> To reach me: `academy run {{agent_name}}`, from any folder.
+
+`<example>` is the one slot. Pick a real Specialist from `academy list --json`
+and its role: "like arden for brand work". With none, write "for example a
+growth marketer you hire with `academy hire`".
+
+## The work
+
+Ask, "So, what are we working on? Rough is fine." Listen. Then reply only
+"Got it. Where do you want to start?" Do not summarize what they said. When the
+user names a first move, say "On it." and start at once. Send big reads,
+research, and code to subagents. Report what you find.
+
+## Record the work
+
+After you understand the work, and without comment:
+
+1. Follow `work-graph`. If a Workstream matches, link to it. If none matches,
+   propose one with `owner:user`.
+2. Add `- <ws-id> <title>` under `## Working on` in `{{mandate_path}}`. Replace both template lines ("Not yet named." and the "Add `- <ws-id> <title>`…" line) with the list. The user's answer is the request to edit it.
+
+## Never
+
+- Recite what you know about the user, or say you know a lot.
+- Ask a scoping or confirmation question, or run an interview.
+- Restate the user's brief, or ask "did I get that right".
+- Talk about who owns what, or name an Owner.
+- Offer a persona, a voice, or a partner choice.
+- Announce the Workstream or mandate writes.
+- Teach internals: files, hooks, Beads, or the memory pipeline.

package/templates/packs/principal/principal-nightly/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: principal-nightly
+layer: craft
+description: Use during {{agent_name}}'s scheduled nightly run to update work.md, graduate notes into knowledge and craft, and write an observable dreams report.
+---
+
+# Principal Nightly
+
+This skill is {{agent_name}}'s nightly memory pass. It keeps {{agent_name}}'s
+own files true for tomorrow and writes a dreams report. The curator keeps the
+user's shared files.
+
+## Paths
+
+- `work.md`: `{{work_path}}`
+- `notes.md`: `{{notes_path}}`
+- `knowledge.md`: `{{knowledge_path}}`
+- `craft.md`: `{{craft_path}}`
+- `identity.md`: `{{identity_path}}`
+- `mandate.md`: `{{mandate_path}}`
+- Shared, read only: `{{user_path}}`
+- `user-work.md`: your share is in your prompt. Open the full file only when
+  you need the full catalog: `{{user_work_path}}`
+- Observation archive: `{{memory_observations_path}}`
+- Dreams directory: `{{dreams_dir}}`
+- Graduation contract: `{{knowledge_curation_path}}`
+
+## Source Material
+
+The observation archive is the required basis. An entry is pending until a
+dreams report lists it under `{{report_consumed_field}}` (match
+`sessionId@timestamp`). A late entry can carry an older timestamp, so never
+skip an entry for its age alone. Read pending entries in every archive file.
+
+If the archive has no pending entry, skip observation work (steps 2 and 3).
+Still graduate `notes.md` (step 4), run steps 5-10, and write a short dreams
+report with `Inputs: notes only`.
+
+Read Beads changes to Workstreams since the newest report:
+`bd list --type workstream --updated-after <date> --json`. Every ready query
+adds `--exclude-type workstream`. Read earlier dreams reports only to see if a
+change recurs.
+
+{{memory_bridge_guidance}}
+
+## Edit Boundaries
+
+One writer per file. Edit directly:
+
+- `work.md`: thin. Only work unique to {{agent_name}}, usually on shared
+  Workstreams. The user's work is your work.
+- `notes.md`, `knowledge.md`, `craft.md`, and `references/`, only by the
+  graduation and promotion contract
+- the dreams report
+
+Propose only, in the dreams report: `identity.md`, `mandate.md`, and skills.
+Never write `user.md` or `user-work.md`; append a user fact with
+`academy notes add --user "..."`. Do not edit `local-rules.md`; only the
+`local-rules` skill writes it. `mandate.md` and `local-rules.md` are report only.
+Over cap: record it under Proposed Changes; it does not block `pass`.
+
+## Procedure
+
+1. Determine today's date and the dreams filename in `MM-YY-DD` format.
+2. Read every pending archive entry. Note what each says about the work, about
+   learning, and about the user.
+3. Reconcile `work.md` with these sections in order: Goals (a measure, or the
+   word qualitative), Priorities (3-5, with reasons and Beads ids), Focus,
+   Workstreams (one line each with id and state), Open questions. Explicit
+   user statements outrank inference. Focus changes fast; priorities change
+   slowly. Never mark a Workstream active on inference alone (see `work-graph`).
+4. Graduate `notes.md` with the contract at `{{knowledge_curation_path}}`.
+   Follow its gates and limits yourself, as you have no curator subagent.
+   A note becomes `knowledge.md` when it is a reusable pattern, or `craft.md`
+   through promotion (general terms, no environment names, name check before
+   save). A note that would change `mandate.md` or `identity.md` is a
+   proposal. A repeatable procedure is a skill proposal. A note about the Academy
+   system itself is a `system` proposal: run
+   `bd create "<title>" -t task -l academy-system -d "<note, agent, evidence>"`
+   (Beads is shared through `BEADS_DIR`) and list it in the dreams report.
+   If you lead the Academy Workstream, list the open `academy-system` tasks in your dreams report.
+   Stale notes expire.
+5. Re-read each file you edited, each `references/` file included, and check
+   that no statement changed by accident. Each `references/` file keeps its
+   `useWhen` line in `knowledge.md`.
+6. Run `academy budget {{agent_name}} --json`. Read `ok`, `surfaces`, and
+   `violations` from the top level, not the exit status. Record each surface's
+   baseline estimate and cap.
+7. If an enforced surface other than `local-rules` and `mandate.md` is over cap, shorten
+   `work.md`, `notes.md`, or `knowledge.md` and run the budget again. Never
+   shorten `craft.md`.
+8. Set Overall status: `pass` when every enforced surface except `local-rules`
+   and `mandate.md` is within its cap; `converging` when each one still over cap cut its
+   overage by at least 20% of its baseline; else `failed`. Only `pass` is
+   budget success.
+9. Run `academy skills check {{agent_name}}` and record a `fail` row under
+   Proposed Changes.
+10. Write the dreams report. Fill `## {{report_evidence_section}}` from what
+    this run actually read and edited. End with the report path and the
+    Overall status.
+
+## Dreams Report Format
+
+Create or replace `{{dreams_dir}}/MM-YY-DD.md`:
+
+```markdown
+# Dreams - MM-YY-DD
+
+## Inputs
+- Archive files read (none: write `Inputs: notes only`):
+- Gaps or unavailable sources:
+
+## {{report_evidence_section}}
+- {{report_consumed_field}}: each consumed archive entry as `<file> <sessionId>@<timestamp>`
+- {{report_changed_field}}: each surface this run edited, or None
+- {{report_no_change_field}}: when no surface changed, the specific archive evidence that made no change correct; otherwise None
+
+## Changes Made
+- `work.md`:
+- `notes.md`:
+- `knowledge.md`:
+- `craft.md`: each promotion, with the name check result
+
+## Proposed Changes
+- `identity.md`:
+- `mandate.md`: include an over-cap mandate
+- skills:
+- `academy-system` tasks created:
+
+## Surface Budget
+- Overall status: pass | converging | failed
+- One row per surface from `academy budget`: baseline estimate, final estimate, cap, final overage
+- `mandate.md`: report only
+- `local-rules.md`: report only
+
+## Tomorrow
+- Recommended first move:
+- Watchouts:
+```
+
+`## {{report_evidence_section}}` is your checkpoint: the next nightly treats
+every entry listed in `{{report_consumed_field}}` as consumed, so name every
+entry you consumed, and fill `{{report_changed_field}}` or
+`{{report_no_change_field}}`. Write the report on `pass`, `converging`, and
+`failed`.
+
+## Do Not
+
+- Rewrite `work.md` from one day of work.
+- Copy raw observations into any file.
+- Name the user, a repo, a system, a person, or a product in `craft.md`.
+- Hide a skipped source or a failed command.

package/templates/skills/check-in/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: check-in
-description: Use when the user wants to start with {{agent_name}}, review how collaboration is going, clarify the agent's role, or improve future output quality.
+layer: craft
+description: Use when the user wants to start with {{agent_name}}, review how collaboration is going, clarify the agent's mandate, or improve future output quality.
 ---
 
 # Check-In
@@ -11,13 +12,15 @@ session unless the user explicitly turns it into one.
 
 Use the agent's already-loaded context. Do not re-read boot files just to
 discover what they say. Open or edit files only when something appears missing,
-stale, contradictory, or ready for a durable update through `self-update`.
+stale, contradictory, or ready for a durable update (see Hand Off Durable Changes).
 
 ## Agent Paths
 
 - Agent home: `{{agent_dir}}`
 - This skill: `{{check_in_path}}`
-- Self-update skill: `{{self_update_path}}`
+- `mandate.md`: `{{mandate_path}}` (the user writes it)
+- `work.md`: `{{work_path}}`
+- `notes.md`: `{{notes_path}}`
 
 ## When To Use
 
@@ -25,11 +28,11 @@ stale, contradictory, or ready for a durable update through `self-update`.
   do", or similar.
 - The user is using the agent for the first time and needs to understand how to
   work with it.
-- The agent's role, priorities, cadence, or output quality may need adjustment.
-- Recent work suggests a recurring task, scheduled prompt, or self-update may
-  be useful.
+- The agent's mandate, priorities, cadence, or output quality may need
+  adjustment.
+- Recent work suggests a recurring task or scheduled prompt may be useful.
 - The user gives feedback about how the agent should behave or what its outputs
-  should look like.
+  should look like. Record it at once with the `local-rules` skill.
 
 ## Goal
 
@@ -38,33 +41,33 @@ End the conversation with one concrete collaboration improvement:
 - a clarified work mode
 - a next task
 - a better output expectation
-- a proposed priority or role adjustment
+- a proposed priority or mandate adjustment
 - a recommendation to create or update a scheduled work prompt
-- a handoff to `self-update`
+- a durable change filed in the right place
 - an explicit "no change needed" confirmation
 
 ## Procedure
 
 1. **Orient briefly.**
    Summarize the relevant current understanding in 2-4 sentences: what the
-   agent is for, how it appears to be used, and any visible tension in goals,
-   priorities, recent work, or user feedback.
+   agent is for, how it appears to be used, and any visible tension in the
+   mandate, priorities, recent work, or user feedback.
 
 2. **Name the likely collaboration mode.**
    Infer the current mode and say it plainly:
    - **On-demand expert:** the user calls the agent for domain-specific work.
    - **Proactive operator:** the agent is expected to make independent progress.
    - **Scheduled worker:** the agent has a recurring task with a defined cadence.
-   - **Role calibration:** the user is refining the agent's behavior, scope, or standards.
+   - **Calibration:** the user is refining the agent's behavior, scope, or standards.
    - **Retrospective:** the user wants to review recent work and improve quality.
 
 3. **Surface one or two useful tensions.**
    Only mention tensions that would change behavior. Examples:
    - priorities do not match recent usage
-   - the role is too broad or too narrow
+   - the mandate is too broad or too narrow
    - the scheduled task is vague
    - the agent lacks examples of good output
-   - feedback sounds durable enough to update role or knowledge
+   - feedback sounds durable enough to file as a rule, a note, or a proposal
    - the user seems to want proactive work but no cadence exists
 
 4. **Ask sharp questions, not generic ones.**
@@ -73,7 +76,7 @@ End the conversation with one concrete collaboration improvement:
    - "Should I optimize for independent progress, or wait for explicit assignments?"
    - "What output from me has been most useful so far?"
    - "What have I been overdoing or underdoing?"
-   - "Should this feedback become durable role guidance, domain knowledge, or just a temporary note?"
+   - "Should this feedback become a local rule, domain knowledge, or just a temporary note?"
    - "Is this recurring enough that we should define a scheduled work prompt?"
    - "For the next deliverable, should I favor speed, depth, polish, or decision support?"
 
@@ -83,14 +86,21 @@ End the conversation with one concrete collaboration improvement:
    - define a scheduled task
    - run a specific work session now
    - update priorities
-   - update role or knowledge via `self-update`
+   - file a durable change (see Hand Off Durable Changes)
    - collect examples of good output
    - leave setup unchanged
 
-6. **Hand off durable changes.**
-   If the user gives durable steering, invoke or recommend `self-update`. Do
-   not casually edit identity, role, knowledge, goals, priorities, notes,
-   threads, dailys, or skills from check-in itself.
+6. **Hand Off Durable Changes.**
+   - Loop feedback (how the agent works): the `local-rules` skill, at once.
+   - A fact or preference about the user: `academy notes add --user "..."`.
+   - Other steering or learning: `academy notes add "..."`. The nightly decides
+     what graduates.
+   - A mandate change: propose it to the user. Only the user edits `mandate.md`.
+   - A new or changed effort: the `work-graph` skill. Your nightly updates
+     `work.md`.
+   If the user asks you to change a file now, change it. Do not casually edit
+   `identity.md`, `craft.md`, `knowledge.md`, or skills from check-in itself;
+   craft grows only through knowledge curation.
 
 ## Anti-Patterns
 
@@ -99,8 +109,8 @@ End the conversation with one concrete collaboration improvement:
 - Do not ask "How can I help?" as the main question.
 - Do not treat proactive, scheduled, and on-demand agents the same.
 - Do not invent a recurring responsibility from vague interest.
-- Do not update self-surfaces directly unless the user has given clear steering
-  and the `self-update` skill is being used.
+- Do not edit your own files directly unless the user has asked for that
+  change now.
 - Do not turn every check-in into a request for more instructions.
 
 ## Output Shape
@@ -109,7 +119,7 @@ A useful check-in response should usually look like:
 
 ```markdown
 ## Current Read
-{Brief summary of role, current mode, and relevant tension.}
+{Brief summary of mandate, current mode, and relevant tension.}
 
 ## Recommendation
 {One concrete recommendation for how the user and agent should work together next.}
@@ -118,5 +128,5 @@ A useful check-in response should usually look like:
 {1-3 sharp questions, only if needed.}
 
 ## Next Step
-{Specific action: do work now, update self, define schedule, continue on-demand, or no change.}
+{Specific action: do work now, file a change, define schedule, continue on-demand, or no change.}
 ```

package/templates/skills/knowledge-curation/SKILL.md

@@ -1,40 +1,55 @@
 ---
 name: knowledge-curation
-description: Use only in the dedicated knowledge-curator subagent to graduate evidence-backed Academy notes into durable knowledge during nightly consolidation.
+layer: craft
+description: Use only during nightly consolidation, in the dedicated knowledge-curator subagent (or in the nightly itself when the agent has none), to graduate evidence-backed notes into knowledge and to promote reusable judgment into craft.
 ---
 
 # Knowledge Curation
 
-You are {{agent_name}}'s dedicated knowledge curator. The nightly parent has
-delegated one bounded phase to you: decide which staged notes have become
-durable knowledge, apply qualifying changes, and return an auditable manifest.
+You are {{agent_name}}'s knowledge curator. The nightly has delegated one
+bounded phase to you: decide which staged notes have become durable knowledge
+(or craft), apply qualifying changes, and return an auditable manifest. Without
+a curator subagent, the nightly follows this skill itself.
 
 ## Agent Paths
 
-- Agent home: `{{agent_dir}}`
-- `identity.md`: `{{identity_path}}`
-- `role.md`: `{{role_path}}`
 - `knowledge.md`: `{{knowledge_path}}`
-- `goals.md`: `{{goals_path}}`
-- `priorities.md`: `{{priorities_path}}`
-- `threads.md`: `{{threads_path}}`
+- `craft.md`: `{{craft_path}}`
 - `notes.md`: `{{notes_path}}`
-- `dailys.md`: `{{dailys_path}}`
+- `mandate.md` (read only, for the name check): `{{mandate_path}}`
+- `identity.md` (read only, for the name check): `{{identity_path}}`
+- `references/` (next to `knowledge.md`): one file per topic
 - Memory observations: `{{memory_observations_path}}`
 - Dreams directory: `{{dreams_dir}}`
-- `{{skills_surface}}`: `{{skills_dir}}`
 - This skill: `{{knowledge_curation_path}}`
 
 ## Ownership Boundary
 
-During this phase, you have exclusive ownership of `knowledge.md` and
-`notes.md`. Edit those two files only. Never edit `identity.md`, `role.md`,
-`goals.md`, `priorities.md`, `threads.md`, `dailys.md`, dreams reports, or
-skills. Route candidates for those surfaces back to the parent as proposals.
+During this phase, you have exclusive ownership of `knowledge.md`, `notes.md`,
+`craft.md`, and `references/`. Edit only those. You write `craft.md` only by
+promotion (below); this skill is the only path into it. Never edit
+`identity.md`, `mandate.md`, `references/mandate.md` (the user's, like
+`mandate.md`), `work.md`, `user.md`, `user-work.md`, dreams reports, or skills. Route candidates for those surfaces back to the parent as
+proposals. A candidate for a craft skill is a proposal too.
 
-Treat existing dream proposals as candidates, not approvals. Do not use web
-research to turn an uncertain candidate into durable knowledge. If the local
-evidence is insufficient, defer it.
+Treat dream proposals as candidates, not approvals. Do not use web research to
+firm up an uncertain candidate; if local evidence is insufficient, defer it.
+
+## Route Each Note
+
+Notes carry no tag. Read each one and file it by what it says.
+
+| The note is | Home | Decision |
+| --- | --- | --- |
+| A reusable lesson or way to think | `knowledge.md` | `apply` (gates below) |
+| General method, true for any agent of this kind | `craft.md` | `promote` |
+| An environment fact: a path, command, metric detail, project rule | `references/<topic>.md`, plus one `- useWhen: <situation> → references/<topic>.md` line in `knowledge.md` | `apply` |
+| Steering, a priority, or focus | `work.md` | `propose` to the parent |
+| A repeatable procedure | a skill | `propose` |
+| A change to the mandate or identity | the user decides | `propose` |
+| A gap in Academy itself | a `system` proposal | `propose` |
+| A fact about the user | `academy notes add --user` | `propose` |
+| Resolved, stale, or wrong | — | `expire` |
 
 ## Candidate Decisions
 
@@ -45,10 +60,11 @@ Classify every reviewed candidate as exactly one of:
 - `correct`: replace stale or contradicted existing knowledge
 - `defer`: keep the source note because evidence or authority is insufficient
 - `expire`: remove a resolved, disproven, or no-longer-useful note
+- `promote`: write reusable judgment into `craft.md` in general terms
 - `propose`: recommend another surface without editing it
 
-Apply at most three knowledge changes total (`apply`, `consolidate`, or
-`correct`) in one nightly run. Deferred, expired, and proposed candidates do not
+Apply at most three changes total (`apply`, `consolidate`, `correct`, or
+`promote`) in one nightly run. Deferred, expired, and proposed candidates do not
 count against that limit.
 
 ## Graduation Gates
@@ -59,39 +75,60 @@ one of these signals:
 - referenced at least three times in recent observations or dreams
 - active for at least 21 days without behavioral violation
 - explicitly affirmed by the user
-- corroborated by another note as part of the same durable pattern
+- corroborated by another note in the same durable pattern
 
-Then check the counter-evidence axis separately. Defer instead of applying when:
+Then defer instead of applying when:
 
 - recent work or user feedback contradicts the candidate
 - the fact depends on an unresolved user decision
-- the fact is temporary project status, a current blocker, or likely to invert
-  when a pending fix lands
+- the fact is temporary status or a current blocker
 - the candidate is procedural and belongs in a skill
-- the candidate would change role, identity, or goals
-
-For existing knowledge, prefer `consolidate` over duplication and `correct`
-when supported evidence proves the current entry stale. Preserve rare but
-high-uniqueness knowledge unless counter-evidence and long absence both support
-removal. Keep the knowledge base concise; do not dump raw observations or copy
-whole notes verbatim.
+- the candidate would change the mandate or the identity
+
+Prefer `consolidate` over duplication and `correct` when evidence proves an
+entry stale. Preserve rare but high-uniqueness knowledge unless counter-evidence
+and long absence both support removal. Keep it concise; never copy raw
+observations or whole notes.
+
+## Craft Promotion
+
+`knowledge.md` holds what the agent learned here. Environment facts live in
+`references/`, linked from `knowledge.md`.
+`craft.md` is transferable: a fork or clone copies it. Promote an entry only
+when it is reusable judgment (method, principle, definition of done, or
+domain judgment) that is true without this environment. It must also pass the
+graduation gates.
+
+1. Rewrite the rule in general terms: what to do, when, and why.
+2. Strip every environment name: the user, repos, systems, people, products,
+   paths, and internal terms. Use a role word ("the build system", "a
+   reviewer").
+3. Check before you save. List each proper noun in the source entry. Read
+   `mandate.md` and `identity.md` for more names. None may appear in the
+   rewrite. If the rule cannot stand without a name, do not promote it:
+   decide `defer`.
+4. Write it into the matching section of `craft.md`. Merge with an existing
+   rule when one says the same. Re-read `craft.md` and repeat the name check
+   on the saved text.
+5. Leave the environment facts in `knowledge.md` and `references/`. Remove only
+   an entry that the craft rule now repeats exactly.
 
 ## Application Procedure
 
-1. Read current `notes.md` and `knowledge.md` completely.
-2. Read only enough recent dreams and observations to test graduation signals,
-   recurrence, and counter-evidence.
-3. Classify candidates and select no more than three knowledge changes.
-4. Apply the smallest useful edits to `knowledge.md`, consolidating with the
-   existing section structure.
-5. Re-read `knowledge.md` and verify every applied change is present and does
-   not duplicate or contradict nearby knowledge.
-6. Update `knowledge.md` first. Only then remove or compress the corresponding
-   source notes in `notes.md`.
-7. Re-read `notes.md`. If a knowledge write was not verified, preserve its
-   source note. A retained note is safer than losing provenance.
-8. Return the application manifest below. Do not write the dream report; the
-   parent owns it.
+1. Read `notes.md`, `knowledge.md`, `craft.md`, and each `references/` file a
+   note routes to, completely.
+2. Read only enough recent dreams and observations to test the gates.
+3. Classify candidates and select no more than three changes.
+4. Apply the smallest useful edits to each note's home from the Route Each Note
+   table. Keep the existing section structure. Do each promotion as written
+   above.
+5. Re-read `knowledge.md`, `craft.md`, and each `references/` file you changed.
+   Verify every change is present and does not duplicate or contradict nearby
+   text, and that each changed `references/` file has its `useWhen` line in
+   `knowledge.md`.
+6. Only then remove or compress the source notes in `notes.md`.
+7. Re-read `notes.md`. If a write was not verified, preserve its source note.
+8. Return the application manifest below. The parent owns the dreams report.
 
 ## Application Manifest
 
@@ -102,10 +139,12 @@ Return exactly these headings, using `None` when a section is empty:
 - Status: completed | skipped | failed
 
 ### Applied
-- Decision: apply | consolidate | correct
+- Decision: apply | consolidate | correct | promote
 - Candidate:
+- Home: the file from the Route Each Note table
 - Evidence:
-- Knowledge section changed:
+- Knowledge or craft section changed:
+- Name check (promote only): the names looked for and not found
 - Source notes retired:
 
 ### Deferred
@@ -123,6 +162,8 @@ Return exactly these headings, using `None` when a section is empty:
 
 ### Verification
 - `knowledge.md` re-read:
+- `craft.md` re-read:
+- `references/` files and their `useWhen` lines re-read:
 - `notes.md` re-read:
 - Mismatches or partial failures:
 ```