Skip to content

docs: scaffold docs/adr/ with template, seed ADR-0001, and INDEX #62

@mikanmarusan

Description

@mikanmarusan

Goal

Stand up the ADR home so the x-recording-adr skill engages. Today the repo has no docs/adr/ and no adoption marker, so the skill exits no-decision ("repository has not opted in") on every run. This issue creates the ADR directory, the MADR-Minimal template, a real seed ADR, and the index. (The CLAUDE.md adr-dir: marker is wired in a separate issue.)

Your Task

Create the following under docs/adr/:

  1. docs/adr/0000-template.md — verbatim MADR-Minimal scaffold from the x-recording-adr skill:
    • YAML frontmatter status: Proposed and applyTo: <repo-relative glob>
    • Headings: # NNNN. <Title>, ## Status, ## Context, ## Decision, ## Consequences
    • Add a single comment line noting that applyTo is a local extension (not a standard MADR field).
  2. docs/adr/0001-jorudan-cookie-flow-scraper.md — seed ADR recording the repo's foundational decision:
    • Frontmatter status: Accepted, applyTo: src/index.mjs
    • Context: Jorudan publishes no public API and fronts its site with a JS-based bot check, so a naive fetch() returns an HTML stub.
    • Decision: hand-rolled 3-step cookie flow on AWS Lambda (Node.js 22, ESM) in src/index.mjs, with the safeJoinUrl() SSRF guard and escapeRegExp() ReDoS guard.
    • Rejected alternatives: a headless browser (heavier cold starts/cost) and a paid/third-party transit API (no Jorudan-equivalent route data; defeats the cheapest-board goal).
    • Consequences: include at least one negative — tight coupling to Jorudan's server-rendered HTML and cookie endpoints means any change to the bot check, set-uuid.cgi flow, <hr size="1" color="black"> delimiter, or 発着時間: route lookahead silently breaks parsing.
    • Add an in-file note that status: Accepted is a deliberate hand-seed of an already-live decision, deviating from the skill's Proposed-only automated-write rule.
  3. docs/adr/INDEX.md — table with the exact shape | ID | Title | Status | applyTo | File | plus the separator row, a one-line lifecycle legend (Proposed → Accepted (on PR merge) → {Deprecated | Superseded | Rejected}), and a "do not hand-edit rows; regenerated on each run" note. One data row for 0001; exclude the 0000 template.

Context

  • Source plan: .plans/planning-adr-spec-docs-20260620.md (Tasks 1–3, decision D1).
  • x-recording-adr writes only under docs/adr/** and treats docs/architecture* as read-only — no overlap with the spec-docs work.
  • Engagement ladder: an adr-dir: marker in CLAUDE.md (added in the CLAUDE.md issue) is rung 1; an existing docs/adr/ directory is rung 3. This issue satisfies the directory side.

Warning

  • Do NOT transcribe real AWS identifiers into the ADR. The repo's docs/architecture.md currently hardcodes the real account ID 470021024556 and resource IDs; the seed ADR must not reproduce them. Refer to secret names only (already public in CLAUDE.md).
  • Do not add a spec-synced-through managed-region marker to any docs/adr/** file — that marker belongs to the spec docs only.

Acceptance Criteria

  • test -f docs/adr/0000-template.md && test -f docs/adr/0001-jorudan-cookie-flow-scraper.md && test -f docs/adr/INDEX.md exits 0.
  • 0001-jorudan-cookie-flow-scraper.md has YAML frontmatter containing both status: Accepted and applyTo: src/index.mjs (verify by reading the file head).
  • The seed ADR body names at least one rejected option and at least one negative consequence (manual read against the list above).
  • grep -rEn '470021024556|E58KEXJEHRAN5|EE7PDHZSW7GW8|63zlpdau7f|arn:aws:[a-z0-9-]+:[a-z0-9-]*:[0-9]{12}:' docs/adr/ returns no matches.
  • grep -n '| ID | Title | Status | applyTo | File |' docs/adr/INDEX.md returns the header row, and INDEX.md has exactly one data row (for 0001).

Metadata

Metadata

Assignees

No one assigned

    Labels

    loop:readyReady for the autonomous fix loop

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions