claude-dev-env 1.41.0 → 1.43.0

package/skills/session-log/SKILL.md

@@ -1,84 +1,76 @@
 ---
 name: session-log
 description: >-
-  Log a session report as a styled HTML file in the vault, track vault context usage, extract unrecorded decisions, tidy the project's session folder, publish via /doc-gist as a shareable webpage, and output a /rename command. Use when the user says /session-log, journal this session, log this work, session report, or any variation of "summarize/log/record this session". Also triggers on "save session", "capture session", or "document what we did".
+  Log a session report by handing the HTML authorship to doc-gist (which designs fresh per session and auto-publishes via the `<!-- @publish-as-gist -->` marker hook), then track vault context, extract unrecorded decisions, tidy the project's session folder, and output a /rename command. Use when the user says /session-log, journal this session, log this work, session report, or any variation of "summarize/log/record this session". Also triggers on "save session", "capture session", or "document what we did".
 ---
 
 # Session Log
 
 ## Overview
 
-Write a structured session report as HTML, then run vault context tracking, decision extraction, session tidying, publish via /doc-gist, and finalize with a /rename clipboard hand-off.
+The HTML artifact is doc-gist's job end-to-end. Session-log owns everything around it: where the file lives in the vault, what number it gets, the frontmatter metadata contract, post-write vault tracking, decision extraction, project-folder hygiene, and the closing `/rename` hand-off.
 
 **Announce at start:** "I'm logging this session."
 
-This skill runs as a 6-step workflow. Every step runs automatically -- no user prompts between steps except where noted.
+## Why this skill delegates HTML to doc-gist
 
-## Gotchas
+Sessions come in many shapes — convergence loops, feature builds, research dives, incidents, refactors, decisions. A single h2-emoji-list template forces every session into the same form regardless of fit, and the artifact reads as a process log rather than a substance log. Doc-gist's principle: *"design fresh per request, drawing on a gallery of 20 HTML shape patterns."* Each session report gets the shape that fits the session.
 
-- **HTML output, not Markdown.** The repo's `md_to_html_blocker` PreToolUse hook rejects Write/Edit on `.md` files outside `.claude/` directories. Headless vault paths (e.g., `$OBSIDIAN_VAULT_PATH`) resolve outside `.claude/`, so session reports use HTML. (The local vault at `~/.claude/vault/` is exempt, but HTML is the uniform format regardless of backend.)
-- **Avoid historical and comparative language.** The `state_description_blocker` hook enforces this for markdown and code files. While the hook does not scan `.html`, the same present-tense, current-state style applies to session reports. The trigger pattern set lives in `~/.claude/rules/no-historical-clutter.md`.
-- **doc-gist uses `--description` for gist title text.** `gist_upload.py` uploads HTML verbatim with no content parsing. Pass `--description "Session [N] — [Title]"` to set the gist description.
-- **doc-gist preview URL takes a few seconds.** The htmlpreview.github.io renderer fetches the raw gist on first hit. Quote both URLs and tell the user to refresh once if the page is blank.
-- **gh must be authenticated.** Running gist_upload.py with `gh` unauthenticated prints the auth prompt and exits non-zero. Surface that message to the user; the local HTML file in the vault is still the canonical artifact, so Step 6 still runs.
-- **Obsidian frontmatter index is sacrificed.** Obsidian's native YAML-frontmatter parser reads only `.md` files. HTML files do not appear in the Obsidian UI's frontmatter index. Search by content still works; search by `type: session-report` does not.
-- **Existing files require the Edit tool.** The `write_existing_file_blocker` hook rejects the Write tool on existing paths. Use Write only when creating a fresh session report; use Edit for Step 2's append and Step 4's auto-fixes.
+The gallery lives at `~/.claude/skills/doc-gist/references/examples/`. Patterns that usually fit session reports:
 
-## Backend Detection (run before Step 1)
+| Session character | Gallery shape to study |
+|---|---|
+| Feature build / PR ships | `17-pr-writeup.html` |
+| Incident, debugging arc, convergence loop | `12-incident-report.html` |
+| Status update / weekly progress | `11-status-report.html` |
+| Implementation plan or decision record | `16-implementation-plan.html` |
+| Exploration of multiple approaches | `01-exploration-code-approaches.html` |
+| Code-explainer with module map | `04-code-understanding.html` |
 
-Determine which storage backend is available. Try in this order and use the first that succeeds:
+The session designer reads the matching gallery file, then designs the report in that shape. **Adapt, do not copy.**
 
-1. **Headless vault** -- run `ob --version` via Bash to verify the obsidian-headless CLI is installed. Then check `OBSIDIAN_VAULT_PATH` environment variable or `~/.claude/vault/` for a vault directory. If the CLI exists and a vault directory resolves, optionally run `ob sync-status --path <vault-path>` to verify sync is active. Set `backend = "headless"`.
+## Gotchas
 
