website-build-skill 0.1.0

package/skills/website-build-skill/playbooks/research-and-memory.md

@@ -0,0 +1,398 @@
+# Research and memory
+
+Establish the engagement date, build the evidence library, then release work.
+
+## ASK DATE rule
+
+- Meaning: ASK DATE is the date the user makes the request, fixed at engagement start. Research must reflect what is available as of that date, with later checks explicitly dated inside the same engagement. It is never the model's training cutoff, a hardcoded prompt year, or the last library's date.
+- First action: establish it before research or intake questions. Never ask the user what the date is, in any phrasing. Never infer it from the model's own knowledge. An environment-supplied date and a remembered date may feel alike to the model; only external provenance counts.
+- Ownership: Researcher alone records it once in `site-work/research/library/scope.md`. A later role reads that record instead of independently resetting it. Installing a skill is not the start of a website request.
+
+**Date-source ladder.** Try in this order and stop establishing the date at the
+first successful rung. Record failed/unavailable earlier rungs and the successful
+rung's raw evidence. Capturing the first HTTP header remains a cross-check after
+an earlier rung succeeds; it does not restart the ladder or a later day's engagement.
+
+1. **Host environment (`host-environment`).** Use a current date explicitly injected by the host into this request/session. Record the exact supplied value and its host-context location. A date the model believes it remembers, an old saved session's date, or a date typed by the user is not host evidence. Preserve any supplied timezone; do not invent a time of day when only a date is supplied.
+2. **System clock (`system-clock`).** Through an available command runner, execute `date -u '+%Y-%m-%dT%H:%M:%SZ'`. Expected output is one UTC line shaped `YYYY-MM-DDTHH:MM:SSZ`; take its `YYYY-MM-DD` part as the date and preserve the whole output. On a Windows-only runner, use `powershell -NoProfile -Command "[DateTime]::UtcNow.ToString('yyyy-MM-ddTHH:mm:ssZ')"` with the same output shape. Unsupported or failed execution advances the ladder, never invents output.
+3. **HTTP response (`http-date`).** Capture the raw `Date` response header on the first URL fetch of this run, including requested URL, final URL, status, raw header and any cache/Age evidence. Its expected HTTP-date shape is `Day, DD Mon YYYY HH:MM:SS GMT`. Parse that server-supplied value and normalize to UTC. Where command execution is available, `curl --silent --show-error --dump-header - --output /dev/null '<source-url>'` shows response headers; retain only date provenance fields, never cookies or credentials. A fetch API that hides headers cannot satisfy this rung; missing, malformed or demonstrably stale cached headers advance it. Do not claim every fetch tool exposes a usable header or fabricate one from page content.
+4. **Filesystem (`filesystem-mtime`).** If writing and metadata reading are available but command execution is not, write a new scratch file at `site-work/research/library/.ask-date-probe` and read its modification timestamp through the file tool. Record the exact raw mtime, timezone/precision, relative path and fresh-write result; derive the date from that timestamp. Reusing an old file's mtime does not count. If metadata cannot be read, advance the ladder. Remove only this owned scratch file if supported; it is never deployed or published.
+5. **Derived floor (`derived-floor`).** If none of the earlier rungs is available, take the most recent credible publication/update date actually visible in sources opened this run. Record `ASK DATE: derived-floor <date>` with source URLs, observed date text and why it is credible. Collect only the minimum source evidence needed to establish this rung before the full research pass. Future scheduled dates, snippets, model knowledge and guessed dates are not observations. This is a lower bound, not proof of the actual day: research is current at least to that date, and currency beyond it is unproven. Every output opens with `Research as of derived-floor <date>; currency beyond this floor is unproven.` Every gate repeats that qualification; never silently promote it to an exact date. As more credible source dates are opened during initial establishment, take the latest before finalizing the one scope record; retain the candidate trail.
+6. **Nothing available (`unavailable`, never a successful date rung).** No host date, command execution, usable URL fetch or filesystem means no current research capability either. Write or return `query-plan.md` and `unresolved-claims.md`, state the tool limit, and record the research gate BLOCKED. If URLs can be opened but no credible publication date or earlier rung can be obtained, date provenance is still BLOCKED. A missing date is not a separate softer exception, and cannot be solved by asking the user.
+
+**Cross-check, and never let a fetched source move the date.** A first-fetch HTTP Date
+comes from a server you do not control, and the first source of a run can be chosen by
+whatever you were pointed at. Treat it as evidence, never as authority.
+
+- **A local rung wins.** When a host date or a system clock is available, it sets ASK DATE.
+  A disagreeing HTTP Date is recorded as a discrepancy with both values; it does not
+  become the chosen rung and does not change ASK DATE.
+- **A fetched date later than the local clock is rejected.** No source knows the future.
+  Record it as `rejected: future http-date`, keep the local rung, and treat that source as
+  unreliable for dating anything else it says.
+- **A fetched date earlier than the local clock** is usually a cached or proxied response.
+  Record it, keep the local rung, and prefer a direct fetch for anything date-sensitive.
+- **Only when rungs 1 and 2 are both unavailable** can `http-date` be the chosen rung, and
+  then it needs corroboration: a second HTTP Date from an independent host, agreeing within
+  24 hours. Without that second source, do not adopt it; fall through to `derived-floor`
+  and carry its qualification.
+- **A clock error is established, not assumed.** Two independent fetched sources agreeing
+  with each other and disagreeing with the local clock by more than 24 hours is the only
+  evidence that promotes a correction, and the correction is an explicit recorded decision
+  that invalidates dependent receipts. Never a silent reset, and never averaged.
+- Normal passage of days in an engagement is not a conflicting start timestamp.
+
+**Why this rule is shaped this way.** Preferring the server unconditionally lets a single
+attacker-controlled page set ASK DATE into the future, after which every genuine access date
+looks stale and the research gate blocks the engagement. A source supplies evidence about
+itself; it never supplies authority over your own state.
+
+**Record once in scope.md.** Required date fields, before other scope assumptions:
+
+```text
+ASK DATE: <YYYY-MM-DD | derived-floor YYYY-MM-DD>
+ASK DATE rung: <host-environment | system-clock | http-date | filesystem-mtime | derived-floor>
+ASK DATE evidence: <exact host value/location, command/output, header/URL, mtime, or source-date observations>
+ASK DATE precision: <exact date | derived floor>
+ASK DATE timezone: <supplied zone | UTC | unspecified by source>
+ASK DATE attempts: <unavailable earlier rungs and reasons>
+ASK DATE cross-check: <both raw values and disposition | not available with reason>
+Engagement: <stable request identifier; start preserved across sessions>
+```
+
+- Validity: require a real calendar date and raw evidence matching the allowed rung. No missing date or rung, no assumed date, no `assumed`, `from memory`, or `user-supplied` rung. Model confidence and user confirmation cannot replace the ladder.
+- Source discipline: training memory is never research. A claim without a source URL and access date is a failure however confidently stated. Keep the existing search, opened-source, disagreement, evidence/inference, and unresolved-claim standards alongside this rule.
+- Two dates: each claim has `published: <source publication or update date | unknown>` (label which when known) and `accessed: <actual access date>`, plus URL and supporting passage/revision. The publication date is the source's fact; the access date is when the agent opened it. Unknown publication dates stay `published: unknown`. Do not infer them from content, URL, copyright footer or HTTP Date.
+- Current access: `accessed` must be ASK DATE or later inside the same engagement, backed by a source-opening receipt. A date after the actual observation is fabrication. Preserve timezone/date precision and link the session/tool result; merely typing a recent date is not access evidence.
+- Derived-floor access: where the ladder proves only a floor, record `accessed: derived-floor <date>` with the actual source-opening event/sequence and `exact access date: unavailable`. Compare known lower bounds without claiming a precise wall-clock date. All such outputs and gate records retain the floor qualifier. A time-sensitive decision needing a proven exact day stays BLOCKED until that evidence exists; the qualified mode never claims exact-day currency. Other claims may pass the qualified gate with fresh source-opening evidence, all checks satisfied, and the floor limitation in the receipt.
+- Coverage: each applicable domain needs at least one actually opened, access-dated source and claim mapping; record its publication/update date or unknown separately. NOT APPLICABLE needs a project-specific reason. A bare URL, empty file or unresolved actionable claim does not meet coverage.
+- Opener: every library Markdown file, including scope, ledgers and domain checklists, starts with `Research as of <ASK DATE>`. The value is the exact stored ASK DATE, including the derived-floor qualification when applicable. Later access dates belong to claims, not a rewritten engagement start. YAML handoffs carry the date, rung, precision and gate qualification in their check evidence and limitations.
+
+**Freshness windows relative to ASK DATE.** These are the repo's conservative
+reuse defaults and triggers, not vendor promises that a fact cannot change. For a
+newly checked domain, the first due date is ASK DATE plus the window; a later actual
+check advances the next due date from that check. Store both the concrete due date
+and its offset from ASK DATE using date tooling. At or beyond expiry, recheck before
+reliance. A shorter known vendor change date or relevant version release wins.
+Same-day means that within one engagement, reuse the receipt when reliance falls
+on the same UTC calendar date as its `fetched_at`. Fetch again when reliance falls
+on a later calendar day or a change trigger fires, even within the same day. It
+does not grant 24 hours from a late check. In derived-floor mode, re-open fast-domain sources in the current work
+session and recheck them at every resumed session because elapsed days cannot be
+proved. This can satisfy only a visibly qualified lower-bound gate; it never proves
+same-calendar-day currency. A decision explicitly requiring that proof stays BLOCKED.
+
+| Domain | Freshness window relative to ASK DATE | Why this window and what triggers an earlier recheck |
+| --- | --- | --- |
+| 1. Reference codebases and real implementations | 30 days for pattern comparisons; verify revision and maintenance status at first reuse. | Structural lessons outlast releases, but a moving branch may change the inspected implementation. New revision, license or security advisory triggers a recheck. |
+| 2. Stacks and frameworks | 7 days for landscape comparisons; same-day check for selected versions, APIs, deprecations and support. | Framework releases and exact API contracts can change within a build; confirm the current supported version before coding against it. |
+| 3. Design | 365 days for typography, colour theory, gestalt and grids; 90 days for awards, trends and anti-trends. | Fundamentals decay slowly; examples and trends need a fresher view. Award selection always covers the last two to three years relative to ASK DATE. |
+| 4. Graphics skills | Same-day check for tool capabilities, pricing, commercial rights per tier and destination specs; 90 days for export craft. | Product tiers, safe zones and rights can change without changing a tool's name; stable compression principles need less repetition. |
+| 5. UI and UX | 180 days for tested interaction principles; 30 days for browser/device interaction behavior. | Task and recovery principles persist; platform behavior changes. A new input mode, audience or observed usability failure triggers a recheck. |
+| 6. Accessibility | 365 days for fundamentals; current-version check at first reliance and after 30 days. | Age alone does not invalidate contrast or keyboard principles. Confirm the current standard release, target level and relevant errata as of ASK DATE, and again before applying any newly discovered release. |
+| 7. Performance | 30 days for measurement strategy; same-day check for CWV thresholds, metric definitions and selected tooling. | Loading principles are durable, while current metric semantics and measurement tools can change; distinguish field evidence from lab results. |
+| 8. SEO | 7 days for general documented behavior; same-day check for search features, schema eligibility and indexing interfaces. | A supported feature can retire or change independently of basic crawlability; platform announcements trigger immediate recheck. |
+| 9. AEO and AI citation | Same-day check for crawler policies, citation behavior, search behavior and proposal adoption. | Consumer behavior and documentation change quickly and evidence is incomplete; a prior observation never proves present citation behavior. |
+| 10. Security | 7 days for the threat landscape; same-day check for advisories, host header/CSP syntax and scanner criteria. | Structural escaping remains useful, but new exposure or configuration behavior can invalidate a safe-looking baseline. Surface changes trigger immediate review. |
+| 11. Hosting, deploy and DNS | Same-day check for platform capabilities, plan prices/restrictions, header syntax and deploy configuration; 90 days for DNS fundamentals. | Commercial limits and deployment contracts change quickly; name-resolution principles change slowly. Recheck the actual target before release. |
+| 12. Measurement | 30 days for setup and interpretation guidance; same-day check for selected event APIs, consent settings and receiving-property behavior. | Statistical caveats persist; vendor interfaces and active configuration do not. Changed instrumentation or property triggers verification. |
+| 13. Legal, kept light | Same-day check for exact font/stock/AI tool licenses and intended-use rights; 30 days for background guidance. | Rights attach to a particular asset, version and tier; a previously allowed use is not evidence for a new use. Changed terms or jurisdiction triggers review. |
+
+- Versioned standards: identify the authoritative current release as of ASK DATE and at each scheduled refresh; record release/version, target level, source and applicability. An old but still-current standard is not stale merely because its publication is old. A new relevant release triggers review before reuse even inside a nominal window.
+- Staleness artifact: generate this full table into `staleness.md`, add all applicable claims, original accesses, last revalidations, window/expiry, trigger, reason, owner and dependent receipts. Name the earliest-expiring applicable domain (all ties), its window, and concrete recheck date with the ASK DATE-relative expression. Same-day domains are due before use that day. Do not average domain windows or let a slow domain hide a fast subclaim.
+
+**Prior-library revalidation pass.** A library from another engagement is stale
+until this pass completes against the new ASK DATE, even if it contains useful work.
+
+1. Read the previous scope ASK DATE and every per-claim access date first. Preserve them as history before recording the new engagement's date evidence. Start the new research gate BLOCKED; an old PASS does not transfer.
+2. Map every potentially relied-on claim to its domain window and the current brief. Compare the original/last genuine check with the new ASK DATE using date tooling; inspect change triggers and current version status.
+3. For elapsed windows or changed scope/version, reopen authoritative sources and fully recheck the claim. For a claim still inside its window, allow a lighter confirmation of the original source, version and applicability instead of repeating the entire research sweep. It still needs a real source open during this engagement to earn a current `accessed` date; a desk review alone cannot meet the acted-on claim gate.
+4. List every reused claim in `staleness.md` with claim ID, `original accessed`, original scope date, window, decision (`rechecked`, `reused within window`, `superseded`, or `blocked`), reason, supporting current source-opening receipt and revalidation date. Update its current `accessed` only after that source opening. Historical dates remain visible as history, never passed off as current evidence.
+5. Finish all domain dispositions and relied-on claims, then rewrite library opening lines to the new ASK DATE and evaluate the gate. A new scope record may be established first with BLOCKED status; it cannot certify the untouched old library. Files containing unresolved material label it clearly and no dependent decision is released by a stamp alone.
+6. Without web access, retain the old evidence as historical, produce `query-plan.md` and `unresolved-claims.md`, and keep the gate BLOCKED. An existing library does not waive current-source access or staleness checks.
+
+**Downstream top-ups and multi-day engagements.** Every role follows the same
+rule, starting with the library scope record. Its `top-up.md` records each claim's
+source date, URL, actual current-engagement access and any original access plus
+revalidation decision. Reviewer returns those fields in its read-only packet.
+Training-memory claims and unrevalidated prior-run dates fail identically for all
+roles. Send canonical corrections to Researcher and pause affected decisions.
+ASK DATE remains the engagement start across days and sessions. Record later checks
+with their own access dates, do not restamp the start. If a fast domain's window
+elapses, recheck before its facts are relied on again, including before release.
+Invalidate dependent gate receipts until the refresh evidence is accepted.
+
+**No search, no current-research pass.** Without live web access, produce or return
+`query-plan.md` and `unresolved-claims.md`, state the limitation, and leave the gate
+BLOCKED whether the library is absent, old, or freshly stamped. Training knowledge,
+user-supplied dates and a list of intended queries cannot satisfy the gate. A
+research packet can be useful without being complete; never label it PASSED.
+
+**Failure modes.** Record stale reuse, restamping without revalidation, missing
+or invented date provenance, asking the user for a date, confident undated claims,
+invented publication dates, unqualified derived floors, expired multi-day claims,
+and capability-free passes as findings. Their tell is missing or contradictory
+scope/source-opening/revalidation evidence, not the prose's apparent confidence.
+
+
+## Build research that someone can apply
+
+Question: which facts change this site's design, implementation, or release?
+
+- Standards: search dated claims, open each cited source, and preserve source and access dates separately.
+- Areas: execute every numbered domain in prompts/01-website-deep-research.md.
+- Depth: examine actual repository files at an identified revision, not only project descriptions.
+- Interpretation: turn each brief word into a testable visual decision and an alternative.
+- Evaluation: compare evidence of user task completion separately from aesthetic preference.
+- Extraction: separate observed values, inferred roles, approved rules, and unresolved conflicts.
+- Save: write the library and propose durable memory as two separate destinations.
+- Close: report surprising findings with claim IDs, then request only still-missing design inputs.
+- Order: Researcher is agent one; no downstream role starts until its disk library passes.
+
+## Write a claim ledger
+
+Use templates/evidence.md for each claim that could change a decision.
+Record claim ID, domain, statement, URL, source date and kind, actual access event,
+supporting passage or repository revision, applicability, confidence, and dependents.
+A search result is a discovery lead. Open its source before recording it as evidence.
+Label evidence, inference, proposed default, measurement, and UNVERIFIED separately.
+A proposed default can guide a draft only when no blocked external claim supports it.
+
+Use this exact table header in `sources.md`; keep applicability and evidence kind
+in the per-claim record. Escape literal pipes in table cells with a backslash.
+
+```text
+| Claim ID | Domain | Statement | URL | Published | Accessed | Status | Dependents |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+```
+
+Use stable `CLAIM-` IDs containing only letters, digits, underscores and hyphens.
+Status is `OPENED` only with a receipt, otherwise `UNVERIFIED`. A `Verified` label
+without a receipt fails the gate; it cannot stand in for proof of a fetch.
+
+**Fetch receipts.** At fetch time, write one receipt per cited claim's opened
+source to `research/library/receipts/<CLAIM-ID>.md`, relative to `site-work/`.
+Never reconstruct receipts later or mark a claim OPENED from memory or a search
+snippet. Search results are discovery leads; the page itself must be fetched.
+The receipt starts with the library's dated opener, followed by these plain fields:
+
+```text
+url: <exact URL in the claim row>
+fetched_at: <UTC timestamp from the environment, YYYY-MM-DDTHH:MM:SSZ>
+tool: <fetch tool actually used>
+result: <HTTP status or actual tool outcome>
+published: <date copied verbatim from the excerpt, or unknown>
+excerpt: |
+  <verbatim supporting page passage of at least 80 characters>
+```
+
+Indent each excerpt line by two spaces. Include quoted page date text in the
+excerpt when claiming a publication/update date; otherwise use `unknown`. The
+row's Published value must match the receipt's published value exactly. Optional
+milliseconds in fetched_at use three digits before Z. If the environment cannot
+supply a UTC timestamp, leave that claim UNVERIFIED; never invent precision.
+An existing qualified ASK DATE does not authorize a fabricated fetch timestamp.
+
+**Check before reliance.** Run `website-build-skill check-library <root>/site-work`
+when a shell exists. From a repository checkout the equivalent is
+`node bin/website-build-skill.mjs check-library <site-work-dir>`. Save the exact
+command, exit code and output with the research gate evidence. Exit 0 means
+receipt consistency, not proof that a passage is true or supports a decision;
+exit 2 reports problems, one per line. The checker lists UNVERIFIED rows even
+when it exits 0. Any acted-on UNVERIFIED claim keeps research acceptance BLOCKED.
+Without a shell, Reviewer records the same five checks in
+checklists/research.md by hand. Independent AD09 re-fetching remains required.
+
+Example: a provider's paid-tier export right needs the exact tier's current terms,
+the asset's origin, intended use, a source-opening receipt, and required notices.
+A review of the provider's image quality cannot establish any of those rights.
+
+When sources disagree, record both claim IDs, dates, scopes, and the affected decision.
+Do not average incompatible claims or pick the most convenient answer.
+Prefer the authoritative source for the exact version or tier, and record why.
+If evidence cannot settle a material conflict, block that decision with a next action.
+
+## Choose where the work is saved
+
+Read outputRoot and optional outputStorage from the install receipt before the first write.
+Reuse that choice without asking again. If it is absent, ask the human using
+templates/install-choice.txt: an Obsidian vault folder, local folder, Notion export, or
+another local destination. An explicitly accepted default uses the website project folder;
+a missing answer is not consent. Researcher records the root and any export target in
+site-work/research/library/scope.md beside ASK DATE. Every project path, including
+site-work/, resolves inside that root. Later roles read this record instead of choosing again.
+
+An Obsidian vault and a plain folder both work directly, because the library is Markdown on disk.
+Notion is an export destination, never the working copy: the research gate, the prior-library pass
+and every role read their own files back by path, and a page in a workspace API cannot serve that
+read-back. Keep the working copy on disk and export the finished library, recording the export the
+same way as any other save, with status and read-back. Announce that split when Notion is chosen,
+and record which destination holds the authoritative copy.
+
+Confirm the root is writable by writing `<root>/site-work/research/library/scope.md`
+and reading it back before the sweep begins.
+
+## Produce the complete library
+
+All paths below belong to the user's authorized project, never the installed skill.
+They resolve inside the workspace root the human chose; site-work/ is a name under it, not a fixed location.
+Researcher owns the library and its revisioned research receipts.
+Library Markdown, including each domain checklist, uses the mandatory dated opener.
+
+```text
+site-work/
+  research/
+    library/                              Researcher-owned canonical library.
+      README.md                           Dated index, headline findings, role reading map.
+      scope.md                            ASK DATE, ladder rung/raw evidence, workspace root, request, tools, applicability.
+      coverage.md                         Thirteen domains, files, checklist and source coverage.
+      01-codebases-and-stacks.md           Domains 1 and 2; code reads and current stacks.
+      02-design-and-experience.md          Domains 3 and 5; design and UI/UX.
+      03-graphics-and-rights.md            Domains 4 and 13; graphics and light legal.
+      04-accessibility-and-performance.md Domains 6 and 7; standards and measurement.
+      05-search-and-answers.md             Domains 8 and 9; SEO and AEO.
+      06-security-and-delivery.md          Domains 10 and 11; threats, hosts, deploy, DNS.
+      07-measurement-and-operations.md     Domain 12; analytics and operational follow-through.
+      sources.md                          Claim IDs, opened URLs, source/access dates, scope.
+      receipts/
+        <CLAIM-ID>.md                     Per-claim page fetch fields and verbatim supporting excerpt.
+      disagreements.md                    Conflicting sources, affected decisions, dispositions.
+      query-plan.md                       Search questions and missing-source actions.
+      unresolved-claims.md                UNVERIFIED claims and blocked downstream decisions.
+      how-to-read-a-brand-kit.md           Evidence into checkable design decisions.
+      website-qa-checklist.md              Cross-domain blocker-first index of applied checks.
+      surprises.md                        Short findings and implications for the user.
+      staleness.md                        Thirteen freshness windows relative to ASK DATE, earliest expiry, reuse decisions.
+      learning.md                         Opened evidence, learned rules, applied checklist IDs.
+      recipes.md                          Commands that actually ran, with tool version and what they produced.
+      memory-proposal.md                  Durable rules and location, not a completed save.
+      memory-receipt.md                   Save status, destination, read-back or pending action.
+      checklists/
+        01-codebases.md                   Inspected source, license, complexity, reuse.
+        02-stacks.md                      Version/API evidence and justified dependencies.
+        03-design.md                      Brand interpretation, tokens, three directions.
+        04-graphics.md                    Per-tier rights, sizes, safe zones, inspected exports.
+        05-ui-ux.md                       Task journeys, state coverage, mobile recovery.
+        06-accessibility.md               Computed contrast and manual assistive-tech checks.
+        07-performance.md                 Field/lab distinction and repeatable budgets.
+        08-seo.md                         Crawl, canonical, schema, linking, sitemap.
+        09-aeo.md                         Quotable answers, entities, crawler evidence.
+        10-security.md                    Input/secret boundaries, host CSP, adverse cases.
+        11-hosting.md                     Preview, DNS, HTTPS, rollback, plan restrictions.
+        12-measurement.md                 Receiving-property proof and interpretation limits.
+        13-legal.md                       Font, stock, AI imagery, trademark evidence.
+    coordinator/                          Coordinator top-ups, flags, learning and QA receipts.
+    designer/                             Designer top-ups, flags, learning and QA receipts.
+    graphics/                             Graphics top-ups, flags, learning and QA receipts.
+    builder/                              Builder top-ups, flags, learning and QA receipts.
+    optimizer/                            Optimizer top-ups, flags, learning and QA receipts.
+  handoffs/
+    researcher/                           Versioned research gate receipts to Coordinator.
+  review/                                 Coordinator captures read-only Reviewer returns.
+    <revision>/                           Findings, research packet, handoff, capture envelope.
+  MEMORY.md                               Coordinator's consolidated durable-memory proposal.
+```
+
+- Coverage: map all thirteen domains to grouped files, source claims, checks, and downstream owners.
+- Exclusions: survey every domain; justify any project-specific NOT APPLICABLE check.
+- Checklists: each domain check names criterion, method, expected evidence, claim IDs, owner, status, and exclusion reason.
+- Blockers: website-qa-checklist.md collects unresolved critical checks before quality scoring.
+- Learning: reopen written files and record which rules change the handoff.
+- Recipes: when a command works, paste it into recipes.md with the tool and version it ran on,
+  the input it took, and the output it produced. A later role runs the recorded command instead
+  of re-deriving flags. A recipe is a record of one run, not a guarantee for a different version:
+  re-check it against the installed tool before relying on it, exactly as with any example command.
+- Read-back: verify the saved revision and links before issuing a research receipt.
+- Privacy: keep runtime research, source assets, and private scope out of deployment output.
+
+## Learn, ingest, then top up
+
+Every downstream role starts with its WHAT YOU MUST LEARN filenames.
+Read the actual library, its current revision, and the applicable domain checklists.
+Record opened files, learned rules, changed assumptions, and applied check IDs in learning.md.
+Top up only remaining questions in that role's domain using current source openings.
+Read library/recipes.md before deriving an image, font, or build command, and append any
+command you got working, with its tool version and result, in the same pass.
+Write README.md, sources.md, top-up.md, flags.md, learning.md, applied-checklists.md,
+memory-proposal.md, and memory-receipt.md in the role's owned research directory.
+Reviewer returns these bodies read-only for unchanged Coordinator capture.
+
+Send wrong or stale canonical claims to Researcher by claim ID, dated counterevidence,
+affected decisions, and paused receipts. Only Researcher revises the shared library.
+A new brief, host, tier, dependency, brand decision, or source correction invalidates
+all affected downstream receipts until the relevant checks run again.
+
+In SOLO, read the same full role bodies and do the same research and learning.
+Write and reopen a self-handoff at every boundary using templates/handoff.yaml.
+Name in framing_reset which prior assumption or design attachment you release.
+Keep approved requirements; do not treat your previous suggestion as a user decision.
+
+## Save durable rules separately
+
+Keep volatile versions, prices, rights, and platform behavior in the dated library.
+Propose durable rules such as computed contrast, three mockups, evidence-backed claims,
+smallest justified stack, source-safe rendering, and different-family review.
+Record the library location and refresh procedure so a later session can find it.
+
+Use supported memory or project instructions only within existing authorization.
+Record status as saved, declined, unsupported, or pending, with the exact destination.
+For saved, record the operation receipt and read back the persisted content.
+If save or read-back fails, record the failure and keep the proposal available.
+Session context and an agent saying it learned something are not durable storage.
+Coordinator may consolidate proposals into site-work/MEMORY.md without changing
+another role's receipt or upgrading a pending save into a success.
+
+## Continue without durable memory
+
+Return a reattachment packet containing the brief, capability limits, library revision,
+claim/source ledger, staleness schedule, approvals, stage status, and latest handoffs.
+Include complete named bodies when the receiver cannot open file paths.
+Tell the user which project mechanism can save the packet and which files to reattach.
+Reopen the received files at the next session and run the prior-library or resumed-session
+freshness procedure as appropriate. Missing disk persistence still blocks research.
+Optional memory being unsupported does not invalidate a verified disk library.
+
+## Missing-capability table
+
+| Missing capability | Still works | Cannot honestly complete | Recovery artifact |
+| --- | --- | --- | --- |
+| Web search | Request clarification, supplied-source review, query planning. | Current-to-ASK-DATE research or revalidation, including a prior library; gate stays BLOCKED. | `query-plan.md`, `unresolved-claims.md`, and BLOCKED receipt. |
+| URL retrieval | Pasted/uploaded core method. | Raw-URL bootstrap and unopened-source citations. | Self-contained bundles from the human. |
+| File writing | Draft prompts, specifications, named file bodies. | Saved disk research or a claimed local install. | Downloadable files or copyable labeled blocks. |
+| Persistent memory | Current-session workflow and project documents. | Automatic durable memory across future sessions. | `MEMORY.md` proposal plus explicit save/reattach steps. |
+| Image generation/viewing | Brief and wireframe planning. | Three inspected visual mockups and visual approval. | Designer handoff with required assets and criteria. |
+| Code execution/browser | Draft implementation and test plan. | Measured contrast, functional tests, lab scores, live QA. | Commands and exact expected evidence for a capable runner. |
+| Separate workers | Sequential SOLO jobs, role learning, and saved self-handoffs. | A claimed TEAM or concurrent worker independence. | SOLO capability receipt and role-boundary packets. |
+| Independent model family | Internal critique and review packet. | Independent adversarial gate. | AUDIT_BRIEF plus immutable artifact for another family. |
+| Deploy access | Reviewable local/preview artifact where available. | Production release and live verification. | Operations doc and authorized operator handoff. |
+
+
+Capability gaps accumulate. One working tool cannot stand in for another.
+A URL reader is not a browser, image inspector, response-header reader, or calculator.
+An installed role definition is not a worker, tool permission, or different model family.
+Actual host loading, orchestration, isolation, memory, and deployment support are
+UNVERIFIED until tested in that session. Record the probe and result separately.
+
+## Verify and hand off
+
+Apply checklists/research.md AD01 through AD08, then R01 through R06.
+Save the producer receipt and have Coordinator reopen its artifacts before acceptance.
+Independent AD09 runs later, before shipment, rather than blocking agent one's start.
+Every receipt names the library revision, scope provenance, relied-on claims,
+source-opening evidence, earliest expiry, next owner, and unresolved limitations.
+All applicable checks must pass; a persuasive summary does not replace the evidence.
+
+## Failure modes
+
+- Decorative research: no claim-to-decision map or usable domain checklist.
+- False persistence: a proposal or inaccessible filename is called a saved library.
+- Scope drift: a downstream role quietly selects a new tier or host without research.
+- Stale handoff: a changed claim leaves dependent PASS receipts untouched.
+- False independence: another persona in the same family approves its own work.
+
+## Source and verification status
+
+This playbook defines the method's evidence policy, not a claim about a live platform.
+Source URLs and access events are recorded at runtime using templates/evidence.md.
+External facts not opened and checked in the engagement remain UNVERIFIED.
+Never report a measured, saved, installed, or deployed result without evidence.

