@forwardimpact/outpost 3.12.0 → 3.13.0

package/templates/.claude/skills/candidate-report/SKILL.md

@@ -1,18 +1,20 @@
 ---
 name: candidate-report
 description: >
-  Generate an A4 single-page HTML candidate assessment report benchmarked
-  against the agent-aligned engineering standard. Use when the user asks you
-  to create a candidate report, one-pager, or visual assessment for a hiring
-  manager.
+  Generate a single-page A4 HTML report that assesses a candidate against the
+  agent-aligned engineering standard. Use when the user asks you to create a
+  candidate report, one-pager, or visual assessment for a hiring manager.
 ---
 
 # Candidate Report
 
+Write tier: `0-Draft` (the report is an export artifact)
+Frontmatter: none
+
 Generate a polished, single-page A4 HTML report that benchmarks a candidate
-against a specific role in the agent-aligned engineering standard. The report is
-designed for hiring managers and pod leads who need a quick visual summary
-before deciding whether to invest interview time.
+against a specific role in the agent-aligned engineering standard. The report
+serves hiring managers and pod leads. They need a quick visual summary before
+they decide whether to invest interview time.
 
 ## Trigger
 
@@ -25,34 +27,36 @@ before deciding whether to invest interview time.
 - `@forwardimpact/pathway` CLI installed (`bunx fit-pathway --help`).
 - Playwright for PDF output
   (`bun install playwright && bunx playwright install chromium`).
-- Candidate has a `brief.md` in `Knowledge/Candidates/{Name}/`.
+- The candidate has a `brief.md` in `2-Confidential/Candidates/{Name}/`.
 
 ## Inputs
 
-- **Candidate name** — locates `Knowledge/Candidates/{Name}/brief.md`.
+- **Candidate name** — locates `2-Confidential/Candidates/{Name}/brief.md`.
 - **Target role** — discipline, level, track (e.g.
-  `software-engineering J070 forward-deployed`). If not given, infer from the
-  candidate's `Req` field → Role file. Ask the user if it can't be inferred.
+  `software-engineering J070 forward-deployed`). If the user does not give it,
+  infer it from the candidate's `Req` field → Role file. Ask the user when you
+  cannot infer it.
 - **Recipient** — pod lead or hiring manager the report is for.
 - **CV file** (optional) — read directly when no `screening.md` exists.
 
 ## Outputs
 
-- `Drafts/{Recipient}-{CandidateSurname}-Report.html` — the A4 one-pager.
-- Optional PDF via `scripts/render-pdf.mjs`.
+- `0-Draft/{Recipient}-{CandidateSurname}-Report.html` — the A4 one-pager.
+- Optional PDF with `scripts/render-pdf.mjs`.
 
 <do_confirm_checklist goal="Verify the report before delivering it">
 
-- [ ] Standard data was loaded via `bunx fit-pathway job` (not guessed).
-- [ ] Every skill rating is evidence-based; two-level scepticism applied to CV
+- [ ] Load the standard data with `bunx fit-pathway job`. Do not guess it.
+- [ ] Base every skill rating on evidence. Apply two-level scepticism to the CV
       claims.
 - [ ] Coverage counters add up to the total skill count.
-- [ ] Verdict class matches the overall assessment.
-- [ ] Report fits on a single A4 page (browser print preview).
-- [ ] CSS is inlined in the `<style>` block.
-- [ ] Footer shows the author name and role from
-      `~/.cache/fit/outpost/state/identity.md`.
-- [ ] Written as if the candidate will read it; no special-category data.
+- [ ] Match the verdict class to the overall assessment.
+- [ ] Fit the report on a single A4 page (browser print preview).
+- [ ] Inline the CSS in the `<style>` block.
+- [ ] Show the author name and role from
+      `~/.cache/fit/outpost/state/identity.md` in the footer.
+- [ ] Write as if the candidate will read the report. Include no
+      special-category data.
 
 </do_confirm_checklist>
 
