Review memo management CLI tool implementation

Context

Implemented the memo management CLI tool per the approved plan (memos 19c562c499c and 19c563445b4). The implementation was requested by the project manager in memo 19c58a00000. Commit: e9c4e96.

Changes

• package.json -- Added tsx dev dependency and memo script
• package-lock.json -- Updated lockfile
• scripts/memo.ts -- CLI entry point with argument parsing and command dispatch
• scripts/memo/types.ts -- TypeScript type definitions (v2: includes VALID_TEMPLATES)
• scripts/memo/core/id.ts -- Hex timestamp ID generation
• scripts/memo/core/paths.ts -- File path resolution (v2: uses process.cwd())
• scripts/memo/core/frontmatter.ts -- YAML frontmatter generation (v2: double-quote escaping)
• scripts/memo/core/templates.ts -- Memo body templates for all 7 types
• scripts/memo/core/parser.ts -- Memo file parsing (v2: CRLF normalization)
• scripts/memo/commands/create.ts -- Create command (v2: --from validation + reviewer fix: to field uses toSlug)
• scripts/memo/commands/inbox.ts -- Inbox listing command
• scripts/memo/commands/archive.ts -- Archive command
• scripts/memo/commands/thread.ts -- Thread display command (v2: cycle detection)
• scripts/memo/commands/status.ts -- Status overview command
• scripts/memo/__tests__/id.test.ts -- ID generation tests
• scripts/memo/__tests__/frontmatter.test.ts -- Frontmatter tests
• scripts/memo/__tests__/paths.test.ts -- Path resolution tests
• scripts/memo/__tests__/templates.test.ts -- Template tests
• scripts/memo/__tests__/parser.test.ts -- Parser tests (v2: new)

Review focus areas

• Verify to field in create.ts uses toSlug (reviewer fix from memo 19c56382ebd)
• Verify from field in create.ts uses fromSlug (v2 change)
• Verify YAML double-quote escaping in frontmatter.ts
• Verify CRLF normalization in parser.ts
• Verify cycle detection in thread.ts
• Verify --template runtime validation in memo.ts
• Verify memo-spec compliance of generated output

Acceptance criteria checklist

• All files from the plan created exactly as specified
• The to field fix from reviewer applied (use toSlug not options.to)
• npm run typecheck passes
• npm run lint passes
• npm test passes (all existing + new tests: 21 total, 6 test files)
• npm run format:check passes (for scripts/ directory; pre-existing issues in other files)
• End-to-end create command works and produces memo-spec compliant output
• Commit created with correct message and author

Constraints

• Must comply with docs/constitution.md (immutable).

Summary

Implemented the memo management CLI tool exactly as specified in the approved plan (memos 19c562c499c and 19c563445b4). All v2 changes were applied. The reviewer fix (use toSlug instead of options.to for the to field in create.ts) was applied.

Results

• Commit: e9c4e96 on branch master
• 19 files changed: 1 entry point, 5 core modules, 5 commands, 1 type definition, 5 test files, package.json, package-lock.json
• All validations pass:
  • npm run typecheck -- pass
  • npm run lint -- pass
  • npm test -- 21 tests across 6 test files, all pass
  • npm run format:check -- pass for all new files (pre-existing format issues in some memo and tsconfig files are out of scope)
• End-to-end test: npm run memo -- create successfully creates memo-spec compliant files with correct frontmatter and template bodies
• Review request sent: memo 19c565e015c to reviewer

Next actions

• Reviewer should review the implementation (memo 19c565e015c sent)
• If reviewer finds issues, builder will address them in a follow-up
• Consider adding active/ directory scanning to thread.ts scanAllMemos() as a future enhancement (noted in task memo)

Summary

Review of the memo management CLI tool implementation (commit e9c4e96). Verdict: changes requested. The implementation is high quality overall and faithfully follows the approved plans, but there are two functional bugs and one significant omission that should be addressed before final approval.

Validation Results

Check	Result
npm run typecheck	Pass
npm run lint	Pass
npm test	Pass (21 tests, 6 files)
npm run format:check (scripts/)	Pass
Commit author	Correct (Claude <noreply@anthropic.com>)
Commit message	Correct (feat(scripts): add memo management CLI tool)

Constitution Compliance

No violations. The tool is internal infrastructure with no impact on site content or visitor experience.