-2. **Local vault** -- fall back to `~/.claude/vault/` as a local vault directory. Create it via `mkdir -p ~/.claude/vault/sessions` if it does not exist. Set `backend = "local"`. This provides a working vault structure that can be upgraded to headless sync later.
+- **Doc-gist's auto-publish hook fires on Write/Edit of any HTML containing `<!-- @publish-as-gist -->`.** Session-log composes the HTML with the marker so auto-publish runs by default — sessions are intended for sharing with collaborators. The hook prints the gist + preview URLs to tool output; capture both.
+- **`gh` must be authenticated.** Auto-publish runs `gh gist create`. If `gh` is unauthenticated, `gh gist create` writes its error message; `gist_upload.py` surfaces it from stderr when present and falls back to stdout when stderr is empty (so the error always appears somewhere in the tool result). The hook exits 0 (does not block the Write). Look at the full tool result, then surface the error to the user; the local vault HTML is still the canonical artifact, so the remaining steps still run.
+- **Vault paths sit outside `.claude/`.** Headless vault paths (e.g., `$OBSIDIAN_VAULT_PATH`) resolve outside the project tree. The `md_to_html_blocker` PreToolUse hook blocks `.md` writes unless the path is exempt — exemptions include any path containing `/.claude/` and README/CHANGELOG files at repo root. Session reports use HTML, which the hook ignores entirely.
+- **Sessions describe current state by convention.** The state_description_blocker hook does not scan .html, but the rule at `~/.claude/rules/no-historical-clutter.md` applies as a writing standard — skip historical and comparative language when composing the report; the rule file lists the full trigger set.
+- **`write_existing_file_blocker` rejects Write on existing paths.** Use Write only when creating a fresh session report; use Edit for the vault-context append in step 3.
+- **Each Write/Edit of the marked HTML creates a fresh gist with a new ID.** `gist_upload.py` calls `gh gist create` with no lookup of any prior gist. Step 3 performs two Edits and Step 5's tidy may Edit the current session a third time — each Edit produces a different gist URL than its predecessor. Quote the URLs from the FINAL publish (the most recent auto-publish run for the session being created — the second Step-3 Edit when Step 5 does not touch the current session, or the Step 5 Edit when it does) to the user; never embed a URL inside the HTML that a later Edit then re-publishes.
+- **Obsidian frontmatter index is HTML-blind.** Obsidian's native YAML-frontmatter parser reads only `.md` files. HTML files do not appear in Obsidian's frontmatter index. Search by content still works; search by `type: session-report` does not.
+- **Auto-published gists carry the default `gist_upload.py` description (`HTML artifact`), not a session-specific title.** The auto-publish hook invokes `gist_upload.py` with only `--input` and `--no-open` — it has no session-title context to pass as `--description`. Browsing or sharing gists, operators see "HTML artifact" rather than `Session [N] — [Title] — session-log — [Project]`. Workaround: after the canonical Edit completes, edit the existing gist's description in place with `gh gist edit <gist-id> --desc "Session [N] — [Title] — session-log — [Project]"` (this updates the existing gist's metadata; no new gist ID is created) if a meaningful title matters for that share. The HTML frontmatter inside the file remains the authoritative session metadata regardless of the gist's external description.
+
+## Backend Detection (run before Step 1)
 
-**Backend capabilities:**
+Determine which storage backend is available. First success wins.
 
-| Capability | headless | local |
-|---|---|---|
-| Write session reports | Write tool to `.html` path | Write tool to `.html` path |
-| Search prior sessions | Bash `ls` + Grep | Bash `ls` + Grep |
-| Session number detection | parse filenames | parse filenames |
-| Frontmatter | YAML inside HTML comment | YAML inside HTML comment |
-| Sync | Obsidian Sync | none (local only) |
+1. **Headless vault** — Bash `ob --version` to verify the obsidian-headless CLI is installed. Check `OBSIDIAN_VAULT_PATH` env var or `~/.claude/vault/` for a vault directory. When the CLI check succeeds AND at least one of those paths resolves to a vault directory, set `backend = "headless"`.
+2. **Local vault** — fall back to `~/.claude/vault/`. Create `~/.claude/vault/sessions` via `mkdir -p` if missing. Set `backend = "local"`.
 
-**Session number detection:**
-- List files in the project directory via Bash `ls`
-- Parse filenames matching `[N]. *.html` or `[N]. *.md` to preserve sequence across the format migration
-- Highest N + 1. If directory does not exist, create it and start at 1
+**Session-number detection:** Bash `ls` the project's session folder, parse filenames matching `[N]. *.html` or `[N]. *.md` to preserve sequence across the format migration. Highest N + 1. New project → start at 1.
 
 **Output paths:**
 - headless: `$OBSIDIAN_VAULT_PATH/sessions/[Project]/[N]. [Title].html` (falls back to `~/.claude/vault/` when the env var is unset)
 - local: `~/.claude/vault/sessions/[Project]/[N]. [Title].html`
 
-Announce the backend: "Using headless vault at [path]." or "Using local vault at ~/.claude/vault/. Run `/obsidian-check` for upgrade options."
+Announce the backend: "Using headless vault at [path]." or "Using local vault at ~/.claude/vault/. Install obsidian-headless and set the `OBSIDIAN_VAULT_PATH` environment variable (PowerShell: `$env:OBSIDIAN_VAULT_PATH = '<path>'`; POSIX shells: `export OBSIDIAN_VAULT_PATH=<path>`) to enable sync."
 
 ---
 
