ldraney/pal-e-api

Archived

Fork

You've already forked pal-e-api

Code Issues 15 Pull requests 1 Projects Releases Packages Wiki Activity Actions

Migrate arch-generic-checkout to template-conformant architecture note (or remove from arch namespace) #254

New issue

Open

opened 2026-04-11 20:30:24 +00:00 by forgejo_admin · 1 comment

forgejo_admin commented

2026-04-11 20:30:24 +00:00

Contributor

Copy link

Type

Feature

Lineage

Discovered during forgejo_admin/claude-custom#239 (mermaid fence enforcement). The hardened hook would deny arch-generic-checkout because it has no mermaid diagram — it's a legacy HTML-table prose note in the arch- namespace that never followed template-architecture. The dev agent grandfathered it by slug to ship the hook on schedule. This ticket is the proper cleanup.

Repo

forgejo_admin/pal-e-api

User Story

As the Superuser (Lucas)
I want every note in the arch- namespace to follow template-architecture (or be moved out of the namespace if it doesn't fit)
So that the architecture triplet axiom holds across the knowledge base and the hook grandfather list shrinks toward zero

Traces to: story:superuser-maintain on project-pal-e-docs.

Architecture

arch:notes — the notes component in arch-domain-pal-e-docs

Context

The hardened check-note-template.sh (claude-custom#239) requires architecture notes to contain a mermaid fence. arch-generic-checkout has none — it's a prose explanation of a generic checkout flow rendered as HTML tables.

Two valid resolutions:

Migrate: rewrite the note with a proper sequenceDiagram of the checkout flow (rename slug to arch-dataflow-generic-checkout).
Demote: change note_type from architecture to doc, rename slug to doc-generic-checkout-flow.

Recommendation: option 1. The content describes a runtime flow, which is what sequenceDiagram is for.

File Targets

This is content work, not code work.

Read: mcp__pal-e-docs__get_note(slug="arch-generic-checkout")
Update via mcp__pal-e-docs__update_note matching template-architecture (Diagram with sequenceDiagram fence, Components, Key Decisions, Related)
After successful update, remove arch-generic-checkout from the grandfather list in hooks/check-note-template.sh (claude-custom)

Acceptance Criteria

arch-generic-checkout (or renamed successor) contains a valid mermaid fence with the correct facet keyword
All 4 required template-architecture sections present (Diagram, Components, Key Decisions, Related)
check-note-template.sh accepts the note WITHOUT being on the grandfather list
Grandfather list updated in claude-custom hook (separate small PR)
No other arch notes affected

Test Expectations

Manual test: invoke mcp__pal-e-docs__update_note against the migrated note and verify the hook accepts on first try
Regression: re-run the 28-note arch fixture test from claude-custom#239 with arch-generic-checkout removed from grandfather — must still pass
Run: bash /tmp/claude-custom-test/hooks/check-note-template.sh against fixture inputs

Constraints

Do not delete existing content — preserve the prose explanation in the new structure
Coordinate with claude-custom hook PR — content migration must land first, then grandfather removal
If demoting (option 2), search board items for any arch: labels pointing to the slug

Checklist

Content migrated
Grandfather entry removed in follow-up PR
No unrelated changes

forgejo_admin/claude-custom#239 — parent ticket that surfaced this
template-architecture — the spec being conformed to
arch-domain-pal-e-docs — example of a template-conformant note

### Type Feature ### Lineage Discovered during forgejo_admin/claude-custom#239 (mermaid fence enforcement). The hardened hook would deny `arch-generic-checkout` because it has no mermaid diagram — it's a legacy HTML-table prose note in the `arch-` namespace that never followed `template-architecture`. The dev agent grandfathered it by slug to ship the hook on schedule. This ticket is the proper cleanup. ### Repo `forgejo_admin/pal-e-api` ### User Story As the Superuser (Lucas) I want every note in the `arch-` namespace to follow `template-architecture` (or be moved out of the namespace if it doesn't fit) So that the architecture triplet axiom holds across the knowledge base and the hook grandfather list shrinks toward zero Traces to: `story:superuser-maintain` on `project-pal-e-docs`. ### Architecture - `arch:notes` — the `notes` component in `arch-domain-pal-e-docs` ### Context The hardened `check-note-template.sh` (claude-custom#239) requires architecture notes to contain a mermaid fence. `arch-generic-checkout` has none — it's a prose explanation of a generic checkout flow rendered as HTML tables. Two valid resolutions: 1. **Migrate**: rewrite the note with a proper sequenceDiagram of the checkout flow (rename slug to `arch-dataflow-generic-checkout`). 2. **Demote**: change `note_type` from `architecture` to `doc`, rename slug to `doc-generic-checkout-flow`. Recommendation: option 1. The content describes a runtime flow, which is what `sequenceDiagram` is for. ### File Targets This is content work, not code work. - Read: `mcp__pal-e-docs__get_note(slug="arch-generic-checkout")` - Update via `mcp__pal-e-docs__update_note` matching `template-architecture` (Diagram with sequenceDiagram fence, Components, Key Decisions, Related) - After successful update, remove `arch-generic-checkout` from the grandfather list in `hooks/check-note-template.sh` (claude-custom) ### Acceptance Criteria - [ ] `arch-generic-checkout` (or renamed successor) contains a valid mermaid fence with the correct facet keyword - [ ] All 4 required template-architecture sections present (Diagram, Components, Key Decisions, Related) - [ ] `check-note-template.sh` accepts the note WITHOUT being on the grandfather list - [ ] Grandfather list updated in claude-custom hook (separate small PR) - [ ] No other arch notes affected ### Test Expectations - [ ] Manual test: invoke `mcp__pal-e-docs__update_note` against the migrated note and verify the hook accepts on first try - [ ] Regression: re-run the 28-note arch fixture test from claude-custom#239 with `arch-generic-checkout` removed from grandfather — must still pass - Run: `bash /tmp/claude-custom-test/hooks/check-note-template.sh` against fixture inputs ### Constraints - Do not delete existing content — preserve the prose explanation in the new structure - Coordinate with claude-custom hook PR — content migration must land first, then grandfather removal - If demoting (option 2), search board items for any `arch:` labels pointing to the slug ### Checklist - [ ] Content migrated - [ ] Grandfather entry removed in follow-up PR - [ ] No unrelated changes ### Related - `forgejo_admin/claude-custom#239` — parent ticket that surfaced this - `template-architecture` — the spec being conformed to - `arch-domain-pal-e-docs` — example of a template-conformant note

forgejo_admin commented

2026-04-11 20:54:39 +00:00

Author

Contributor

Copy link

Scope Review: APPROVED

Review note: review-968-2026-04-11

Ticket is template-conformant, traceability triangle verified (story:superuser-maintain on project-pal-e-docs, arch:notes maps to the notes component in arch-domain-pal-e-docs), file targets check out, 5 machine-verifiable AC. Fits a single agent pass (5-10 min). Ready to advance backlog → todo.

Non-blocking guidance for dispatch:

Before renaming slug, check get_note_links for inbound refs — prefer in-place update_note to preserve links.
Preserve existing schema/endpoint tables and JSON spec under Components or a supporting subsection (Constraints forbid deletion).
Pick one facet (Data Flow vs Domain Model). If both feel necessary, flag to Ava rather than splitting unilaterally — template-architecture says one diagram per note.
Verify final note passes check-note-template.sh locally before committing.

## Scope Review: APPROVED Review note: `review-968-2026-04-11` Ticket is template-conformant, traceability triangle verified (story:superuser-maintain on project-pal-e-docs, arch:notes maps to the `notes` component in arch-domain-pal-e-docs), file targets check out, 5 machine-verifiable AC. Fits a single agent pass (5-10 min). Ready to advance backlog → todo. Non-blocking guidance for dispatch: - Before renaming slug, check `get_note_links` for inbound refs — prefer in-place `update_note` to preserve links. - Preserve existing schema/endpoint tables and JSON spec under Components or a supporting subsection (Constraints forbid deletion). - Pick one facet (Data Flow vs Domain Model). If both feel necessary, flag to Ava rather than splitting unilaterally — template-architecture says one diagram per note. - Verify final note passes `check-note-template.sh` locally before committing.

Commenting is not possible because the repository is archived.

No Branch/Tag specified

main

265-fix-add-partial-index-declarations-to-mo

256-cors-middleware

158-incident-fix-migration-crash-drop-hnsw-i

128-add-jinja2-template-rendering-endpoint-p

132-fix-template-endpoint-qa-nits-is-public

123-clean-up-test-seed-block-objects-with-nu

124-harden-anchor-id-column-to-not-null

119-generate-anchor-ids-for-all-block-types

111-7e-1a-qa-nits-cleanup-redundant-assignme

11-fix-repos-formatting

5-browse-frontend

1-scaffold-project

No results found.

Labels

Clear labels

QA passed, awaiting merge approval

status:in-progress

Dev agent is actively working

status:needs-fix

QA found issues, back to dev

status:qa

PR submitted, awaiting QA review

type:bug

Bug fix

type:devops

Infrastructure/CI/config work

No labels

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

ldraney/pal-e-api#254

Reference in a new issue

Repository

ldraney/pal-e-api

Title

Body

No description provided.

Delete branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?

Rows
Columns