[aliasunder]

Refreshes the ## Code standards section of AGENTS.md from the cross-project standards notes (last distilled 2026-08-24), keeping the section's hand-written rules. The review passes then corrected or clarified claims in five other sections (Project Overview, Repository Structure, Development Guidelines, Social preview card, Adding a reference file) and the header comment of scripts/render-social-preview.ts.

Code standards section

• Writing: adds the authoring test (walk the whole artifact per reader; re-read the whole document after a section edit), reader's-motive openings for procedure copy, troubleshooting entries that end in steps, destructive claims paired with recovery, Valid values: / Default: lines for setting references, defensive copy only after the problem occurred, reviewed copy has a job, prerequisites follow the reader, and no implicit contrasts.
• Multi-path, lockstep, restructuring: restructured as lists; adds all-path notes attaching to none, derived artifacts regenerated in the same change, generation steps holding structure only, one conceptual home per feature, and the surfaces to sweep per kind of addition.
• Comments: adds the "what vs why" rewrite step, guard comments naming scenario and mechanism, chosen numbers commented above, regex constants commented, short complete sentences with no colon-hinged labels, and retracing-risk as rationale.
• Intro: states that the rules are authoring guidance for what you write, and that an existing file is brought into line when a change already edits the passage, never in a sweep.
• TypeScript (scripts/): adds readonly inputs and no mutation-as-fold, no chained ternaries, named params, named constants, exhaustive switch over unions, platform built-ins before hand parsing, per-operation try/catch with every catch logging or re-throwing, and Node built-ins only, since Node runs every script.

Other sections

• Project Overview: glosses the Agent Skills format and the session protocol; counts the per-client instruction files correctly.
• Repository Structure: drops counts the tree already shows; lists all four workflows.
• Development Guidelines: states the script runtime once (Bun locally, Node in CI and for the render script); names which generated skills carry the protocol pointer; introduces vault-cortex.
• Social preview card: names the Chrome pin's source and the puppeteer.skipDownload mechanism; splits the design-family note into its own paragraph; opens the regenerate procedure with the reader's motive.
• Adding a reference file: adds the lockstep step (structure tree and README) and the Phase 6 "during skill generation" form.
• scripts/render-social-preview.ts: the header comment now points at the Social preview card section instead of restating the install story.

Review follow-ups, one commit each

• README.md: the Status section drops its stale sentence about the initial pull request, so the public copy no longer carries a PR number the standards forbid.
• references/setup-verification.md: each Troubleshooting entry is numbered steps ending in a safe fallback, matching the rule this change codifies.
• scripts/validate-structure.ts: restyled to the TypeScript rules (no semicolons, arrow constants, entries() instead of an index loop), then the remaining lint flags cleared (toSorted(), at(-1), absent values handled at the use site instead of ?? "", inline regexes lifted into doc-commented constants). Output under Node 24 and Bun is byte-identical to the original.

AGENTS.md size: 8,758 → 17,597 bytes (budget 30,720). scripts/validate-structure.ts passes under Bun and Node 24.

🤖 Generated with Claude Code

[umm-actually]

Reconcile README's PR #1 link with the OSS-boundary rule
Low severity · conventions · medium confidence

README.md:49 — beyond the diff's line ranges, in code the changes touch or depend on.

AGENTS.md's Code standards state an unqualified OSS boundary: 'no issue/PR numbers, incident dates, deployment names, or task-board IDs in any public artifact.' README.md — a public artifact — contains a PR number in its Status section. The restated rule and the repository's own public-facing doc contradict each other, which undermines the rule's enforceability.

Failure scenario: A contributor who wants to add a tracking ID to a comment or public doc reads the OSS-boundary rule, sees README.md already referencing PR #1, and concludes the rule is advisory or only applies to code comments — an internal ticket, release date, or deployment name then ships in a public artifact.

Suggested fix

Remove the PR-number reference from README's Status section (e.g. 'is merged and now in validation') or add a qualifier to the OSS-boundary rule permitting references to the project's own public GitHub PRs.

---

umm-actually · deepseek/deepseek-v4-flash-0731

[umm-actually]