-## Step 1: Write Session Report (HTML)
+## Step 1: Compose Session Metadata
 
-1. Review the conversation to identify: key outcomes, blockers, decisions, and next steps.
+Review the conversation to identify the session's primary outcome and the small set of facts a cold reader needs.
 
-2. Determine session metadata:
-   - **Project name:** infer from conversation context
-   - **Session number:** list the project's vault folder via Bash `ls`, parse `[N]. *.html` and `[N]. *.md` filenames, take highest+1. If no prior sessions, start at 1.
-   - **Date:** today's date
-   - **Title:** a 2-5 word summary of the session's primary outcome or focus area. Pick the single most important thing that happened. Examples: "Amazon Auth Migration", "Source Loading Fix", "Vault Reorganization". Avoid generic titles like "Bug Fixes" or "Various Updates".
+Resolve the metadata used by the frontmatter and the vault path:
 
-3. **Write to the vault path** via the Write tool. Create the project directory via `mkdir -p` if it does not exist. If the write fails, output the content in the conversation so the user can copy it manually. Skip Steps 2-5 and go directly to Step 6.
+- **Project name:** infer from conversation context
+- **Session number:** from backend detection above
+- **Date:** today's date
+- **Title:** a 2–5 word summary of the session's primary outcome. Examples: "Amazon Auth Migration", "Source Loading Fix", "PR 475 Convergence". Avoid generic titles like "Bug Fixes".
 
-### Vault Format -- HTML Session Report
-
-The vault note is a self-contained HTML file. Frontmatter lives inside an HTML comment so it is human-readable but does not affect rendering. Styling is minimal so doc-gist's template wraps the body cleanly in Step 5.
+The frontmatter contract every session report carries (inside an HTML comment, as the first child of `<body>`):
 
 ```html
-<!DOCTYPE html>
-<html lang="en">
-<head>
-<meta charset="utf-8">
-<title>Session [N] — [Title]</title>
-</head>
-<body>
 <!--
 type: session-report
 project: [name]
@@ -86,253 +78,126 @@ session: [N]
 date: [YYYY-MM-DD]
 status: completed|in-progress|blocked
 blocked: true|false
-tags: [session, [project-tag]]
+vault_context_retrieved: true|false
+tags: [session, [project-tag], [topic-tags]]
 -->
-
-<h1>Session [N] Report — [Month Day, Year]</h1>
-
-<h2>[emoji] [Section Title]</h2>
-<p>[1-3 sentence explanation of what happened and why it matters]</p>
-<ul>
-  <li><strong>[Label]:</strong> [detail]</li>
-</ul>
-<p><strong>Fix:</strong> [what was done]</p>
-
-<h2>[emoji] [Section with tabular data]</h2>
-<p>[Context sentence]</p>
-<table>
-  <thead><tr><th>#</th><th>Item</th><th>Status</th></tr></thead>
-  <tbody>
-    <tr><td>1</td><td>...</td><td>...</td></tr>
-  </tbody>
-</table>
-
-<h2>[emoji] Notes</h2>
-<ul>
-  <li><strong>[Topic]:</strong> [detail]</li>
-</ul>
-
-</body>
-</html>
 ```
 
-### Emoji Status Indicators
+Every session report carries this metadata block verbatim so vault search and the tidy step in step 5 work. **Initial values for Step 2's Write:** substitute concrete values for every placeholder — for `vault_context_retrieved`, write the literal value `false` (the safe default before Step 3's vault-MCP-tool scan completes). Step 3 then Edits this to `true` if any of the three vault MCP tools fired this session.
 
-| Emoji | Meaning | Use when |
-|-------|---------|----------|
-| ✅ | Done/Fixed | A problem was resolved or a deliverable completed |
-| 🚫 | Blocked | Something couldn't be done (external limit, dependency, etc.) |
-| ⚠️ | Warning/Note | Important context, gotchas, or things to remember |
-| 🔧 | In Progress | Work started but not finished |
-| 📋 | Queued | Work identified but not yet started |
+## Step 2: Compose the HTML via doc-gist's shape principles
 
-### Formatting Rules
+Design the artifact for **this session's character**, drawing on the doc-gist gallery patterns listed above. The report must answer for a cold reader, from the H2 headers alone, three questions: *what shipped*, *why it matters*, *what impact it had*. Process narration (commit-by-commit walks, agent gotchas, retry counts) belongs at the end, not in the opening sections.
 
