@natjswenson/devlog 0.1.9 → 0.4.0

package/CHANGELOG.md

@@ -2,6 +2,78 @@
 
 All notable changes to `@natjswenson/devlog` are documented here.
 
+## 0.4.0 (2026-06-28) — researched, end-to-end implementation-guide posts
+
+**Changed**
+- `/devlog` now writes each release entry as a researched, cited, end-to-end
+  implementation guide rather than a narrative summary of what shipped. Step 6
+  derives the engineering topic(s) the work touched, researches them against
+  reputable outside sources (cited inline and in a `## Sources` section), and
+  writes a setup → build → use → verify walkthrough with multiple
+  copy-paste-reusable, language-tagged code blocks that together form a complete,
+  runnable whole (right-sized: roughly 3-6 essential blocks for a substantive
+  feature, fewer for a small change, never padded). A short `## Shipped` hook
+  still opens the post and `## Changelog` still closes it. Updated the skill
+  description and the Step 6 / 6a-6c guidance accordingly.
+
+**Added**
+- `deepDive` config block: `topicDomains` (default: AI, DevOps/SRE, software
+  engineering) and `minSources` (default 2) to steer topic selection and the
+  citation floor. Repo-agnostic; user-supplied values live in `config.json`.
+
+## 0.3.1 (2026-06-20) — fetch tags before discovering releases
+
+**Fixed**
+- `/devlog` now runs a best-effort `git fetch --tags --quiet` per project at the
+  start of release discovery (Step 3), before listing tags. Releases are
+  commonly cut by CI on the remote (a version-driven GitHub Release on green
+  `main`/`master`), so the tag is born on the remote; a local clone that hadn't
+  fetched would list only stale local tags and silently report "no new release"
+  for a release that was already live. The fetch is best-effort: on failure
+  (offline, no remote, auth prompt) it notes the failure and proceeds on local
+  tags rather than aborting. `--tags` takes no untrusted input and `project.path`
+  is validated + single-quoted per Step 0.5.
+
+## 0.3.0 (2026-06-18) — release-focused entries, written in your voice
+
+**Changed (behavior)**
+- `/devlog` now generates one entry **per version release** (a semver git tag) instead of
+  one entry per day. An entry summarizes the commits in a release's tag range
+  (`<prevTag>..<thisTag>`), scoped by `pathFilter` when present. The run is **idempotent**:
+  a release's entry is written once and never overwritten, and re-running produces nothing
+  until a new tag is cut. The per-day "Update — HH:MM" append mode is removed.
+- Entries are keyed by version: `<project-key>/<version>.md` (e.g. `v0.2.0.md`), with a
+  `version` field added to the frontmatter and to each `manifest.json` entry. Entry sections
+  are now **What Shipped / What's Next / Commits**. The entry `date` is the tag's commit date.
+
+**Added**
+- **Voice-driven publishing.** Entries are written in the user's voice using a voice profile
+  resolved in this order: `config.voicePath` → `~/.claude/skills/ghostwriter/voice` (if
+  installed) → a bundled fallback at `~/.claude/skills/devlog/voice/`. devlog reads
+  `voice-profile.md` and `voice-notes.md` (overrides) — and never `algorithm.md`, since
+  LinkedIn reach tuning does not apply to a dev log.
+- `voicePath` (top-level, optional) and `projects[].tagPrefix` (optional, default `v`) config
+  fields, with security validation in both `bin/devlog.js` and SKILL.md. `tagPrefix` lets each
+  project in a monorepo detect its own releases (e.g. `devlog-v`, `ghostwriter-v`).
+- `init` prompts for the voice directory and release tag prefix, and installs the bundled
+  voice template. `config` shows the voice path and each project's tag pattern.
+- The React example carries the optional `version` field through frontmatter parsing and
+  manifest validation.
+
+**Migration note:** existing per-day `YYYY-MM-DD.md` entries are left untouched; new entries
+are per-release. To detect a monorepo project's releases, set its `tagPrefix`.
+
+## 0.2.0 (2026-06-08) — monorepo subdirectory filtering
+
+**Added**
+- `projects[].pathFilter` config field: scope a project's commits to a repo-relative
+  subdirectory (e.g. `skills/devlog`). Lets several logical projects share one monorepo
+  `path`/`remote` while each collects only its own subtree's commits. `git log` gains a
+  `-- <pathFilter>` pathspec; commit links still resolve to `<remote>/commit/<hash>`.
+- SKILL.md documents the field, its security validation (no leading `-`/`/`, no `..`,
+  single-quoted), and the multi-skill monorepo workflow.
+- `bin/devlog.js` validates `pathFilter` and shows it as `scope:` in `devlog config`.
+
 ## 0.1.9 (2026-06-05) — accessibility fix
 
 **Accessibility**