umm-actually re-reviewed at fe3eec0

2 new finding(s) posted (21 tracked finding(s) across all runs).

Context notes

• Priority docs already in context: skills/vault-onboarding/references/setup-verification.md, scripts/validate-structure.ts

---

umm-actually · deepseek/deepseek-v4-flash-0731

[umm-actually]

Reconcile CONTRIBUTING.md release workflows with this repo's actual CI
Medium severity · correctness · medium confidence

CONTRIBUTING.md:12 — beyond the diff's line ranges, in code the changes touch or depend on.

CONTRIBUTING.md instructs maintainers to cut a release via an Actions 'Manual Release' workflow and describes 'Manual Release' (manual_release.yml) and 'Auto Release' (auto_release.yml) CI tables, but this repository's only workflow is validate.yml per AGENTS.md's structure tree ('⋮ .github/workflows/validate.yml ⋮ Runs the structural checks on PRs + pushes to main'), and README's Status describes a pre-release project with the 'first GitHub release' still pending. The release documentation appears to have been carried over from a different repo and is stale here.

Failure scenario: A maintainer follows CONTRIBUTING.md's 'Cut a release from the GitHub UI' steps, navigates to Actions, finds no 'Manual Release' workflow, and cannot run the described bump/tag/zip/release steps; a contributor reading the CI table believes a v* tag push triggers an auto-release that does not exist.

Suggested fix

Rewrite the Releasing and 'How the CI works' sections to describe only the actual workflows in .github/workflows/ (validate.yml runs via AGENTS.md), and either delete the manual/auto-release steps or add the workflows they describe. At minimum, add a pragmatic release path (e.g. the validate.yml CI plus a documented tag-and-release process) that matches what exists.

---

umm-actually · deepseek/deepseek-v4-flash-0731

[aliasunder]

On the CONTRIBUTING.md release-workflow finding (umm-actually, CONTRIBUTING.md:12):

Not changing CONTRIBUTING.md: the workflows it describes exist. .github/workflows/ holds auto_release.yml (name "Auto Release", on push), manual_release.yml (name "Manual Release", on workflow_dispatch), umm_review.yml and validate.yml. The finding rested on this file's Repository Structure tree, which listed only validate.yml; 5ed11e3 lists all four so the tree no longer implies the others are missing.

---

🔍 ship-check · pr-monitor · claude-fable-5-1

[umm-actually]

Give troubleshooting entries numbered-steps form matching the new rule
Low severity · conventions · high confidence

skills/vault-onboarding/references/setup-verification.md:190 — beyond the diff's line ranges, in code the changes touch or depend on.

The newly codified rule requires troubleshooting entries to end in numbered steps the reader can take, with a safe fallback, never in a diagnosis alone. setup-verification.md's Troubleshooting section, the repo's model for such entries, ends each entry in plain diagnostic bullets, contradicting the standard an agent is now told to follow.

Failure scenario: An agent drafting a new troubleshooting entry mirrors setup-verification.md's bullet-list-with-diagnosis format instead of the numbered-steps-with-fallback the rule mandates, so newly added entries keep ending in a diagnosis and the rule stays unimplemented.

Suggested fix

Restructure each troubleshooting entry to end in numbered steps with a safe fallback, e.g. '### Agent doesn't know my name\n1. Verify the instruction file exists at the expected path.\n2. Check it is not empty or malformed.\n3. For paste surfaces, re-paste and check for truncation.\n4. If it still fails, ask the user to re-paste from the vault note.'

---

umm-actually · deepseek/deepseek-v4-flash-0731

[aliasunder]

On the troubleshooting-entries finding (umm-actually, skills/vault-onboarding/references/setup-verification.md:190):

The entries do end in diagnostic bullets rather than numbered steps with a fallback, so the file does not match the rule as written. Not restructuring it here: it is shipped skill content outside this change, and this is the third existing file a round has found that predates a newly codified rule. 38b8ee9 states the class boundary once, at the top of the Code standards section: the rules are authoring guidance for the prose and code you write, and an existing file is brought into line when a change already edits that passage, never in a sweep of its own. The maintainer decides whether the Troubleshooting section gets its own change.