-- **Section headers** (`<h2>`) get one emoji + descriptive title
-- **Explanatory paragraphs** (`<p>`) under each header -- not just bullets. Explain what happened and why.
-- **Bold inline labels** for key facts: `<strong>Fix:</strong>`, `<strong>Account:</strong>`, etc.
-- **Tables** (`<table>`) for anything with 3+ rows of structured data (queued items, test results, file lists)
-- **Bullets** (`<ul><li>`) for lists of 2+ related items
-- **Links** (`<a href="...">`) where useful: file paths, URLs, PR links
-- **No inline `style=` attributes and no `<style>` block.** Doc-gist wraps the body in its own template; inner styles fight the wrapper.
-
-### What NOT to include
-
-- Play-by-play of debugging steps or failed approaches
-- Process narration ("First I tried X, then Y")
-- Redundant sections -- if nothing was blocked, skip the blocked section
-- Historical or comparative language — see `~/.claude/rules/no-historical-clutter.md` for the trigger pattern set. The `state_description_blocker` hook rejects writes containing these patterns in markdown/code; the same rule applies to session report HTML.
-
-### Example
+**Required somewhere in the HTML (commonly in `<head>`):** the auto-publish marker.
 
 ```html
-<!DOCTYPE html>
-<html lang="en">
-<head>
-<meta charset="utf-8">
-<title>Session 6 — Developer Docs Sources Fixed</title>
-</head>
-<body>
-<!--
-type: session-report
-project: claude-academy
-session: 6
-date: 2026-03-27
-status: completed
-blocked: false
-tags: [session, claude-academy]
--->
+<!-- @publish-as-gist -->
+```
 
-<h1>Session 6 Report — March 27, 2026</h1>
+The marker triggers the PostToolUse hook after Write or Edit — the hook scans the entire HTML for the literal sentinel string and uploads the file to a secret gist, then prints the gist + preview URLs to your tool output. The marker must be the literal comment text exactly; whitespace inside breaks it.
 
-<h2>✅ Developer Docs Sources Fixed</h2>
-<p>Both Developer Docs notebooks load fully with working sources:</p>
-<ul>
-  <li><strong>Notebook #28 — Building with Claude &amp; Tools:</strong> 52 sources loaded (all green)</li>
-  <li><strong>Notebook #29 — Agent SDK &amp; Testing:</strong> 49 sources loaded (all green)</li>
-</ul>
-<p><strong>Fix:</strong> Use <code>docs.anthropic.com/en/docs/X</code> URLs (drop the .md extension, swap domain). Tested one URL first, then bulk-loaded.</p>
+**Required at the top of `<body>`:** the frontmatter HTML comment from step 1.
 
-<h2>🚫 Audio Generation Blocked</h2>
-<p>All 10 Audio Overviews are ready to generate but hit the daily limit wall.</p>
+**Required as the first content section:** an opening "What this session shipped" paragraph + bullets — written so a reader with zero prior context understands the outcome. For continuation sessions (where the substantive work landed in a prior session), recap the parent session's outcome briefly so the report stands alone.
 
-<h2>⚠️ Session 7 Notes</h2>
-<ul>
-  <li><strong>Account:</strong> Notebooks live under secondary@example.com (authuser=1), NOT the default primary@example.com.</li>
-  <li><strong>Audio budget:</strong> Once the 24h window resets, all 10 overviews fit within the 20/day Pro limit.</li>
-</ul>
+**Required: self-contained HTML.** Embed all styles in a `<style>` block inside `<head>` (inline `style="..."` attributes are also fine if preferred); no `./relative/paths` to local assets. Doc-gist's transport sends a single HTML file with no neighbors, so any relative-path reference (CSS, JS, images) cannot resolve and the asset will be missing from the preview. Absolute external URLs (CDN-hosted assets, image hotlinks) work but add an external dependency the report should not need — design the report to stand alone with no external dependencies.
 