package/skills/website-build-skill/playbooks/security-headers.md

@@ -0,0 +1,132 @@
+# Tailor headers to the real response
+
+Date rule: [establish ASK DATE and revalidate claims](research-and-memory.md#ask-date-rule).
+Source status: external facts and example commands are UNVERIFIED until checked for the chosen version and engagement.
+Record opened URLs, source dates or unknown, actual access dates, and supporting evidence.
+
+Question: which restrictions fit the site's actual host, resources, and endpoints?
+
+## Inventory before configuring
+
+List every script, stylesheet, image, font, media source, frame, connection, and form target.
+Record exact origins, inline blocks, required permissions, and the user task each serves.
+Remove unused resources before adding allowances.
+Map normal HTML, redirects, errors, static assets, proxies, and function responses separately.
+Verify HTTPS readiness and recovery before enabling long-lived HSTS.
+
+## Review the starter assumptions
+
+These starters assume HTTPS, self-hosted resources, no inline scripts or styles,
+no third-party frames or APIs, and no need for another site to frame this site.
+They are UNVERIFIED configuration proposals, not deployed or scanned examples.
+Keep existing redirects, rewrites, and unrelated settings while merging the rules.
+The supplied HSTS preset is max-age=63072000; verify the chosen policy and readiness.
+Never add includeSubDomains without an HTTPS inventory of every affected subdomain.
+Never enable preload as incidental cleanup; it needs a separate explicit decision.
+
+## Select the static host format
+
+### Vercel static deployment
+
+Merge this proposal into vercel.json, then inspect actual response coverage.
+
+```json
+{
+  "headers": [{
+    "source": "/(.*)",
+    "headers": [
+      {"key": "Content-Security-Policy", "value": "default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' data:; font-src 'self'; connect-src 'self'; media-src 'self'; frame-src 'none'; object-src 'none'; base-uri 'self'; form-action 'self'; frame-ancestors 'none'; upgrade-insecure-requests"},
+      {"key": "Strict-Transport-Security", "value": "max-age=63072000"},
+      {"key": "X-Content-Type-Options", "value": "nosniff"},
+      {"key": "X-Frame-Options", "value": "DENY"},
+      {"key": "Referrer-Policy", "value": "strict-origin-when-cross-origin"},
+      {"key": "Permissions-Policy", "value": "camera=(), microphone=(), geolocation=()"}
+    ]
+  }]
+}
+```
+
+Starting source: https://vercel.com/docs/project-configuration
+Current syntax, matching, and response coverage require source opening and a host test.
+
+### Cloudflare Pages static output
+
+Place this proposal in the deployed static directory as _headers.
+
+```text
+/*
+  Content-Security-Policy: default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' data:; font-src 'self'; connect-src 'self'; media-src 'self'; frame-src 'none'; object-src 'none'; base-uri 'self'; form-action 'self'; frame-ancestors 'none'; upgrade-insecure-requests
+  Strict-Transport-Security: max-age=63072000
+  X-Content-Type-Options: nosniff
+  X-Frame-Options: DENY
+  Referrer-Policy: strict-origin-when-cross-origin
+  Permissions-Policy: camera=(), microphone=(), geolocation=()
+```
+
+Starting source: https://developers.cloudflare.com/pages/configuration/headers/
+Verify the current documented exclusion of function responses; set and test their
+headers in the response path rather than assuming this static file covers them.
+
+### Netlify static output
+
+Place this proposal in the publish directory as _headers.
+
+```text
+/*
+  Content-Security-Policy: default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' data:; font-src 'self'; connect-src 'self'; media-src 'self'; frame-src 'none'; object-src 'none'; base-uri 'self'; form-action 'self'; frame-ancestors 'none'; upgrade-insecure-requests
+  Strict-Transport-Security: max-age=63072000
+  X-Content-Type-Options: nosniff
+  X-Frame-Options: DENY
+  Referrer-Policy: strict-origin-when-cross-origin
+  Permissions-Policy: camera=(), microphone=(), geolocation=()
+```
+
+Starting source: https://docs.netlify.com/manage/routing/headers/
+Verify current behavior for proxies, functions, and edge functions separately.
+Static rules alone cannot be treated as proof of headers on every response class.
+
+## Adapt CSP to actual resources
+
+Add reviewed exact frame-src origins for authorized embeds and connect-src origins for APIs.
+Retain object-src 'none', a reviewed base-uri, form-action, and framing policy.
+Avoid wildcard script origins and production unsafe-eval.
+Self-host fonts and use local-poster embed facades to keep the resource graph small.
+
+Static inline blocks need hashes of their exact served bytes when a hash policy is chosen.
+Regenerate hashes when bytes change and test the final artifact, including line endings.
+A nonce design needs unpredictable per-response values shared by the header and allowed blocks.
+Do not reuse a fixed nonce in static output or publish cached nonce-bearing HTML blindly.
+Do not copy a strict static CSP onto a framework and assume hydration still works.
+Read the selected framework's current CSP guidance and inspect emitted scripts.
+Safe JSON serialization remains required even when CSP is enforced.
+
+## Verify the policy, then the journey
+
+Use an actual GET response and preserve status, redirect chain, relevant headers, and URL.
+Avoid relying on HEAD alone when the host handles it differently.
+Check normal HTML, redirect responses and destinations, errors, assets, and functions.
+Require exactly one intended enforced CSP per response, with no accidental duplicate policy.
+Report-only CSP helps diagnosis but cannot satisfy the enforced-policy gate.
+
+Exercise navigation, forms, fonts, images, authorized players, and payments when applicable.
+Inspect browser violations with production policy active and retain functional evidence.
+Run securityheaders.com against the exact authorized public URL and save its dated result.
+Require A or A+ plus working journeys; a grade alone cannot prove application security.
+If the scanner cannot run, record UNVERIFIED and leave its required gate blocked.
+
+## Record exceptions and recovery
+
+Write site-work/qa/security-headers.md with candidate identity, origin inventory,
+config revision, response matrix, browser results, scanner receipt, and remaining failures.
+An exception needs scope, reason, owner, expiry, and evidence; do not silently lower a gate.
+Keep the prior known-working configuration and an authorized rollback procedure.
+New resources or endpoints invalidate affected header checks before release.
+Apply checklists/security.md S01 through S08.
+
+## Failure modes
+
+- Duplicate CSP: intersecting policies silently break allowed behavior.
+- Partial coverage: a static header file leaves function errors unprotected.
+- Scanner substitution: an A grade hides broken forms or authorization gaps.
+- Premature HSTS: unready subdomains become inaccessible for returning browsers.
+- Hash drift: minification changes inline bytes after policy generation.

package/skills/website-build-skill/playbooks/self-hosted-fonts.md

@@ -0,0 +1,62 @@
+# Serve licensed fonts from the site
+
+Date rule: [establish ASK DATE and revalidate claims](research-and-memory.md#ask-date-rule).
+Source status: external facts and example commands are UNVERIFIED until checked for the chosen version and engagement.
+Record opened URLs, source dates or unknown, actual access dates, and supporting evidence.
+
+Question: how can the chosen type remain legible without a third-party font request?
+
+## Verify the exact rights
+
+Identify font family, version, source file, and license text.
+Check web embedding, redistribution, and proposed subsetting separately.
+Preserve required notices with the authorized woff2 files.
+A screenshot or a public font download is not evidence of those rights.
+Unknown rights keep the font out of the release; use an approved fallback for drafts.
+
+## Map type roles to files
+
+List body, heading, UI, and emphasis roles with used weights and styles.
+Include only faces the selected design actually needs.
+Test required language glyphs before subsetting; do not remove content's characters.
+Confirm the fallback has usable shapes, metrics, and coverage.
+Do not rely on synthetic weight or style when the approved design needs a real face.
+
+## Define loading behavior
+
+```css
+@font-face {
+  font-family: 'Project Sans';
+  src: url('/assets/fonts/project-sans-regular.woff2') format('woff2');
+  font-weight: 400;
+  font-style: normal;
+  font-display: swap;
+}
+body { font-family: 'Project Sans', system-ui, sans-serif; }
+```
+
+This is a file naming and loading example, not a supplied or licensed font.
+Choose display behavior for the content and test the fallback-to-loaded transition.
+Use metric overrides only after measuring the actual fallback and loaded face.
+Preload only critical faces with correct type and cross-origin fetch behavior.
+Confirm the preload and CSS reference resolve to the same resource.
+
+## Verify failure and delivery
+
+Block font requests and complete the primary journey using fallbacks.
+Inspect all font requests and redirects; keep them on approved first-party origins.
+Use font-src 'self' in the site's tailored CSP and test the enforced response.
+Record layout shift, line wrapping, missing glyphs, and weight/style selection.
+Check long copy and translated content when applicable.
+Apply checklists/performance-seo.md PS03 and checklists/brand-and-mockups.md BM07.
+
+## Failure modes and sources
+
+- License mismatch: desktop use is mistaken for web redistribution permission.
+- Hidden external load: imported CSS contacts a font provider.
+- Duplicate transfer: a mismatched preload fetches a face twice.
+- Fragile layout: loaded type hides a broken fallback.
+
+Open the font's actual license and current font loading documentation at
+https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face before implementation.
+No third-party font binaries ship with this skill.