---

🔍 ship-check · pr-monitor · claude-fable-5-1

[umm-actually]

Log the actual exec failure in commandAvailable's catch
Low severity · subtle bugs · medium confidence

scripts/render-social-preview.ts:14 — beyond the diff's line ranges, in code the changes touch or depend on.

The new Code standards in AGENTS.md state 'Every catch logs or re-throws; a swallowed error is worse than an uncaught one', and this script is the in-repo example that must model that rule. commandAvailable() silently swallows any execFileSync failure and returns false, so a failure that is NOT 'command not found' (e.g. 'which' itself missing on a native Windows shell, or a permission error) produces the same misleading 'optipng not found — install via…' warning as a genuinely absent binary. The catch needs to distinguish the expected not-found case from other errors, or log the underlying error message.

Failure scenario: On a Windows host without the POSIX 'which' utility (CONTRIBUTING.md documents Windows support), execFileSync throws ENOENT rather than a non-zero status; commandAvailable returns false, and a user who has optipng installed is told to install it. Similarly, any transient filesystem/permission error on 'which' is reported as 'optipng not found' with no diagnostic.

Suggested fix

In the catch block, capture the error and short-circuit based on it, e.g.:
```ts
const commandAvailable = (command: string): boolean => {
  try {
    execFileSync("which", [command], { stdio: "pipe" })
    return true
  } catch (error) {
    if (error && typeof error === "object" && "status" in error) return false // not found
    console.warn(`could not locate ${command}: ${String(error)}`)
    return false
  }
}
```
This makes 'not found' the silent fast path while surfacing unexpected failures per the new 'every catch logs or re-throws' rule.

---

umm-actually · deepseek/deepseek-v4-flash-0731

[aliasunder]

On the commandAvailable catch finding (umm-actually, scripts/render-social-preview.ts:28):

Not changing this: commandAvailable runs which optipng as a probe, and the catch is the probe's negative answer (optipng is not installed), not a swallowed failure. Its only caller, optimizePng, already reports that case with a warning naming the install commands, so the script's output tells the reader what happened. Logging the execFileSync error there would print a "Command failed: which optipng" error on every machine without optipng, which is the expected case, not a fault. The catch at line 41, the one that covers a real optipng failure, warns. The Windows case the finding describes (no which, so an installed optipng is reported as missing) costs the reader a wrong install hint while the PNG still renders unoptimized, which is too little to earn an error-classifying branch in a maintainer-only script.

---

🔍 ship-check · pr-monitor · claude-fable-5-1

[aliasunder]

On the README Status finding (umm-actually, README.md:49):

Fixed in 3886be9: the maintainer chose to drop the sentence that linked the initial pull request, so the Status section now reads "vault-onboarding is in active development and not yet released. The install command works, but treat it as pre-release until testing passes and a first GitHub release is cut." No other public file in the repo carries a pull-request number.

---

🔍 ship-check · pr-monitor · claude-fable-5-1

[aliasunder]

On the troubleshooting-entries finding (umm-actually, skills/vault-onboarding/references/setup-verification.md:190):

Fixed in 7550bfd: the maintainer chose to rewrite the section now. Each of the five Troubleshooting entries is numbered steps the reader can take and ends in a safe fallback (regenerate from the template, run the protocol by hand, tighten the scope callout, keep working with the plain task list, re-paste the missing sections). scripts/validate-structure.ts passes, including its heading cross-reference check on the rewritten "Upgrading lightweight to full protocol" reference.

---

🔍 ship-check · pr-monitor · claude-fable-5-1

[umm-actually]

Open the Releasing procedure with the reader's motive
Low severity · conventions · medium confidence

CONTRIBUTING.md:10 — beyond the diff's line ranges, in code the changes touch or depend on.

The new Writing rule requires procedure copy to open with the reader's motive, not the operation's name. CONTRIBUTING.md's Releasing section — the repo's model for a procedure — opens with 'Cut a release from the GitHub UI:', the operation, so the in-repo example contradicts the rule it was meant to illustrate.

