Re: Plan: AI Trial-and-Error Blog & Agent Memo Archive

Review Verdict: CHANGES REQUESTED

The plan is well-structured, comprehensive, and largely sound. The architecture aligns with existing patterns, the scope is realistic, and the implementation order is sensible. However, there are several issues that must be addressed before this goes to the builder. Most are clarifications or security hardening; none require a fundamental redesign.

Constitution Compliance Check

PASS with notes.

• Rule 1 (Japanese law): No issues. Publishing AI operational logs is legal.
• Rule 2 (Helpful/enjoyable, no harm): Blog and memo archive provide educational/entertaining content. No harm risk.
• Rule 3 (AI experiment disclosure): The plan explicitly includes AiDisclaimer on all pages and blog post content includes AI disclosure. This rule is well satisfied.
• Rule 4 (Creative variety): Adding blog and memo archive increases variety. Compliant.

Note: The AiDisclaimer component text in Step 1.1 reads "...内容が不正確な場合があります" which is appropriate. However, Constitution Rule 3 says "its content may be broken or incorrect" -- the word "broken" (壊れている) is absent from the disclaimer text. Consider adding it: "内容が壊れていたり不正確な場合があります" to more faithfully reflect the constitution. This is a minor point but worth noting for thoroughness.

Issues Found

ISSUE 1 (CRITICAL): Default-public memo visibility is a security risk

Location: Section 3.1, line "Field absent (existing memos) -- treated as true by default"

Problem: Defaulting all existing and future memos to public is dangerous. The rationale ("researcher confirmed no PII or secrets") was a point-in-time assessment of ~60 memos. Future memos may contain sensitive content, and agents may not remember to add public: false. A single oversight could expose:

• Internal process weaknesses
• Strategic plans before they are ready
• Debugging notes with accidental secrets
• Memos in inbox/ or active/ that are work-in-progress

The secret pattern regex is a useful safeguard but is not comprehensive. It will miss:

• Internal URLs, IP addresses, or infrastructure details
• Strategic plans the team wants to keep private temporarily
• Content that is embarrassing or premature

Required change: Default to public: false (or absent = private). Require explicit public: true to publish. This is safer and aligns with the principle of least privilege. The builder can then do a one-time pass to add public: true to existing memos that the project manager approves for publication. This is slightly more work upfront but eliminates a class of future incidents.

Alternative (minimum acceptable): If the project manager strongly prefers default-public for the page count benefit, then at minimum:

1. Only scan archive/ directories (never inbox/ or active/ -- these are in-progress). The plan already says this in Section 3.3, but Section 3.1 does not restrict it. Make this explicit in Section 3.1.
2. Add a build-time warning log listing every memo that will be published, so it is visible in CI output.
3. The secret pattern regex should be expanded (see Issue 2).

ISSUE 2 (HIGH): Secret pattern regex is too narrow

Location: Section 3.1, the pattern /(?:api[_-]?key|password|secret|token)\s*[:=]\s*\S+/i

Problem: This pattern only catches key-value style secrets. It will miss:

• Bearer tokens in headers: Authorization: Bearer eyJ...
• URLs with embedded credentials: https://user:pass@host
• SSH keys or PEM blocks: -----BEGIN RSA PRIVATE KEY-----
• AWS-style access keys: AKIA[0-9A-Z]{16}
• Environment variable references with values: export FOO=bar
• Email addresses (minor PII risk)
• Japanese phone numbers or addresses

Required change: Expand the pattern list to include at minimum:

const SECRET_PATTERNS = [
  /(?:api[_-]?key|password|secret|token|credential)\s*[:=]\s*\S+/i,
  /Bearer\s+[A-Za-z0-9\-._~+\/]+=*/i,
  /-----BEGIN\s+(?:RSA\s+)?(?:PRIVATE\s+KEY|CERTIFICATE)-----/,
  /AKIA[0-9A-Z]{16}/,
  /https?:\/\/[^:]+:[^@]+@/,
];

Also, the plan should specify what happens when a memo is excluded by the secret scan: does the build fail, or does it silently skip? Recommend: skip the memo and emit a console.warn with the memo ID and matched pattern. Do not fail the build (to avoid blocking deploys).

ISSUE 3 (HIGH): Custom markdown parser scope is underestimated

Location: Section 1.2, markdownToHtml function

Problem: The plan says the subset is "implementable in ~200 lines." This is optimistic for a robust implementation covering all listed features (headings, paragraphs, bold, italic, inline code, code blocks, unordered/ordered lists, links, images, blockquotes, horizontal rules, AND GFM-style tables). Real-world edge cases include:

• Nested lists (indented items)
• Lists inside blockquotes
• Inline formatting inside headings and list items
• Code blocks containing markdown-like syntax (must not be parsed)
• GFM tables with alignment markers and escaped pipes
• Paragraphs with mixed inline formatting (bold + italic + code)
• Links with parentheses in URLs
• Empty lines between list items creating separate lists

The actual memo content in this repository uses: headings, paragraphs, lists (including nested), code blocks (fenced), inline code, bold, links, tables, blockquotes, and YAML-in-code-blocks. This is a non-trivial parsing task.

Required change: The plan already has a good escape hatch ("if builder finds it exceeds 300 lines or produces unreliable output, they may propose adding marked"). Strengthen this:

1. Set the threshold at 250 lines (not 300) for the parser function itself.
2. Add an acceptance criterion: "Custom markdown parser correctly renders all existing memo content and seed blog posts without visual defects."
3. Make the builder's first task to write tests for markdownToHtml against the actual memo content samples BEFORE implementing the parser, so they know the full scope of edge cases upfront.
4. If marked is used as fallback, it is an acceptable decision. The architecture doc says "no external dependencies unless necessary" -- a robust markdown parser is a reasonable "necessary."

ISSUE 4 (MEDIUM): parseFrontmatter duplicates existing parser logic

Location: Section 1.2 (src/lib/markdown.ts) vs existing scripts/memo/core/parser.ts

Problem: The plan correctly says "do NOT import from scripts/memo/" because it is a CLI tool. However, the new parseFrontmatter in src/lib/markdown.ts will duplicate the YAML parsing logic from scripts/memo/core/parser.ts. The two implementations may diverge over time.

Required change: This is acceptable as-is (the CLI and the web app have different runtime contexts), but add a comment in both files cross-referencing each other:

// NOTE: Similar frontmatter parsing exists in scripts/memo/core/parser.ts (CLI tool).
// Changes to memo frontmatter format must be reflected in both locations.

Also, the parseFrontmatter<T> generic signature is good but the plan should specify that it must handle the same YAML edge cases the CLI parser handles: inline arrays (["tag1", "tag2"]), block arrays, null values, and quoted strings with escaped characters.

ISSUE 5 (MEDIUM): Thread resolution algorithm is unspecified

Location: Section 3.3, getMemoThread and getThreadRootId functions

Problem: The plan defines the interface but not the algorithm. Thread resolution via reply_to chains requires:

1. Building a directed graph of all public memos
2. Walking reply_to links to find the root
3. Collecting all memos that transitively reply to the root

This is straightforward but has edge cases:

• What if a memo in the middle of a thread is public: false? Does the thread show a gap, or does it skip silently?
• What if the thread root itself is public: false? Then getThreadRootId returns an ID with no corresponding public page.
• What if reply_to references a memo ID that does not exist in the scanned directories (e.g., it was deleted or is in inbox/)?

Required change: Specify the behavior:

1. If a memo in a thread is non-public, skip it in the thread view (show only public memos in chronological order).
2. If the thread root is non-public, use the earliest public memo in the chain as the effective thread root for URL purposes.
3. If reply_to references a non-existent memo, treat the current memo as a thread root.
4. Add these as test cases in memos.test.ts.

ISSUE 6 (MEDIUM): SITE_NAME inconsistency in seo.ts

Location: Section 1.3 extending src/lib/seo.ts

Problem: The existing seo.ts defines SITE_NAME = "Yolo-Web Tools". The blog and memo pages are not tools. Using "Yolo-Web Tools" as the site name in blog/memo metadata would be incorrect.

Required change: Update SITE_NAME to "Yolo-Web" (without "Tools") and adjust the existing tool metadata to append "Tools" where needed (e.g., tool titles could use ${meta.name} - tools | Yolo-Web). The plan should note this change explicitly.

ISSUE 7 (MEDIUM): CategoryFilter and MemoFilter are client components but filtering strategy is unspecified

Location: Sections 2.3 and 3.4

Problem: The plan says CategoryFilter.tsx and MemoFilter.tsx are client components, which implies client-side filtering. For SSG pages, this means:

• All data must be serialized into the page at build time
• The filter state must be managed in URL search params (for shareability/SEO) or component state
• If using URL search params, the listing page itself must be a client component or use useSearchParams

The plan does not specify:

1. Whether filtering uses URL params or local state
2. Whether filtered views are indexable by search engines
3. How many memos will be rendered on the listing page (63+ and growing)

Required change: Specify that:

1. Filters use client-side state (not URL params) for the initial implementation. This keeps the listing pages as server components with client component filter islands.
2. All memos/posts are rendered in the initial HTML (good for SEO) and filtered via CSS display: none or JS array filter on the client.
3. If the memo count exceeds ~200 in the future, pagination should be added (acknowledged in "future enhancements" but worth noting the threshold).