-</body>
-</html>
-```
+Beyond those four requirements, design the shape that fits. A convergence loop session reads naturally as an incident timeline (`12-incident-report.html`); a feature build reads as a PR writeup (`17-pr-writeup.html`); a research session reads as a feature explainer (`14-research-feature-explainer.html`). Read the matching gallery entry for typography, palette, spatial idioms — adapt, do not copy.
 
----
+**Write the file** via the Write tool to the vault path. Create the project directory via `mkdir -p` if it does not exist. The auto-publish hook fires after the Write completes and prints a gist + preview URL pair to tool output (the bare preview URL on stdout; both labeled `Gist: <url>` and `Preview: <url>` lines on stderr — both streams appear in the agent's tool-result). Step 3 performs **two Edit calls** and each one re-fires the hook with a fresh URL pair — only the URL pair from the second (final) Step-3 Edit is canonical for the just-created session (the step-2 pair and the first step-3 pair are orphaned the moment the next Edit lands). Always quote the URL pair from the **most recent auto-publish run for the session being created**. Note: Step 5's tidy audits every `.html` file in the project folder including the just-created session, so if Step 5's frontmatter auto-fix touches the current session, the Step 5 republish URL pair becomes the new canonical pair for that session (re-quote it to the user with a "Session republished — new preview: <url>" line). The second Step-3 Edit's URL pair stays canonical only when Step 5 does not touch the current session.
 
-## Step 2: Vault Context Tracking
+**If the Write fails**, output the HTML content in the conversation so the user can copy it manually. Before emitting the HTML to chat, resolve the `vault_context_retrieved` placeholder to `true` or `false` based on the same vault-MCP-tool scan that Step 3 would have run, and include the matching vault-context `<li>` line (Retrieved or Not retrieved) so the emitted HTML is a valid copy-paste artifact with complete frontmatter. Skip Step 3 and continue at step 4.
 
-This step runs automatically after Step 1 completes.
+## Step 3: Vault Context Tracking
 
-1. **Check vault context usage.** Review the conversation history for any use of these MCP tools (excluding this skill's own calls during Step 1):
-   - `mcp__obsidian__search_notes`
-   - `mcp__obsidian__read_note`
-   - `mcp__obsidian__read_multiple_notes`
+This step runs automatically after step 2.
 
-   Track whether vault context was used and which notes were read (if any). This determines the Notes line appended in step 2.
+Review the conversation history for any use of these vault MCP tools (look only at tool calls the session made before /session-log itself ran):
 
-2. **Append a tracking line to the Notes section** via the Edit tool. Target the closing `</ul>` of the last `<h2>...Notes</h2>` block:
-   - If retrieved: `<li><strong>Vault context:</strong> Retrieved ([list of note paths])</li>`
-   - If not retrieved: `<li><strong>Vault context:</strong> Not retrieved</li>`
+- `mcp__obsidian__search_notes`
+- `mcp__obsidian__read_note`
+- `mcp__obsidian__read_multiple_notes`
 
-   If no Notes section exists, append a fresh one before `</body>`:
-   ```html
-   <h2>⚠️ Notes</h2>
-   <ul>
-     <li><strong>Vault context:</strong> Not retrieved</li>
-   </ul>
-   ```
+Edit the vault HTML via two Edit calls (each Edit re-fires the auto-publish hook and creates a fresh gist; **the URL pair from the second/final Edit is canonical** — the first Edit's URLs are orphaned the moment the second Edit lands):
 
----
+1. Set the frontmatter `vault_context_retrieved` field to `true` when any of the three tools fired this session, `false` otherwise.
+2. Append one fact — vault-context status — into whatever section the report designer placed for notes / metadata / references. If the report has no such section, append a fresh `<h2>Notes</h2>` block before `</body>`:
 
-## Step 3: Decision Extraction
+```html
+<h2>Notes</h2>
+<ul>
+  <!-- Pick exactly one of the two forms based on whether vault MCP tools fired this session: -->
+  <li><strong>Vault context:</strong> Retrieved ([list of note paths])</li>
+  <li><strong>Vault context:</strong> Not retrieved</li>
+</ul>
+```
 
-This step runs automatically after Step 2 completes.
+If the report already has a notes / references section, use Edit to insert one matching child element at the end of that section. The element shape mirrors whatever the section already uses: an extra `<li>` before the closing `</ul>` for a list, an extra `<dt>Vault context</dt><dd>…</dd>` pair before the closing `</dl>` for a description list, an extra `<p><strong>Vault context:</strong> …</p>` before the section's closing tag for a paragraph-based section. Pick the form that matches the surrounding markup.
 
-Scan the conversation for decisions, gotchas, or architectural choices that were not already saved via `/remember` or to memory. For each one found, ask the user:
+The gist URL stays out of the HTML body on purpose: each Edit re-fires the auto-publish hook and produces a brand-new gist ID, so any URL embedded in the file becomes stale the instant the next Edit lands. The canonical gist + preview URL is the pair from **the most recent auto-publish run that touched the current session report** — typically the second (final) Step-3 Edit, but the Step 5 Edit takes over as canonical when Step 5's frontmatter auto-fix edits the current session (re-quote the Step 5 pair with a "Session [N] republished — new preview: <url>" line per the Step 2 guidance at line 107). Quote whichever pair is most recent when announcing the report.
 
-> "I noticed this decision: [summary]. Want me to save it to the vault with /remember?"
+## Step 4: Decision Extraction
 
-Only write decision notes the user confirms. If no unrecorded decisions are found, skip silently.
+Scan the conversation for decisions, gotchas, or architectural choices that were not already saved via `/remember`. For each one found, ask the user via `AskUserQuestion`:
 
----
+> "I noticed this decision: [summary]. Save it to the vault via `/remember`?"
 
-## Step 4: Session Tidy (Project Scope)
+Only invoke `/remember` for decisions the user confirms; `/remember` writes the decision as a vault note. If no unrecorded decisions are found, skip silently.
 
-This step runs automatically after Step 3 completes. Scope: the current project's session folder only.
+## Step 5: Session Tidy (Project Scope)
 
-1. **List files** in the project's vault session folder via Bash `ls`.
+Scope: the current project's session folder only.
 
+1. **List files** in the project's vault session folder via Bash `ls`.
 2. **Quick audit** each `.html` file for:
    - **Naming convention:** must match `[N]. [Title].html`
-   - **Frontmatter completeness:** HTML comment block at top contains `type`, `project`, `session`, `date`, `status`, `blocked`, `tags`
+   - **Frontmatter completeness:** HTML comment block at top of `<body>` contains `type`, `project`, `session`, `date`, `status`, `blocked`, `vault_context_retrieved`, `tags`
    - **Status coherence:** `status: completed` with `blocked: true` is contradictory. `status: in-progress` or `status: blocked` on sessions older than 7 days is stale.
-
-3. **Auto-fix minor issues silently** via Edit tool:
-   - Missing frontmatter fields that can be inferred (e.g., `blocked: false` when status is `completed`)
+3. **Auto-fix minor issues** via Edit:
+   - Missing frontmatter fields that can be inferred (e.g., `blocked: false` when status is `completed`; `vault_context_retrieved: false` when the field is absent, since the field defaults to false in pre-existing sessions)
    - `type` field set to a wrong value (correct to `session-report`)
 
+   Each Edit on a marked HTML file re-fires doc-gist's auto-publish hook and produces a fresh gist + preview URL pair in the agent's tool output (the bare preview URL on stdout; both labeled `Gist: <url>` and `Preview: <url>` lines on stderr) — the prior gist URL becomes orphaned. Surface a `Session [N] republished — new preview: <url>` line per Edit so the user can update any prior shares.
 4. **Report issues that need user input:**
    - Files with wrong naming convention (propose new name)
    - Stale statuses (propose update to `completed` or ask)
    - Contradictory status/blocked combos
 
    If no issues are found, skip silently. Do not report "all clean."
-
 5. **Rollup check:** if the project has 5+ sessions and no `Summary.html` or `Summary.md`, mention it:
-   > "This project has [N] sessions and no summary. Run `/session-tidy` for a full rollup."
-
----
-
-## Step 5: Publish via /doc-gist
-
-This step runs automatically after Step 4 completes.
-
-### 5a. Run gist_upload.py
-
-Hand the freshly-written HTML file to `/doc-gist` via its gist_upload.py script. Use the PowerShell tool so quoting handles spaces in the vault path:
-
-```powershell
-python "$HOME/.claude/skills/doc-gist/scripts/gist_upload.py" `
-  --input "<absolute path to the .html file>" `
-  --description "Session [N] — [Title] · session-log · [Project]"
-```
-
-Replace the bracketed values from Step 1's metadata. The script writes a temp copy, uploads as a secret gist, and prints two URLs to stderr — capture both:
-
-- **Preview:** `https://htmlpreview.github.io/?https://gist.githubusercontent.com/...`
-- **Gist:** `https://gist.github.com/...`
-
-Quote both URLs back to the user as clickable links.
-
-**If gh is not authenticated**, gist_upload.py exits non-zero with the `gh auth login` prompt. Surface that message to the user, skip 5b, and continue with Step 6 — the vault HTML is the canonical artifact. The publish step is a hand-off, not a gate.
-
-**If the browser should not open automatically**, append `--no-open`. The gist still publishes; only the auto-open is suppressed.
+   > "This project has [N] sessions and no summary. A rollup would help; `/session-tidy` is defined for the Markdown session format and may mis-audit or propose destructive renames against HTML sessions, so a manual rollup is the safe path."
 