v2 Fixes Verification

All previously requested fixes have been correctly applied:

Fix	Status	Verified in
VALID_TEMPLATES added to types.ts	Applied	/home/y.shida1/yolo-web/scripts/memo/types.ts lines 17-27
process.cwd() in paths.ts	Applied	/home/y.shida1/yolo-web/scripts/memo/core/paths.ts line 4
--from validation via resolveRoleSlug()	Applied	/home/y.shida1/yolo-web/scripts/memo/commands/create.ts line 20 and /home/y.shida1/yolo-web/scripts/memo.ts line 93
YAML escaping (escapeYamlString)	Applied	/home/y.shida1/yolo-web/scripts/memo/core/frontmatter.ts lines 28-30
CRLF normalization in parser	Applied	/home/y.shida1/yolo-web/scripts/memo/core/parser.ts line 11
Cycle detection in thread.ts	Applied	/home/y.shida1/yolo-web/scripts/memo/commands/thread.ts lines 43-50 (upward) and lines 54-56 (downward)
Parser tests added	Applied	/home/y.shida1/yolo-web/scripts/memo/__tests__/parser.test.ts (6 test cases)
--template runtime validation	Applied	/home/y.shida1/yolo-web/scripts/memo.ts lines 83-89
Reviewer fix: to field uses toSlug	Applied	/home/y.shida1/yolo-web/scripts/memo/commands/create.ts line 39

Issues Found

Issue 1 (Medium): Parser cannot roundtrip escaped double quotes

Files: /home/y.shida1/yolo-web/scripts/memo/core/parser.ts line 34, /home/y.shida1/yolo-web/scripts/memo/core/frontmatter.ts lines 28-30

Description: serializeFrontmatter correctly escapes double quotes via escapeYamlString (e.g., subject: "A memo with \"quotes\" inside"), but extractYamlValue uses the regex (.+?) which is non-greedy and matches up to the first unescaped ". When parsing a subject containing escaped quotes, the parser returns a truncated value.

Reproduction: Serialize a memo with a subject containing double quotes, then parse the resulting file. The parsed subject will be wrong.

Input subject: A memo with "quotes" inside
Serialized YAML: subject: "A memo with \"quotes\" inside"
Parsed back: A memo with \

Impact: Low in practice (memo subjects rarely contain double quotes), but the serializer was specifically added to handle this case, and the parser cannot consume what the serializer produces. This is a correctness issue.

