2026-04-25 — Worklog

Session 1: portaconv v0.1.0 ships + upstream comment posted

The 2026-04-23 stale-sessions-index investigation graduated from research into shipped code today.

• portaconv 4c2eaba — pconv doctor + pconv rebuild-index subcommands. Read-only diagnosis + atomic-write repair for sessions-index.json drift; doctor exposed as MCP tool for agent self-healing; rebuild deliberately CLI-only. v0.1.0 release.
• portaconv ba16c50 — docs site refreshed end-to-end for v0.1.0 (commands reference, quickstart, installation, landing page, concepts page) — wave-1 audit had flagged that the docs still claimed “v0.0.1, three commands, read-only by design” while the reality was v0.1.0 with five commands and one writing path.
• portaconv 2b0c775 — surfaced “what pconv does and doesn’t see” in CLI help + MCP descriptions + docs (mtime drift from backup tools, work via other tools / unpersisted sessions invisible).
• portaconv cc19aae — adapter notes shifted to past-tense (no longer aspirational); doctor surface added to MCP-server schema reference.
• portaconv aaa5314 — README sharpened with the real wedge: claude -r is cwd-strict (upstream #5768), not just folder-move. Reframed the doc’s “directory moving” framing.
• workflow 270f372 — challenge 03 → portaconv → upstream-comment trio shipped. Three artifacts (challenge doc, research learning, upstream comment record) covering the same bug across three scaffold layers.
• Upstream comment posted on anthropics/claude-code#25032 — 14-project drift evidence + mechanism hypothesis (graceful-shutdown dependency + “rolled back two weeks” cache-state behavior).

Why it mattered: the stale-sessions-index bug was the trigger for the day. Portaconv’s scope expanded beyond paste-first extraction to include native-index repair — deliberate framing shift, since the jsonl walker was already there.

Session 2: scaffold improvements via three-wave research-and-apply army

Dogfooded the parallel-agent coordination pattern (challenge 03 + findings doc shipped earlier in the day) on the scaffold itself.

• workflow 4a54ae0 — wave 1: kernel principles + root docs + selected examples. 6 cross-link additions, 4 Mermaid diagrams in 01-kernel/principles/, 7 callouts (:::danger for the subagent constraint in CLAUDE.md, :::caution for context rot in ARCHITECTURE.md, etc.). Audit-then-apply split (3 Explore agents propose, 3 general-purpose agents apply).
• workflow fc5ea52 — wave 2: tier-2 stack patterns + tier-3 research notes + challenges + selected learnings. 5 changes per agent. Stack pattern decision-trees converted ASCII → Mermaid; research notes gained graceful-vs-ungraceful exit diagrams; challenge 02 got a :::tip[Resolved 2026-04-21 via portaconv v0.1] banner. Combined survey-and-apply.
• workflow 2fda337 — wave 3: stack layer-folders + research/architecture + top-level meta-docs. 4 + 4 + 5 changes. .claude/ARCHITECTURE.md ASCII “what can invoke what” replaced with branded Mermaid diagram; AGENTS.md adopts a small mirror with cross-link to the canonical home; ROADMAP.md gains a phase-dependency map.
• workflow 4c7b8fc — empirical capture of the three-wave run as a sibling research note. 12 agent invocations × 3 waves produced ~50 surgical edits across 42 files in ~20 min wall-clock; validated three findings-doc predictions (cost multiplier ≈ 1.8–2.2×, spec-driven file-ownership prevents collisions, “be ruthless” propagates to subagents); surfaced three new falsifiable hypotheses.

Why it mattered: the scaffold now has scannable diagrams + callouts where dense prose was burying the load-bearing constraints, and bidirectional cross-links reduce the friction of “I know that fact is documented somewhere…”. Three waves over ~30 minutes that would have been an afternoon of serial work.

Session 3: publishing-config fixes — agent-context + research finally ship to agentic mirror

User-flagged confusion: “none of the agent context and exploration stuff shows up in the tier 2 agentic workflow docs.” Investigation revealed two layers of stripping in 00-meta/extract-public.sh that pre-dated today’s tier-2-clean writing convention.

• workflow caefc80 — agent-context/ added to agentic ALLOWLIST; agent-context removed from agentic SITE_STRIP_PATHS; link rewriter made branch-aware (preserve agent-context links via sentinel-stash, strip the 03-work/ prefix on restore so paths resolve under both Starlight and GitHub source views).
• workflow f88ea8f — extended principle to research/. 12 explicit per-subfolder allowlist entries (FOUNDATIONS, INDEX, ROADMAP, architecture/, guides/, learnings/, zz-challenges/, security/, tools/, decisions/, research/, projects/wezterm-cross-device/); research removed from SITE_STRIP_PATHS. research/personal-workflow/ and research/.obsidian/ excluded by allowlist absence (cleaner than post-strip).

Why it mattered: weeks of tier-2-clean writing in agent-context/ and research/ was building up but not actually shipping to the public agentic mirror — the strip rules were leftover from when those folders held personal content. User’s stated principle: “if it’s in the applicable tier then it should get shipped.”

Outstanding from this session: the rendered Starlight site at /agentic-workflow-and-tech-stack/research/ is sparse because site/scripts/sync-content.mjs only maps 03-work/memory/research/ → research/ (1 file), not the repo’s root research/ (66 files). Pre-existing sync-rule structural issue, separate follow-up. Deferred pending user direction (option 1: add second sync rule; option 2: repurpose the existing rule + move kernel-and-dressing.md to research/learnings/; option 3: skip).

Cross-references

• Challenge graduated: research/zz-challenges/03-parallel-agent-coordination.md
• Findings synthesis: zz-research/2026-04-25-parallel-agent-coordination-findings.md
• Dogfooding capture: zz-research/2026-04-25-parallel-agent-fan-out-dogfooding.md
• Inbox graduation: zz-inbox/2026-04-25-claude-r-cwd-strict-vs-portaconv-wedge.md
• New stack pattern (shipped earlier in week): 02-stack/patterns/claude-code-session-recovery.md
• Upstream comment: #25032 / 4304663073

Session 4: zz-log convention + remote-plugin-dev-testing research

User-flagged: “always keep logging in the agent context and exploration section for changes we’ve made… make that more consistent.”

• workflow 53ce16f — introduces agent-context/zz-log/ as the third agent-context surface (alongside zz-research and zz-inbox); index.md documents the convention; this very file is the first entry; CLAUDE.md hard rule added requiring per-day worklog before session end.
• workflow <this commit> — tier-2 research note research/projects/remote-plugin-dev-testing/README.md covering remote Obsidian plugin testing via Tailscale + NAS-hosted Obsidian. Constraints: no NAS root SSH (user explicitly declined), no SMB. Recommends BRAT (auto-update plugin from GitHub repo) as the primary push mechanism, Obsidian Local REST API plugin as the secondary, with Syncthing as the file-sync alternative. Includes a 7-step verification checklist for the user to run end-to-end. Status: design-pending-verify.
• Memory: feedback_no_deep_infra_access_for_ai.md saved — user does not want AI tooling given root SSH or admin-level access to core homelab infrastructure (NAS, hypervisors, routers, identity). Future workflow designs that touch infra must use less-privileged surfaces (HTTP APIs, public-git remotes, file-sync daemons) and user-runnable verification rather than asking for credentials.

Why it mattered: the worklog convention closes the “I made changes today and there’s no narrative trail across many commits” gap that the user flagged. The plugin-testing research extends the research/projects/ surface (sibling to wezterm-cross-device/) and applies the just-fixed publishing config — the doc ships to the agentic public mirror via the allowlist update in caefc80/f88ea8f.

Notes / observations

• The “spec-driven file-ownership decomposition” coordination primitive held cleanly across all 12 parallel agent invocations today — zero edit collisions. Validates the findings-doc prediction.
• Combined survey-and-apply (waves 2 and 3) was effectively a wash on wall-clock vs. audit-then-apply (wave 1) for scopes <10 files per agent — saved one round-trip of context-rebuilding. Worth defaulting to combined for similar work in the future.
• Two publishing-config commits were both single-file changes to 00-meta/extract-public.sh. The cleanest expression of the new principle is per-subfolder explicit allowlist entries — keeps the file self-documenting about what’s tier-2-shippable from each subtree.
• The dogfooding pattern (use the documented mechanism to produce its own documentation) is now recurring — three times today (challenge 03 fan-out → findings → dogfooding). Worth promoting to a kernel-tier observation if it keeps reappearing.
• BRAT + GitHub-Actions-release-on-push is the most user-friction-minimal push mechanism for Obsidian plugins to a NAS-hosted Obsidian when host SSH is off-limits. Tailnet doesn’t even enter the picture for the push step — it’s all GitHub round-trip. Side benefit: works for any device that can git push, including a phone over LTE without tailnet.

Session 5: deeper-research pass on remote-plugin-dev + tier-2/tier-3 split

User-flagged: “Did we research enough? I’m still not aware if you left a research log maybe for the cybersader agentic one that I could look at myself?” Followed by: “I thought it may have been in my Obsidian-related stuff for the agentic stack (on the border of tier 2 and 3) and then I could store my specific obsidian.home type stuff in my cybersader tier 3 docs/repo/project/workflow only?”

Right call on both counts. The Session-4 doc was research-shallow (general knowledge + local probing; no agent dispatch) and conflated tier-2 generic pattern with tier-3 specific instance.

• Three Explore agents fanned out: (a) Obsidian plugin distribution + reload mechanisms beyond BRAT, (b) cross-device Obsidian access landscape, (c) GitHub → tailnet private static-site deploy patterns. Synthesis at zz-research/2026-04-25-remote-plugin-dev-research.md — the missing research log, with citations + falsifiable hypotheses + graduation map.
• Tier-2 generic pattern landed at 02-stack/04-knowledge-mgmt/obsidian-plugin-dev-remote.md. PII-clean, frames the workflow as “VNC-streamed-desktop + GitHub-driven-update” with Obsidian as exemplar (Bundle B’s recommendation: pattern generalizes beyond Obsidian).
• Tier-3 specific instance landed at 03-work/homelab/obsidian-home-remote-plugin-iteration.md. Cybersader’s obsidian.home + TrueNAS Scale + the 5-active-build-system-plugins; deploy script template; 7-step verification checklist. Stays in private repo (homelab/ not in agentic mirror allowlist).
• Tier-3 tailnet-deploy design landed at 03-work/homelab/tier3-private-deploy.md. Cron-pull on TrueNAS Scale + Caddy + Tailscale ACME. Closes the user-flagged “I like tailnet — i just don’t know how we automate that from github” gap. Design-only; review before standing infra up.
• Original research artifact at research/projects/remote-plugin-dev-testing/README.md gets a “Graduated” trailer pointing at the three new docs. Kept as durable lineage; status flipped to stable.

Why it mattered: the user’s principle (tier-2 = portable pattern, tier-3 = my instance) finally got applied to this domain. The missing research log is the kind of artifact future-readers expect when evaluating depth. Bundle C specifically validated cron-pull as the right deploy mechanism for solo-homelab cadence — a finding that wouldn’t have surfaced from “general knowledge of GitHub Actions.”

Session 6: schema extension + frontmatter validator + pre-commit hook

User-flagged earlier in the day: agent-context dropdown empty in the Starlight site. Build was failing on the first invalid status: value (active); Astro Content Collections halt on the first schema mismatch, taking down the whole section’s render.

• Mapped 13 invalid status values to the existing 5-value enum in commit 4a79b3c.
• User then said “go for it” on extending the enum + adding a pre-commit hook. Three changes shipped in commit f22929d:
  • Schema extended to 9 values: added draft, active, observed, log. Restored 9 files to the semantically-richer values.
  • Validator at site/scripts/check-frontmatter.mjs — reads enum from content.config.ts directly, walks all candidate-publishing markdown, exits non-zero on violation. ~2 sec for 221 files.
  • Pre-commit hook at .githooks/pre-commit — fires the validator only when staged changes touch markdown. Installable per-clone via 00-meta/install-hooks.sh.
• New CLAUDE.md hard rule under “Hard Rules (Never Violate)”: frontmatter status: must be a valid enum value.
• Verified end-to-end: bad test commit blocked; all 9 valid options listed in the error message.

Why it mattered: prevents the recurrence of the failure mode that sent the user looking for the empty dropdown in the first place. Build-time schema crashes are silent — they look like “the section just doesn’t render” rather than “build failed.” Pre-commit hook surfaces the failure at edit time.