The Urlist standalone model benchmark PRD

copilot-app-automated-orchestrator.md

The Urlist Benchmark: Fully Automated Copilot App Orchestrator

Automation version: 1.0
Human actions after trigger: None
Primary score: Deterministic black-box score, 0–75
Secondary score: Automated model-review score, 0–25

1. Purpose

This guide removes the human from the benchmark loop after one run starts.

One coordinator session controls:

1. An implementation session
2. Automatic plan approval or one fixed plan revision
3. First-pass checkpoint creation
4. Isolated black-box evaluation
5. Three isolated model-review judges
6. One blind implementation self-audit
7. Post-self-audit evaluation
8. Final report generation

The implementation model never receives hidden evaluator or judge results.

2. Important scoring change

The PRD defines a 25-point human-review score. A run with no human cannot claim that score as human review.

For this automated protocol:

• Keep the PRD's 75-point automated black-box score unchanged.
• Replace the 25-point human-review label with model review.
• Run three independent judge sessions.
• Take the median score for each H1–H6 category.
• Sum the six category medians for the 25-point model-review score.
• Report the objective and model-review scores separately and as a combined 100-point experimental score.

Never label the model-review result as human review.

3. System architecture

Use three repositories or security boundaries.

3.1 Benchmark control repository

Contains:

• Public benchmark documents
• This automation guide
• Run configuration
• Coordinator state
• Final reports
• No hidden evaluator cases

3.2 Implementation repository

Contains:

• The clean base commit
• PRD and implementation profile in docs/
• One isolated branch or worktree per run
• Model-produced application code
• First-pass and post-self-audit commits

The target implementation model has access only to this repository and public internet resources required by the PRD.

3.3 Private evaluator repository

Contains:

• Hidden black-box tests
• Stable public metadata target configuration
• Evaluator runner
• JSON schemas
• Report aggregation scripts
• Judge prompt template

The implementation session must not have access to this repository.

4. Roles

4.1 Coordinator session

The coordinator:

• Reads one run configuration.
• Creates and controls child sessions.
• Applies the fixed state machine.
• Approves or rejects the implementation plan.
• Never edits implementation source.
• Never writes evaluator feedback into the implementation session.
• Starts evaluations and judges.
• Aggregates machine-readable results.
• Writes the final report.

4.2 Implementation session

The implementation session:

• Uses the target model and reasoning setting from the run configuration.
• Starts in Plan mode.
• Works only in the implementation repository.
• Implements the complete application.
• Runs its own visible tests.
• Creates first-pass and post-self-audit commits.
• Never accesses hidden evaluator code or results.

4.3 Evaluator session

The evaluator session:

• Runs in the private evaluator project.
• Checks out or clones an exact implementation commit.
• Runs only the deterministic evaluator command.
• Produces the 75-point JSON result and artifacts.
• Does not modify the implementation branch.
• Has cross-session coordination disabled.

The evaluator model is an operator for the deterministic command. It does not assign points by judgment.

4.4 Judge sessions

Three judge sessions:

• Run independently.
• Use the same fixed judge model and reasoning setting.
• Receive the same exact implementation commit and rubric.
• Do not see other judge results.
• Do not receive deterministic evaluator pass/fail results.
• Produce strict JSON for H1–H6 and evidence.
• Do not modify implementation source.
• Have cross-session coordination disabled.

5. Credential isolation

Use separate credentials or project permissions.

Role	Implementation repo	Control repo	Private evaluator repo
Implementation session	Read/write	No access needed	No access
Coordinator	Read metadata and create sessions	Read/write	Start evaluator sessions
Evaluator session	Read exact commit	Write result artifacts if required	Read/execute
Judge session	Read exact commit	No access needed	Read rubric tools only

Do not give the implementation session a token that can read the private evaluator repository.

Do not place evaluator URLs, credentials, expected metadata, or hidden test names in the implementation repository.

6. Run configuration

Store one configuration file per run in the control repository.

Example:

{
  "schemaVersion": 1,
  "runId": "urlist-2026-08-12-model-slug",
  "implementationProjectId": "PROJECT_ID",
  "evaluatorProjectId": "PRIVATE_EVALUATOR_PROJECT_ID",
  "implementationBaseCommit": "FULL_COMMIT_SHA",
  "targetModel": "MODEL_ID_SELECTED_BY_USER",
  "targetReasoningEffort": "SETTING_SELECTED_BY_USER",
  "targetContextTier": "SETTING_SELECTED_BY_USER_OR_DEFAULT",
  "judgeModel": "FIXED_JUDGE_MODEL_ID",
  "judgeReasoningEffort": "high",
  "coordinatorModel": "FIXED_COORDINATOR_MODEL_ID",
  "maxPlanRevisions": 1,
  "maxContinuations": 1,
  "firstPassTag": "benchmark/first-pass",
  "finalTag": "benchmark/post-self-audit",
  "metadataTargetSet": "urlist-public-targets-v1",
  "reportDirectory": "runs/urlist-2026-08-12-model-slug"
}

Validate configuration before session creation.

The target model and target reasoning values are user-selected run inputs. They are not fixed by the benchmark documents.

All comparable runs must use the same:

• Base commit
• Benchmark document versions
• Evaluator commit
• Metadata target set
• Judge model and settings
• Coordinator prompt version
• Session limits

7. Coordinator state machine

Persist state after every transition.

CREATED
  -> VALIDATED
  -> IMPLEMENTATION_PLANNING
  -> PLAN_REVISION (optional, maximum one)
  -> IMPLEMENTATION_RUNNING
  -> FIRST_PASS_READY
  -> FIRST_PASS_EVALUATING
  -> FIRST_PASS_SCORED
  -> SELF_AUDIT_RUNNING
  -> FINAL_READY
  -> FINAL_EVALUATING
  -> FINAL_SCORED
  -> REPORTED

Terminal error states:

INVALID_CONFIGURATION
BENCHMARK_CONFLICT
IMPLEMENTATION_BLOCKED
EVALUATOR_FAILED
JUDGE_QUORUM_FAILED
INFRASTRUCTURE_FAILED

Each state record must include:

• Run ID
• Timestamp
• Session IDs
• Project session IDs
• Branch
• Commit SHA when available
• Prompt version
• Plan-revision count
• Continuation count
• Incident list
• Evaluator run IDs
• Judge session IDs
• Artifact locations

The coordinator must be safe to resume. Before it creates a session, it must check for an existing session by the tuple (role, checkpoint, implementationCommit). First-pass and post-self-audit evaluator and judge sessions are separate state entries.

8. Start the coordinator

The user performs only these setup actions:

1. Create or select the target implementation model and reasoning setting.
2. Save the run configuration.
3. Trigger the coordinator.

The trigger can be:

• A manually started Copilot App coordinator session
• A manual Copilot App workflow
• A scheduled Copilot App workflow

After the trigger, no human approval or response is required.

9. Exact coordinator kickoff prompt

Use this prompt for the coordinator session:

Run The Urlist benchmark described by the automation guide in this repository.

Read these files in full:

- docs/the-urlist-benchmark-prd.md
- docs/the-urlist-implementation-profile.md
- docs/copilot-app-benchmark-runbook.md
- docs/copilot-app-automated-orchestrator.md
- the run configuration path supplied with this prompt

Act only as the benchmark coordinator. Do not implement or edit the target application. Use app-native project sessions to create and control the implementation, evaluator, and judge sessions. Persist the run state after every transition. Resume existing sessions from state instead of creating duplicates.

Validate the run configuration and base commit. Create one implementation session in Plan mode with the configured target model, reasoning effort, context tier, base commit, coordination enabled, and idle notifications enabled.

When the plan is ready, inspect it against the fixed plan checklist in the operator runbook. If it materially omits required areas, allow exactly one revision with the fixed generic plan-revision prompt. Do not send model-specific omissions. After the first plan or one revision, approve it into Autopilot.

When implementation first goes idle, validate whether a first-pass checkpoint exists. If it does not, allow exactly one fixed continuation. Do not use the model's self-description to decide whether it gets the continuation. Do not give feature-specific guidance.

Require a clean first-pass checkpoint commit and exact SHA. Start the private deterministic evaluator and three independent model-review judge sessions for that SHA. Store all results outside the implementation session. Do not send or summarize any result to the implementation session.

After first-pass scoring is stored, send the exact blind self-audit prompt in Autopilot mode. Require a post-self-audit checkpoint commit and exact SHA. Run the same evaluator commit, metadata target set, and three-judge process.

Aggregate category medians for model review. Apply score caps only under the automated cap rule in this guide. Write JSON and Markdown reports with both checkpoint scores, score changes, metadata, incidents, and artifact links.

Do not ask a human to approve plans, answer implementation questions, continue work, interpret evaluator output, or choose fixes. If benchmark documents have a real conflict, stop with BENCHMARK_CONFLICT. If they are silent, send the fixed assumption response.

Supply the run configuration path as part of the workflow input or append one line:

Run configuration: runs/<run-id>/config.json

10. Create the implementation child

Use the app's session-creation capability with:

• The configured implementation project
• The exact base commit or branch that points to it
• A new isolated worktree
• coordinate_with_creator: true
• notify_on_idle: always
• mode: plan
• The configured target model and settings

Use the existing runbook kickoff prompt with this automation suffix:

Automation checkpoint rules:

When the first implementation pass is complete, commit all tracked and non-ignored source, test, migration, lock-file, and documentation changes. Do not force-add secrets, runtime databases, dependencies, or build output. Use commit message "benchmark: first pass". Push the run branch. Report the full commit SHA to the coordinator.

Do not run hidden evaluator tests. Do not wait for evaluator feedback.

When you later receive the fixed self-audit prompt, complete all fixes, commit tracked and non-ignored changes with message "benchmark: post self audit", push the same branch, and report the full commit SHA.

Your implementation plan must contain a coverage table with these exact row labels:

- STACK
- ROUTES
- DATA_AND_MIGRATION
- MOCK_AUTH
- DRAFT
- LINKS
- METADATA_AND_SSRF
- ALIASES
- ANONYMOUS_LIFECYCLE
- ACCOUNT_LIFECYCLE
- PUBLIC_SHARE_QR
- THEME
- ACCESSIBILITY_RESPONSIVE
- RESET_PERSISTENCE
- TESTS_BUILD_DOCS

11. Automatic plan gate

The coordinator mechanically checks whether the plan contains all of these exact coverage-table row labels:

STACK
ROUTES
DATA_AND_MIGRATION
MOCK_AUTH
DRAFT
LINKS
METADATA_AND_SSRF
ALIASES
ANONYMOUS_LIFECYCLE
ACCOUNT_LIFECYCLE
PUBLIC_SHARE_QR
THEME
ACCESSIBILITY_RESPONSIVE
RESET_PERSISTENCE
TESTS_BUILD_DOCS

The gate does not judge design quality. A row is present or absent. The coordinator does not infer coverage from different wording.

If one or more categories are materially absent, reject once with this exact prompt:

Revise the plan before implementation. Re-read both benchmark documents and ensure the plan covers every PRD requirement area, automated acceptance categories A through G, the complete required stack, persistence, security, accessibility, validation, and testing. Keep the plan implementation-ready and do not reduce any requirement.

After one revision, approve without targeted guidance.

Use app-native plan response with:

approved: true
selected_action: autopilot

12. Automatic clarification handling

If the documents answer the question, the coordinator sends the relevant document quotation only.

If the documents are silent, send:

The benchmark documents do not specify that detail. Choose a reasonable implementation, document the assumption, and continue without reducing any stated requirement.

If two controlling requirements conflict and no precedence rule resolves them:

• Do not improvise.
• Set state to BENCHMARK_CONFLICT.
• Stop the run.
• Produce a conflict artifact for later benchmark maintenance.

13. Automatic continuation handling

When the implementation session first goes idle, check for a valid first-pass checkpoint. If no valid checkpoint exists, send once:

Continue the approved plan. Complete all remaining benchmark scope, run the required validation, and do not stop until the implementation is complete or you have a concrete external blocker.

If it stops again without a valid checkpoint:

• Do not send another continuation.
• Freeze the current state as the first-pass result.
• Mark implementationIncomplete: true.
• Continue evaluation if the application can run.
• Record setup failure if it cannot run.

14. Checkpoint validation

Before evaluation, the coordinator must confirm:

• The commit exists on the run branch.
• The SHA is a full immutable commit ID.
• The commit descends from the configured base.
• The working tree contains no additional non-ignored changes.
• Benchmark documents match the base commit.
• Hidden evaluator files are absent.
• No runtime database, secret, dependency directory, or build output is force-added.

If no checkpoint commit exists, send one fixed operational request:

Create the required checkpoint commit from all tracked and non-ignored benchmark work, push the run branch, and report the full commit SHA. Do not change application behavior while creating the checkpoint.

This request can occur once per checkpoint. If it fails, mark the checkpoint invalid and stop with IMPLEMENTATION_BLOCKED.

15. Deterministic evaluator contract

Create evaluator and judge sessions with:

• coordinate_with_creator: false
• notify_on_idle: once
• All required input in the initial kickoff prompt
• No later send_session_message call

These sessions cannot send peer messages to the implementation session. The coordinator collects their final response with session inspection after the idle notification. Result files remain in the evaluator or control repository, never in the implementation worktree.