Failure scenario: An agent drafting a new procedure section mirrors CONTRIBUTING.md's Releasing section and opens with the operation's name instead of the reader's motive, propagating the exact pattern the new Writing rule was added to eliminate.

Suggested fix

Open with the motive, e.g. 'To cut a release, run the Manual Release workflow from the Actions tab:', then keep the numbered steps.

---

umm-actually · deepseek/deepseek-v4-flash-0731

[umm-actually]

State the conditions for generated skills in the README
Low severity · correctness · medium confidence

README.md:22 — beyond the diff's line ranges, in code the changes touch or depend on.

The 'What it does' capability list states all four generated skills unconditionally, but SKILL.md generates session-start/session-end only when the protocol is enabled, remember only when memory is enabled, and project-role only for the full protocol — conditional capabilities the repo's new Code standards rule says must be stated conditionally.

Failure scenario: A user who opts into only memory and task boards (no protocol) reads 'Generated skills — session-start, session-end, remember, and project-role skills' and expects all four after onboarding; the session skills are never generated without the protocol, so the delivered system does not match the README's capability list.

Suggested fix

Reword the bullet to state the conditions, e.g. 'Generated skills — session-start and session-end when the protocol is enabled, remember when memory is enabled, and project-role when the full protocol is chosen, each tailored to your actual vault structure.'

---

umm-actually · deepseek/deepseek-v4-flash-0731

[umm-actually]

Correct the sessions-folder gating claim in memory-system.md
Low severity · correctness · high confidence

skills/vault-onboarding/references/memory-system.md:13 — beyond the diff's line ranges, in code the changes touch or depend on.

The Three-Layer Model table claims project sessions/ folders are 'created only when the session protocol is enabled', but SKILL.md Phase 3 scaffolds a sessions/ subfolder into every project folder regardless of the Phase 6 protocol decision. The claim is accurate only for the vault-root Sessions/ folder.

Failure scenario: A vault whose project was scaffolded in Phase 3 but whose protocol was declined in Phase 6 still contains the project's sessions/ folder; an agent that read memory-system.md believes sessions/ folders exist only with the protocol and misroutes or ignores the existing folder when handling session logs.

Suggested fix

Split the gating: '`Sessions/` (vault root) — created only when the session protocol is enabled; project `sessions/` subfolders — scaffolded with each project in Phase 3.'

---

umm-actually · deepseek/deepseek-v4-flash-0731

[umm-actually]

Add the missing 'during X' read lines to Phases 5 and 7
Low severity · conventions · medium confidence

skills/vault-onboarding/SKILL.md:514 — beyond the diff's line ranges, in code the changes touch or depend on.

AGENTS.md's new 'Adding a reference file' step 3 requires a bold read line at the top of every phase that uses a reference file, naming the step when only one uses it. SKILL.md Phases 5 and 7 each use references/setup-verification.md in a single step (the plugin walkthrough and the per-client checks) without that bold line, even though the file's own reference list promises reads during those phases.

Failure scenario: An agent following AGENTS.md step 3 to add a new reference file mirrors the existing phases: it adds bold read lines to the phases that have them but, copying Phase 5, omits the line for a phase that uses the file in only one step — reproducing the exact gap the rule was written to close.

Suggested fix

Add '**Read `references/setup-verification.md` during the plugin walkthrough.**' at the top of Phase 5 and '**Read `references/setup-verification.md` during the per-client checks.**' at the top of Phase 7.

---

umm-actually · deepseek/deepseek-v4-flash-0731

[aliasunder]

On the Releasing-procedure lead (umm-actually, CONTRIBUTING.md:10) and the Phase 5 and 7 read lines (umm-actually, skills/vault-onboarding/SKILL.md:514):

Not changing these here: both are existing passages that predate the rule they now sit beside, and this change edits neither. The Code standards section states the boundary for that case at its top: the rules are authoring guidance for what you write, and an existing file is brought into line when a change already edits that passage, never in a sweep of its own. Each becomes a one-line edit in whichever change next touches CONTRIBUTING.md's Releasing section or SKILL.md's Phase 5 and Phase 7.

---

🔍 ship-check · pr-monitor · claude-fable-5-1