You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Make the x-syncing-specs skill engage and establish the spec-docs IA. Today there is no docs/architecture/ directory, so the skill exits no-drift ("not a spec-sync target"). This issue migrates the detail sections out of the single docs/architecture.md into per-subsystem detail docs (redacting leaked identifiers along the way) and reduces docs/architecture.md to a thin overview/index. (The CLAUDE.mdspec-doc: marker is wired in a separate issue.)
Your Task
Create docs/architecture/ and move (do not copy) the detail sections out of docs/architecture.md:
"Production Deploy Constraint" + "CI/CD Deploy Role IAM Policy" (policy JSON)
Each detail doc opens with # Heading + a breadcrumb line > Part of [Architecture overview](../architecture.md). (breadcrumb stays outside any managed region).
Managed-region markers only on code-derived docs: jorudan-cookie-flow.md, html-parsing.md, api-contract.md each wrap their migrated body in <!-- spec-synced-through: a710d8f --> … <!-- /spec-synced-through -->. observability.md and deploy-and-iam.md carry NO marker (ops/runbook/rationale with no code source to reconcile — leaving them marker-free keeps x-syncing-specs from overwriting hand-written ops info).
Redact every real identifier during migration (especially in deploy-and-iam.md): 470021024556 → <ACCT>, and resource IDs → <CF_DISTRIBUTION_ID> / <OAC_ID> / <REST_API_ID> / <SAM_ARTIFACT_BUCKET> / <FRONTEND_BUCKET>, matching the existing <ACCT> convention in CLAUDE.md.
Fix relative-link depth in moved content (one level deeper): ../CLAUDE.md → ../../CLAUDE.md, ../template.yml → ../../template.yml, ../.github/... → ../../.github/....
Reduce docs/architecture.md to an overview/index: keep title, intro, the High-Level Architecture table, and the diagram links (./diagrams/... paths unchanged); replace the removed detail sections with a "Detail Documents" table linking the five new docs. Leave overview prose outside any managed-region marker.
Context
Source plan: .plans/planning-adr-spec-docs-20260620.md (Tasks 4–5; Codex finding Add Claude Code GitHub Workflow #1 on marker scoping; Security T1 on identifier redaction).
a710d8f is the current HEAD SHA at plan time; it anchors the next on-demand sync's diff range.
x-syncing-specs writes only docs/architecture.md + docs/architecture/** — no overlap with docs/adr/**.
Warning
This change MUST remove the real account ID 470021024556 from the working tree (it appears 12× in docs/architecture.md today). After migration the identifier grep must be clean — the skills' sensitive-scan does not run on this manual edit and would not match a bare account ID anyway.
Move content, never duplicate it: a fact must live in exactly one of the overview vs a detail doc, or the docs drift.
CI has no link checker, so verify every relative link by hand.
Acceptance Criteria
test -d docs/architecture && ls docs/architecture/jorudan-cookie-flow.md docs/architecture/html-parsing.md docs/architecture/api-contract.md docs/architecture/observability.md docs/architecture/deploy-and-iam.md all exist.
grep -rEn '470021024556|E58KEXJEHRAN5|EE7PDHZSW7GW8|63zlpdau7f|samclisourcebucket-[a-z0-9]+|arn:aws:[a-z0-9-]+:[a-z0-9-]*:[0-9]{12}:' docs/architecture docs/architecture.md returns no matches.
grep -l 'spec-synced-through' docs/architecture/*.md lists exactly the three code-derived docs (jorudan-cookie-flow, html-parsing, api-contract) and NOT observability.md or deploy-and-iam.md.
Each of the three code-derived docs contains exactly one opening <!-- spec-synced-through: a710d8f --> marker.
Every relative link in docs/architecture.md and docs/architecture/*.md resolves: for each ](./...) / ](../...) target, test -e from the file's own directory exits 0.
docs/architecture.md no longer contains the migrated detail bodies (e.g. grep -c 'set-uuid.cgi' docs/architecture.md returns 0) and has a "Detail Documents" table linking the five docs.
Goal
Make the
x-syncing-specsskill engage and establish the spec-docs IA. Today there is nodocs/architecture/directory, so the skill exitsno-drift("not a spec-sync target"). This issue migrates the detail sections out of the singledocs/architecture.mdinto per-subsystem detail docs (redacting leaked identifiers along the way) and reducesdocs/architecture.mdto a thin overview/index. (TheCLAUDE.mdspec-doc:marker is wired in a separate issue.)Your Task
docs/architecture/and move (do not copy) the detail sections out ofdocs/architecture.md:docs/architecture/jorudan-cookie-flow.mdsafeJoinUrl()SSRF guarddocs/architecture/html-parsing.mdescapeRegExp()ReDoS guarddocs/architecture/api-contract.mddocs/architecture/observability.mddocs/architecture/deploy-and-iam.md# Heading+ a breadcrumb line> Part of [Architecture overview](../architecture.md).(breadcrumb stays outside any managed region).jorudan-cookie-flow.md,html-parsing.md,api-contract.mdeach wrap their migrated body in<!-- spec-synced-through: a710d8f -->…<!-- /spec-synced-through -->.observability.mdanddeploy-and-iam.mdcarry NO marker (ops/runbook/rationale with no code source to reconcile — leaving them marker-free keepsx-syncing-specsfrom overwriting hand-written ops info).deploy-and-iam.md):470021024556→<ACCT>, and resource IDs →<CF_DISTRIBUTION_ID>/<OAC_ID>/<REST_API_ID>/<SAM_ARTIFACT_BUCKET>/<FRONTEND_BUCKET>, matching the existing<ACCT>convention inCLAUDE.md.../CLAUDE.md→../../CLAUDE.md,../template.yml→../../template.yml,../.github/...→../../.github/....docs/architecture.mdto an overview/index: keep title, intro, the High-Level Architecture table, and the diagram links (./diagrams/...paths unchanged); replace the removed detail sections with a "Detail Documents" table linking the five new docs. Leave overview prose outside any managed-region marker.Context
.plans/planning-adr-spec-docs-20260620.md(Tasks 4–5; Codex finding Add Claude Code GitHub Workflow #1 on marker scoping; Security T1 on identifier redaction).a710d8fis the current HEAD SHA at plan time; it anchors the next on-demand sync's diff range.x-syncing-specswrites onlydocs/architecture.md+docs/architecture/**— no overlap withdocs/adr/**.Warning
470021024556from the working tree (it appears 12× indocs/architecture.mdtoday). After migration the identifier grep must be clean — the skills' sensitive-scan does not run on this manual edit and would not match a bare account ID anyway.Acceptance Criteria
test -d docs/architecture && ls docs/architecture/jorudan-cookie-flow.md docs/architecture/html-parsing.md docs/architecture/api-contract.md docs/architecture/observability.md docs/architecture/deploy-and-iam.mdall exist.grep -rEn '470021024556|E58KEXJEHRAN5|EE7PDHZSW7GW8|63zlpdau7f|samclisourcebucket-[a-z0-9]+|arn:aws:[a-z0-9-]+:[a-z0-9-]*:[0-9]{12}:' docs/architecture docs/architecture.mdreturns no matches.grep -l 'spec-synced-through' docs/architecture/*.mdlists exactly the three code-derived docs (jorudan-cookie-flow, html-parsing, api-contract) and NOT observability.md or deploy-and-iam.md.<!-- spec-synced-through: a710d8f -->marker.docs/architecture.mdanddocs/architecture/*.mdresolves: for each](./...)/](../...)target,test -efrom the file's own directory exits 0.docs/architecture.mdno longer contains the migrated detail bodies (e.g.grep -c 'set-uuid.cgi' docs/architecture.mdreturns 0) and has a "Detail Documents" table linking the five docs.