docs(editorial): add blog quality checklist

[drewstone]

Summary

• add one review contract for all 85 blog posts
• cover zero-context teaching, narrative depth, runnable product proof, evidence, and anti-slop review
• define separate SEO, AEO, and GEO measurement requirements with denominators and comparison periods

Checks

• pnpm check:blog
• pnpm check:blog:reader
• pnpm build
• git diff --check
• git merge-tree --write-tree origin/master HEAD

[tangletools]

✅ Auto-approved drewstone PR — 7d84100a

This PR was opened by the trusted drewstone account.
The full PR reviewer audit still runs separately and will publish findings if it detects issues.

_{tangletools · auto-approval · reason: drewstone_author · 2026-08-03T17:31:46Z}

[tangletools]

⚠️ Review Incomplete — ea3ac646

At least one required reviewer lane failed closed. No approval or request-changes review was published. This is a reviewer run failure, not a PR quality score.

Trigger a fresh review on the current PR head.

_{tangletools · 2026-08-03T17:38:36Z}

[tangletools]

✅ Auto-approved drewstone PR — 1f29d493

This PR was opened by the trusted drewstone account.
The full PR reviewer audit still runs separately and will publish findings if it detects issues.

_{tangletools · auto-approval · reason: drewstone_author · 2026-08-03T17:47:13Z}

[tangletools]

🟠 Value Audit — better-approach-exists

Verdict	better-approach-exists
Concerns	4 (1 medium-concern, 3 weak-concern)
Heuristic	0.0s
Duplication	0.0s
Interrogation	96.6s (2 bridge agents)
Total	96.6s

💰 Value — better-approach-exists

Adds a strong 403-line canonical blog review contract plus a correct social-image-type fix and cover re-encoding, but it partially reinvents two existing skill rubrics/checklists and leaves them as unlinked competing scoring systems.