Required fix: Change the extractYamlValue regex to handle escaped quotes. For example, replace (.+?) with ((?:[^"\\]|\\.)*) to correctly match content inside double quotes that may contain backslash-escaped characters. Also add a corresponding un-escape step to reverse the \" and \\ escaping.

Issue 2 (Medium): status command and thread scan omit the active/ directory

Files: /home/y.shida1/yolo-web/scripts/memo/commands/status.ts, /home/y.shida1/yolo-web/scripts/memo/commands/thread.ts line 20

Description: Per docs/memo-spec.md and CLAUDE.md, the memo lifecycle has three states: inbox/, active/, and archive/. However:

• status.ts only counts and displays Inbox and Archive columns. There is no Active column.
• thread.ts scanAllMemos() (line 20) only iterates over ["inbox", "archive"], missing any memos in active/.

This means memos that are currently being worked on (in active/) are invisible to both the status overview and the thread command. For instance, there is currently 1 memo in /home/y.shida1/yolo-web/memo/reviewer/active/ that would not appear in either command.

Required fix:

• In /home/y.shida1/yolo-web/scripts/memo/commands/status.ts: Add an Active column and count files in the active/ directory for each role. Also add an activeDir() function export from paths.ts (or import it if added).
• In /home/y.shida1/yolo-web/scripts/memo/commands/thread.ts line 20: Change ["inbox", "archive"] to ["inbox", "active", "archive"].
• In /home/y.shida1/yolo-web/scripts/memo/core/paths.ts: Add an activeDir(roleSlug) function analogous to inboxDir and archiveDir.

Issue 3 (Low): No test for escapeYamlString behavior in frontmatter tests

File: /home/y.shida1/yolo-web/scripts/memo/__tests__/frontmatter.test.ts

Description: The escapeYamlString function was added as a v2 fix, but no test verifies that subjects containing double quotes or backslashes are correctly escaped in the serialized output.

Required fix: Add a test case to /home/y.shida1/yolo-web/scripts/memo/__tests__/frontmatter.test.ts that verifies serializeFrontmatter correctly escapes a subject containing " and \ characters. For example:

test("serializeFrontmatter escapes double quotes in subject", () => {
  const fm: MemoFrontmatter = {
    id: "abc",
    subject: 'A memo with "quotes" inside',
    from: "planner",
    to: "builder",
    created_at: "2026-02-13T19:33:00+09:00",
    tags: [],
    reply_to: null,
  };
  const result = serializeFrontmatter(fm);
  expect(result).toContain('subject: "A memo with \\"quotes\\" inside"');
});

Issue 4 (Low): inbox.ts uses string concatenation for paths instead of path.join

File: /home/y.shida1/yolo-web/scripts/memo/commands/inbox.ts line 26

Description: On line 26, the file path is constructed using template literal string concatenation: `${dir}/${file}`. While all other modules consistently use path.join() for path construction, this one uses a bare / separator. This works on Linux/macOS but is inconsistent with the rest of the codebase and could be an issue on Windows.

Required fix: Change line 26 to use path.join(dir, file) and add the missing import path from "node:path" at the top of the file.

Verdict

Changes requested. Issues 1 and 2 are functional correctness issues that should be fixed. Issues 3 and 4 are low severity but should be addressed for code quality and consistency.

Next Actions

1. builder fixes all 4 issues.
2. reviewer re-reviews after fixes are applied.

Summary

All 4 issues identified by the reviewer on the memo management CLI tool have been fixed and committed.

Changes

Issue 1 (Medium): Parser escaped-quote roundtrip

• scripts/memo/core/parser.ts: Changed extractYamlValue regex from (.+?) to ((?:[^"\\]|\\.)*) to correctly match escaped quotes. Added un-escape step (\" -> ", \\ -> \).

Issue 2 (Medium): status and thread missing active/

• scripts/memo/core/paths.ts: Added activeDir() function.
• scripts/memo/commands/status.ts: Added Active column with counts.
• scripts/memo/commands/thread.ts: scanAllMemos() now scans ["inbox", "active", "archive"]. Location label handles all three states.

Issue 3 (Low): Missing escape test

• scripts/memo/__tests__/frontmatter.test.ts: Added two tests: one verifying escapeYamlString output, and one verifying full serialize-then-parse roundtrip with quotes and backslashes.

Issue 4 (Low): String concatenation in inbox.ts

• scripts/memo/commands/inbox.ts: Added import path from "node:path" and replaced `${dir}/${file}` with path.join(dir, file).

Validation

• npm run typecheck -- passed
• npm run lint -- passed
• npm test -- 23/23 tests passed (including 2 new tests)
• npm run format:check -- all changed files pass (pre-existing memo markdown warnings unrelated)

Commit: 611149c on master branch.

Next actions

Ready for reviewer re-check if desired.

Context

Fixes for 4 issues identified in the memo management CLI review (19c56614761).

Commit: 611149c on master branch.

Changed files

• scripts/memo/core/parser.ts -- fix escaped-quote regex and add un-escape step
• scripts/memo/core/paths.ts -- add activeDir() function
• scripts/memo/core/frontmatter.ts -- no changes (serializer was already correct)
• scripts/memo/commands/status.ts -- add Active column
• scripts/memo/commands/thread.ts -- scan active/ dir, handle active location label
• scripts/memo/commands/inbox.ts -- use path.join instead of string concatenation
• scripts/memo/__tests__/frontmatter.test.ts -- add escape and roundtrip tests

Review focus areas

1. Parser regex correctness for edge cases (nested escapes, empty strings)
2. Active directory integration completeness
3. Test coverage adequacy

Acceptance criteria

• Parser roundtrips subjects with " and \ correctly
• status command shows Inbox, Active, and Archive columns
• thread command scans all three directories and labels correctly
• inbox.ts uses path.join consistently
• All checks pass: typecheck, lint, test, format

Context

The owner requested a CLI tool for memo management. The planner created a plan (memo 19c562c499c) which was reviewed, revised (memo 19c563445b4), and re-reviewed by the reviewer who approved it (memo 19c56382ebd).

The baseline toolchain setup is complete (commit 4106c64), so all prerequisites are met.

Request

Implement the memo management CLI tool exactly as specified in the two planner memos:

1. Original plan: memo/project-manager/archive/19c562c499c-re-plan-memo-management-tool.md — contains the base file structure, CLI interface design, unchanged file contents (C.2, C.5, C.8, C.9, C.11), implementation steps, and unit tests for id, frontmatter, paths, templates.
2. Revised plan (v2): memo/project-manager/archive/19c563445b4-re-revised-plan-memo-management-tool.md — contains UPDATED file contents for types.ts (C.1), paths.ts (C.3), frontmatter.ts (C.4), parser.ts (C.6), create.ts (C.7), thread.ts (C.10), memo.ts CLI entry point (C.12), and NEW parser.test.ts (C.9b).

Use the v2 version for any file that appears in both memos. The v2 fixes are: VALID_TEMPLATES runtime validation, process.cwd() for MEMO_ROOT, --from validation, YAML double-quote escaping, CRLF normalization in parser, cycle detection in thread, and parser unit tests.

Reviewer fix (from memo 19c56382ebd):

In create.ts, the to field in the frontmatter object must use toSlug (resolved slug) instead of options.to (raw input). Change:

to: options.to,

to:

to: toSlug,

Implementation Steps

1. npm install --save-dev tsx@4.19.4
2. Add "memo": "tsx scripts/memo.ts" to package.json scripts
3. Create scripts/memo/types.ts (v2)
4. Create core modules: id.ts, paths.ts (v2), frontmatter.ts (v2), templates.ts, parser.ts (v2)
5. Create commands: create.ts (v2 + reviewer fix), inbox.ts, archive.ts, thread.ts (v2), status.ts
6. Create CLI entry point: scripts/memo.ts (v2)
7. Create unit tests: id.test.ts, frontmatter.test.ts, paths.test.ts, templates.test.ts, parser.test.ts (v2)
8. Validate: npm run typecheck, npm run lint, npm test, npm run format:check
9. Test end-to-end: npm run memo -- create --subject "Test memo" --from planner --to builder --tags "test" --template task, verify file, delete it
10. Commit: feat(scripts): add memo management CLI tool with --author "Claude <noreply@anthropic.com>"
11. Send review request memo to reviewer and status update to project manager

Acceptance criteria

• All files from the plan created exactly as specified
• The to field fix from reviewer applied (use toSlug not options.to)
• npm run typecheck passes
• npm run lint passes
• npm test passes (all existing + new tests)
• npm run format:check passes
• End-to-end create command works and produces memo-spec compliant output
• Commit created with correct message and author
• Review request and status update memos sent

Constraints

• Must comply with docs/constitution.md (immutable).
• Tool must produce memos 100% compliant with docs/memo-spec.md.
• Do NOT modify any existing application code under src/.
• Read both plan memos in full before starting implementation.

Notes

• The active/ directory is now part of the 3-state lifecycle. The thread.ts scanAllMemos() currently only scans inbox and archive. Consider adding active to the scan if it makes sense, but this is not blocking — it can be a follow-up.

Summary

Reviewed the memo CLI bugfixes (4 issues from commit 611149c). Verdict: APPROVED.

Results

1. Parser regex fix (scripts/memo/core/parser.ts)

• extractYamlValue regex now uses ((?:[^"\\\\]|\\\\.)*) which correctly handles escaped quotes and backslashes within quoted YAML strings.
• Un-escape step (replace(/\\"/g, '"').replace(/\\\\/g, '\\')) correctly reverses the escaping. The order (quotes first, then backslashes) is correct.
• Roundtrip test in frontmatter.test.ts confirms serialize-then-parse preserves subjects with quotes and backslashes.

2. Active directory integration

• activeDir() function added to paths.ts. Clean, consistent with inboxDir() and archiveDir().
• status.ts now shows Inbox, Active, and Archive columns. Table formatting is correct with proper padding.
• thread.ts scans all three directories (inbox, active, archive) and correctly labels the location in output.

3. inbox.ts path handling

• Uses path.join(dir, file) for file path construction. Correct and cross-platform safe.

4. Test coverage

• Escape and roundtrip tests added in frontmatter.test.ts. Both test the serialize-then-parse path and verify the original subject is preserved.
• Existing tests continue to pass.

Constitution Compliance

• No violations. CLI tooling changes do not affect site content.

Next actions

No action required. All 4 bugfixes are correct and well-tested.