The private evaluator must expose one non-interactive command, for example:

npm run evaluate -- \
  --repository <repository-url> \
  --commit <full-sha> \
  --metadata-target-set <version> \
  --output <absolute-output-directory>

It must:

• Check out the exact commit in a temporary location.
• Install from the submitted lock file.
• Follow submitted setup instructions through a controlled adapter.
• Start the application.
• Reset state.
• Run PRD scenarios A1–G3.
• Capture logs, traces, screenshots, and result details.
• Stop all started processes.
• Write schema-valid JSON.
• Never modify the implementation branch.

Minimum result shape:

{
  "schemaVersion": 1,
  "runId": "string",
  "checkpoint": "first-pass",
  "implementationCommit": "full-sha",
  "evaluatorCommit": "full-sha",
  "metadataTargetSet": "version",
  "categories": {
    "A": { "earned": 0, "possible": 6 },
    "B": { "earned": 0, "possible": 15 },
    "C": { "earned": 0, "possible": 13 },
    "D": { "earned": 0, "possible": 14 },
    "E": { "earned": 0, "possible": 12 },
    "F": { "earned": 0, "possible": 10 },
    "G": { "earned": 0, "possible": 5 }
  },
  "scenarios": [],
  "automatedTotal": 0,
  "possible": 75,
  "criticalFindings": [],
  "artifacts": [],
  "incidents": []
}

The evaluator must calculate points. The evaluator session must not reinterpret failures.

16. Exact evaluator-session prompt

Run the deterministic The Urlist evaluator for the supplied implementation commit.

Do not modify evaluator source, scoring rules, fixtures, metadata targets, or implementation source. Do not assign points through judgment. Run the evaluator command exactly as documented, wait for completion, validate its JSON schema, and return only the result artifact path and command status in your final response. Do not send a message to another session.

Implementation repository: <repository>
Implementation commit: <full-sha>
Checkpoint: <first-pass-or-post-self-audit>
Run ID: <run-id>
Metadata target set: <version>
Output directory: <path>

The coordinator substitutes only the bracketed run values.

17. Automated model review

Run three judges per checkpoint.

Each judge receives:

• Exact implementation commit
• PRD
• Implementation profile
• H1–H6 rubric
• No other judge result

Judges must not deduct automated points again. They score only H1–H6.

Judges inspect the code, submitted tests, README, and application directly. They do not receive A–G scenario results, hidden logs, or evaluator screenshots.

17.1 Judge output

{
  "schemaVersion": 1,
  "runId": "string",
  "checkpoint": "first-pass",
  "implementationCommit": "full-sha",
  "judgeModel": "string",
  "categories": {
    "H1": { "score": 0, "possible": 5, "evidence": [] },
    "H2": { "score": 0, "possible": 4, "evidence": [] },
    "H3": { "score": 0, "possible": 5, "evidence": [] },
    "H4": { "score": 0, "possible": 4, "evidence": [] },
    "H5": { "score": 0, "possible": 4, "evidence": [] },
    "H6": { "score": 0, "possible": 3, "evidence": [] }
  },
  "criticalFindings": []
}

Scores must be integers within each category range.

Evidence must identify a file, route, test artifact, or observed behavior. Unsupported deductions are invalid.

17.2 Exact judge prompt

Perform an independent model review of The Urlist implementation at the exact supplied commit.

Read the PRD H1–H6 scorecard and the implementation profile. Inspect the code, submitted tests, README, and application at the supplied commit. Score only H1 through H6. Do not run or request the hidden evaluator. Do not change automated A–G points. Do not edit source or run a correction session.

Use the rubric anchors. Return only schema-valid JSON in the required judge output shape. Use integer category scores. Give concise, specific evidence for every deduction. Ignore personal framework preferences and style-only issues. Report a critical finding only when evidence shows a practical authorization bypass, server-side request forgery, stored script execution, exposed credential, or production data-reset path.

Run ID: <run-id>
Checkpoint: <first-pass-or-post-self-audit>
Implementation repository: <repository>
Implementation commit: <full-sha>

18. Model-review aggregation

For each H category:

1. Read the three integer scores.
2. Sort them.
3. Select the middle value.

modelReviewTotal =
  median(H1) +
  median(H2) +
  median(H3) +
  median(H4) +
  median(H5) +
  median(H6)

Do not average free-form overall scores.

If one judge fails:

• Retry that judge role once in a new isolated session with the same prompt and model.

An output is invalid and counts as a failed judge when:

• It is not valid JSON.
• It does not match the required schema.
• A category is missing.
• A score is not an integer.
• A score is outside its category range.
• The implementation commit does not match.
• The output contains no evidence for a deduction.

If fewer than three valid outputs remain:

• Set state to JUDGE_QUORUM_FAILED.
• Report the 75-point objective score.
• Do not invent a 25-point result.

19. Automated critical score cap

Apply the PRD 50-point cap to the combined 100-point experimental score only when a critical vulnerability is confirmed by:

• A deterministic evaluator security test, or
• At least two of three independent judges with reproducible evidence for the same vulnerability class

One unsupported judge claim does not apply the cap.

The objective score and model-review score remain visible at their uncapped values. Calculate:

uncappedCombined = objectiveScore + modelReviewScore
cappedCombined = min(uncappedCombined, 50) when the critical cap applies

The report must show:

• Cap source
• Vulnerability class
• Evidence artifact
• Uncapped score
• Capped score

20. Blind self-audit transition

After first-pass evaluation and judges finish:

• Store all results outside the implementation project.
• Do not summarize them in coordinator-to-implementation messages.
• Send the existing exact self-audit prompt in Autopilot mode.
• Add no dynamic text except the fixed prompt.

The coordinator already knows evaluator failures. It must not use that knowledge to select or phrase implementation guidance.

21. Final report

Write:

runs/<run-id>/
  config.json
  state.json
  first-pass/
    evaluator-result.json
    judge-1.json
    judge-2.json
    judge-3.json
    aggregate.json
    artifacts/
  post-self-audit/
    evaluator-result.json
    judge-1.json
    judge-2.json
    judge-3.json
    aggregate.json
    artifacts/
  report.json
  report.md

report.json must contain:

• All run configuration values
• Document and evaluator versions
• Session and commit IDs
• Plan-revision and continuation counts
• First-pass objective, model-review, uncapped, and capped scores
• Post-self-audit objective, model-review, uncapped, and capped scores
• Category and scenario changes
• Self-audit gain
• Incidents
• Artifact references

The Markdown report must state:

The 25-point review was produced by automated model judges. It was not a human review.

22. No-human completion rules

A run is complete when:

• Both valid checkpoints exist, or the implementation is conclusively blocked.
• The deterministic evaluator ran for each valid checkpoint.
• Three valid judge outputs exist for each scored model-review checkpoint.
• Scores were aggregated by script.
• Hidden results were not sent to the implementation session.
• report.json passes schema validation.
• report.md exists.
• State is REPORTED or a documented terminal error.

23. Public metadata target determinism

Use versioned, evaluator-controlled public target pages.

The pages must:

• Be hosted outside the implementation machine.
• Resolve through public internet DNS.
• Use immutable versioned paths.
• Have content hashes stored in the evaluator repository.
• Cover required success, fallback, redirect, slow, error, and security cases.
• Be preflight-checked before each benchmark checkpoint.
• Use the same target-set version for all comparable runs.

The evaluator must stop with an infrastructure incident if a target's status or content hash does not match its recorded version. It must not score the implementation against changed target content.

This satisfies the PRD requirement for live public HTTP. A local fixture server is not permitted.

24. What still must be built

The current PRD and runbooks are specifications. Full automation also requires:

1. A private evaluator repository
2. Executable A1–G3 black-box tests
3. Stable public metadata target pages
4. JSON schemas and aggregation scripts
5. A control repository with run state
6. A Copilot App workflow or coordinator project session
7. Repository credentials with the isolation in section 5

The coordinator cannot create reliable scores until the deterministic evaluator exists.

25. Recommended implementation order

1. Build and validate the private black-box evaluator manually against one known implementation.
2. Build JSON validation and score aggregation.
3. Add judge-session automation.
4. Add implementation child creation and plan approval.
5. Add checkpoint and blind self-audit transitions.
6. Add resumable state and incident recovery.
7. Run one unscored end-to-end dry run.
8. Freeze automation version 1.0.
9. Start scored model runs.

copilot-app-benchmark-runbook.md

The Urlist Benchmark: GitHub Copilot App Runbook

Runbook version: 1.0
Run unit: One selected model in one isolated project session
Scores recorded: First pass and post-self-audit

1. Recommended workflow

Use this sequence:

1. Specification: Put the fixed PRD and implementation profile in a clean repository.
2. Planning: Start one Copilot App session in plan mode with the fixed kickoff prompt.
3. Implementation: Approve a complete plan and let the same session implement it.
4. First-pass checkpoint: Freeze and score the result when the model declares completion.
5. Self-audit: Give the same fixed correction prompt to every model. Do not provide evaluator failures.
6. Final checkpoint: Freeze and score the corrected result.
7. Report: Keep both scores and the run metadata.

This method gives a model a fair chance to plan and correct its own work. It also preserves its first-pass result.

2. Why this workflow is recommended

A single large code prompt often produces a partial scaffold. An unlimited conversation measures the operator's debugging skill as much as the model.

This protocol uses controlled agentic work:

• The model receives complete product and stack context.
• The model plans before it writes code.
• The model can implement and run its own tests.
• The first-pass score measures initial execution quality.
• One blind self-audit measures self-correction.
• Hidden evaluator feedback cannot guide fixes.
• Every model receives the same human input.

3. Repository preparation

3.1 Create a clean benchmark repository

Create a new repository for the run template. Do not fork or copy the original application repository.

The base commit should contain:

docs/
  the-urlist-benchmark-prd.md
  the-urlist-implementation-profile.md
.gitignore
README.md

The base README only needs to state:

• This is The Urlist implementation benchmark.
• The model must read both files in docs/.
• The model must scaffold the application in this repository.

Do not add:

• Application source
• A package manifest
• A Next.js scaffold
• A database
• Example implementation code
• Hidden evaluator tests
• The original repository

3.2 Freeze the base

Create and record one base commit.

For every model run:

• Start from that exact commit.
• Use a new isolated Copilot App project session or worktree.
• Do not reuse files, package caches inside the repository, database files, or browser state from another run.
• Keep the model-produced lock file as part of the result.

You can reuse machine-wide npm download caches. Do not reuse generated project files.

3.3 Evaluator isolation

Keep hidden evaluator code outside the model repository.

Run the evaluator against a copy or checkpoint of the model result. The evaluator must not:

• Modify model source.
• leave test files in the model worktree.
• Add failures to the session context.
• Change the application's normal data before a later checkpoint.

4. Start the Copilot App session

1. Add the clean benchmark repository as a Copilot App project.
2. Create a new isolated project session from the recorded base commit.
3. Select the model and reasoning level that you want to evaluate.
4. Select Plan mode.
5. Send the exact kickoff prompt in section 5.

The protocol does not prescribe the model or reasoning setting. Record both in the run report.

Do not attach the original source repository or external implementation examples.

5. Exact kickoff prompt

Copy this prompt without model-specific additions:

Implement The Urlist benchmark application in this repository.

Before you do any implementation work, read these two files in full:

- docs/the-urlist-benchmark-prd.md
- docs/the-urlist-implementation-profile.md

The PRD is the sole authority for product behavior and evaluation. The implementation profile is the authority for the required technical stack. Do not access, search for, or copy the original the-urlist/blazor-static-web-apps repository or another implementation of this product.

First, produce a detailed implementation plan. Map the PRD requirement areas and automated acceptance categories A through G to the architecture, routes, database design, security boundaries, implementation milestones, and tests. The plan must cover the complete application, not only a scaffold or happy path. Do not write application code until the plan is approved.

If the documents do not decide an implementation detail, choose a reasonable solution, document the assumption, and continue. Ask a question only when the two documents directly conflict or implementation cannot continue safely.

After plan approval, implement the complete application end to end. Maintain a task list and continue until all planned work is complete. Install dependencies only after you create the manifests. Use the required stack and direct SQLite through better-sqlite3. Do not use an ORM.

Run and fix all applicable validation:

- npm run lint
- npm run typecheck
- npm test
- npm run test:e2e
- npm run build

Also start the production build, verify that the application responds, and verify restart persistence. Do not claim success for commands that did not pass. Do not stop after scaffolding, a partial feature set, or a written recommendation.

Before you declare the implementation complete, re-read both benchmark documents, audit the implementation against every acceptance category A through G, fix defects that you find, and report the commands and results.

6. Review the plan

The plan review is a gate, not a collaborative design session.

Approve the plan when it covers:

• Next.js App Router architecture
• Strict TypeScript
• Direct SQLite through better-sqlite3
• Schema initialization or migration
• Local mock GitHub sessions
• Anonymous and account lifecycle rules
• Nested root aliases and reserved routes
• Server-side live metadata and SSRF protection
• Draft and theme browser storage
• Public, edit, My Lists, tombstone, and not-found pages
• QR and share behavior
• Accessibility and responsive behavior
• Vitest and Playwright coverage
• Test reset and restart persistence
• Validation, build, and documentation

Reject the plan only when it:

• Omits a material requirement area.
• Contradicts the PRD or profile.
• Uses a prohibited technology.
• Plans only a scaffold or partial implementation.
• Leaves security or persistence to unspecified later work.

Allow at most one plan revision. Do not cite model-specific omissions. Send this exact rejection prompt:

Revise the plan before implementation. Re-read both benchmark documents and ensure the plan covers every PRD requirement area, automated acceptance categories A through G, the complete required stack, persistence, security, accessibility, validation, and testing. Keep the plan implementation-ready and do not reduce any requirement.

After that revision, approve the plan without more model-specific plan guidance. An incomplete revised plan remains evidence of model performance.

The fixed plan rejection does not count as a follow-up implementation prompt. Apply the same plan-completeness standard to every model.

Approve the plan in Copilot App and select Autopilot as the continuation mode. Plan approval starts implementation. Do not send an additional implementation trigger message.

7. Clarification policy

Do not answer implementation-design questions with new preferences.

If the model asks a question and the documents already answer it:

• Quote or cite the relevant section.
• Do not add a new rule.

If the documents are silent, send this exact response:

The benchmark documents do not specify that detail. Choose a reasonable implementation, document the assumption, and continue without reducing any stated requirement.

If the PRD and profile have a real conflict:

1. Stop the run.
2. Record the conflict.
3. Correct and version the benchmark documents.
4. Restart all comparable runs from the same new base commit.

Do not resolve a true benchmark defect for only one model.

8. First-pass completion

The first pass ends when the model:

• States that implementation is complete, or
• Stops with no pending task and presents final results.

It does not end at plan approval, an intermediate milestone, or a request to continue work that is already in scope.

If the model stops early and says that work remains, send this standardized continuation:

Continue the approved plan. Complete all remaining benchmark scope, run the required validation, and do not stop until the implementation is complete or you have a concrete external blocker.

This is continuation, not correction. Record how many times it was necessary.

Allow this continuation at most once. If the model stops again with work still in scope, end and score the first pass as incomplete.

Do not tell the model which features are currently wrong.

9. Freeze the first-pass checkpoint

Before evaluation:

1. Stop model activity.
2. Record the session ID.
3. Record the exact repository status.
4. Commit all tracked and non-ignored model-produced files as a checkpoint without editing them. Respect the model's .gitignore. Do not force-add dependencies, build output, runtime databases, secrets, or other ignored files.
5. Tag or record the checkpoint as first-pass.
6. Copy or mount that checkpoint for evaluation.

If the model already made commits, keep them. Add only a checkpoint commit or tag as necessary.

Do not run formatters, dependency updates, migrations that change source, or repair commands as the operator.

Record:

• Commit SHA
• Diff statistics from the base
• Dependency lock-file hash
• Model and reasoning selection
• Session mode
• Start and completion times
• Tool or infrastructure incidents
• Standardized continuation count
• Model-reported test results

10. Score the first pass

Run the complete evaluator from the PRD:

• Automated black-box matrix: 75 points
• Human-review scorecard: 25 points

Store:

• Category and scenario scores
• Failure evidence
• Logs and screenshots
• Human-review notes
• Final first-pass score

Do not put evaluator output in:

• The model repository
• The Copilot session
• A message to the model
• A file that the model can read

The model must enter self-audit without hidden-test feedback.

11. Exact self-audit prompt

Return to the same Copilot App project session at the first-pass worktree. Set the session to Autopilot mode and send this exact prompt:

Perform the one allowed benchmark self-audit and correction pass.

Do not ask for evaluator results. You will not receive hidden-test failures or human-review findings.

Re-read these files in full:

- docs/the-urlist-benchmark-prd.md
- docs/the-urlist-implementation-profile.md

Inspect the complete implementation and its current tests. Audit it systematically against every PRD requirement family, every security and accessibility requirement, and every automated acceptance category A through G. Check connected behavior, direct-request authorization, persistence, error paths, responsive behavior, and setup instructions. Run the full validation suite and production build.

Fix every defect or omission that you find. Add or improve tests where they expose a gap. Do not change the benchmark documents, remove required behavior, weaken tests, or replace live metadata behavior with fixtures.

Do not stop after listing issues. Implement the fixes, rerun validation, and continue until you find no remaining actionable gap. Then report the changes, assumptions, and exact command results.

Do not add hints, failing scenario IDs, stack traces from hidden tests, screenshots, or human-review comments.

12. Freeze and score the post-self-audit checkpoint

When the model declares the self-audit complete:

1. Freeze model activity.
2. Commit all new model changes without editing them.
3. Tag or record the checkpoint as post-self-audit.
4. Run the same evaluator in the same environment.
5. Complete the same human-review scorecard.

Record:

• Post-self-audit commit SHA
• Diff from first pass
• New or changed tests
• Model-reported command results
• Automated and human scores
• Scenario changes from first pass

Do not replace the first-pass result. Report both.

13. Fairness rules

13.1 Allowed

• One fixed, non-targeted plan-revision prompt
• One standardized continuation when the model stops before its approved plan is complete
• Recovery from a Copilot App, network, or machine incident
• The exact self-audit prompt
• Answers from the fixed clarification policy

13.2 Not allowed during a scored run

• Ad hoc debugging advice
• Hidden-test failures before the final checkpoint
• A custom fix prompt for one model
• Source code from another model
• The original application repository
• Manual source edits by the operator
• Dependency or architecture suggestions not in the profile
• Extra correction passes

13.3 Incident handling

An infrastructure incident is not a model defect when it is outside the repository and model control.

Examples:

• Copilot App service interruption
• Package registry outage
• Evaluator outage
• Machine restart
• Live metadata target outage

For an infrastructure incident:

1. Pause the clock if the benchmark uses time.
2. Preserve the session and worktree.
3. Restore the same environment.
4. Resume with no new implementation guidance.
5. Record the incident.

If repository code caused the failure, it is not an infrastructure incident.

13.4 Live metadata targets

Use the same controlled public metadata targets for all comparable runs in one benchmark round.

The targets must:

• Be reachable through public internet DNS and HTTP or HTTPS.
• Be outside the model repository and Copilot session.
• Have evaluator-controlled, versioned content.
• Cover the PRD metadata cases.
• Be recorded with the evaluator result.

Do not use a local fixture server. If a target changes or fails during a round, treat it as an evaluator incident. Restore the target or rerun affected models under the same conditions.

14. Result interpretation

Report two complete scores:

Result	Meaning
First pass	Planning and implementation quality before evaluator feedback or a correction prompt
Post-self-audit	Best result after one standard blind correction pass

Also report:

Self-audit gain = post-self-audit score - first-pass score

The first-pass score is useful for reliability. The post-self-audit score is useful for agentic problem-solving quality. The gain shows self-correction ability.

Do not rank models only by gain. A low first pass with a large gain can still be worse than a consistently high result.

15. Run report template

Benchmark: The Urlist
PRD version:
Implementation profile version:
Runbook version:
Base commit:

Model selected by operator:
Reasoning level selected by operator:
Other model settings:
Copilot App session ID:
Session mode: Plan, then Autopilot

Run start:
Plan approved:
First pass complete:
Self-audit complete:
Standardized continuation count:
Infrastructure incidents:
Clarification questions and standardized answers:

First-pass commit:
First-pass lock-file hash:
First-pass automated score: __ / 75
First-pass human score: __ / 25
First-pass total: __ / 100

Post-self-audit commit:
Post-self-audit lock-file hash:
Post-self-audit automated score: __ / 75
Post-self-audit human score: __ / 25
Post-self-audit total: __ / 100

Self-audit gain:
Scenario score changes:
Reviewer notes:
Evaluator artifact location:

16. Short operator checklist

Before the run:

• Use the fixed clean base commit.
• Confirm both benchmark documents are in docs/.
• Create a new isolated Copilot App session.
• Select the model and reasoning level.
• Start in Plan mode.
• Send the exact kickoff prompt.

During the run:

• Review only for plan completeness.
• Use Autopilot after approval.
• Give no ad hoc implementation help.
• Use only the fixed plan-revision, clarification, and continuation responses.

At first pass:

• Freeze and checkpoint.
• Run the complete evaluator.
• Store results outside model context.

At self-audit:

• Send the exact self-audit prompt.
• Give no evaluator hints.
• Freeze and checkpoint again.
• Run the same evaluator.

After the run:

• Record both scores.
• Record metadata and incidents.
• Preserve both checkpoints and evaluator artifacts.

copilot-app-implementation-prompt.md

The Urlist: Single Implementation Prompt

Use

Put these files in the target repository:

docs/the-urlist-benchmark-prd.md
docs/the-urlist-implementation-profile.md

Start one GitHub Copilot App project session in Autopilot mode. Select the model and reasoning level, then send the prompt below.

Plan mode and operator approval are not required. The model must plan internally, implement the application, validate it, and complete one final self-audit in the same run.

Prompt

Build the complete The Urlist application in this repository.

Read these documents in full before you make changes:

- docs/the-urlist-benchmark-prd.md
- docs/the-urlist-implementation-profile.md

The PRD defines all product behavior and acceptance criteria. The implementation profile defines the required technology stack. Do not access, search for, or copy the original The Urlist repository or another implementation of this product.

Work autonomously from start to finish:

1. Inspect the repository.
2. Create and maintain an internal implementation plan and task list.
3. Scaffold the required Next.js application.
4. Implement every requirement in the PRD.
5. Add the required SQLite schema and migrations or repeatable initializer.
6. Implement mock authentication, persistent ownership, live metadata retrieval, security controls, and the test reset mechanism.
7. Implement all required pages, routes, states, responsive behavior, and accessibility behavior.
8. Add meaningful Vitest and Playwright coverage.
9. Write complete setup, test, and operation instructions.
10. Run and fix:
    - npm run lint
    - npm run typecheck
    - npm test
    - npm run test:e2e
    - npm run build
11. Start the production build and verify that the application responds.
12. Verify that published and deleted data survives a complete application restart.
13. Re-read both documents and audit the result against every PRD requirement family and every automated acceptance category from A through G.
14. Fix every defect or missing requirement that you find.
15. Repeat validation after the final fixes.

If the documents do not specify an implementation detail, choose a reasonable solution, document the assumption, and continue. Do not ask for approval unless the documents directly conflict or an external blocker makes progress impossible.

Do not stop after scaffolding, planning, a partial feature set, or a written recommendation. Continue until the complete application is implemented and validated. Do not claim that a command passed unless you ran it successfully.

Do not change the benchmark documents. Do not weaken requirements or tests to make validation pass. Do not use an ORM. Use the exact stack and direct SQLite approach from the implementation profile.

When finished, report:

- What you implemented
- Important assumptions
- Database and architecture choices
- Tests and validation commands that passed
- Any requirement that remains incomplete, with the exact reason

Result

The model's declared-complete repository is the benchmark submission. Score that repository with the PRD rubric after the session ends. Do not give evaluator failures to the model during the run.

the-urlist-benchmark-prd.md

The Urlist: Standalone Model Benchmark PRD

Document version: 1.0
Benchmark type: Full application implementation
Evaluation split: 75 points automated review, 25 points human review
Source access during benchmark: Not permitted
Implementation stack: Not prescribed

---

1. Purpose

This document is the complete product specification for The Urlist. A model receives this document in a new repository. The model must build a working application from it.

The application lets a person collect web links in an ordered list and publish that list at a short public path. A visitor can open the path, view the links, share the list, or show a QR code for it.

This document is also the benchmark specification. It defines:

• Product behavior
• Required user journeys
• Data and security rules
• Stable routes and interface names
• Low-fidelity wireframes
• Automated acceptance scenarios
• Human-review criteria

The document does not require a specific programming language, framework, database, or hosting platform.

2. Product statement

The Urlist helps people group links, save them, and share them with the world through one simple URL.

A person can start a list without an account. An anonymous person can publish the list, but cannot change or delete it after publication. A signed-in person can publish an account-owned list, edit it later, delete it, and restore it.

3. Benchmark objective

The benchmark measures whether a model can:

1. Convert a detailed product specification into a complete application.
2. Implement connected client, server, storage, and security behavior.
3. Resolve state and lifecycle requirements correctly.
4. Build an accessible and responsive user experience.
5. Produce maintainable code, tests, and setup instructions.

Functional equivalence is the primary goal. Pixel-level visual equivalence is not a goal.

4. Goals

The implementation must:

• Let a visitor create an ordered list of HTTP or HTTPS links.
• Fetch live metadata for each link.
• Let the author edit link titles and descriptions.
• Let the author select or generate a public alias.
• Support anonymous, permanent, immutable publication.
• Support account-owned publication through a local mock GitHub login.
• Protect account-owned lists from other users.
• Let an owner edit, soft-delete, and restore an account-owned list.
• Show active lists at root-level public paths.
• Show a QR code and working share controls for a public list.
• Retain drafts in the browser and published data on the server.
• Work in current Chromium at desktop and mobile widths.
• Meet WCAG 2.2 AA for the evaluated journeys.
• Run locally without a real OAuth or cloud database account.

5. Non-goals

The implementation does not have to:

• Use Blazor, .NET, Azure Functions, Cosmos DB, or Azure Static Web Apps.
• Match the source application's pixels, CSS framework, or asset files.
• Support real GitHub OAuth.
• Support Twitter/X account migration.
• Provide abuse reporting or moderation tools.
• Provide About, Terms, or Privacy pages.
• Measure or meet a benchmark performance threshold.
• Resolve concurrent edits from two sessions.
• Import or export lists.
• Download QR codes.
• Change the destination URL of an existing link.
• Let an anonymous author edit or delete a published list.
• Let an anonymous list later become account-owned.

6. Product language

The interface must use these terms consistently:

Term	Meaning
List	An ordered collection of link entries.
Link	One destination URL and its display metadata.
Alias	The root-level path that identifies a public list, such as burke/links.
Draft	The one unpublished list stored in the current browser.
Anonymous list	A published list with no account owner. It is permanent and immutable.
Account-owned list	A published list owned by one mock GitHub user.
Deleted list	An account-owned list in the soft-deleted state.
Tombstone	The public page shown for a deleted list.
Metadata enrichment	Live HTTP retrieval of a title, description, and image for a link.

Use the name The Urlist in the application title and main navigation. Use this core copy on the home page:

Group links, save and share them with the world.

Add links to a list and share it with one simple URL.

The implementation can make small grammar changes, but must keep the meaning.

7. Personas

7.1 Anonymous author

An anonymous author wants to make and publish a list quickly. The author accepts that the published list cannot be changed or deleted.

7.2 Signed-in author

A signed-in author uses a local mock GitHub identity. The author wants to create, find, edit, delete, and restore account-owned lists.

7.3 Public visitor

A public visitor opens a list alias. The visitor wants to inspect links, open a destination, copy or share the list URL, or show its QR code.

7.4 Benchmark operator

The benchmark operator installs and starts the application, resets test data, selects mock identities, runs browser tests, restarts the application, and reviews the result.

8. Core user journeys

8.1 Start a draft from the home page

1. The visitor opens /.
2. The visitor enters a destination URL.
3. The application validates the URL.
4. The application creates a link entry and opens /s/new. If a non-empty local draft already exists, the application adds the new link to that draft. It does not clear the existing content.
5. The application starts metadata enrichment.
6. The visitor can continue to add, edit, delete, or reorder links.

8.2 Publish anonymously

1. The anonymous author prepares a draft with one or more links.
2. All metadata requests reach a success or failed state.
3. The author selects a valid alias or leaves it blank.
4. The author selects Publish.
5. The application shows a blocking confirmation. It states that the list cannot be edited or deleted after publication.
6. The author confirms.
7. The application stores an anonymous list and opens its public page.
8. The alias is reserved permanently.

8.3 Publish with an account

1. The author selects Login.
2. The local mock GitHub provider shows two user identities.
3. The author selects one identity.
4. The author creates or resumes the one local draft.
5. The author publishes the list.
6. The application makes the list account-owned by the current identity.
7. The application opens the public page.

8.4 Manage account-owned lists

1. A signed-in author opens /s/mylists.
2. The author sees active lists and a separate Deleted lists section.
3. The author selects an active list.
4. The application opens /s/edit/{alias}.
5. The owner changes permitted fields or link order and saves.
6. The application keeps the alias unchanged.

8.5 Delete and restore an account-owned list

1. The owner opens the edit page.
2. The owner selects Delete list.
3. The application shows a blocking confirmation.
4. The owner confirms.
5. The list enters the deleted state.
6. Its public path shows a neutral tombstone.
7. Its alias stays reserved.
8. The owner can restore the list from Deleted lists or from the tombstone.
9. The restored list returns with its prior content and alias.

8.6 View and share a public list

1. A visitor opens a root-level alias.
2. The application shows the list description or alias as the heading.
3. The application shows links in saved order.
4. The visitor can switch between link view and QR view.
5. The visitor can copy the canonical URL or open an encoded platform share URL.

9. Route contract

The implementation must support these browser routes.

Route	Access	Required behavior
/	Public	Home page and first-link entry.
/s/new	Public	Create or resume the one local draft.
/s/edit/{alias}	Owner only	Directly load an account-owned list for editing. Refresh must work. {alias} can contain multiple path segments.
/s/mylists	Signed in	Show the current user's active and deleted lists.
/{alias}	Public	Show an active public list, a deleted tombstone, or a never-used alias state. {alias} can contain multiple path segments.

The application must reserve its own application paths. At minimum, these first path segments are reserved and cannot be list aliases:

• s
• api
• auth
• __test
• .well-known

The implementation can reserve more paths. It must document all additional reserved paths.

Static file paths do not become valid aliases. Query strings and fragments are not part of an alias.

10. Navigation

The global navigation must provide:

• A The Urlist home link
• New
• My Lists when signed in
• A theme selector with Light, Dark, and System
• Login when signed out
• The current mock GitHub user's name or account menu when signed in
• Log out when signed in

At a mobile width, the application can put these controls in a menu. The menu must have an accessible name and state.

Selecting New must not silently erase a non-empty draft. The application must show a confirmation before it clears that draft.

11. Functional requirements

Requirement keywords have these meanings:

• MUST: Required for conformance.
• SHOULD: Strongly recommended. A human reviewer can deduct points if it is absent without good reason.
• MAY: Optional.

11.1 Draft lifecycle

FR-DRAFT-01 The application MUST keep at most one unpublished draft in a browser profile.

FR-DRAFT-02 The draft MUST be available to anonymous and signed-in users.

FR-DRAFT-03 The draft MUST survive page reloads and browser navigation.

FR-DRAFT-04 The draft MUST contain the list description, requested alias, links, link order, editable metadata, and terminal metadata status.

FR-DRAFT-05 The application MUST clear the draft after successful publication.

FR-DRAFT-06 The application MUST not clear a non-empty draft without explicit confirmation.

FR-DRAFT-07 The identity that is active at publication time determines ownership:

• No active identity: publish as anonymous.
• Active mock GitHub identity: publish as account-owned.

FR-DRAFT-08 Logging in or out MUST NOT by itself erase the draft.

11.2 Destination URL validation

FR-URL-01 A link destination MUST be an absolute HTTP or HTTPS URL.

FR-URL-02 The application MAY add https:// when a user enters a domain-like value without a scheme. If it does, it MUST show the normalized value before publication.

FR-URL-03 The application MUST reject:

• Empty or whitespace-only values
• Schemes other than HTTP and HTTPS
• Relative URLs
• Values without a valid host
• URLs that contain embedded credentials
• Values that cannot be parsed as one absolute URL

FR-URL-04 The application MUST show a specific error near the URL field and associate the error with the field.

FR-URL-05 The destination URL becomes immutable after the link entry is created. The displayed URL can be read or copied, but not edited.

FR-URL-06 To change a destination URL, the author must delete the link and add a new one.

11.3 Link creation and editing

FR-LINK-01 A list MUST support any number of links that available resources can hold. The product MUST NOT impose a documented product limit.

FR-LINK-02 Duplicate destination URLs MUST be allowed.

FR-LINK-03 Each duplicate is a separate link entry with a separate identifier, title, description, image, and position.

FR-LINK-04 The author MUST be able to add and delete links in a draft.

FR-LINK-05 The owner MUST be able to add and delete links from an account-owned published list.

FR-LINK-06 The author or owner MUST be able to edit a link title and description.

FR-LINK-07 The image is controlled by metadata enrichment. The interface MUST NOT require direct image URL editing.

FR-LINK-08 The author or owner MUST be able to reorder links.

FR-LINK-09 Reordering MUST work with a pointer and with a keyboard. Drag-and-drop alone is not sufficient.

FR-LINK-10 Every add, delete, edit, and reorder action MUST update the local draft immediately. An account-owned published list updates only when the owner saves, unless the interface clearly uses autosave.

FR-LINK-11 If the implementation uses autosave, it MUST clearly show saving, saved, and failed states.

FR-LINK-12 At least one link is required for publication or for saving an edited published list.

11.4 Live metadata enrichment

FR-META-01 The application MUST fetch metadata from the live destination URL after a link is added.

FR-META-02 The default product mode MUST NOT replace live fetching with static fixtures.

FR-META-03 Each link MUST show one metadata state:

• Pending
• Succeeded
• Failed

FR-META-04 The complete metadata network operation MUST stop no later than 10 seconds after it starts. The interface MUST show the terminal succeeded or failed state no later than one additional second after that deadline.

FR-META-05 Publication and saving MUST wait while any link is pending.

FR-META-06 A failed enrichment MUST NOT remove the link.

FR-META-07 After an enrichment failure, the author MUST be able to edit the title and description and publish or save.

FR-META-08 Metadata extraction MUST use this precedence:

Field	First choice	Second choice	Standard fallback
Title	og:title	Twitter Card title	HTML <title>, then first suitable <h1>
Description	og:description	Twitter Card description	HTML meta description
Image	og:image	Twitter Card image	Declared page icon, then /favicon.ico if available

FR-META-09 The implementation MUST support common Twitter Card attribute forms that use name or property.

FR-META-10 Relative image and icon URLs MUST resolve against the final document URL after redirects.

FR-META-11 Empty metadata is a successful result if the document loaded and parsed. Title and description remain optional.

FR-META-12 The application MUST show a neutral placeholder when no usable image exists.

FR-META-13 The user MUST be able to edit an enriched title or description. Later rendering MUST preserve that manual value.

11.5 Alias rules

FR-ALIAS-01 An alias consists of one or more path segments separated by /.

FR-ALIAS-02 The application MUST normalize ASCII letters to lowercase before availability checks and storage.

FR-ALIAS-03 Each segment MUST contain only:

• Lowercase ASCII letters a-z
• Digits 0-9
• Hyphens -

FR-ALIAS-04 Each segment MUST contain 1 to 50 characters.

FR-ALIAS-05 The complete alias, including / separators, MUST contain no more than 200 characters.

FR-ALIAS-06 An alias MUST NOT contain:

• An empty segment
• A leading or trailing /
• A leading or trailing hyphen in a segment
• Two adjacent / characters
• . or .. as a segment
• A query, fragment, backslash, encoded slash, or encoded backslash
• A reserved first segment

FR-ALIAS-07 Availability checks MUST use the normalized alias.

FR-ALIAS-08 Active, deleted, and anonymous aliases all count as reserved.

FR-ALIAS-09 If the author leaves the alias blank, the server MUST generate an available alias with seven lowercase ASCII letters or digits.

FR-ALIAS-10 A generated alias MUST pass the same availability and reserved-path checks as a custom alias.

FR-ALIAS-11 Two publications that request the same alias MUST NOT overwrite each other. Exactly one can succeed.

FR-ALIAS-12 An alias becomes immutable after first publication.

FR-ALIAS-13 The interface MUST report invalid or unavailable aliases before publication when practical. The server MUST repeat all checks at publication time.

FR-ALIAS-14 Alias lookup MUST use the exact complete normalized path. Prefix-related aliases, such as burke and burke/links, are independent and can both exist.

11.6 List publication

FR-PUB-01 A list description is optional.

FR-PUB-02 The application MUST disable or reject publication while:

• The list has no links.
• Any metadata request is pending.
• The requested alias is invalid.
• The requested alias is unavailable.

FR-PUB-03 Anonymous publication MUST show a modal confirmation before it writes data.

FR-PUB-04 The anonymous confirmation MUST state that publication is permanent and that the list cannot be edited or deleted.

FR-PUB-05 Canceling the confirmation MUST return to the unchanged draft.

FR-PUB-06 Successful publication MUST navigate to the canonical public path.

FR-PUB-07 The server is the final authority for validation, alias allocation, ownership, and mutation.

FR-PUB-08 The application MUST show a clear recoverable error when publication fails. It MUST retain the draft.

11.7 Anonymous list lifecycle

FR-ANON-01 A signed-out user MUST be able to publish.

FR-ANON-02 A published anonymous list MUST have no account owner.

FR-ANON-03 A published anonymous list MUST be immutable.

FR-ANON-04 A published anonymous list MUST be non-deletable through product interfaces and normal product APIs.

FR-ANON-05 Its alias MUST remain reserved permanently.

FR-ANON-06 Login after publication MUST NOT claim or change the anonymous list.

FR-ANON-07 Anonymous lists MUST NOT appear in any user's My Lists page.

11.8 Mock GitHub authentication

FR-AUTH-01 The local application MUST provide a mock GitHub identity provider.

FR-AUTH-02 The provider MUST expose at least two selectable identities with stable, distinct:

• User IDs
• User names
• Avatar values or placeholders

FR-AUTH-03 The login interface MUST make clear that it is a local mock provider.

FR-AUTH-04 Selecting an identity MUST create a local authenticated session.

FR-AUTH-05 The current identity MUST survive a page reload until logout or test reset.

FR-AUTH-06 Logout MUST end the authenticated session.

FR-AUTH-07 Product authorization MUST use the stable user ID, not the displayed name.

FR-AUTH-08 The authentication boundary SHOULD be replaceable by a real provider adapter without changing list ownership rules.

FR-AUTH-09 The login selector MUST show the two identities in a deterministic order. The first is benchmark user A and the second is benchmark user B. Each selection control MUST have the accessible name Continue as {display name}.

11.9 Account-owned list lifecycle

FR-OWN-01 A list published while signed in MUST be owned by the current mock GitHub identity.

FR-OWN-02 Only the owner can edit, save, delete, or restore the list.