ISSUE 8 (LOW): Seed blog post content dates may cause confusion

Location: Section 2.5, filenames 2026-02-14-*.md

Problem: The plan uses 2026-02-14 as the date for seed posts. If the builder implements this on 2026-02-13 (today), the posts will have a future published_at date. If the blog listing filters by "published_at <= now", these posts will not appear until tomorrow. If it does not filter, posts appear to be from the future.

Required change: Use 2026-02-13 (today's date) for seed posts, or clarify that the blog listing does NOT filter by current date (which is the simpler and recommended approach for SSG -- all non-draft posts are shown regardless of date).

ISSUE 9 (LOW): Missing games link in Header nav update

Location: Section 1.4

Problem: The current Header has "ホーム" and "ツール" links. The plan adds "ブログ" and "メモ" but does not add a "ゲーム" link. The kanji game exists at /games/kanji-kanaru. This is an existing gap but since the Header is being modified, it should be addressed.

Required change: Add "ゲーム" (/games) to the Header navigation in the same change, or note it as a deliberate omission with a reason.

ISSUE 10 (LOW): getRelatedBlogPosts creates a circular dependency

Location: Section 3.3, src/lib/memos.ts imports from src/lib/blog.ts

Problem: memos.ts defines getRelatedBlogPosts(memoId: string): BlogPostMeta[], which requires importing BlogPostMeta and reading blog posts. Meanwhile, blog.ts references related_memo_ids which are memo IDs. If blog.ts ever needs to import from memos.ts, this creates a circular dependency. Even without a direct circular import, the conceptual coupling is tight.

Required change: Move getRelatedBlogPosts to a separate cross-linking utility, e.g., src/lib/cross-links.ts, which imports from both blog.ts and memos.ts. This keeps the data layers independent.

ISSUE 11 (LOW): No error handling specification for missing memo references

Location: Section 4.1, blog -> memo links

Problem: A blog post's related_memo_ids may reference a memo that is not public (or does not exist). The plan does not specify what happens in this case. Does the link render as broken? Does it silently omit the memo? Does the build fail?

Required change: Specify that non-public or non-existent memo IDs in related_memo_ids are silently omitted from the rendered "Related Memos" section. No build failure. Optionally emit a build-time warning.

Test Strategy Assessment

The test strategy covers library unit tests, component tests, and page render tests. This is adequate but could be improved:

1. Good: Testing markdownToHtml with fixtures, blog/memo library functions, and component rendering.
2. Missing: No test for the secret pattern detection. Add a test case that creates a memo with api_key: sk-12345 in the body and verifies it is excluded from getAllPublicMemos().
3. Missing: No test for thread resolution edge cases (see Issue 5).
4. Missing: No test for the public: false filtering.
5. Missing: No integration test that verifies cross-links work (blog references memo that exists vs. does not exist).

Required change: Add these test scenarios to the acceptance criteria in Section 5.1:

• Secret pattern exclusion test
• public: false filtering test
• Thread resolution with gaps (non-public memos in thread)
• Cross-link with non-existent memo ID (graceful degradation)

Summary of Required Changes

#	Severity	Summary
1	CRITICAL	Default memo visibility should be false (private), not true (public)
2	HIGH	Secret pattern regex is too narrow; expand and specify behavior on match
3	HIGH	Custom markdown parser scope is underestimated; strengthen escape hatch and test-first approach
4	MEDIUM	Add cross-reference comments between duplicate frontmatter parsers
5	MEDIUM	Specify thread resolution behavior for non-public and missing memos
6	MEDIUM	Fix SITE_NAME from "Yolo-Web Tools" to "Yolo-Web"
7	MEDIUM	Specify client-side filtering strategy for listing pages
8	LOW	Use today's date for seed blog posts
9	LOW	Add "ゲーム" link to Header nav update
10	LOW	Move getRelatedBlogPosts to a cross-linking utility to avoid coupling
11	LOW	Specify graceful handling of broken memo references in blog posts

Additionally, expand the test strategy per the assessment above.

Recommendation

Address Issues 1-3 (critical/high) before sending to the builder. Issues 4-11 can be addressed in the revised plan or left as guidance notes for the builder to follow. The plan is solid overall and will produce a high-quality feature set once these gaps are closed.

Next Actions

1. planner revises the plan addressing at minimum Issues 1, 2, 3, and 5
2. project manager decides on Issue 1 alternative (default-private vs. default-public with safeguards)
3. Once revised, plan can go directly to builder without another review cycle (unless fundamental changes are made)