{"description":"Structured rationale contract for required why explanations, quality rules, anti-patterns, QA coverage, and stress tests.","objective":"Give a future agent enough structure to start from the main URL and understand how to inspect, plan, build, validate, and improve a serious website without needing prior chat context.","why_explanations":{"objective":"Require useful rationale wherever an agent could otherwise follow a broad objective without understanding the reason, evidence, tradeoff, or failure mode.","why":"This system is designed for agents that build websites. Agents need explicit reasoning scaffolds so they can continue work, stress test decisions, avoid bad examples, and adapt patterns without guessing.","requiredSurfaces":[{"id":"roadmap-items","surface":"/product-roadmap.json","requiredFields":["objective","why","valueMultiplier","objectiveAlignment"],"why":"Roadmap work should explain why each value multiplier matters and how it supports the system purpose."},{"id":"walkthrough-steps","surface":"/walkthroughs.json","requiredFields":["objective","why","steps.why","objectiveAlignment"],"why":"Step-by-step work needs rationale at the step level, not only at the heading level."},{"id":"contract-registry","surface":"/contract-registry.json","requiredFields":["purpose","evidence","failureMode"],"why":"A contract is only useful when agents know why it exists, how it is proven, and what breaks when it drifts."},{"id":"site-studies","surface":"/site-studies.json","requiredFields":["strongPatterns.why","avoidPatterns.why","agentTakeaways"],"why":"Good and bad examples should become reusable reasoning, not screenshots or impressions."},{"id":"qa-and-evaluation","surface":"/seo-aeo-evaluation.json and /qa-contract.json","requiredFields":["why","evidenceRequired","passCriteria","warningCriteria","failCriteria"],"why":"QA gates need to explain what they prove and what they do not prove."},{"id":"source-and-claims","surface":"/source-traceability.json","requiredFields":["policy.why","publicUse","requiredQualifier"],"why":"Claim safety depends on explicit source support, blocked use, and qualifier rationale."},{"id":"design-and-aeo-context","surface":"/design-system-contracts.json and /aeo-geo-context.json","requiredFields":["why","objectiveAlignment","rules with why fields"],"why":"Design and model-context work are easy to overgeneralize unless the contract explains tradeoffs and risks."}],"qualityRules":["A useful why explains the consequence of doing or skipping the work.","A useful why names the specific agent failure it prevents.","A useful why connects to evidence, QA, source truth, or the system objective.","A useful why is specific enough to guide a future implementation decision.","A useful why distinguishes pass, warning, and fail states when the work is evaluative."],"antiPatterns":["Because it is best practice.","Because SEO needs it.","Because users like it.","Because the design looks better.","Because agents need context, with no detail about what context or failure mode.","A broad objective with no step-level rationale."],"qaCoverage":[{"check":"Roadmap items","command":"npm run qa:aeo","coverage":"Requires objective, why, valueMultiplier, and objectiveAlignment on each item."},{"check":"Walkthrough steps","command":"npm run qa:aeo","coverage":"Requires why on every execution step."},{"check":"Contracts","command":"npm run qa:aeo","coverage":"Requires purpose, evidence, and failureMode."},{"check":"Site studies","command":"npm run qa:aeo","coverage":"Requires why on strong and avoid patterns."},{"check":"Context contracts","command":"npm run qa:aeo","coverage":"Requires why-bearing objects in design and AEO/GEO context."}],"stressTests":["Remove a walkthrough step why and confirm QA fails.","Replace a site-study why with vague best-practice language and flag it during review.","Ask a future agent to choose between two tasks using only rationale fields.","Remove a contract failureMode and confirm QA fails.","Check that every done task has evidence links that explain why it is complete."],"passCriteria":["Required rationale surfaces are listed.","Each required surface names fields that carry rationale.","Anti-patterns describe vague explanations to avoid.","QA coverage maps rationale checks to commands.","Stress tests explain how to prove rationale is useful."],"warningCriteria":["A rationale exists but is too generic to guide implementation.","A rationale explains value but not failure mode.","A rationale cites evidence but not objective alignment.","A completed task has evidence links but no clear why."],"failCriteria":["A major objective lacks a why.","A walkthrough step lacks a why.","A contract lacks failureMode or evidence.","A good/bad example lacks why.","A QA check lacks pass/warn/fail reasoning."],"objectiveAlignment":"Makes the operating system explainable enough for future agents to execute, audit, stress test, and adapt without relying on hidden assumptions."}}