package/README.md

@@ -5,9 +5,9 @@
 [![security](https://img.shields.io/badge/security-audited-green)](./SECURITY.md)
 [![vulnerabilities](https://img.shields.io/badge/npm%20audit-0%20issues-brightgreen)](#security)
 
-A Claude Code skill that turns your daily git commits into a published dev log — and a React example for displaying it on your site.
+A Claude Code skill that turns each version release (a git tag) into a published dev log entry, written in your own voice — and a React example for displaying it on your site.
 
-> **Build in public, automatically.** Make commits like you always do. Run `/devlog`. Today's work shows up on your site as a narrative entry, not raw commit messages.
+> **Build in public, by release.** Tag a release like you always do. Run `/devlog`. Each new version shows up on your site as a narrative entry — in your voice — not raw commit messages.
 
 ## Live example
 
@@ -15,9 +15,11 @@ The skill is in production at [natejswenson.com/devlog](https://natejswenson.com
 
 ## How it works
 
-1. **You commit code** in your projects, like you already do.
-2. **Run `/devlog` in Claude Code.** The skill reads today's commits, writes a narrative markdown entry, and pushes it to your dev-log GitHub repo.
-3. **Your site fetches it.** Static `manifest.json` + per-day markdown files served from `raw.githubusercontent.com` — no backend needed.
+1. **You ship a release** — tag it (e.g. `git tag v0.3.0`), like you already do.
+2. **Run `/devlog` in Claude Code.** The skill finds tags that don't yet have an entry, summarizes each release's changes into a narrative markdown entry written in your voice, and pushes it to your dev-log GitHub repo. It's idempotent — re-running does nothing until you cut a new release.
+3. **Your site fetches it.** Static `manifest.json` + per-release markdown files served from `raw.githubusercontent.com` — no backend needed.
+
+**In your voice.** Entries are written using a voice profile, resolved in this order: your `config.voicePath` → [ghostwriter](../ghostwriter)'s `voice/` dir if installed → a bundled default. devlog reads `voice-profile.md` (and `voice-notes.md` overrides) — never ghostwriter's `algorithm.md`, since LinkedIn reach tuning doesn't apply to a dev log.
 
 ## Quick start
 
@@ -63,12 +65,16 @@ to see your dev log rendered locally at `http://localhost:5173`.
 ```
 ~/.claude/skills/devlog/
 ├── SKILL.md          # The /devlog slash-command instructions
-└── config.json       # Your settings (mode 0600)
+├── config.json       # Your settings (mode 0600)
+└── voice/            # Bundled fallback voice profile (last resort)
+    ├── voice-profile.md
+    └── voice-notes.md
 
 github.com/<you>/daily-dev-log/   # Created by init, populated by /devlog
 ├── myproject/
 │   ├── manifest.json
-│   ├── 2026-05-01.md
+│   ├── v0.3.0.md
+│   ├── v0.2.0.md
 │   └── ...
 └── ...
 ```
@@ -77,8 +83,11 @@ github.com/<you>/daily-dev-log/   # Created by init, populated by /devlog
 
 ```sh
 gh repo create <you>/daily-dev-log --public --add-readme
-mkdir -p ~/.claude/skills/devlog
+mkdir -p ~/.claude/skills/devlog/voice
 curl -o ~/.claude/skills/devlog/SKILL.md https://raw.githubusercontent.com/natejswenson/devlog/main/SKILL.md
+# Optional fallback voice profile (used when voicePath and ghostwriter are both absent):
+curl -o ~/.claude/skills/devlog/voice/voice-profile.md https://raw.githubusercontent.com/natejswenson/devlog/main/voice/voice-profile.example.md
+curl -o ~/.claude/skills/devlog/voice/voice-notes.md https://raw.githubusercontent.com/natejswenson/devlog/main/voice/voice-notes.example.md
 # Then copy config.example.json → ~/.claude/skills/devlog/config.json and fill it in
 ```
 
@@ -116,8 +125,8 @@ The dev-log repo has this layout, all served as raw files from `https://raw.gith
 <repo>/
 └── <project-key>/
     ├── manifest.json          # Index of all entries (newest first)
-    ├── 2026-05-01.md          # One entry per day
-    ├── 2026-04-30.md
+    ├── v0.3.0.md              # One entry per release (named by version)
+    ├── v0.2.0.md
     └── ...
 ```
 
@@ -125,34 +134,36 @@ The dev-log repo has this layout, all served as raw files from `https://raw.gith
 ```json
 {
   "entries": [
-    { "date": "2026-05-01", "file": "2026-05-01.md", "title": "...", "summary": "..." }
+    { "date": "2026-06-08", "file": "v0.2.0.md", "title": "...", "summary": "...", "version": "v0.2.0" }
   ]
 }
 ```
 
 Strict validation rules (entries that don't match are silently dropped by the React example):
-- `date` matches `YYYY-MM-DD`
+- `date` matches `YYYY-MM-DD` (the release/tag date)
 - `file` matches `^[a-zA-Z0-9._-]+\.md$`
 - `title` and `summary` are non-empty strings
+- `version` (optional) matches `^[a-zA-Z0-9._-]+$`
 
 **Entry markdown:**
 
 ```markdown
 ---
-title: "Concise day summary"
-date: 2026-05-01
+title: "Concise release summary"
+date: 2026-06-08
 project: myproject
+version: v0.2.0
 summary: "1-2 sentence summary"
 ---
 
-## What I Built
-Narrative paragraphs.
+## What Shipped
+Narrative paragraphs, written in your voice.
 
 ## What's Next
 Forward-looking note.
 
-## Public Commits
-- [myproject] commit message ([abc1234](https://github.com/.../commit/abc1234567...))
+## Commits
+- commit message ([abc1234](https://github.com/.../commit/abc1234567...))
 ```
 
 That's the entire contract.
@@ -165,13 +176,16 @@ That's the entire contract.
 |---|---|---|
 | `targetRepo` | `"<owner>/<repo>"` | Repo where dev log entries are published. Must match `^[a-z0-9][a-z0-9._-]*\/[a-z0-9][a-z0-9._-]*$`. |
 | `branch` | string (optional) | Branch in the dev-log repo. Defaults to `main`. Must not contain `..` or start with `-`. |
-| `gitAuthor` | string | Used as `git log --author=...` to find your commits. Whitespace OK; no shell metacharacters. |
+| `gitAuthor` | string | Your name. Retained for backward compatibility; it is **not** currently rendered on entries (the author filter was removed, and release notes summarize all commits in a tag range). Still **required** by config validation — it must be present and non-empty (don't drop it). Whitespace OK; no shell metacharacters. |
 | `githubUser` | string | Your GitHub username. |
+| `voicePath` | string (optional) | Directory holding `voice-profile.md` (and optionally `voice-notes.md`) used to write entries in your voice. A leading `~` is expanded. If unset, devlog uses ghostwriter's `voice/` if installed, else the bundled default. Read only — never shell-interpolated. |
 | `projects` | array | One entry per project you want dev logs for. |
 | `projects[].key` | string | Subdirectory name in the dev-log repo. Strict token: `^[a-z0-9][a-z0-9._-]*$`, no `..`. |
 | `projects[].label` | string (optional) | Display name for the tab. Defaults to `key`. |
 | `projects[].path` | string | Local filesystem path to the project. Whitespace OK. |
 | `projects[].remote` | `"<owner>/<repo>"` | The project's GitHub remote. Used to mark public commits and link them. |
+| `projects[].pathFilter` | string (optional) | Repo-relative subdir scoping this project's commits in a monorepo (e.g. `skills/devlog`). |
+| `projects[].tagPrefix` | string (optional) | Prefix of the git tags that mark this project's releases (e.g. `devlog-v`). Defaults to `v`. Used in `git tag --list '<tagPrefix>*'`. |
 
 See [`config.example.json`](./config.example.json) for a complete template, or run `npx @natjswenson/devlog config` to inspect your current config with validation.
 
@@ -195,7 +209,8 @@ The package is designed to be safe to install on a developer's machine and have
 
 ## Customization
 
-- **Tweak the entry template:** edit `~/.claude/skills/devlog/SKILL.md` (Step 4 — generate the entry).
+- **Tweak the entry template:** edit `~/.claude/skills/devlog/SKILL.md` (Step 6 — generate the entry).
+- **Tweak your voice:** edit the `voice-profile.md` / `voice-notes.md` in your `voicePath` (or `~/.claude/skills/devlog/voice/`).
 - **Tweak the UI:** override the `--devlog-*` CSS variables in `examples/react/DevLogPage.css` to match your theme.
 - **Add more projects:** `npx @natjswenson/devlog add-project` (no manual JSON editing required).