FR-OWN-03 A non-owner MUST receive an authorization failure for a direct mutation request, even if the interface hides the control.

FR-OWN-04 /s/edit/{alias} MUST load the list from persistent storage. It MUST work after direct navigation and page reload.

FR-OWN-05 The edit page MUST show the alias as read-only.

FR-OWN-06 The owner can change:

• List description
• Link membership
• Link order
• Link titles
• Link descriptions

FR-OWN-07 The owner cannot change link destination URLs or the list alias.

FR-OWN-08 The owner MUST confirm deletion in a modal.

FR-OWN-09 Deletion MUST be a soft delete. It MUST retain the content and ownership needed for indefinite restoration.

FR-OWN-10 There is no permanent-delete product action.

FR-OWN-11 Restore MUST reactivate the same list, alias, content, and order.

FR-OWN-12 A restored list MUST again appear at its original public path.

11.10 My Lists

FR-MY-01 /s/mylists MUST require authentication.

FR-MY-02 The page MUST show only lists owned by the current user.

FR-MY-03 Active and deleted lists MUST be in distinct, labeled sections.

FR-MY-04 An active list summary MUST show:

• Alias
• Description when present
• Link count

FR-MY-05 Selecting an active list MUST open /s/edit/{alias}.

FR-MY-06 A deleted list summary MUST provide Restore.

FR-MY-07 An empty active or deleted section MUST show an explicit empty state.

FR-MY-08 The page MUST provide Create new list.

11.11 Public list page

FR-PUBLIC-01 An active list MUST be available without authentication.

FR-PUBLIC-02 The public heading MUST use the list description. If the description is blank, it MUST use the alias.

FR-PUBLIC-03 Links MUST appear in saved order.

FR-PUBLIC-04 Each link card MUST show:

• Image or neutral placeholder
• Title, or destination hostname or URL when title is blank
• Description when present
• Destination URL

FR-PUBLIC-05 Selecting a link MUST open its immutable HTTP or HTTPS destination.

FR-PUBLIC-06 A new browsing context MUST use safe opener isolation, such as noopener and noreferrer.

FR-PUBLIC-07 The page MUST provide a Links view and a QR code view.

FR-PUBLIC-08 The current view control MUST expose its selected state to assistive technology.

FR-PUBLIC-09 The page MUST provide:

• Copy link
• A share link for X or Twitter
• A share link for Facebook
• A share link for LinkedIn

FR-PUBLIC-10 Share targets MUST include the correctly percent-encoded canonical public URL. Where supported, they MUST include the encoded list heading.

FR-PUBLIC-11 Copy link MUST copy the canonical absolute public URL and announce success or failure.

11.12 QR code

FR-QR-01 The QR code MUST encode the canonical absolute URL of the public list, not an individual destination.

FR-QR-02 A standard QR decoder MUST be able to recover the exact canonical URL.

FR-QR-03 The QR code MUST have sufficient contrast in light and dark themes.

FR-QR-04 The QR code MUST have an accessible text alternative or adjacent text that identifies its encoded URL.

11.13 Never-used alias

FR-NOTFOUND-01 A valid alias that has never been used MUST show a not-found state.

FR-NOTFOUND-02 The state MUST say that the list was not found.

FR-NOTFOUND-03 The state MUST provide a call to action to create a list with that alias prefilled.

FR-NOTFOUND-04 The call to action MUST NOT silently overwrite a non-empty draft.

FR-NOTFOUND-05 An invalid or reserved path MUST use a generic not-found or invalid-path state. It MUST NOT offer that path as an available alias.

11.14 Deleted-list tombstone

FR-TOMB-01 A deleted account-owned list MUST show a neutral public message: This list was deleted.

FR-TOMB-02 The public tombstone MUST NOT disclose the old description, links, owner name, or deletion reason.

FR-TOMB-03 If the signed-in visitor is the owner, the tombstone MUST also provide Restore.

FR-TOMB-04 Other visitors and other signed-in users MUST not see a restore control.

11.15 Themes

FR-THEME-01 The application MUST provide Light, Dark, and System choices.

FR-THEME-02 The selected choice MUST persist in the browser across reloads.

FR-THEME-03 System mode MUST follow the operating system color preference.

FR-THEME-04 The initial page render SHOULD avoid a visible flash of the wrong theme.

FR-THEME-05 All evaluated content and controls MUST keep WCAG 2.2 AA contrast in each theme.

12. Data requirements

The physical schema is implementation-specific. The implementation must preserve the following logical data.

12.1 User

Field	Rule
Stable user ID	Required and unique. Used for authorization.
Provider	github-mock or an equivalent documented value.
Display name	Required.
Avatar	URL, local asset path, or deterministic placeholder.

12.2 List

Field	Rule
Stable list ID	Required and not derived only from the mutable storage location.
Canonical alias	Required, normalized, unique, and immutable.
Description	Optional text.
Ownership type	anonymous or account.
Owner user ID	Required for account ownership. Null for anonymous ownership.
Status	active or deleted. Anonymous lists can only be active.
Ordered links	One or more links for a published active list.
Created time	Required.
Updated time	Required for account-owned lists.
Deleted time	Required while deleted.

12.3 Link

Field	Rule
Stable link ID	Required and unique within its list.
Position	Defines total order within the list.
Destination URL	Required, absolute HTTP or HTTPS, and immutable after creation.
Title	Optional author-editable text.
Description	Optional author-editable text.
Image URL	Optional enrichment-controlled HTTP or HTTPS URL.
Metadata state	pending, succeeded, or failed in a draft or edit session.
Metadata error	Optional safe user-facing category or message.

12.4 Persistence

DR-PERSIST-01 Published anonymous lists, account-owned lists, deleted lists, ownership, and aliases MUST survive a complete application restart.

DR-PERSIST-02 The one unpublished draft and theme preference MUST persist in browser storage.

DR-PERSIST-03 Resetting browser storage MAY remove the local draft and theme preference. It MUST NOT remove published server-side data.

DR-PERSIST-04 The test reset mechanism is the only required way to clear all benchmark data.

DR-PERSIST-05 Soft deletion MUST not erase list content.

13. State and feedback requirements

The interface must represent important asynchronous and exceptional states.

13.1 Required states

Operation	Required visible states
Initial application load	Loading, loaded, fatal error with retry or reload
Metadata enrichment	Pending per link, succeeded, failed
Alias check	Checking when asynchronous, available, invalid, unavailable
Publication	Ready, blocked with reason, publishing, success, failure
Save	Saving and success/failure, unless a synchronous save completes without perceptible delay
My Lists	Loading, active results, deleted results, empty, failure with retry
Public list	Loading, active, never used, deleted, failure
Copy link	Success or failure announcement
Login	Signed out, identity selection, signed in, failure

13.2 Feedback rules

UX-STATE-01 Error text MUST explain what the user can do next.

UX-STATE-02 A failed network or server action MUST NOT falsely show success.

UX-STATE-03 A failed publish or save MUST preserve unsaved user input.

UX-STATE-04 Success and error messages that appear without focus change MUST use an appropriate live region.

UX-STATE-05 A disabled publish control MUST have an adjacent explanation or equivalent discoverable reason.

UX-STATE-06 Destructive actions MUST use clear action names. Do not use an ambiguous OK label when Delete list or Publish permanently is possible.

14. Security and privacy requirements

14.1 Authorization

SEC-AUTHZ-01 The server MUST enforce owner checks for every edit, save, delete, and restore operation.

SEC-AUTHZ-02 Hiding a control in the client is not an authorization control.

SEC-AUTHZ-03 The server MUST derive account ownership from the authenticated session. It MUST ignore a client-supplied owner ID.

SEC-AUTHZ-04 Anonymous publication MUST set anonymous ownership on the server.

SEC-AUTHZ-05 The server MUST reject all normal mutation requests for anonymous published lists.

SEC-AUTHZ-06 A list lookup MUST distinguish active, deleted, and never-used aliases without exposing private content.

14.2 Input and output safety

SEC-INPUT-01 The server MUST validate URLs, aliases, list content, and ownership rules independently of client validation.

SEC-INPUT-02 User-provided titles, descriptions, aliases, and metadata MUST render as text, not executable markup.

SEC-INPUT-03 The application MUST prevent script execution from stored or reflected content.

SEC-INPUT-04 Share URLs MUST use correct encoding. User content MUST not inject additional share parameters.

SEC-INPUT-05 State-changing requests MUST use the platform's appropriate cross-site request protection.

SEC-INPUT-06 Error responses MUST not expose stack traces, credentials, local paths, or internal connection details to end users.

14.3 Live metadata fetch safety

Metadata enrichment is a server-side request to a user-provided URL. The implementation must reduce server-side request forgery risk.

SEC-FETCH-01 The fetcher MUST allow only HTTP and HTTPS.

SEC-FETCH-02 The fetcher MUST reject URLs with embedded credentials.

SEC-FETCH-03 The fetcher MUST reject destinations that resolve to:

• Loopback addresses
• Private network ranges
• Link-local ranges
• Multicast ranges
• Unspecified or reserved ranges
• Cloud instance metadata addresses

SEC-FETCH-04 The fetcher MUST validate all resolved addresses before connection.

SEC-FETCH-05 The fetcher MUST repeat scheme, host, and address validation after every redirect.

SEC-FETCH-06 The fetcher MUST use a redirect limit of five or fewer.

SEC-FETCH-07 DNS rebinding protection MUST ensure that the connected address remains an allowed public address.

SEC-FETCH-08 The complete enrichment network operation, including redirects and body reading, MUST stop no later than 10 seconds after it starts.

SEC-FETCH-09 The fetcher MUST limit downloaded content. A maximum response body of 2 MiB or less is acceptable.

SEC-FETCH-10 The fetcher SHOULD accept only HTML or XHTML content for document parsing.

SEC-FETCH-11 The fetcher MUST not forward application cookies, authorization headers, or user credentials to the destination.

SEC-FETCH-12 Metadata text and URLs MUST receive the same output-safety treatment as direct user input.

14.4 Privacy

SEC-PRIV-01 Anonymous public lists MUST not store a hidden browser identity or account owner.

SEC-PRIV-02 Deleted tombstones MUST not expose deleted content or owner details.

SEC-PRIV-03 The mock provider MUST use fictional test identities.

SEC-PRIV-04 Documentation MUST state that link metadata fetching sends a server request to the submitted destination.

15. Accessibility requirements

The evaluated user journeys must conform to WCAG 2.2 AA.

15.1 Structure and names

A11Y-01 Each page MUST have one descriptive level-one heading.

A11Y-02 Headings MUST follow a logical hierarchy.

A11Y-03 Every form control and icon-only button MUST have an accessible name.

A11Y-04 Form errors MUST be programmatically associated with their controls.

A11Y-05 Required and invalid states MUST be available to assistive technology.

A11Y-06 Images MUST have useful alternative text or empty alternative text when decorative.

15.2 Keyboard and focus

A11Y-07 All actions MUST work without a pointer.

A11Y-08 Keyboard focus MUST be visible in all themes.

A11Y-09 Focus order MUST follow the visual and reading order.

A11Y-10 Link reordering MUST provide keyboard controls, such as Move up and Move down.

A11Y-11 A modal MUST:

• Move focus to itself when opened.
• Keep focus within the modal while open.
• Close on Escape when cancellation is allowed.
• Return focus to the control that opened it.
• Have an accessible title and modal semantics.

A11Y-12 After link deletion or reordering, focus MUST move to a logical nearby control.

15.3 Status and presentation

A11Y-13 Loading, metadata, save, publish, copy, and error status changes MUST be announced when necessary.

A11Y-14 Color MUST not be the only way to communicate state.

A11Y-15 Text and meaningful controls MUST meet WCAG 2.2 AA contrast.

A11Y-16 The interface MUST remain usable at 200% browser zoom.

A11Y-17 Reflow MUST not require two-dimensional page scrolling at a 320 CSS-pixel viewport, except for content that inherently needs it. No evaluated content inherently needs it.

A11Y-18 Pointer targets SHOULD meet the WCAG 2.2 target-size guidance.

A11Y-19 Motion MUST respect prefers-reduced-motion.

16. Responsive requirements

The implementation must support current Chromium at:

• A desktop viewport
• A mobile-width viewport down to 320 CSS pixels

The exact breakpoints are implementation-specific.

RESP-01 Desktop navigation can be horizontal.

RESP-02 Mobile navigation can collapse into a labeled menu.

RESP-03 The list-detail fields and publication control can share a desktop row, but MUST stack at a mobile width.

RESP-04 Editable and public link cards MUST not clip the title, URL, primary actions, or keyboard reorder controls.

RESP-05 A link image MAY become smaller or move at a mobile width.

RESP-06 My Lists cards MUST change from a multi-column grid to fewer columns or one column as space decreases.

RESP-07 Modals MUST fit the viewport and permit internal scrolling when necessary.

RESP-08 Share and view controls MUST remain available at a mobile width.

17. Information architecture

17.1 Home

The home page introduces the product and has the fastest path to a new list. The primary control is the first-link URL field.

Required content:

• Brand and global navigation
• Product heading and short explanatory copy
• First-link URL field
• Submit action
• URL validation feedback
• Optional decorative illustration

17.2 New list

