pal-e-docs

Review: Spike: Define link visibility tiers and assign current links

review-1379-2026-06-07 Review

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Template Completeness

  • [x] Type — Spike
  • [x] Lineage — references ldraney/palinks #16
  • [x] Repo — ldraney/palinks
  • [x] Question — well-structured with 6 sub-questions
  • [x] Deliverables — 3 checklist items
  • [x] Time-box — 2 hours
  • [x] Related — lists service, related issue, parent story
All required spike template sections present and complete.

Traceability

  • [x] story:auth-roles label — present on board item
  • [ ] story note MISSING — [SCOPE] No project-palinks note exists in pal-e-docs. User stories live in docs/user-stories.md in the repo (US-4: Role-Based Link Visibility is the relevant story). Create project-palinks project page with user-stories section, or document the repo-local convention.
  • [x] arch:palinks label — present on board item
  • [ ] arch note MISSING — [SCOPE] No arch-palinks note found in pal-e-docs. Architecture docs live in docs/architecture.md in the repo. Create arch-palinks note in pal-e-docs or link to the repo doc.
  • [x] Forgejo issue — ldraney/palinks#17, open

File Targets

Spike template expects a docs/{topic}.md as the primary file target.
  • [x] docs/visibility.md — already exists in the repo with tier definitions and mermaid diagrams. However, the "Current Link Inventory" section (line 105) is marked TODO with an empty table. This is the core deliverable of the spike.
Note: docs/visibility.md already existing means part of the spike deliverable is partially done. The agent executing this spike must complete the inventory, not create the file from scratch.

Repo Placement

OK. Issue filed on ldraney/palinks, work targets ldraney/palinks. Single repo.

Dependencies

  • ldraney/palinks #16 (Keycloak integration spike, board item #1378) — open, in backlog. The issue body says #16 "depends on visibility model," meaning this spike (#17) should complete first. This dependency ordering is correct and documented in the issue lineage.
  • Board item #1381 (Write dev seed data) — also story:auth-roles, in backlog. Seed data will need to reference visibility tiers once defined. Not a blocker, but should consume this spike's output.

Acceptance Criteria

Spike deliverables assessment:
  • docs/visibility.md created with tier definitions, mermaid diagram, and link inventory audit — partially verifiable. The doc already exists with tiers and diagrams. The inventory audit is the remaining work. An agent can verify this by checking the table is populated.
  • Each current link assigned a proposed visibility tier — verifiable. Agent can query the database or read the completed table.
  • Follow-up ticket for adding visibility column to links schema — verifiable. Agent can check Forgejo for a new issue.

Blast Radius

Critical inconsistency found: The codebase has two conflicting role/tier models:
  • docs/visibility.md defines 3 tiers: public, member, superadmin
  • docs/architecture.md (line 70-76) and docs/user-stories.md (US-4, line 103) define 4 roles: public, lead, collaborator, admin
This spike must reconcile these two models. The issue's Question section asks the right questions but doesn't acknowledge this existing inconsistency. The executing agent needs to be aware that the docs already contain conflicting tier definitions.
No visibility column exists in the schema yet (db/schema.rb has no visibility field). The Link model has no visibility scope. Impact is contained to docs and follow-up tickets.

Decomposition Assessment

Single repo, docs-only output, 3 deliverables, estimated <30 min agent time. No decomposition needed.

Recommendations

  • [BODY] Add a note in the Question section acknowledging that docs/visibility.md already exists with partial content (tiers and diagrams done, inventory TODO). The spike should be framed as "complete the existing doc" not "create from scratch."
  • [BODY] Add a sub-question: "Reconcile 3-tier model (visibility.md: public/member/superadmin) with 4-role model (architecture.md: public/lead/collaborator/admin). Which is canonical?"
  • [SCOPE] Create project-palinks project page in pal-e-docs with a user-stories section linking to repo docs.
  • [SCOPE] Create arch-palinks architecture note in pal-e-docs or register the repo-local docs/architecture.md as the canonical source.