-### 5b. Inject the gist URL back into the session log
-
-After 5a succeeds, edit the vault HTML to embed the Preview URL inside the Notes section so future readers of the local file can jump to the published gist. Use the Edit tool with the absolute path from Step 1.
+## Step 6: Finalize
 
-Target: the closing `</ul>` of the last `<h2>...Notes</h2>` block. Insert this line directly before it:
+Copy a `/rename` command to the user's clipboard via PowerShell:
 
-```html
-  <li><strong>Published as:</strong> <a href="<preview URL from 5a>">gist preview</a></li>
 ```
-
-If the file has no Notes section, append a fresh one before `</body>`:
-
-```html
-<h2>⚠️ Notes</h2>
-<ul>
-  <li><strong>Published as:</strong> <a href="<preview URL from 5a>">gist preview</a></li>
-</ul>
+pwsh -NoProfile -Command "Set-Clipboard '/rename [Project] - [Primary Outcome]'"
 ```
 
-The vault HTML now contains the gist URL inline. Subsequent re-publishes will overwrite the entry only if step 5b is rerun with the new URL — the safe path is to leave the first entry as-is unless the user explicitly asks for a re-publish.
-
----
-
-## Step 6: Finalize
-
-Copy a `/rename` command to the user's clipboard via Bash: `echo -n "/rename [Project] - [Primary Outcome]" | clip.exe`. Then tell the user:
+Then tell the user:
 
 > "Copied `/rename [Project] - [Primary Outcome]` to your clipboard. Paste it to rename this session."
 
-The primary outcome comes from the session title determined in Step 1.
+The primary outcome comes from the session title resolved in step 1.
 
 ---
 
-## Best Practices
-
-- Each section in the session report is an outcome, not a process step ("Sources Fixed" not "We debugged source loading")
-- Body should be self-contained -- no context needed beyond the note itself
-- If the session was exploratory with no concrete outcome, use 🔧 or 📋 sections to describe what was investigated and what's next
-- Keep it scannable: a reader should grasp the session in 15 seconds from headers alone
-- Tables are powerful -- use them whenever you have structured data (queued work, test results, file inventories)
-- Skip inline styling. Doc-gist's template provides the visual rhythm; semantic HTML (h1/h2/p/ul/table) carries the structure.
-
 ## Run-and-report checklist
 
-Copy and check off:
-
 - [ ] Backend detected and announced
-- [ ] Session number resolved from `[N]. *.html` files
-- [ ] HTML written to vault path (Write tool, fresh path)
-- [ ] Vault context line appended to Notes section (Edit tool)
+- [ ] Session number resolved from `[N]. *.html` and `[N]. *.md` files (both parsed to preserve sequence across the format migration)
+- [ ] HTML composed via doc-gist's shape principles (gallery-anchored)
+- [ ] `<!-- @publish-as-gist -->` marker present somewhere in the HTML
+- [ ] Frontmatter HTML comment present at top of `<body>`
+- [ ] Opening section answers "what shipped / why / impact" for a cold reader
+- [ ] Self-contained HTML (no relative-path asset refs; avoid external dependencies)
+- [ ] Auto-publish URLs captured from step 2 and step 3 (or HTML emitted to chat when step 2 Write failed)
+- [ ] Vault-context line appended via Edit (step 3); URL pair from the most recent auto-publish run for the current session quoted to the user (typically the final Step-3 Edit, but the Step 5 republish takes over when Step 5 edits the current session)
 - [ ] Decision extraction surfaced any unrecorded items
 - [ ] Session tidy reported anomalies or stayed silent
-- [ ] doc-gist publish script invoked with `--input` and `--description`
-- [ ] Preview URL and Gist URL quoted to the user
-- [ ] Preview URL injected back into the vault HTML's Notes section
-- [ ] /rename command copied to clipboard via `clip.exe`
+- [ ] `/rename` command copied to clipboard via `pwsh Set-Clipboard`
 
 ## Folder map
 

package/_shared/pr-loop/scripts/config/claude_permissions_constants.py

@@ -1,36 +0,0 @@
-"""Constants shared by grant_project_claude_permissions and revoke_project_claude_permissions."""
-
-from pathlib import Path
-
-from config.preflight_constants import GIT_DIRECTORY_NAME
-
-__all__ = (
-    "ALL_PERMISSION_ALLOW_TOOLS",
-    "AUTO_MODE_ENVIRONMENT_ENTRY_TEMPLATE",
-    "CLAUDE_SETTINGS_DIRECTORY_NAME",
-    "CLAUDE_SETTINGS_FILENAME",
-    "GIT_DIRECTORY_NAME",
-    "TEXT_FILE_ENCODING",
-    "UNIQUE_TEMPORARY_SUFFIX_BYTE_LENGTH",
-    "get_claude_user_settings_path",
-)
-
-
-ALL_PERMISSION_ALLOW_TOOLS: tuple[str, ...] = ("Edit", "Write", "Read")
-
-AUTO_MODE_ENVIRONMENT_ENTRY_TEMPLATE: str = (
-    "Trusted local workspace: {project_path}/.claude/** is the user's "
-    "project Claude Code config tree; edits inside are routine"
-)
-
-CLAUDE_SETTINGS_DIRECTORY_NAME: str = ".claude"
-
-CLAUDE_SETTINGS_FILENAME: str = "settings.json"
-
-TEXT_FILE_ENCODING: str = "utf-8"
-
-UNIQUE_TEMPORARY_SUFFIX_BYTE_LENGTH: int = 8
-
-
-def get_claude_user_settings_path() -> Path:
-    return Path.home() / CLAUDE_SETTINGS_DIRECTORY_NAME / CLAUDE_SETTINGS_FILENAME

package/hooks/config/pr_description_enforcer_constants.py

@@ -1,19 +0,0 @@
-"""Configuration constants for the pr_description_enforcer PreToolUse hook."""
-
-import os
-import re
-
-
-_PLUGIN_ROOT: str = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
-PR_GUIDE_PATH: str = os.path.join(_PLUGIN_ROOT, "docs", "PR_DESCRIPTION_GUIDE.md")
-
-MINIMUM_SUBSTANTIVE_PROSE_CHARS: int = 40
-
-FENCED_CODE_BLOCK_PATTERN: re.Pattern[str] = re.compile(r"```.*?```", re.DOTALL)
-INLINE_CODE_PATTERN: re.Pattern[str] = re.compile(r"`[^`]*`")
-HEADING_LINE_PATTERN: re.Pattern[str] = re.compile(r"^#+[ \t].*$", re.MULTILINE)
-BOLD_PAIR_PATTERN: re.Pattern[str] = re.compile(r"\*\*([^*]+?)\*\*")
-BULLET_MARKER_PATTERN: re.Pattern[str] = re.compile(r"^\s*[-*+]\s+", re.MULTILINE)
-BLOCKQUOTE_MARKER_PATTERN: re.Pattern[str] = re.compile(r"^\s*>\s+", re.MULTILINE)
-LINK_TEXT_PATTERN: re.Pattern[str] = re.compile(r"\[([^\]]+)\]\([^)]+\)")
-WHITESPACE_RUN_PATTERN: re.Pattern[str] = re.compile(r"\s+")