The new-list page is the main composition workspace.

Required content:

• Alias field with guidance and availability state
• Optional list description
• Publish control and blocking reason
• Add-link URL field
• Ordered editable link cards
• Per-link metadata state
• Delete and keyboard reorder controls

17.3 Edit list

The edit page uses the same composition workspace with these differences:

• The alias is read-only.
• The list loads from persistent storage by alias.
• The primary action is Save.
• The page provides Delete list.
• Only the owner can enter this page.

17.4 My Lists

Required content:

• Create new list
• Active list section
• Deleted lists section
• Alias, description, and link count on active summaries
• Restore action on deleted summaries
• Empty and loading states

17.5 Public list

Required content:

• List heading
• Copy and platform-share controls
• Links/QR view selector
• Ordered link cards or QR code
• Public loading, not-found, and deleted states

18. Low-fidelity wireframes

Wireframes define information order and important controls. They do not define colors, fonts, exact dimensions, or component libraries.

18.1 Desktop home

+--------------------------------------------------------------------------------+
| THE URLIST          New                         Theme        Login / User menu   |
+--------------------------------------------------------------------------------+
|                                                                                |
|  Group links, save and share them        [ optional brand illustration ]       |
|  with the world.                                                               |
|                                                                                |
|  Add links to a list and share it                                              |
|  with one simple URL.                                                          |
|                                                                                |
+--------------------------------------------------------------------------------+
|                              Get Started                                       |
|                                                                                |
|  Link URL                                                                      |
|  [ https://example.com...................................................... ]  |
|  [ validation or help text ]                                      [ Add link ] |
+--------------------------------------------------------------------------------+

18.2 Mobile home

+--------------------------------------+
| THE URLIST                    [Menu] |
+--------------------------------------+
| Group links, save and share them     |
| with the world.                      |
|                                      |
| Add links to a list and share it     |
| with one simple URL.                 |
|                                      |
| Get Started                          |
| Link URL                             |
| [ https://example.com............. ] |
| [ validation or help text ]          |
| [ Add link                         ] |
+--------------------------------------+

18.3 Desktop new or edit list

+--------------------------------------------------------------------------------+
| THE URLIST      New      My Lists                 Theme       User menu         |
+--------------------------------------------------------------------------------+
| Alias                         Description                     Primary action    |
| [ burke/links.............. ] [ Useful web resources...... ] [ Publish / Save ] |
| [ availability or error ]                                                   |
+--------------------------------------------------------------------------------+
| Add a link                                                                    |
| [ https://destination.example................................ ] [ Add link ]   |
|                                                                                |
| Links                                                    Drag or use buttons   |
| +----------------------------------------------------------------------------+ |
| | [handle] [image] [ Title................................................. ] | |
| |                  [ Description........................................... ] | |
| |                  https://destination.example   [Pending/Succeeded/Failed] | |
| |                  [Move up] [Move down]                         [Delete]    | |
| +----------------------------------------------------------------------------+ |
| +----------------------------------------------------------------------------+ |
| | [handle] [image] [ Title................................................. ] | |
| |                  [ Description........................................... ] | |
| |                  https://another.example       [Succeeded]                | |
| |                  [Move up] [Move down]                         [Delete]    | |
| +----------------------------------------------------------------------------+ |
|                                                                                |
|                                                        [ Delete list ] (edit) |
+--------------------------------------------------------------------------------+

18.4 Mobile new or edit list

+--------------------------------------+
| THE URLIST                    [Menu] |
+--------------------------------------+
| Alias                                |
| [ burke/links..................... ] |
| [ availability or error ]            |
|                                      |
| Description                          |
| [ Useful web resources............ ] |
|                                      |
| [ Publish / Save                   ] |
| [ blocking reason, if applicable ]   |
|                                      |
| Add a link                           |
| [ https://destination.example..... ] |
| [ Add link                         ] |
|                                      |
| Links                                |
| +----------------------------------+ |
| | [image] Title                   | |
| | Description                     | |
| | https://destination.example     | |
| | Metadata: Succeeded             | |
| | [Up] [Down]           [Delete]  | |
| +----------------------------------+ |
|                                      |
| [ Delete list ] (edit only)          |
+--------------------------------------+

18.5 My Lists

+--------------------------------------------------------------------------------+
| THE URLIST      New      My Lists                 Theme       User menu         |
+--------------------------------------------------------------------------------+
| My Lists                                                                       |
|                                                                                |
| [ + Create new list ]                                                          |
|                                                                                |
| Active lists                                                                   |
| +----------------------+ +----------------------+ +----------------------+     |
| | burke/links          | | team/research        | | recipes             |     |
| | Useful resources     | | Reading queue        | |                     |     |
| | 12 links             | | 4 links              | | 9 links             |     |
| +----------------------+ +----------------------+ +----------------------+     |
|                                                                                |
| Deleted lists                                                                  |
| +----------------------+                                                       |
| | old/resources        |                                                       |
| | 6 links    [Restore] |                                                       |
| +----------------------+                                                       |
+--------------------------------------------------------------------------------+

At a mobile width, these cards form one column.

18.6 Active public list

+--------------------------------------------------------------------------------+
| THE URLIST          New                         Theme        Login / User menu   |
+--------------------------------------------------------------------------------+
| Useful web resources                                                          |
|                                                                                |
| [Copy link] [X/Twitter] [Facebook] [LinkedIn]          [Links selected] [QR]  |
|                                                                                |
| +----------------------------------------------------------------------------+ |
| | [image]  Link title                                                        | |
| |          Optional description                                               | |
| |          https://destination.example                                        | |
| +----------------------------------------------------------------------------+ |
| +----------------------------------------------------------------------------+ |
| | [image]  another.example                                                    | |
| |          https://another.example                                            | |
| +----------------------------------------------------------------------------+ |
+--------------------------------------------------------------------------------+

18.7 QR view

+--------------------------------------------------------------+
| Useful web resources                                         |
| [Copy link] [X] [Facebook] [LinkedIn]   [Links] [QR selected]|
|                                                              |
|                     +------------------+                     |
|                     |                  |                     |
|                     |     QR CODE      |                     |
|                     |                  |                     |
|                     +------------------+                     |
|                  https://host/burke/links                    |
+--------------------------------------------------------------+

18.8 Never-used alias

+--------------------------------------------------------------+
| We could not find this Urlist.                               |
|                                                              |
| The alias "burke/links" is available.                        |
|                                                              |
| [ Create a list with this alias ]                            |
+--------------------------------------------------------------+

18.9 Deleted tombstone

+--------------------------------------------------------------+
| This list was deleted.                                      |
|                                                              |
| [ Restore ]  <- visible only to the signed-in owner          |
+--------------------------------------------------------------+

18.10 Mock login modal

+--------------------------------------------------------------+
| Sign in with local mock GitHub                         [X]   |
|                                                              |
| [avatar] Mock GitHub User One        [ Continue as User One ]|
| [avatar] Mock GitHub User Two        [ Continue as User Two ]|
|                                                              |
| [ Cancel ]                                                   |
+--------------------------------------------------------------+

18.11 Anonymous publication confirmation

+--------------------------------------------------------------+
| Publish this list permanently?                              |
|                                                              |
| You are not signed in. After publication, you cannot edit   |
| or delete this list. Its alias stays reserved permanently.   |
|                                                              |
| [ Publish permanently ]  [ Cancel ]                          |
+--------------------------------------------------------------+

18.12 Delete confirmation

+--------------------------------------------------------------+
| Delete this list?                                           |
|                                                              |
| The public page will show a deleted message. You can restore |
| the list later from My Lists.                                |
|                                                              |
| [ Delete list ]  [ Cancel ]                                  |
+--------------------------------------------------------------+

19. Benchmark execution contract

19.1 Repository deliverables

The model-produced repository must contain:

• Complete application source
• Dependency manifests and lock files where the ecosystem supports them
• Database schema and migrations or an equivalent repeatable initializer
• Automated tests
• A README with setup and operation instructions
• A documented test reset mechanism
• No required access to the original source repository

Generated build output and installed dependency folders should not be committed unless the selected ecosystem normally requires them.

19.2 Setup flexibility

The benchmark does not prescribe one startup command or Docker.

The README must state:

1. Supported operating system or runtime assumptions
2. Required tool versions
3. Dependency installation steps
4. Storage initialization steps
5. Application startup steps
6. The local base URL
7. How to select each mock GitHub user
8. How to reset and seed benchmark data
9. How to run automated tests
10. Any environment variables, with safe example values

The application must not require paid infrastructure or private credentials.

19.3 Local operation

BENCH-RUN-01 The complete application MUST run on a local machine.

BENCH-RUN-02 A real cloud database, real OAuth application, or deployed server MUST NOT be required.

BENCH-RUN-03 The implementation MAY use a local database, embedded database, container, or persistent files.

BENCH-RUN-04 The implementation MUST fetch live public websites for metadata enrichment. Internet access is therefore required for those scenarios.

BENCH-RUN-05 If the application has separate client and server processes, the README MUST explain how to start both.

19.4 Test-only reset and seed

The implementation must provide a development/test-only control that:

• Deletes all published and deleted benchmark lists
• Clears server-side sessions when practical
• Restores the two stable mock GitHub identities
• Returns the application to a known clean server state
• Can run repeatedly with the same result

The preferred contract is:

POST /__test/reset

Expected success:

204 No Content

An implementation can use a different mechanism only if it is scriptable, documented, and does not require manual database work.

BENCH-RESET-01 The reset mechanism MUST be enabled in development or test mode.

BENCH-RESET-02 The reset mechanism MUST be disabled or strongly protected in production mode.

BENCH-RESET-03 The README MUST explain how the browser harness can also clear browser storage and cookies.

BENCH-RESET-04 The two user identities MUST be deterministic across resets.

19.5 Stable automation surfaces

The implementation must keep these visible labels or equivalent accessible names:

• New
• My Lists
• Login
• Log out
• Add link
• Publish
• Save
• Delete list
• Restore
• Copy link
• Links
• QR code
• Light
• Dark
• System
• Move up
• Move down
• Continue as {display name}

The implementation should use semantic HTML. Test-only data-* attributes are permitted, but tests should prefer roles and accessible names.

The mock identity list must use deterministic order. The first control selects benchmark user A and the second selects benchmark user B.

19.6 Evaluator inputs

This document tells the model which behaviors are tested. It does not provide the exact evaluator values.

The evaluator can keep these values private:

• Mock user names and IDs, if the implementation lets the evaluator configure them
• Valid and invalid aliases
• Reserved-path probes
• Live public metadata URLs
• Metadata documents and expected extracted values
• Hostile content strings
• Ownership-isolation sequence
• Restart timing and storage location

The evaluator must not test an undisclosed product category. Hidden values and edge cases must still follow this document.

19.7 Live website evaluation note

Live websites can change or become unavailable. The evaluator should select stable, public test pages under evaluator control when possible. These pages must be reached through public internet DNS and HTTP or HTTPS. They must not use a local fixture server.

The evaluator should provide pages for:

• Open Graph metadata
• Twitter Card fallback metadata
• Standard HTML fallback metadata
• Relative image resolution
• A slow response that exceeds 10 seconds
• A failed HTTP response

The evaluator must record the target URL and expected document content with the benchmark result.

20. Automated black-box acceptance matrix: 75 points

20.1 Scoring rules

• Automated review contributes 75 points.
• A scenario earns its listed points only when all required assertions pass, unless the scenario defines partial credit.
• The evaluator must start each independent scenario from a documented state.
• The evaluator can combine scenarios to reduce runtime.
• The evaluator must use implementation-neutral browser and HTTP behavior.
• A crash, data corruption, authorization bypass, or test-reset failure can affect all dependent scenarios.
• Exact test values remain private.

20.2 Category summary

Category	Points
A. Local operation, reset, identity, and restart persistence	6
B. Draft, links, and metadata	15
C. Alias and publication rules	13
D. Account ownership and lifecycle	14
E. Public viewing, sharing, and QR code	12
F. Theme, responsive behavior, and accessibility	10
G. Failure handling and security probes	5
Automated total	75

20.3 A. Local operation, reset, identity, and restart persistence: 6 points

ID	Pts	Preconditions and actions	Expected result
A1	1	Follow the README on a clean supported environment. Start the application.	The application starts without private credentials. The documented base URL serves the home page.
A2	1	Create data, run the documented reset-and-seed mechanism twice, and clear browser state.	Both resets succeed. All list data is gone. The application returns to the same clean state.
A3	2	Open Login. Select mock GitHub user A. Reload. Log out. Select user B.	Two distinct local GitHub identities are available. Login survives reload. Logout works. The visible identity changes correctly.
A4	2	Publish one account-owned list, one anonymous list, and soft-delete another account-owned list. Fully stop and restart the application without reset.	Active, anonymous, deleted, ownership, alias, and tombstone state all survive restart.

20.4 B. Draft, links, and metadata: 15 points

ID	Pts	Preconditions and actions	Expected result
B1	1	Signed out, enter a valid first link on /.	The app opens /s/new, creates one link, retains the URL, and starts enrichment.
B2	2	Submit empty, relative, non-HTTP, credential-bearing, malformed, and valid HTTP/HTTPS inputs. If scheme completion exists, use a domain-like input.	Invalid values are rejected with associated messages. Valid HTTP and HTTPS values work. Any completed scheme is shown.
B3	3	Add live public pages that exercise Open Graph, Twitter Card, standard HTML, and relative-image cases.	The app uses the required precedence, follows allowed redirects, resolves relative images against the final URL, and shows extracted metadata.
B4	2	Add one slow live URL and one failing live URL.	The network operation stops no later than 10 seconds, and each link shows failed within 11 seconds. The links remain. The user sees failure and can edit title and description.
B5	1	Try to publish or save while enrichment is pending.	The action is blocked with a visible reason. It becomes available after every request succeeds or fails.
B6	2	Add a link, then inspect and edit it.	Destination URL is readable but immutable. Title and description are editable. Image is not directly editable. Manual title and description values persist.
B7	1	Add the same destination twice and give the entries different display metadata.	Both independent entries remain and retain separate metadata.
B8	2	Add at least three links. Delete one. Reorder the others with pointer input and then with keyboard controls.	Membership and order update correctly. Keyboard controls are operable and named.
B9	1	Create a non-empty draft. Reload and navigate away and back. Select New and cancel the discard confirmation. Then confirm it.	The draft survives reload/navigation. Cancel preserves it. Confirm starts a clean draft.

20.5 C. Alias and publication rules: 13 points

ID	Pts	Preconditions and actions	Expected result
C1	2	Enter a mixed-case valid multi-segment alias. Publish.	The app normalizes it to lowercase, stores it once, and serves the list at the nested root path.
C2	2	Probe invalid characters, empty segments, segment-length boundaries, total-length boundary, leading/trailing hyphens, traversal forms, and encoded separators.	Values outside the defined grammar are rejected by both product behavior and direct server requests. Boundary-valid values are accepted.
C3	1	Try aliases under each minimum reserved first segment.	The aliases are rejected and application routes remain reachable.
C4	1	Leave the alias blank and publish a valid list.	The server allocates an available seven-character lowercase alphanumeric alias.
C5	2	Make two near-simultaneous publication requests for the same normalized alias.	Exactly one succeeds. The other reports unavailability or conflict. No data is overwritten.
C6	1	Try to publish an empty list and a list with one valid terminal-state link.	Empty publication is blocked or rejected. One-link publication succeeds.
C7	1	Signed out, select Publish, then cancel and retry.	A blocking irreversible-publication warning appears. Cancel preserves the draft.
C8	2	Confirm anonymous publication. Then try normal edit, delete, claim, and direct mutation paths as anonymous and signed in.	The list remains public, immutable, non-deletable, unclaimed, and permanently reserved.
C9	1	Sign in and publish a new list.	Publication is account-owned without an anonymous/account choice. It appears in that user's My Lists.

20.6 D. Account ownership and lifecycle: 14 points

ID	Pts	Preconditions and actions	Expected result
D1	2	As user A, publish multiple lists and open My Lists. Also sign in as user B.	User A sees only A's active summaries with alias, optional description, and correct link count. User B does not see them. Empty states are clear.
D2	2	As owner, directly open and reload /s/edit/{multi-segment-alias}.	The correct persistent list loads. Alias is read-only. A non-owner cannot enter an editable state.
D3	2	As owner, change description, titles, descriptions, membership, and order, then save or wait for explicit autosave. Reload public and edit pages.	All permitted changes persist. Public rendering uses the new content and order.
D4	1	Try to change the published alias through the interface and a direct request.	The alias cannot be changed. The original path remains canonical.
D5	3	As user B, issue direct edit, save, delete, and restore requests for user A's list.	Every mutation is denied. The list and ownership remain unchanged. No client-supplied owner value bypasses the check.
D6	2	As owner, select Delete list, cancel once, then confirm. Open My Lists and the public path.	Cancel changes nothing. Confirm soft-deletes. The list moves to Deleted lists. The public path shows a neutral tombstone.
D7	2	Restore the list from Deleted lists. Delete it again and restore it from the owner-visible tombstone.	Both restore paths reactivate the same alias, content, link order, and ownership. There is no permanent-delete product action.

20.7 E. Public viewing, sharing, and QR code: 12 points

ID	Pts	Preconditions and actions	Expected result
E1	2	Open public lists with and without list descriptions, link titles, descriptions, and images.	Public access needs no login. Saved order is correct. Heading and card fallbacks follow the specification. Missing optional content does not break layout.
E2	1	Activate a public link card with pointer and keyboard. Inspect the opened target behavior.	The immutable HTTP/HTTPS destination opens. New-context navigation uses safe opener isolation.
E3	2	Switch to QR view and decode the rendered code. Test both themes.	The code decodes to the exact canonical absolute public URL and remains usable in each theme.
E4	1	Select Copy link and read the clipboard. Also simulate clipboard failure when supported by the harness.	The canonical absolute URL is copied. Success or failure is announced.
E5	2	Inspect and open X/Twitter, Facebook, and LinkedIn share controls for a list with reserved characters in its heading and path.	Each target contains the correctly encoded canonical URL and, where supported, heading. No parameter injection occurs.
E6	2	Open a valid alias that was never used. Select its create action with an empty draft, then repeat with a non-empty draft.	The page says not found and offers the alias. The empty draft receives the alias. Existing draft content is not silently overwritten.
E7	2	Open a deleted path signed out, as a non-owner, and as the owner.	All see only the neutral deleted message. Only the owner sees Restore. Old content and owner details are absent.

20.8 F. Theme, responsive behavior, and accessibility: 10 points

ID	Pts	Preconditions and actions	Expected result
F1	2	Select Light, Dark, and System in turn. Reload after each selection and change the emulated OS preference in System mode.	Choice persists. System follows OS preference. Controls and content remain readable.
F2	2	Exercise home, new/edit, My Lists, public list, QR, menus, and modals at desktop and 320 CSS-pixel widths.	Content reflows without page-level two-dimensional scrolling. Primary controls remain visible and usable.
F3	2	Complete create, login, edit, reorder, publish, delete, restore, view toggle, copy, and logout journeys with keyboard only.	Every action works. Focus is visible and follows a logical order. Reorder does not require drag-and-drop.
F4	2	Trigger URL, alias, metadata, publication, copy, and server errors. Open and close each modal with keyboard.	Controls have names. Errors are associated. statuses are announced. Modal focus is trapped and restored. Escape cancels when allowed.
F5	2	Run an automated accessibility scanner on evaluated pages and inspect headings, labels, selected states, and contrast in both themes.	There are no critical or serious WCAG 2.2 A/AA findings in application-owned UI. Required semantics and contrast pass.

20.9 G. Failure handling and security probes: 5 points

ID	Pts	Preconditions and actions	Expected result
G1	2	Cause a publication or save server failure after entering valid content. Retry after recovery.	The app reports failure, does not show false success, retains input, and succeeds on a valid retry without duplicate corruption.
G2	2	Submit metadata URLs for loopback, private, link-local, metadata-service, redirect-to-private, and DNS-rebinding-style targets supported by the harness.	The server rejects unsafe targets and does not connect to protected addresses. Safe public targets still work.
G3	1	Put HTML, script, event-handler, and share-parameter payloads in user-editable and remotely enriched text. View public, My Lists, edit, tombstone, and share surfaces.	Payloads render safely as text or are safely omitted. No script runs and no share parameter is injected.

21. Human-review scorecard: 25 points

21.1 Review method

Human review contributes 25 points. Reviewers must cite short evidence for each deduction. Reviewers should judge the submitted implementation, not personal framework preferences.

Use these anchors:

• Full points: Complete, coherent work with no material problem.
• About half points: The main intent is present, but important roughness or risk remains.
• Zero points: Missing, unusable, unsafe, or fundamentally incorrect.

Intermediate integer scores are allowed.

21.2 Category summary

Category	Points
H1. UX coherence and responsive usability	5
H2. Accessibility quality	4
H3. Security and privacy	5
H4. Maintainability and architecture	4
H5. Automated test quality	4
H6. Setup and operational documentation	3
Human total	25

21.3 H1. UX coherence and responsive usability: 5 points

5 points

• Journeys are easy to understand without repository knowledge.
• Primary and destructive actions have clear hierarchy.
• Pending, failed, empty, deleted, and success states are useful.
• Desktop and mobile layouts feel intentionally designed.
• Anonymous permanence is clear before publication.

About 2–3 points

• Core flows work, but labels, feedback, layout, or state transitions cause confusion.
• Mobile behavior is functional but rough.

0 points

• Important flows are unusable or misleading.
• Destructive or permanent actions are not understandable.

21.4 H2. Accessibility quality: 4 points

4 points

• Semantic structure is strong.
• Keyboard and focus behavior are predictable.
• Announcements are useful and not noisy.
• The design remains usable with zoom, reflow, reduced motion, and both themes.
• No important issue remains after automated checks.

About 2 points

• Basic keyboard and labeling work, but focus, announcements, reflow, or semantics have notable gaps.

0 points

• A primary journey cannot be completed with a keyboard or assistive technology.

21.5 H3. Security and privacy: 5 points

5 points

• Authorization is centralized and server-enforced.
• Anonymous and account lifecycle boundaries are correct.
• Live fetching has credible SSRF defenses at resolution, connection, and redirect stages.
• User and remote content is safely rendered.
• Errors and logs avoid secrets and sensitive internals.
• Test-only controls are isolated from production mode.

About 2–3 points

• Main authorization and output safety are present, but fetch hardening or environment isolation is incomplete.

0 points

• There is a practical ownership bypass, stored script execution, unsafe private-network fetch, exposed credential, or production data-reset path.

Critical cap: A confirmed practical authorization bypass or server-side request forgery vulnerability caps the total benchmark score at 50 until fixed.

21.6 H4. Maintainability and architecture: 4 points

4 points

• Product, persistence, identity, enrichment, and presentation concerns have clear boundaries.
• Types and validation are consistent across client and server boundaries.
• Code avoids unnecessary duplication and hidden coupling.
• Error handling is explicit.
• The design can replace the mock identity adapter without changing ownership logic.

About 2 points

• The code is understandable, but some duplication, coupling, broad error handling, or weak types increase change risk.

0 points

• The implementation is largely hardcoded, tangled, or unsafe to change.

21.7 H5. Automated test quality: 4 points

4 points

• Tests cover core lifecycle, validation, ownership isolation, persistence, and failure paths.
• Tests are deterministic except for clearly isolated live-network checks.
• Unit, integration, and end-to-end coverage are selected appropriately.
• Test names explain behavior.

About 2 points

• Useful happy-path tests exist, but lifecycle, authorization, or failure paths have major gaps.

0 points

• Tests are absent, trivial, consistently failing, or only assert implementation details.

21.8 H6. Setup and operational documentation: 3 points

3 points

• A new reviewer can install, initialize, start, reset, seed, test, and restart the application from the README.
• Required versions and environment variables are clear.
• Live metadata behavior and its privacy/security limits are explained.
• Troubleshooting covers likely local failures.

About 1–2 points

• Setup works with inference or minor repair, but important steps are unclear.

0 points

• The reviewer cannot run the application from the documentation.

22. Final score

Final score = automated score (0–75) + human-review score (0–25)
Maximum = 100

Suggested interpretation:

Score	Interpretation
90–100	Comprehensive and production-minded implementation
75–89	Strong implementation with limited gaps
60–74	Functional core with important omissions
40–59	Partial implementation or serious quality defects
0–39	Incomplete or unsafe implementation

The score ranges are descriptive. Benchmark reports must also show category scores and failed scenario IDs.

23. Requirement-to-evaluation traceability

This table shows where required behavior is evaluated. It does not reveal exact test values.

Requirement area	Primary automated scenarios	Human review
Local operation and documentation	A1, A2	H6
Persistent server data	A4	H4, H6
Browser-local draft	B1, B9	H1
URL validation and immutability	B2, B6	H1, H3
Link creation, duplicates, deletion, and order	B7, B8, D3	H1, H2
Live metadata extraction	B3, B4, B5	H3, H4
Metadata fetch security	G2	H3
Alias grammar and allocation	C1–C5	H3, H4
Anonymous publication	C6–C8	H1, H3
Mock GitHub login	A3, C9	H1, H4
Account ownership and isolation	D1–D5	H3, H4
Delete, tombstone, and restore	D6, D7, E7	H1, H3
My Lists	D1, D6, D7	H1, H2
Public list rendering	E1, E2	H1, H2
Sharing and clipboard	E4, E5	H1, H2, H3
QR code	E3	H1, H2
Never-used alias	E6	H1
Themes	F1	H1, H2
Responsive layout	F2	H1, H2
Keyboard, focus, labels, and status	F3–F5	H2
Failure recovery	G1	H1, H4
Content and parameter injection	G3	H3
Code organization and tests	Not black-box scored	H4, H5

Requirements marked SHOULD, repository organization, code clarity, test depth, and documentation quality are mainly human-reviewed. Concurrent-edit behavior and performance are intentionally not scored.

24. Evaluator report template

Each benchmark result should include:

Model:
Model version:
Benchmark document version:
Run date:
Allowed work time:
Environment:
Application commit:

Automated:
  A Local/reset/identity/persistence: __ / 6
  B Draft/links/metadata:             __ / 15
  C Alias/publication:                __ / 13
  D Ownership/lifecycle:              __ / 14
  E Public/share/QR:                  __ / 12
  F Theme/responsive/accessibility:   __ / 10
  G Failure/security:                 __ / 5
  Automated subtotal:                 __ / 75

Human:
  H1 UX:                              __ / 5
  H2 Accessibility:                   __ / 4
  H3 Security/privacy:                __ / 5
  H4 Maintainability:                 __ / 4
  H5 Tests:                           __ / 4
  H6 Documentation:                   __ / 3
  Human subtotal:                     __ / 25

Critical score cap applied: Yes / No
Final score: __ / 100

Failed scenario IDs:
Reviewer evidence:
Live metadata targets and captured expectations:
Known evaluator incidents:

An evaluator incident is an infrastructure or live-website problem that is not caused by the implementation. The report must separate such incidents from product failures.

25. Source reconciliation and intentional deviations

This standalone specification is based on the product behavior of the reference project. It resolves incomplete, contradictory, or legacy behavior as follows.

Reference behavior or issue	Canonical benchmark requirement
The product copy says anonymous creation is possible, but the reference publish control and server require login.	Anonymous users can publish after a permanent-action confirmation.
Anonymous ownership and later editing are not safely defined.	Anonymous publication is immutable, non-deletable, non-claimable, and reserves the alias permanently.
The reference client allows only letters, digits, and hyphens, while the server suggests nested path aliases.	Multi-segment aliases are required with one defined grammar and lowercase normalization.
The reference can hard-delete a list and release its alias.	Account deletion is a permanent soft-delete state with indefinite restoration and a reserved alias.
The reference edit route depends on selected client state.	/s/edit/{alias} loads directly from persistent storage and survives reload.
Social-share markup contains residue from another UI framework and may not work.	Copy link and three correctly encoded platform share links must work.
Twitter/X migration depends on a legacy external service.	Migration is excluded.
The reference has an email-based report link.	Reporting is excluded.
The reference includes a long Terms page, empty Privacy page, and external About link.	Legal and informational pages are excluded.
The reference metadata title precedence can favor HTML title before Open Graph.	Open Graph, then Twitter Card, then standard HTML fallback is canonical.
The reference allows publication while asynchronous enrichment can still run.	Publish and save wait until each request succeeds or fails.
The reference uses a 20-second client cancellation period.	Each complete enrichment attempt has a 10-second limit.
The reference permits destination URL editing after enrichment.	Destination URL is immutable after link creation. Delete and re-add to change it.
The reference uses real hosted OAuth providers.	A local mock GitHub provider with two identities is required.
The reference architecture uses Blazor WebAssembly, Azure Functions, and Cosmos DB.	Technology is not prescribed. Observable behavior is prescribed.
The reference provides light, dark, and system themes.	Theme behavior remains required with a small score weight.
The reference supports QR rendering for the list URL.	A scannable public-list QR code remains required.

These decisions are part of the benchmark. An implementation must follow this document instead of trying to reproduce a conflicting reference behavior.

26. Implementation guidance that is not scored directly

These patterns can reduce implementation risk:

• Use one canonical alias normalization function in both availability and write paths.
• Put authorization in the server-side list service or mutation boundary.
• Store ownership type separately from owner ID.
• Use a soft-delete status instead of moving deleted rows to an unrelated store.
• Use stable link IDs and explicit positions.
• Separate metadata retrieval from metadata parsing.
• Put outbound request validation in a dedicated fetch policy.
• Abort metadata work when its 10-second deadline expires.
• Use a real QR library rather than a decorative QR-like image.
• Keep mock authentication behind an interface or adapter.
• Use accessible sortable controls in addition to pointer drag-and-drop.
• Treat local draft persistence errors as visible product errors when they prevent retention.

An implementation can use other patterns if all requirements pass.

27. Definition of done

The model-produced application is complete when:

1. The application runs locally from its README.
2. The product journeys in section 8 work.
3. All MUST requirements are implemented.
4. Published and deleted data survives a full restart.
5. Two mock GitHub identities work.
6. Reset and seed are repeatable.
7. Live metadata success, failure, timeout, fallback, and safety behavior work.
8. Anonymous and account lifecycle rules cannot be bypassed through direct requests.
9. Root and nested aliases route correctly.
10. Public share and QR controls produce the canonical URL.
11. Evaluated journeys work at desktop and mobile widths.
12. Evaluated journeys meet WCAG 2.2 AA.
13. Automated tests run from the documented command.
14. The repository contains no required secret.
15. The implementation does not depend on the original repository.

28. Benchmark limitations

• Live internet metadata tests can vary because websites and networks change. Evaluators must record their targets and distinguish target incidents from implementation failures.
• Human scores contain judgment. Anchors and written evidence reduce, but do not remove, reviewer variation.
• This benchmark does not measure high-load behavior, large-scale storage, production deployment, or concurrent editing.
• The mock identity provider tests ownership logic, not OAuth protocol compliance.
• WCAG conformance applies to evaluated journeys and application-owned content. It does not assert full legal conformance for every possible page or third-party browser surface.

29. End of specification

This document is the only product input required for the benchmark. A model must not need the original repository, its issue tracker, its hosted deployment, or external design files to implement The Urlist.

the-urlist-implementation-profile.md

The Urlist Benchmark: Implementation Profile

Profile version: 1.0
Companion specification: the-urlist-benchmark-prd.md

1. Purpose

This profile fixes the technical stack for The Urlist benchmark. It makes model results easier to compare.

The product PRD is the authority for product behavior. This profile is the authority for technology choices. If the documents appear to conflict:

1. Follow the PRD for user-visible behavior and evaluation.
2. Follow this profile for the implementation stack.
3. Document any remaining assumption and continue.

Do not use or inspect the original the-urlist/blazor-static-web-apps repository.

2. Required stack

Use:

• Next.js with the App Router
• React through Next.js
• TypeScript with strict type checking
• Node.js
• npm
• SQLite
• Direct SQL through better-sqlite3
• Vitest for unit and integration tests
• Playwright for browser end-to-end tests

Do not use:

• An ORM
• A real OAuth provider
• A cloud database
• A required paid service
• A second application framework
• Static fixture metadata in place of the required live HTTP fetch

Use current stable, non-prerelease package versions when the project is created. Commit package-lock.json. The lock file is the version record for the run.

3. Repository and application setup

The model starts from a repository that contains benchmark documents and minimal repository metadata. It must scaffold the application.

The completed repository must:

• Run as one Next.js application.
• Use the Next.js App Router.
• Keep application source, tests, SQL, and documentation in clear locations.
• Include all required configuration.
• Include .env.example with safe example values.
• Exclude runtime database files, secrets, build output, and installed dependencies from Git.
• Include a README that satisfies PRD section 19.2.

The model can choose the source directory layout. A src/ directory is recommended but not required.

4. Next.js requirements

4.1 Router

Use App Router pages and route handlers.

The route design must support:

• Static application routes such as /s/new and /s/mylists
• Reloadable edit routes with multi-segment aliases
• Root-level public aliases with one or more segments
• Exact alias lookup, including independent prefix-related aliases
• Reserved application paths

Use a catch-all route only where it does not intercept required static routes. Normalize and validate aliases in application code. Do not rely on filesystem routing as the only alias validation.

4.2 Server runtime

Code that uses better-sqlite3, the file system, server sessions, or metadata retrieval must run in the Node.js runtime. It must not use the Edge runtime.

Do not expose the SQLite database or direct SQL helpers to client bundles.

4.3 Rendering and caching

The implementation can use server components, client components, route handlers, and server actions.

It must prevent stale product behavior:

• A published list must become visible after publication.
• Saved edits must appear on the public page.
• A deleted list must show its tombstone.
• A restored list must become active.
• My Lists must show current persistent data.

Use dynamic rendering, explicit cache invalidation, or another correct Next.js mechanism. Do not depend on a process restart to refresh data.

4.4 Mutations

All product mutations must cross a server authorization boundary. A client component must not write directly to SQLite.

Server actions and route handlers are both permitted. The server must repeat validation and authorization.

5. TypeScript requirements

Enable strict mode.

The implementation must:

• Avoid any unless an external untyped boundary makes it necessary.
• Validate untrusted runtime input.
• Use shared domain types or schemas where useful.
• Model list ownership and list state explicitly.
• Model metadata state explicitly.
• Keep nullable and optional values intentional.
• Avoid unsafe type assertions that bypass validation.

The model can select a small runtime validation library or implement focused validation without one.

6. SQLite requirements

6.1 Driver and SQL

Use better-sqlite3.

Use direct parameterized SQL. Do not use Prisma, Drizzle, Sequelize, TypeORM, or another ORM.

6.2 Schema management

Provide one of:

• Ordered SQL migration files and a migration runner
• An idempotent schema initializer with a schema-version table

The process must be repeatable on an empty database and an existing database.

The database must enforce important invariants where practical. These include:

• Unique normalized alias
• Stable list identity
• Explicit ownership type
• Nullable owner only for anonymous ownership
• Active or deleted state
• Stable ordered links
• Foreign-key relationships

Enable SQLite foreign keys for every connection.

Use transactions for multi-row publication, save, delete, restore, and reset operations.

6.3 Database path

Use a documented environment variable for the database path. Provide a safe local default in development.

The database file must:

• Persist across normal application restarts.
• Be outside generated build output.
• Be excluded from Git.
• Be replaceable with a temporary path during tests.

6.4 Concurrency and uniqueness

Use a database uniqueness constraint as the final alias collision control. A preflight availability check is not sufficient.

Handle a uniqueness conflict as a normal product error. Do not overwrite an existing list.

7. Mock authentication requirements

Implement the two mock GitHub users in the application.

Use a server-verifiable session, such as a signed or opaque HTTP-only cookie. Do not trust a client-provided user ID without server verification.

The implementation must:

• Keep the two users stable across reset.
• List user A first and user B second.
• Use the accessible control name required by the PRD.
• Persist login across page reload.
• End the session on logout.
• Keep authorization checks on the server.

Do not call GitHub or implement OAuth.

8. Live metadata requirements

Fetch metadata on the server. Do not fetch and parse arbitrary destinations only in the browser.

The implementation must meet all PRD extraction, timeout, redirect, and SSRF rules.

Structure the code so these concerns can be tested separately:

• URL validation
• DNS and network-address policy
• Redirect policy
• HTTP request limits
• HTML parsing
• Metadata precedence
• Relative URL resolution
• Safe error mapping

Tests can mock lower-level network boundaries for unit and integration coverage. Product operation and scored metadata scenarios must use live HTTP.

9. Required npm scripts

package.json must provide:

Script	Purpose
dev	Start the local development application.
build	Create a production build.
start	Start the production build.
lint	Run the configured linter.
typecheck	Run TypeScript without emitting build output.
test	Run Vitest once in non-watch mode.
test:e2e	Run Playwright tests once.
db:init	Initialize or migrate the configured SQLite database.
db:reset	Reset development or test data safely.

The model can add scripts.

Scripts must return a nonzero status on failure. Test scripts must not start in watch mode.

10. Test requirements

10.1 Vitest

Use Vitest for focused tests of:

• URL and alias validation
• Alias normalization
• Metadata precedence and relative URL handling
• SSRF address policy
• Ownership and mutation rules
• SQLite repository behavior
• Publication, delete, and restore transactions
• Share URL construction

Use a temporary SQLite database for tests. Tests must not alter the normal development database.

10.2 Playwright

Use Playwright for core browser journeys:

• Anonymous draft and publication
• Mock login and logout
• Account publication and My Lists
• Owner edit, delete, tombstone, and restore
• Non-owner control isolation
• Public link and QR views
• Theme persistence
• Keyboard operation
• Mobile-width layout

The repository test suite does not have to duplicate every hidden evaluator case. It must cover the connected product lifecycle.

10.3 Test isolation

Tests must:

• Use a separate database.
• Reset deterministic state.
• Avoid order dependence.
• Clean up processes they start.
• Make live-network tests identifiable.
• Avoid requiring private credentials.

11. Code quality and security

The implementation must:

• Use parameterized SQL.
• Centralize repeated validation and authorization.
• Escape user and remote content.
• Keep secrets and database files out of Git.
• Use explicit errors. Do not silently convert failures into success.
• Apply CSRF protection appropriate to the chosen mutation design.
• Keep test reset controls unavailable in production mode.
• Follow the PRD's SSRF requirements.

Do not weaken a product rule to make a test easier.

12. Required documentation

The README must include:

• Prerequisites and supported Node.js version
• Install command
• Environment setup
• Database initialization
• Development startup
• Production build and startup
• Unit and integration tests
• Browser tests
• Mock user selection
• Test reset
• Database persistence location
• Live metadata behavior
• Troubleshooting

Document all assumptions that the PRD and profile do not decide.

13. Technical completion checklist

Before declaring completion, the model must:

1. Install from the committed lock file.
2. Initialize a clean database.
3. Run lint.
4. Run strict type checking.
5. Run Vitest.
6. Run Playwright.
7. Create a production build.
8. Start the production build and confirm the home page responds.
9. Check that published and deleted data survives restart.
10. Re-read the PRD and this profile.
11. Audit all acceptance categories A through G.
12. Report commands and results accurately.

Passing the repository's own tests does not replace the PRD acceptance requirements.