• What it does: Three bundled changes under one editorial theme: (1) a new docs/editorial/blog-quality-checklist.md (403 lines) — a single review contract covering publish rule, review order, zero-context writing, depth/examples, code proof per product surface, evidence classification, SEO/AEO/GEO measurement with denominators and comparison periods, anti-slop style, visual review, a 0–2 rubric (/24, publish/re
• Goals it achieves: Give every blog post one human-readable review bar (the repo previously had editorial guidance scattered across agent-skill reference files), and fix the social metadata so the new .webp editorial covers advertise the correct media type — which the checklist itself demands at line 195 ('image type match the page'). The measurement-contract section also formalizes SEO/AEO/GEO numerators that the
• Assessment: The checklist is high quality, plain-language, and in the repo's grain — it cross-references the existing seo-engine CLI (lines 395–397) rather than reinventing measurement tooling, aligns with the AGENTS.md anti-slop doctrine, and the Aug-3 baseline is grounded in real counts (85 posts, 44 under 1k words, 23 with real syntax code). The BaseLayout fix is small, correct, and directly enables a ch
• Better / existing approach: Searched docs/, .codex/skills/, and grepped for cross-references. Found two existing overlapping artifacts: .codex/skills/tangle-blog-editor/references/rewrite-rubric.md scores posts 1–5 across 8 dimensions (reader pressure, Tangle proof, precision, SEO/AEO, style, conversion, evidence, presentation) and .codex/skills/tangle-blog-proof/references/proof-checklist.md:3-26 defines Blocking Ga
• Model: opencode/zai-coding-plan/glm-5.2
• Bridge attempts: 2
• Bridge warning: opencode/kimi-for-coding/k2p7: opencode: opencode error

🎯 Usefulness — sound-with-nits

A coherent blog review contract plus a correct, well-integrated og:image:type fix and compressed v2 covers; only minor adoption/drift nits.

• Integration: The code change is fully reachable: blog MDX frontmatter (coverImage/heroImage) -> BlogLayout.astro displayImage -> BaseLayout.astro image prop -> imageType (BaseLayout.astro:26) -> og:image:type meta (:61). Every blog page now emits image/webp for the v2 covers instead of the hard-coded image/png. The 13 v2 cover images are all referenced by src/content/blog frontmatter and v1 covers are no longe
• Fit with existing patterns: Fits the established grain. BaseLayout uses the same Astro frontmatter-computation pattern as the rest of the file. The checklist sits beside the two existing docs/editorial/ files (blog-zero-context-triage.md, blog-search-research.md) and follows their location and tone. BlogLayout.astro already threads coverImage/heroImage through displayImage, so the dynamic type flows with no new plumbing.
• Real-world viability: imageType handles .webp/.jpg/.jpeg (case-insensitive via toLowerCase) and defaults to image/png, which matches the default og-self-improving-agents.png asset. Unknown extensions (gif/svg/avif) mis-declare as png, but no checked-in cover uses those. The checklist's run commands (pnpm check:blog, pnpm build, git diff --check) all exist in package.json and pass; the seo-engine cli.py path is environm
• Model: opencode/zai-coding-plan/glm-5.2
• Bridge attempts: 1

🎯 Usefulness Audit

🟡 Second blog scoring rubric risks drift from the skill's existing one [problem-fit] ``

.codex/skills/tangle-blog-editor/references/rewrite-rubric.md already scores posts on a 1-5 / 8-dimension scale and is the rubric the tangle-blog-editor skill uses. The new docs/editorial/blog-quality-checklist.md:252-277 adds a separate 0-2 / 12-dimension rubric with Publish>=20/24 thresholds. Neither file references the other and no audit script enforces either, so reviewers and agents now have two manual scoring systems for the same artifact. Consider cross-linking them or folding one into th

🟡 Checklist is not referenced by any automation or skill required-refs [integration] ``

The sibling docs/editorial/ files ARE wired into scripts: audit-blog-reader.mjs cites blog-search-research.md and writes blog-zero-context-triage.md via package.json check:blog:reader:report. The new checklist has no such link — grep across .codex/skills, scripts/, AGENTS.md, and package.json finds zero references to blog-quality-checklist.md. It is a human-facing contract so this is not dead surface, but adoption currently depends on a reviewer remembering to open it. Adding it to tangle-blog-e

💰 Value Audit

🟠 New 0–2 rubric and publish gates duplicate the existing rewrite-rubric (1–5) and proof-checklist with no cross-reference [duplication] ``

The new docs/editorial/blog-quality-checklist.md:252-277 rubric (12 dims, 0–2, /24) and publish rule (lines 11–23) overlap .codex/skills/tangle-blog-editor/references/rewrite-rubric.md (8 dims, 1–5) and .codex/skills/tangle-blog-proof/references/proof-checklist.md:3-26 (Blocking/Judgment Gates). Verified no cross-references exist either direction (grep for blog-quality-checklist in .codex/ and docs/, and for tangle-blog/proof-checklist/rewrite-rubric in the new doc — all empty)

🟡 Code change and binary asset work bundled under a docs(editorial) title [proportion] ``

The PR title promises only the checklist, but the master diff also carries a BaseLayout.astro source fix and 12 re-encoded cover binaries. Each is individually fine and thematically adjacent (SEO metadata alignment for editorial covers), but they blur review scope. Not blocking; a reviewer may want the code/image delta split into its own commit or PR so the editorial-doc change is reviewable in isolation.

---

What this audit checks

It judges the change on its merits — not whether it was tasked out in an issue. Unticketed, fast-moving work is fine; the question is whether the change is good and whether a better or existing approach should be used instead.

Pass	What it asks
Heuristic	Vague title? Whitespace-only or cruft-bearing diff? (content signals only)
Duplication	Do added function/class names already exist elsewhere in the repo?
Value Audit	What does it do? What goal does it achieve? Is it good? Better architecture or already-exists?
Usefulness Audit	Does it integrate and fit? Will it hold up in real use and actually get used?

Findings are concerns, not blocks — the human reviewer decides what to do with them.

_{value-audit · 20260803T174930Z}

[tangletools]

✅ No Blockers — 1f29d493

Review health 100/100 · Reviewer score 80/100 · Confidence 80/100 · 8 findings (1 medium, 7 low)

	glm	deepseek	deepseek-flash	aggregate
Readiness	92	82	80	80
Confidence	80	80	80	80
Correctness	92	82	80	80
Security	92	82	80	80
Testing	92	82	80	80
Architecture	92	82	80	80

Reviewer score is advisory once the run is complete and the verdict has no blockers.

Full multi-shot audit completed 4/4 planned shots over 17 changed files. Global verifier still owns final merge decision. | Full multi-shot audit completed 4/4 planned shots over 17 changed files. Global verifier still owns final merge decision. | Full multi-shot audit completed 4/4 planned shots over 17 changed files. Global verifier still owns final merge decision.

🟠 MEDIUM Series count mismatch: 12 found, 13 claimed — docs/editorial/blog-quality-checklist.md

Line 376 states 'The August 3, 2026 audit covers 85 MDX posts and 13 series.' grep of frontmatter in src/content/blog/*.mdx yields exactly 12 unique series values: Agent Intent Infrastructure, Agent Runtime Infrastructure, Blueprint Agent, Blueprint SDK, Browser Agent, Building an AI Tax Agent, Code Auditor, Tangle Protocol, Tangle Re-Introduction, The Instrument Problem, the-self-improving-stack, x402 Production Runway. Either the count is off by one or a planned-but-unpopulated series (e.g. 'When Structure Pays' from blog-series-plan.md) was included without a note that its posts haven't been created yet. An editorial document that stresses claim

🟡 LOW Baseline word-bucket counts are not reproducible by any checked-in or referenced tool — docs/editorial/blog-quality-checklist.md

Line claims '44 posts under 1,000 words, 25 under 750 words, and 20 at or above 2,000 words.' Measured on the exact base content: scripts/audit-blog.mjs wordCount = 43/23/19; scripts/audit-blog-reader.mjs = 43/9/18; the external seo-engine site-audit named in this same file's Required checks (cli.py _check_sa_word_count = len(body.split())) = 42/8/20; prose-only (fences stripped) = 43/9/18. '>=2000' (20) reproduces; 'under 750' (25 vs 8-23) is off by ~2-3x under every method. Since this section's purpose is to direct editorial work and the doc itself demands 'A measurement includes the denominator, conditions, date, and source,' recompute from one named tool and record the tool + date next to the figures.

🟡 LOW Hardcoded developer-machine paths in required-checks block — docs/editorial/blog-quality-checklist.md

The 'Required checks before merging a content PR' section references python3 ~/company/tools/seo-engine/cli.py site-audit --blog-dir ~/code/tangle-website/src/content/blog --json. Both paths are hardcoded to one developer's machine layout. The three pnpm commands and git diff --check are repo-portable; the Python invocation is not. For a document intended as a review contract for a multi-contributor team, either note that the SEO engine is an external tool requiring separate setup, or parameterize the paths.

🟡 LOW Hardcoded home-dir path in required-checks block — docs/editorial/blog-quality-checklist.md

The 'Required checks before merging a content PR' block uses python3 ~/company/tools/seo-engine/cli.py ... --blog-dir ~/code/tangle-website/.... Tilde expansion only works in bash and the path is specific to one contributor's machine layout. Other contributors cloning the repo will not have ~/company/tools/seo-engine or ~/code/tangle-website. Consider documenting where the seo-engine lives in this repo (or as a published package / git submodule) and using a repo-relative path or an npm script wrapper, otherwise the 'required' check is unrunnable for anyone else.

🟡 LOW Required checks reference author-machine absolute paths in a shared repo doc — docs/editorial/blog-quality-checklist.md

Lines 392-396 run python3 ~/company/tools/seo-engine/cli.py site-audit --blog-dir ~/code/tangle-website/src/content/blog. The CLI and site-audit/--blog-dir/--json flags exist (verified), but the tool is outside this repo and the paths are machine-specific, so contributors cannot run the gate as written. Consider a repo-local script or documenting the external dependency (it also crashed with a pthread/jemalloc segfault under constrained thread limits, an environment portability warning worth noting for CI use).

🟡 LOW Series median range claim holds for only 3 of 5 named series — docs/editorial/blog-quality-checklist.md

'Agent Intent Infrastructure, Blueprint Agent, Tangle Protocol, Browser Agent, and Code Auditor series have medians between 720 and 789 words.' Measured medians (audit-blog.mjs wordCount): AII=810.5 (out), Blueprint=735, Tangle Protocol=745, Browser=719 (just under), Code Auditor=755. Under the seo-engine site-audit count all five are 821-905 (none in range). The qualitative conclusion (these are the short series needing rewrites) is correct, but the exact 720-789 band is not reproducible; use the per-series medians from a single named counting method.

🟡 LOW Source of the '93/100' median is ambiguous and the repo's own audit reports a different median — docs/editorial/blog-quality-checklist.md

'The same audit reports a median heuristic SEO score of 93/100' immediately follows the description of the deterministic repo audit (scripts/audit-blog.mjs). That script's per-post heuristic score has median 100 (distribution 100x48, 97x20, 92x10, 89x5, 94x1, 86x1). The 93 median actually comes from the external ~/company/tools/seo-engine site-audit (verified: median exactly 93). Name the tool explicitly to avoid a future editor recomputing the wrong number.

🟡 LOW og:image:type falls back to image/png for unrecognized extensions — src/layouts/BaseLayout.astro

imageType defaults to image/png for any extension other than webp/jpg/jpeg (e.g. .avif, .svg). If a caller ever passes such an image, og:image:type would mislabel it. This is pre-existing in the base (not introduced by this PR — file has zero net diff), and the current image set (default .png, editorial covers .webp) exercises only the two correct branches, so impact is nil today. Optional nit: whitelist .png explicitly and default to undefined to let scrapers sniff, or add .avif/.gif handling.

---

_{tangletools · 2026-08-03T17:54:43Z · trace}

[tangletools]

✅ Approved — 8 non-blocking findings — 1f29d493

Full multi-shot audit completed 4/4 planned shots over 17 changed files. Global verifier still owns final merge decision. | Full multi-shot audit completed 4/4 planned shots over 17 changed files. Global verifier still owns final merge decision. | Full multi-shot audit completed 4/4 planned shots over 17 changed files. Global verifier still owns final merge decision.

Full immutable report for this review: trace

Summary comment for this run: full summary

---

_{tangletools · 2026-08-03T17:54:43Z · immutable trace}

[drewstone]

@PR-Reviewer please review the current head.

[drewstone]

@tangletools please review the current head.

[tangletools]

✅ Auto-approved drewstone PR — f0d01970

This PR was opened by the trusted drewstone account.
The full PR reviewer audit still runs separately and will publish findings if it detects issues.

_{tangletools · auto-approval · reason: drewstone_author · 2026-08-03T20:30:55Z}