package/hooks/config/test_pr_description_enforcer_constants.py

@@ -1,82 +0,0 @@
-"""Behavior tests for pr_description_enforcer_constants module."""
-
-from __future__ import annotations
-
-import os
-import sys
-from pathlib import Path
-
-_HOOKS_ROOT = Path(__file__).resolve().parent.parent
-if str(_HOOKS_ROOT) not in sys.path:
-    sys.path.insert(0, str(_HOOKS_ROOT))
-
-from config import pr_description_enforcer_constants as constants_module
-
-
-def test_plugin_root_is_private_module_attribute() -> None:
-    assert hasattr(constants_module, "_PLUGIN_ROOT")
-    assert isinstance(constants_module._PLUGIN_ROOT, str)
-    assert os.path.isabs(constants_module._PLUGIN_ROOT)
-
-
-def test_plugin_root_public_name_is_not_exported() -> None:
-    assert not hasattr(constants_module, "PLUGIN_ROOT")
-
-
-def test_pr_guide_path_resolves_under_plugin_root_docs() -> None:
-    expected_pr_guide_path = os.path.join(
-        constants_module._PLUGIN_ROOT, "docs", "PR_DESCRIPTION_GUIDE.md"
-    )
-    assert constants_module.PR_GUIDE_PATH == expected_pr_guide_path
-
-
-def test_minimum_substantive_prose_chars_is_positive_integer() -> None:
-    assert isinstance(constants_module.MINIMUM_SUBSTANTIVE_PROSE_CHARS, int)
-    assert constants_module.MINIMUM_SUBSTANTIVE_PROSE_CHARS > 0
-
-
-def test_fenced_code_block_pattern_matches_triple_backtick_block() -> None:
-    sample_markdown = "before ```python\ncode\n``` after"
-    match = constants_module.FENCED_CODE_BLOCK_PATTERN.search(sample_markdown)
-    assert match is not None
-    assert match.group(0).startswith("```")
-    assert match.group(0).endswith("```")
-
-
-def test_inline_code_pattern_matches_single_backtick_span() -> None:
-    match = constants_module.INLINE_CODE_PATTERN.search("see `value` here")
-    assert match is not None
-    assert match.group(0) == "`value`"
-
-
-def test_heading_line_pattern_matches_atx_heading() -> None:
-    match = constants_module.HEADING_LINE_PATTERN.search("## Description\n")
-    assert match is not None
-    assert match.group(0).strip() == "## Description"
-
-
-def test_bold_pair_pattern_captures_inner_text() -> None:
-    match = constants_module.BOLD_PAIR_PATTERN.search("this is **bold** text")
-    assert match is not None
-    assert match.group(1) == "bold"
-
-
-def test_bullet_marker_pattern_strips_dash_bullet_from_line() -> None:
-    stripped_line = constants_module.BULLET_MARKER_PATTERN.sub("", "- first item")
-    assert stripped_line == "first item"
-
-
-def test_blockquote_marker_pattern_strips_quote_marker_from_line() -> None:
-    stripped_line = constants_module.BLOCKQUOTE_MARKER_PATTERN.sub("", "> quoted line")
-    assert stripped_line == "quoted line"
-
-
-def test_link_text_pattern_captures_anchor_text() -> None:
-    match = constants_module.LINK_TEXT_PATTERN.search("See [the docs](https://example.com) now")
-    assert match is not None
-    assert match.group(1) == "the docs"
-
-
-def test_whitespace_run_pattern_collapses_multiple_spaces() -> None:
-    collapsed_text = constants_module.WHITESPACE_RUN_PATTERN.sub(" ", "a   b\t\tc\n\nd")
-    assert collapsed_text == "a b c d"

package/skills/bugteam/scripts/config/claude_permissions_common_constants.py

@@ -1,20 +0,0 @@
-"""Configuration constants for claude_permissions_common shared helpers."""
-
-from __future__ import annotations
-
-TEXT_FILE_ENCODING: str = "utf-8"
-ALL_PERMISSION_ALLOW_TOOLS: tuple[str, ...] = ("Edit", "Write", "Read")
-AUTO_MODE_ENVIRONMENT_ENTRY_TEMPLATE: str = (
-    "Trusted local workspace: {project_path}/.claude/** is the user's "
-    "project Claude Code config tree; edits inside are routine"
-)
-ATOMIC_WRITE_TEMPORARY_SUFFIX: str = ".tmp"
-GIT_DIRECTORY_MARKER: str = ".git"
-CLAUDE_DIRECTORY_MARKER: str = ".claude"
-CLAUDE_USER_SETTINGS_FILENAME: str = "settings.json"
-DEFAULT_SETTINGS_FILE_MODE: int = 0o600
-SETTINGS_PERMISSIONS_KEY: str = "permissions"
-SETTINGS_ALLOW_KEY: str = "allow"
-SETTINGS_ADDITIONAL_DIRECTORIES_KEY: str = "additionalDirectories"
-SETTINGS_AUTO_MODE_KEY: str = "autoMode"
-SETTINGS_ENVIRONMENT_KEY: str = "environment"