@@ -63,16 +67,17 @@ before deciding whether to invest interview time.
 Read whatever exists for the candidate:
 
 ```text
-Knowledge/Candidates/{Name}/brief.md        # required
-Knowledge/Candidates/{Name}/screening.md    # if produced by req-screen
-Knowledge/Candidates/{Name}/interview-*.md  # if produced by req-assess
-Knowledge/Candidates/{Name}/CV.pdf|CV.md    # raw CV if needed
+2-Confidential/Candidates/{Name}/brief.md        # required
+2-Confidential/Candidates/{Name}/screening.md    # if produced by req-screen
+2-Confidential/Candidates/{Name}/interview-*.md  # if produced by req-assess
+2-Confidential/Candidates/{Name}/CV.pdf|CV.md    # raw CV if needed
 ```
 
 If `screening.md` exists, treat its skill and behaviour ratings as the primary
-source — they're already standard-calibrated. Otherwise map manually in Step 3.
+source. They are already standard-calibrated. Otherwise map them manually in
+Step 3.
 
-Search the graph for surrounding context: `rg "{Candidate Name}" Knowledge/`.
+Search the graph for surrounding context: `rg "{Candidate Name}" [0-9]-*/`.
 
 ### 2. Load the standard benchmark
 
@@ -91,14 +96,14 @@ Group skills by capability area (Delivery, AI, Business, Docs, ML).
 
 ### 3. Benchmark the candidate
 
-Map evidence against each skill and behaviour using the rubric in
-[references/rubric.md](references/rubric.md): rating pills, behaviour bar widths
-and colours, level-gauge window. Count totals into Gap / Partial / Unknown / Met
-for the coverage counters.
+Map the evidence against each skill and behaviour with the rubric in
+[references/rubric.md](references/rubric.md). The rubric covers the rating
+pills, the behaviour bar widths and colours, and the level-gauge window. Count
+the totals into Gap / Partial / Unknown / Met for the coverage counters.
 
 ### 4. Determine verdict
 
-Pick one of `verdict-proceed`, `verdict-caution`, or `verdict-pass` using the
+Pick one of `verdict-proceed`, `verdict-caution`, or `verdict-pass` with the
 verdict table in [references/rubric.md](references/rubric.md). Write a one-line
 headline and a short detail sentence.
 
@@ -106,10 +111,10 @@ headline and a short detail sentence.
 
 1. Read `references/report.css`.
 2. Read `references/report-template.html`.
-3. Replace every `{{PLACEHOLDER}}` with candidate-specific data, populating the
+3. Replace every `{{PLACEHOLDER}}` with candidate-specific data. Populate the
    sections listed in
    [references/rubric.md](references/rubric.md#template-sections-to-populate).
-4. Inline the CSS into the `<style>` block — required for PDF rendering.
+4. Inline the CSS into the `<style>` block. The PDF output needs this.
 
 Respect the **A4 single-page budget** in
 [references/rubric.md](references/rubric.md#a4-single-page-budget). If the print
@@ -120,7 +125,7 @@ preview overflows, cut content.
 Save the completed HTML to:
 
 ```text
-Drafts/{Recipient}-{CandidateSurname}-Report.html
+0-Draft/{Recipient}-{CandidateSurname}-Report.html
 ```
 
 `{Recipient}` is the first name of the person the report is for.
@@ -136,5 +141,5 @@ node .claude/skills/candidate-report/scripts/render-pdf.mjs \
   ~/Desktop/{CandidateSurname}-Report.pdf
 ```
 
-Requires Playwright. If missing, ask the user to run
+This step needs Playwright. If Playwright is missing, ask the user to run
 `bun install playwright && bunx playwright install chromium`.

package/templates/.claude/skills/candidate-report/references/report-template.html

@@ -9,8 +9,8 @@
   This is the structural skeleton for the A4 one-page candidate assessment.
   Replace all {{PLACEHOLDER}} tokens with candidate-specific data.
 
-  The stylesheet is in references/report.css — inline it here with a <style>
-  tag (required for PDF rendering).
+  The stylesheet is in references/report.css. Inline it here with a <style>
+  tag. The PDF output needs it inline.
 
   LAYOUT BUDGET (fits 297mm A4 height):
     Header:      ~60px
@@ -18,9 +18,9 @@
     Body:        ~680px  (6 sections at ~110px avg)
     Footer:      ~28px
 
-  When customising, test with Ctrl+P (print preview) in a browser to verify
-  the report fits on a single page. If content overflows, reduce the number
-  of benchmark skills shown or shorten the strengths list.
+  When you customise the template, test with Ctrl+P (print preview) in a
+  browser. Verify that the report fits on a single page. If content overflows,
+  reduce the number of benchmark skills shown or shorten the strengths list.
 -->
     <style>
       {{INLINE_CSS}}
@@ -59,7 +59,7 @@
           <dl class="snap">
             <!--
           Typical fields: Experience, Education, Source, Stack.
-          Add/remove <dt>/<dd> pairs as needed for the candidate.
+          Add or remove <dt>/<dd> pairs to fit the candidate.
         -->
             {{SNAPSHOT_DL_ITEMS}}
           </dl>
@@ -115,8 +115,8 @@
 
         Group the framework's capability areas into 4 visual blocks.
         If there are 6 capability areas, combine the smallest two.
-        Show only skills where evidence exists or the gap is notable —
-        aim for 4-6 rows per block to stay within A4 height.
+        Show only skills where evidence exists or the gap is notable.
+        Aim for 4-6 rows per block to stay within A4 height.
 
         Pill classes:
           p-g  = Gap (red)
@@ -151,7 +151,7 @@
           <div class="stitle">Coverage Summary</div>
           <div class="counters">
             <!--
-          Four counter boxes. Colours are fixed:
+          Four counter boxes. Use these fixed colours:
             Gap:     background:#FEE2E2  text:#991B1B
             Partial: background:#FEF3C7  text:#92400E
             Unknown: background:var(--s100) text:var(--s500)
@@ -184,7 +184,7 @@
           <ol>
             <!--
           2-4 numbered action items. Each:
-          <li><strong>Action.</strong> Detail explaining the step.</li>
+          <li><strong>Action.</strong> Detail that explains the step.</li>
         -->
             {{RECOMMENDATION_LI_ITEMS}}
           </ol>

package/templates/.claude/skills/candidate-report/references/report.css

@@ -1,11 +1,11 @@
 /*
  * candidate-report — A4 single-page candidate assessment report
  *
- * This stylesheet is designed for a 210mm × 297mm page.
- * It is loaded into the HTML template by the candidate-report skill.
+ * This stylesheet targets a 210mm × 297mm page.
+ * The candidate-report skill loads it into the HTML template.
  *
  * IMPORTANT: All colours must use print-color-adjust: exact so they survive
- * PDF rendering via Playwright. Avoid box-shadow and fixed positioning.
+ * when Playwright renders the PDF. Avoid box-shadow and fixed positioning.
  */
 
 @import url("https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700;800&display=swap");
@@ -107,7 +107,7 @@ body {
   color: var(--s600);
 }
 
-/* Verdict colour variants — set on the element via class */
+/* Verdict colour variants — add one as a class on the element */
 .verdict-caution {
   background: #fef3c7;
 }

package/templates/.claude/skills/candidate-report/references/rubric.md

@@ -1,11 +1,11 @@
-# Benchmarking Rubric
+# Benchmark Rubric
 
 Reference data for `candidate-report` Step 3 (benchmark) and Step 4 (verdict).
 
 ## Skill ratings
 
-Map each agent-aligned engineering standard skill against candidate evidence (CV
-or `screening.md`).
+Map each skill in the agent-aligned engineering standard against the candidate
+evidence (CV or `screening.md`).
 
 | Rating      | Criteria                                           | Pill class |
 | ----------- | -------------------------------------------------- | ---------- |
@@ -14,8 +14,9 @@ or `screening.md`).
 | **Gap**     | No evidence, or clearly below expected             | `p-g`      |
 | **Unknown** | Cannot assess from available evidence              | `p-u`      |
 
-Apply the **two-level scepticism rule** from `req-screen`: default two levels
-below CV claims unless concrete, quantified evidence is provided.
+Apply the **two-level scepticism rule** from `req-screen`. Default to two levels
+below the CV claims, unless the candidate supplies concrete, quantified
+evidence.
 
 ## Behaviour bar widths
 
@@ -38,17 +39,17 @@ candidate's estimate and the target level.
 
 Pick one verdict class for the report header.
 
-| Verdict              | Class             | When to use                                                         |
-| -------------------- | ----------------- | ------------------------------------------------------------------- |
-| Proceed              | `verdict-proceed` | Candidate benchmarks at or above target level                       |
-| Proceed with Caution | `verdict-caution` | Mixed signals; viable for scoped role or needs interview to resolve |
-| Pass                 | `verdict-pass`    | Clear misalignment with role requirements                           |
+| Verdict              | Class             | When to use                                                               |
+| -------------------- | ----------------- | ------------------------------------------------------------------------- |
+| Proceed              | `verdict-proceed` | Candidate benchmarks at or above target level                             |
+| Proceed with Caution | `verdict-caution` | Mixed signals. Viable for a scoped role, or needs an interview to resolve |
+| Pass                 | `verdict-pass`    | Clear misalignment with role requirements                                 |
 
 Write a one-line headline and a brief detail sentence.
 
 ## Template sections to populate
 
-Drives the placeholder substitution in Step 5.
+Use this table to replace the placeholders in Step 5.
 
 | Section           | Source                                                             |
 | ----------------- | ------------------------------------------------------------------ |
@@ -69,8 +70,8 @@ The report **must** fit on a single A4 page (210mm × 297mm):
 
 - Snapshot: max 6 `<dt>`/`<dd>` pairs.
 - Strengths: max 5 `<li>`, one sentence each.
-- Benchmark grid: 4–6 rows per capability area; prioritise notable
-  gaps/strengths, omit "Unknown" rows when tight.
+- Benchmark grid: 4–6 rows per capability area. Prioritise the notable gaps and
+  strengths. Omit "Unknown" rows when the space is tight.
 - Combine small capability areas (e.g. Docs + ML) into one block.
 - Recommendation: max 4 `<li>`.
-- Test with browser print preview (Ctrl+P); cut content if it overflows.
+- Test with the browser print preview (Ctrl+P). Cut content if it overflows.

package/templates/.claude/skills/candidate-report/scripts/render-pdf.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env bun
 /**
- * Render a candidate report HTML file to A4 PDF using Playwright.
+ * Render a candidate-report HTML file to A4 PDF with Playwright.
  *
  * Usage: node scripts/render-pdf.mjs [input.html] [output.pdf]
  *
@@ -14,7 +14,7 @@
 import { resolve, join } from "node:path";
 import { homedir } from "node:os";
 
-const HELP = `render-pdf — render candidate report HTML to A4 PDF via Playwright
+const HELP = `render-pdf — render candidate-report HTML to A4 PDF with Playwright
 
 Usage: node scripts/render-pdf.mjs [input.html] [output.pdf] [-h|--help]
 

package/templates/.claude/skills/changelog/SKILL.md

@@ -1,60 +1,79 @@
 ---
 name: changelog
-description: Record the knowledge-graph changes made during the current session into a single shared Knowledge/CHANGELOG.md so the team can see what changed and why. Use when the user asks to log, record, or write up the changes they just made to the knowledge base — typically at the end of a session of edits.
+description: Record the knowledge-graph changes from the current session into one CHANGELOG.md per shared tier. The team can then see what changed and why. Use when the user asks to log, record, or write up the changes they just made to the knowledge base. This typically happens at the end of a session of edits.
 ---
 
 # Changelog
 
-Record the changes made to the **knowledge graph** (`Knowledge/`) during the
-current working session in one shared `Knowledge/CHANGELOG.md`, newest first, so
-teammates syncing the same filesystem can see what changed and why.
+Write tier: each shared tier (rank 1 and up)
+Frontmatter: changelog
 
-This tracks **graph content** — notes under `Knowledge/People/`,
-`Organizations/`, `Projects/`, `Topics/`, `Candidates/`, `Priorities/`, and the
-other subdirectories. It does **not** track changes to instructions
-(`CLAUDE.md`, agents, skills) — that is the `upstream-instructions` skill's job.
+Record the changes to the **knowledge graph** (the tier directories) from the
+current working session. Write them into one `CHANGELOG.md` per shared tier
+(`<N>-<Label>/CHANGELOG.md`, ranks 1 and up), newest first. Teammates who
+receive a tier can then see what changed in it and why.
+
+The changelog is per tier because its audience is the tier's audience. An
+entry never names a note in a narrower tier: a change to a tier-2 note goes
+to `2-Confidential/CHANGELOG.md` only, never to `3-Team/CHANGELOG.md`.
+`0-Draft/` keeps no changelog. Discover changelogs inside the tier
+directories only.
+
+This skill tracks **graph content**: the notes under each tier's entity
+subdirectories (`People/`, `Organizations/`, `Projects/`, `Candidates/`, and
+the rest). It does **not** track changes to instructions (`CLAUDE.md`,
+agents, skills). The `upstream-instructions` skill owns those, and the root
+instruction `CHANGELOG.md` is a personal surface this skill never touches.
 
 ## Trigger
 
-- The user asks to write, update, or record a changelog after editing the KB.
-- A session has added, modified, removed, or renamed notes in `Knowledge/` and
-  the user wants those changes documented for the team.
+- The user asks to write, update, or record a changelog after they edit the KB.
+- A session added, modified, removed, or renamed notes in a shared tier. The
+  user wants a record of those changes for the team.
 
 ## Inputs
 
-- **The edits made in the current session** — the source of truth. The KB lives
-  on a synced filesystem and is not version-controlled, so there is no commit
-  history to diff. Recall every note created, edited, removed, or renamed under
-  `Knowledge/` during this conversation.
-- `~/.cache/fit/outpost/state/identity.md` — the current user's identity. Its
-  **Name** is the author recorded on each entry. The KB is shared, so every
-  change must be attributed to the team member who made it. Resolve `~` to
-  `$HOME` before reading.
-- `Knowledge/CHANGELOG.md` — the existing changelog, to see what's already
-  recorded and avoid duplicates.
+- **The edits made in the current session** — the source of truth. A tier may
+  sync over a mount with no version control, so never rely on commit history.
+  Recall every note that you created, edited, removed, or renamed in a shared
+  tier during this conversation.
+- `~/.cache/fit/outpost/state/identity.md` — the current user's identity. Use
+  its **Name** as the author on each entry. The tiers are shared, so every entry
+  must name the team member who made the change. Resolve `~` to `$HOME` before
+  you read it.
+- `<N>-<Label>/CHANGELOG.md` per shared tier — the existing changelogs. Read
+  them to see what is already recorded and to avoid duplicates.
 
 ## Outputs
 
-- `Knowledge/CHANGELOG.md` — a **single** reverse-chronological changelog
-  covering all graph subdirectories. No per-folder or per-note changelogs.
+- One `CHANGELOG.md` per shared tier that had changes: a
+  reverse-chronological log that covers that tier's subdirectories. No
+  per-folder or per-note changelogs, and none in `0-Draft/`.
 
 ## Ethics
 
-`Knowledge/` is shared with the team. Every entry obeys the KB's integrity
-rules: objective and factual, work-relevant, no personal judgments. Assume the
-person a note is about will read its changelog entry. Describe
-**what changed in the graph**, not opinions about the people in it.
+The team shares each tier with its own audience. Every entry obeys the KB's
+integrity rules: objective and factual, work-relevant, no personal judgments.
+Assume the person a note is about will read its changelog entry. Describe
+**what changed in the graph**. Do not record opinions about the people in it.
 
 <do_confirm_checklist goal="Verify the changelog is accurate and shareable">
 
-- [ ] Exactly one `Knowledge/CHANGELOG.md`; no stray per-folder changelogs.
-- [ ] Every entry names its **Scope** — the specific note(s) or folder(s)
-      touched, by full path.
-- [ ] Each entry has **Who** (author, from identity), **What**, and **Why**.
-- [ ] Descriptions are specific enough to be useful (not "updated some notes").
-- [ ] Dates are the date the change was actually made, not guessed.
-- [ ] No duplicate entries for a change already in the changelog.
-- [ ] Entries are factual and would be fine for the subject to read.
+- [ ] Keep exactly one `CHANGELOG.md` per shared tier, at the tier root.
+      Leave no stray per-folder changelog and none in `0-Draft/`.
+- [ ] Route every entry to the changelog of the tier that holds the changed
+      note. Never name a narrower tier's note in a wider tier's changelog.
+- [ ] Write every entry as **one line**: type, **Scope** (tier-prefixed
+      paths), **Who**, and a short pointer. No `What:`/`Why:` blocks.
+- [ ] Make the pointer specific enough to locate the change (never "updated
+      some notes").
+- [ ] Use the real date of each change. Never guess a date.
+- [ ] Add no duplicate entry for a change already in the changelog.
+- [ ] Keep every entry factual and fit for the subject to read.
+- [ ] Stamp the frontmatter core (`type: changelog`, `created`, `updated`) on
+      a changelog you create; stamp `updated` on one you edit.
+- [ ] Keep each file short (see Step 5). Compact or drop old entries when it
+      grows.
 
 </do_confirm_checklist>
 
@@ -63,31 +82,33 @@ person a note is about will read its changelog entry. Describe
 ### 1. Find what's already recorded, and who you are
 
 ```bash
-head -30 Knowledge/CHANGELOG.md 2>/dev/null     # newest date already logged, if any
-cat "$HOME/.cache/fit/outpost/state/identity.md"  # Name → the author for this session's entries
+head -30 3-Team/CHANGELOG.md 2>/dev/null          # per tier you changed
+cat "$HOME/.cache/fit/outpost/state/identity.md"  # Name → the author
 ```
 
 If `identity.md` is missing or stale, run the `person-identify` skill to refresh
-it before logging — don't guess the author.
+it before you log the changes. Never guess the author.
 
 ### 2. Reconstruct this session's changes
 
-Recall every change made to `Knowledge/` during the current conversation:
-creations, edits, removals, renames. Group them by note. If you are unsure a
-change landed, confirm it before logging:
+Recall every change you made to the shared tiers during the current
+conversation: creations, edits, removals, and renames. Group them by note,
+then by tier. If you are unsure that a change landed, confirm it before you
+log it:
 
 ```bash
-rg --files Knowledge/ | rg "<note name>"        # confirm a note exists
-cat "Knowledge/People/Doe, Jane.md"             # confirm content landed
+rg --files [0-9]-*/ | rg "<note name>"            # confirm a note exists
+cat "3-Team/People/Doe, Jane.md"                  # confirm content landed
 ```
 
-Optionally surface anything edited recently that you might have missed:
+Optionally, surface anything you edited recently and might have missed:
 
 ```bash
-find Knowledge -name '*.md' -newermt '-1 day' -not -path '*/.*'
+find [0-9]-* -name '*.md' -newermt '-1 day' -not -path '*/.*'
 ```
 
-Use `Knowledge/CHANGELOG.md` only to avoid duplicating an entry already there.
+Use each tier's `CHANGELOG.md` only to avoid a duplicate of an entry already
+there.
 
 ### 3. Classify each change
 
@@ -98,39 +119,73 @@ Use `Knowledge/CHANGELOG.md` only to avoid duplicating an entry already there.
 | `removed`  | Note deleted                         |
 | `renamed`  | Note renamed or moved                |
 
-Related changes that form one logical edit (e.g. a new project note plus the
-backlinks added to the people it involves) are recorded as **one entry** whose
-Scope lists every note touched.
+Some related changes form one logical edit. An example is a new project note
+plus the backlinks to the people it involves. Record these as **one entry**
+when they live in one tier. Changes that span tiers split into one entry per
+tier, each naming only that tier's notes.
 
 ### 4. Write the changelog
 
-Create or update `Knowledge/CHANGELOG.md` (newest first). Group entries under
-one heading per day; one bullet per logical change:
+Create or update the changed tiers' `CHANGELOG.md` files (newest first).
+Group entries under one heading per day. Write one bullet per logical change.
+A new changelog opens with the frontmatter core (`type: changelog`,
+`created`, `updated`); an edited one gets a fresh `updated`.
 
 ```markdown
-# Knowledge Changelog
+---
+type: changelog
+created: 2026-01-01
+updated: 2026-01-01
+---
+
+# Team Changelog
 
-Changes to the shared knowledge graph, newest first. Maintained by hand at the
-end of editing sessions via the `changelog` skill. The KB is not
-version-controlled, so this is the record of what changed and why.
+Terse, newest-first pointers to changes in this tier. This is a hint for
+teammates who sync the same files, not a precious record. The `changelog`
+skill maintains it, and compacts and drops old entries as the file grows.
 
 ## <YYYY-MM-DD>
 
-- **<added | modified | removed | renamed>** — _<Scope: full path(s)>_ · <Who>
-  **What:** <one-line summary of the change.>
-  **Why:** <the reason — the email, meeting, or request that prompted it.>
+- **<added | modified | removed | renamed>** — _<Scope: tier-prefixed path(s)>_ · <Who> — <short pointer: what changed, and why only if it isn't obvious.>
 ```
 
-Use the real date the change was made (today's date is in context) and the
-**Name** from `identity.md` as `<Who>`. Because the file is shared, the author
-travels on each entry — not just the day's heading — so a day with edits from
-more than one teammate stays unambiguous. Keep each entry to its What and Why —
-this is a ledger, not a diff.
+**Keep entries brief — a pointer, not a summary.** One line each. State the
+type, the scope (tier-prefixed paths), the author, and a short clause that
+lets a teammate find the change and grasp its gist. Do **not** reproduce the
+content of the edit. If someone needs the detail, they open the note.
+
+Use the real date of the change (today's date is in context). Use the **Name**
+from `identity.md` as `<Who>`. The team shares the file, so the author travels
+on each entry.
+
+Collapse related same-tier edits into one line. Several notes touched for one
+purpose, or the same note created-then-reworked in a session, is a single
+entry. Combine the types (e.g. `**added / renamed**`) and name the notes in
+the scope.
+
+### 5. Compact each file when it grows
+
+A changelog is a **disposable hint file, not an archive**. The notes
+themselves are the record. Keep it short. After you add this session's
+entries, compact the file in the same pass when it has grown large (rough
+guide: **more than ~150 lines, or older than ~2 months of daily headings**):
+
+- **Roll up old days.** Fold each day older than ~2 weeks into one or two
+  thematic lines per author.
+- **Merge iterative churn.** Collapse a run of edits to the same file or
+  topic into a single line that describes the net result.
+- **Drop the stale tail.** Delete day headings older than ~2–3 months
+  outright. The change already lives in the notes.
+
+Be aggressive: losing granularity here costs nothing. Never rewrite an entry
+to say something the edit did not do. Do not drop a *recent* change just to
+save space.
 
 ## Notes
 
-- This skill **documents only** — it records changes already made; it does not
-  make or undo edits.
-- One `Knowledge/CHANGELOG.md` at the graph root, never per-folder.
+- This skill **documents only**. It records changes you already made. It does
+  not make or undo edits.
+- One `CHANGELOG.md` per shared tier, at the tier root, never per-folder.
 - For changes to instructions (`CLAUDE.md`, agents, skills), use
-  `upstream-instructions` instead.
+  `upstream-instructions` instead; its root `CHANGELOG.md` is a separate
+  personal artifact.