# Specification: Day Shift Website and Documentation Experience Revamp ## 1. Summary Revamp the Day Shift website and documentation so a first-time visitor can understand the product before learning its internal planning, lifecycle, evidence, and repository-state models. The revised public experience must communicate Day Shift in this order: 1. Recognizable problem 2. Practical outcome 3. Smallest useful workflow 4. Normal planned-feature workflow 5. Product evidence 6. Technical model 7. Advanced governance capabilities The public website must stop requiring visitors to understand Human-Agent-Contracts, artifact hierarchies, planning-readiness dispositions, implementation attempts, lifecycle dimensions, revision-bound validation, reconciliation, or repository transactions before they can determine whether Day Shift is relevant to them. The documentation must be reorganized around user intent and task completion while preserving complete technical references for: * Canonical specifications * Basic, Structured, and Governed planning * Task definitions * Implementation summaries * Agent modes * Evidence profiles * Readiness * Implementation attempts * Validation evidence * Review and explicit disposition * Promotion * Migration * Operational recovery This specification does not reduce the technical rigor of Day Shift. It controls when, where, and for which audience that rigor is introduced. ### 1.1 Recertification Result Disposition: **update-active** as of 2026-07-31. The active goal remains necessary. The linked Governed work contains `slice-overview.md` and eight refined phase overviews, but no milestones, task pairs, implementation summaries, or reconciliations. Specification 28 therefore has not been implemented through its own planning slice and must remain active planning input. The repository does contain a substantial implemented baseline from specifications 12, 24, and 25. `apps/website` already provides outcome-led first-contact copy, Basic/Structured/Governed framing, a reproducible demonstration, commercial and trust surfaces, route metadata, accessibility contracts, performance checks, and analytics contracts. `apps/docs` already provides the canonical Astro Starlight documentation application, publication eligibility, generated public/inference artifacts, and workflow/reference content. This specification must inventory, retain, revise, redirect, or remove that baseline; it must not plan those shipped foundations as greenfield work. Specifications 29 through 32 are authoritative downstream product-direction evidence for this revamp: * Specification 29 adds authored decomposition contracts, per-artifact refinement state, and explicit non-executed post-create validation/link handoffs. * Specification 30 adds topology-aware direct-work behavior, canonical implementation-summary generation, explicit implementation completion, and complete CLI-only workflow playthrough gates. * Specification 31 adds command-owned single validation execution, resumable lifecycle run evidence, exact receipt apply, reconciliation acceptance, resolved-finding traceability, decision-complete bounded output, and deterministic metadata synchronization. * Specification 32 replaces unnumbered Basic and Structured new-write paths with numbered roots and numbered direct Structured task directories while preserving stable semantic identities and compatibility reads. The remaining active scope is the cross-surface content and navigation delta: apply the communication sequence in this specification consistently, reorganize canonical documentation around user intent, remove stale or duplicate explanations, update commands and paths to shipped contracts, and prove comprehension and truthfulness without rebuilding already-shipped website, documentation, commerce, publication, or release foundations. This source-specification update changes the revision consumed by the existing slice and phase scaffolds. Before slice 28 is expanded into milestones or tasks, that downstream planning must be recertified against this active delta. This specification recertification intentionally does not rewrite those planning artifacts or create a new planning layer. The 2026-08-05 repository quality review is also active input. It found nine failing documentation tests caused by stale command inventory, product-truth, prompt-discovery, and prompt-upgrade expectations; a website lint error plus warnings; a marketing-copy policy failure; accessibility and first-contact contract drift; stale Basic evidence; missing Structured link-materialization evidence; cross-application rollout-ledger drift; and no website validation job in GitHub CI. These are not a new product phase. They are concrete unsatisfied evidence under Stage 8 and the existing `08-accessibility-validation-and-measurement` phase, which must close every finding and prevent recurrence before the public experience is considered release-ready. --- ## 2. Alignment With the CLI Product Model The website and documentation must reflect the following settled product behavior. ### 2.1 Workflow Levels Day Shift supports three workflow levels: * **Basic** is the fastest path for one independently useful scoped task. * **Structured** is the normal path for planned feature work and the default when valid specification input is supplied without an explicit workflow level. * **Governed** is the staged path for large, risky, long-running, or cross-team initiatives requiring formal hierarchy, review, and reconciliation. The website must not describe Basic as the CLI default. Basic creates one parentless task pair. When another Basic task already exists, the current CLI requires `--confirm-independent` before creating a second one. Dependent or coordinated multi-task work should use Structured work or an explicit promotion path instead. The website may present Basic first because it is the smallest useful learning path, but it must clearly distinguish: > First workflow shown does not mean default planning workflow. ### 2.2 Canonical Specifications New non-emergent specifications created by `spec create` use: ```text .day-shift/specs/-/.md ``` Specification creation requires an explicit numbered-prefix choice through `--implementation-order `. `next` selects the lowest unused positive order. `spec create` rejects `00`; that order remains reserved for separate emergent intake and registration. Registered specification paths remain under `.day-shift/specs/`; the emergent exception uses `.day-shift/specs/00-emergent/00-YYYY-MM-DD-.md`. The selected order is canonical specification metadata and remains traceable through planning, implementation evidence, review, and reconciliation. Specifications are authored, refined, reviewed, and dispositioned independently from planning organization. Creating or reviewing a specification does not: * Select a workflow level * Generate a `work_id` * Create planning directories * Move the specification into a planning tree Structured and Governed planning reference canonical specifications rather than copying them into planning directories. ### 2.3 Canonical Planning Roots For the current creation commands, new planning work is organized under these exact shapes: ```text .day-shift/planning/ ├── basic/ │ └── tasks/-/ │ ├── task-definition.md │ └── implementation-summary.md ├── structured/ │ └── -/ │ ├── overview.md │ └── tasks/-/ └── governed/ └── -/ ├── slice-overview.md └── phases//milestones//tasks// ``` Basic task-root and Structured work-root prefixes come from `implementation_order`; a direct Structured task prefix is its parent-local `sequence` rendered as two digits. These prefixes order directories but are not part of stable `task_id` or `work_id` values. Basic and Structured creation must expose explicit or deterministic order allocation, and ordinary reads or lifecycle writes must not rename legacy paths implicitly. Governed work has one numbered slice root. It does not add a separate `overview.md` parent or another nested `slices/` container. Unnumbered Basic roots, unnumbered Structured roots, unnumbered direct Structured task directories, former `.day-shift/planning/-/` roots, and nested `.day-shift/planning/governed//slices/...` layouts are compatibility read or explicit migration inputs rather than canonical new-write destinations. These paths are relative to the effective Day Shift workspace root selected by the nearest valid `.day-shift/config.toml`; that workspace is at repository root by default but may be initialized in a supported repository subdirectory. These paths may be shown in technical documentation. They should not be required for understanding introductory marketing pages. ### 2.4 Shared Task and Evidence Model All workflow levels reuse: ```text task-definition.md implementation-summary.md ``` The task definition is the canonical work agreement. The implementation summary is the canonical task evidence artifact. The public experience may describe these as: * Work agreement * Implementation evidence * Reviewable handoff record Technical documentation must preserve the canonical artifact names. ### 2.5 Independent Task Dimensions The product represents four separate concepts: | Dimension | Values | Purpose | | ---------------- | ------------------------------------- | -------------------------------------------------------- | | Workflow level | `basic`, `structured`, `governed` | How work is organized and governed | | Agent mode | `autonomous`, `guided`, `interactive` | Check-in cadence and routine in-scope decision handling | | Evidence profile | `runtime`, `contract`, `hybrid` | What type of completion evidence is required | | Next action | Versioned derived actions | What the repository evidence indicates should happen now | Agent mode never expands execution authority. Autonomous, Guided, and Interactive agents stop at the same scope, evidence, approval, destructive-action, and external-system boundaries. Introductory pages must not combine these concepts into one generic “mode.” ### 2.6 Review and Mutation Boundary Review-evaluation commands are read-only. This includes `spec review`, `task readiness-review`, `task review`, `implementation-summary review`, `work review`, `phase review`, `milestone review`, and `reconciliation review`. Governed slice-level coverage uses `work review`; the reserved `slice review` descriptor is not currently callable. They may produce findings and recommendations, but they do not: * Mark work complete * Accept work * Rewrite evidence * Create follow-up tasks * Promote work * Change parent state Readiness authorization, implementation completion, canonical project-review persistence, reconciliation acceptance, repair successors, acceptance, requested changes, cancellation, blocking, closure, deterministic metadata synchronization, and other lifecycle mutations require separate explicit writes. In particular, `task readiness-authorize`, `task implementation-complete`, `work project-review create`, `reconciliation accept`, `metadata sync-status-from-review`, and `task review-repair` are write-capable commands even though their inputs are review evidence or their names refer to review. Revision-bound mutation previews and receipts do not imply that a write occurred. Where a command emits a reusable exact mutation receipt, `apply --receipt --expect-command ` remains the separate guarded write. Public examples must distinguish preview, exact apply, idempotent replay, and stale-receipt rejection. ### 2.7 Validation Boundary The current CLI uses `task validation-record` for three explicit postures: execute one selected validation command supplied after `--` and derive its observed result, record caller-supplied manual evidence without execution, or import verified CI/external evidence. Command-owned execution is one deliberate invocation, not an automatic sweep of every validation command declared by a task. `validation smoke`, `validation rollup`, and `validation links-check` are read-only Day Shift evidence checks. They do not execute the arbitrary validation commands declared by a task. Public copy may say: > Day Shift preserves required validation and its recorded results, and can execute one explicitly selected validation command when the operator invokes that posture. Public copy must not claim: > Day Shift automatically runs every validation command. Any demonstration of commands being executed must clearly identify whether execution was performed by: * A human * A coding agent * CI * Another external system * An explicitly invoked Day Shift command-owned execution ### 2.8 Agent Enforcement Boundary The CLI stores, resolves, and exposes agent-mode policy. It does not independently guarantee that every external coding agent obeys that policy. Public copy may state: > Day Shift tells compatible agents how independently to work and when to stop or check in. Public copy must not imply universal behavioral enforcement across unsupported agents. ### 2.9 Implementation History Material implementation and review cycles are preserved as stable implementation attempts. After readiness authorization, `task attempt-open` explicitly opens the current attempt. Runtime and Hybrid tasks then capture `task baseline` after the attempt is open and before implementation writes. Contract or explicit runtime-attribution-opt-out tasks may record validation with evidence-only binding and must not fabricate a runtime baseline. `implementation-summary build` refreshes the canonical paired evidence artifact. After applicable baseline, acceptance-criterion, and validation evidence is complete, `task implementation-complete` performs the separate revision-bound implementation-completion transition. It does not accept review, close the attempt, close the task, or mutate parent/reconciliation state. When an operator chooses a repository-local lifecycle run, `resume run open`, `resume run record`, `resume run status`, and `resume run resume` preserve bounded run evidence and recovery context. These run records support continuation; they do not replace canonical task, summary, review, reconciliation, or lifecycle state. Changes-requested retries do not overwrite earlier: * Baselines * Validation results * Deviations * Waivers * Review outcomes `task retry-authorize` opens a readiness-bound successor after changes are requested, while `task review-repair` is the explicit audited successor path after accepted closeout. Implementation-attempt details belong in technical documentation and technical demonstrations, not introductory marketing copy. --- ## Problem Day Shift contains a coherent and technically defensible workflow model, but the public experience still exposes too much of that model too early or inconsistently across surfaces. The implemented website baseline has already corrected part of the original problem: the homepage leads with a recognizable outcome, distinguishes the three workflow levels, includes reproducible product proof, and provides focused install and demo actions. The documentation baseline has already established a canonical Starlight application with publication controls and shipped workflow mirrors. Those are current-state inputs to preserve, not future scope. The remaining problem is that Human-Agent-Contract and hierarchy language still appears in first-contact identity and proof surfaces, current navigation and documentation taxonomy do not yet implement the complete intent-first journey below, and post-spec-28 command/path behavior is not consistently reflected across public examples. A first-time visitor may encounter: * Human-Agent-Contracts * Repository workflow layers * Specifications * Planning registration * Slices * Phases * Milestones * Tasks * Implementation summaries * Reconciliation * Agent modes * Evidence profiles * Readiness * Implementation attempts * Derived next actions * Validation revisions * Compatibility evidence * Release-line licensing * Repository-native governance Each concept may be valid individually. Together, they create excessive cognitive load before the visitor establishes a simple mental model of the product. The public experience also contains overlapping entry points: * Homepage * Product page * Interactive demo * Resources * FAQ * Human-Agent-Contract concept page * Comparison pages * Installation * Documentation * Getting Started * First Project * Lightweight Workflow * Workflow Overview * Command Reference * Architecture * Decisions * Known Limitations * Pricing The visitor must choose a learning path before understanding the product well enough to make that choice. The current documentation also presents the full planning hierarchy too close to the beginning of the experience. This makes the workflow appear disproportionate to ordinary agent-assisted work. This produces five failures: 1. Visitors cannot quickly explain what Day Shift does. 2. Evaluation appears more expensive than the underlying problem. 3. Product terminology is learned before product value is established. 4. The public experience reflects internal architecture more strongly than user intent. 5. Public descriptions may diverge from the actual CLI workflow and enforcement boundaries. --- ## 4. Product Communication Definition Day Shift must use one stable primary definition across the website and introductory documentation. ### 4.1 Primary Definition > Day Shift is a local CLI that keeps coding-agent plans, scope, validation evidence, and handoff records in your repository. “Validation evidence” is preferred over “validation” where wording could imply that Day Shift automatically executes every declared validation command rather than requiring an explicit command-owned execution or external evidence posture. ### 4.2 Supporting Definition > These records give humans and coding agents a shared continuation point across sessions, tools, and contributors. ### 4.3 Category Term > Together, the work agreement and implementation evidence form a Human-Agent-Contract. “Human-Agent-Contract” must be introduced after the concrete workflow is understood. It must not be the first concept a visitor must decode. ### 4.4 Core Promise > Keep coding-agent work aligned across sessions. ### 4.5 Core Problem > Coding-agent plans, decisions, scope, validation results, and unfinished work are frequently scattered across chat history, tickets, terminal output, and individual memory. ### 4.6 Core Outcome > Day Shift preserves the work agreement and implementation evidence in the repository where the work occurs. ### 4.7 Workflow-Level Language Use the following public descriptions consistently: #### Basic > The fastest path for one scoped task. #### Structured > The normal path for planned feature work. #### Governed > The staged path for formal review and reconciliation. ### 4.8 Product Boundary Statement > Day Shift organizes and preserves agent-assisted engineering work. It does not replace the coding agent, Git, CI, issue tracking, or code review. --- ## Goals ### Primary Goals * Make the Day Shift value proposition understandable within the first page viewport. * Allow a visitor to explain Day Shift without using internal terminology. * Establish one clear evaluation path from discovery to first successful use. * Present Basic as the fastest explicit evaluation path without describing it as the default planning workflow. * Present Structured as the normal planned-feature path and CLI default when valid specification input is present. * Present Governed as the formal staged workflow. * Separate introductory product communication from advanced technical explanation. * Organize documentation around user tasks and operational questions. * Reduce navigation overlap between the website, resource hub, demo, and documentation. * Explain canonical specification ownership accurately. * Explain the difference between task agreement, implementation evidence, review, and explicit disposition. * Make the interactive demo understandable without requiring knowledge of the artifact hierarchy. * Improve pricing, licensing, compatibility, and limitation communication. * Create a durable terminology system used consistently across all public surfaces. * Preserve access to detailed architecture, schemas, decisions, recovery behavior, and technical evidence. * Make it clear when Day Shift is and is not appropriate. * Support human readers and coding agents without mixing their instructions on the same primary pages. * Make technical proof available without placing it ahead of the product explanation. * Ensure the website never claims CLI or agent behavior beyond the implemented enforcement boundary. * Gate public claims according to shipped CLI capabilities. ### Secondary Goals * Improve discoverability through clearer page titles and stable terminology. * Reduce duplicated explanations across public pages. * Make documentation easier for coding agents to retrieve and interpret. * Provide small, verifiable adoption stories instead of relying only on broad claims. * Make tested compatibility easy to verify. * Clarify evaluation use and commercial use. * Reduce the interpretation required to choose a workflow. * Create a structure that can expand as workflows and integrations are added. * Make current versus planned functionality distinguishable. * Support versioned technical documentation. * Give every major CLI command a canonical reference owner. --- ## Non-Goals This revamp will not: * Remove technical documentation. * Hide known product limitations. * Replace repository-native artifacts with a hosted dashboard. * Require account creation for evaluation. * Introduce mandatory cloud services. * Replace the CLI with a web application. * Present Day Shift as a coding assistant. * Present Day Shift as a replacement for Git, CI, issue tracking, or code review. * Claim that Day Shift automatically executes every declared validation command or runs command-owned validation without an explicit invocation. * Claim that the CLI can force unsupported external agents to obey agent-mode policy. * Claim that path declarations are universal filesystem enforcement. * Present a read-only review as an acceptance or closure action. * Introduce “evidence record” as a second canonical artifact name that competes with `implementation-summary.md`. * Invent customer metrics, testimonials, compatibility claims, or enforcement guarantees. * Describe planned workflow levels as shipped before their release gates are satisfied. * Require visitors to consume documentation sequentially. * Make the homepage a complete product manual. * Expose internal transaction, revision, waiver, or lifecycle mechanics on introductory pages. * Reproduce the complete CLI parent specification in the public documentation. --- ## Constraints * Public CLI claims must be grounded in callable command inventory, current help, and implemented behavior. * The website revamp does not change CLI lifecycle semantics, artifact ownership, or mutation authority. * Executable examples must use complete shipped arguments and distinguish read-only commands from writes. * Repository paths must be described relative to the effective Day Shift workspace root. * Planning artifacts are local by default; committing or otherwise version-controlling them remains a team choice. * Validation and agent-integration claims must preserve the execution and enforcement boundaries in this specification. --- ## 7. Target Audiences ### 7.1 Individual Software Engineer Needs to: * Continue agent work across sessions. * Preserve task scope and validation evidence. * Avoid reconstructing project context. * Evaluate Day Shift with one task. * Decide when a specification-driven workflow is justified. Primary question: > Will this reduce the work I lose between agent sessions? ### 7.2 Engineering Lead Needs to: * Review agent work without reading complete chat histories. * Establish consistent task boundaries. * Make validation and deviations visible. * Separate review findings from lifecycle approval. * Determine whether the workflow adds disproportionate ceremony. Primary question: > Will this make agent-assisted work easier to review and govern? ### 7.3 Infrastructure or Automation Engineer Needs to: * Use local or mixed inference systems. * Preserve deterministic repository state. * Support multiple agent interfaces. * Integrate Day Shift with existing engineering workflows. * Inspect machine-readable next-action and policy output. Primary question: > Does this create a durable control layer without forcing a specific agent platform? ### 7.4 Technical Evaluator Needs to: * Understand architecture and limitations. * Review artifact schemas and command behavior. * Verify local operation. * Understand concurrency and recovery behavior. * Determine compatibility and migration risk. Primary question: > What exactly does Day Shift create, record, validate, and guarantee? ### 7.5 Coding Agent Needs to: * Locate repository orientation. * Identify selected work. * Understand workflow level. * Resolve effective agent mode. * Understand allowed scope. * Identify evidence-profile requirements. * Read the derived next action. * Record implementation evidence. * Stop at explicit authorization boundaries. Primary question: > What work is authorized, how independently should I proceed, and what evidence must I return? --- ## 8. Experience Principles ### 8.1 Outcome Before Architecture Explain what changes for the user before explaining how Day Shift represents the change internally. ### 8.2 Familiar Language Before Product Language Introduce the familiar problem first. Introduce Day Shift terminology after the visitor has a working mental model. ### 8.3 Smallest Useful Path First The first workflow demonstrated should be Basic because it is the smallest useful path. This principle does not redefine the CLI default. Structured remains the default for specification-backed planning work. ### 8.4 Normal Workflow Must Be Visible After demonstrating Basic, introduce Structured as the normal path for planned feature work. Visitors must not leave with the belief that Day Shift is primarily a collection of unrelated task files. ### 8.5 Progressive Disclosure Advanced governance and lifecycle concepts remain available but appear only when the reader’s task requires them. ### 8.6 One Page, One Job Each major page must have one primary purpose. ### 8.7 Evidence Over Claims Use actual command output, artifact examples, validation evidence, review findings, and repository state to support product claims. ### 8.8 Human and Agent Instructions Are Distinct Human guidance and reusable agent policy must not compete within the same primary reading flow. ### 8.9 Read and Write Boundaries Must Be Visible Documentation must distinguish: * Review * Recommendation * Explicit mutation * Acceptance * Closure ### 8.10 Limitations Increase Trust Known limitations must explain actual operational and enforcement boundaries. ### 8.11 Shipped Behavior Before Planned Behavior Public pages must not present a specified but unimplemented capability as currently available. ### 8.12 Technical Depth Must Be Navigable Deep content must be accessible through dedicated reference and architecture paths rather than embedded throughout introductory material. --- ## 9. Public Information Architecture The top-level experience must support three user intentions: 1. Understand 2. Try 3. Operate ### 9.1 Recommended Primary Navigation ```text Product Demo Try Day Shift Documentation Pricing ``` Secondary navigation or footer: ```text Use Cases Resources Compatibility Known Limitations FAQ Architecture Decisions Support ``` ### 9.2 Navigation Definitions #### Product Explains: * The problem * The outcome * How the product works * Workflow levels * Who it is for * What it does not replace * Key technical properties #### Demo Shows: * A Basic outcome replay * An optional Structured planning replay * A technical repository replay * Read-only review and explicit disposition as separate actions #### Try Day Shift Provides: * Evaluation requirements * Installation * Explicit Basic workflow selection * Expected files and results * Existing repository safety guidance * Continuation into a second session * Structured next steps #### Documentation Provides: * Basic evaluation * Specification lifecycle * Structured planned-feature workflow * Governed workflow * Agent guidance * Command and schema reference * Architecture * Recovery * Troubleshooting #### Pricing Explains: * Evaluation rights * Commercial rights * License duration * Version entitlement * Upgrade behavior * Support entitlement * Concrete examples --- ## 10. Homepage Specification ### 10.1 Homepage Job The homepage must answer: 1. What problem does Day Shift solve? 2. What changes after using it? 3. What is the smallest useful workflow? 4. What is the normal planned-feature workflow? 5. Is it relevant to me? 6. Can I inspect evidence? 7. What should I do next? The homepage must not teach the complete artifact or lifecycle model. ### 10.2 Required Homepage Structure #### Section 1: Hero ##### Headline > Keep coding-agent work aligned across sessions. ##### Supporting text > Day Shift is a local CLI that keeps plans, allowed scope, validation evidence, and handoff records in your repository. ##### Primary action > Try one task ##### Secondary action > Watch the workflow The hero must not initially use: * Repository workflow layer * Human-Agent-Contract infrastructure * Planning-readiness disposition * Evidence profile * Implementation attempt * Milestone reconciliation * Deterministic artifact graph * Optimistic concurrency #### Section 2: Recognizable Problem Explain: * The plan exists in one chat. * The implementation occurs in another. * Scope is implied. * Validation results are buried in terminal or CI output. * Review decisions are mixed with implementation conversation. * The next contributor reconstructs context. #### Section 3: Before and After Before Day Shift: * Prompt and plan live in chat history. * Scope is implied. * Validation evidence is inconsistently preserved. * Review and approval are easy to conflate. * Handoffs depend on memory. * Retries may overwrite the previous explanation. With Day Shift: * The task agreement lives in the repository. * Allowed scope is explicit. * Implementation evidence is preserved. * Review findings remain separate from acceptance. * Changes-requested attempts remain inspectable. * Another session can identify what should happen next. #### Section 4: Three-Step Basic Mechanism 1. Define the task. 2. Implement and record evidence. 3. Review, then explicitly accept or revise. Do not imply that review automatically completes the task. #### Section 5: Smallest Workflow Present Basic as: > The fastest path for one scoped task. Show: * Objective * Allowed paths * Acceptance criteria * Validation requirements * Implementation summary * Review result * Explicit disposition * Continuation state The example must fit within one common desktop viewport where practical. #### Section 6: Normal Planned-Feature Workflow Present Structured as: > The normal path for planned feature work. Explain simply: 1. Create or import a specification. 2. Refine and review it. 3. Explicitly approve or waive planning readiness. 4. Create Structured work linked to the canonical specification. 5. Implement direct child tasks. 6. Run read-only work review. 7. Explicitly persist canonical `project-review.md` evidence. 8. Close the work through a separate explicit action. Do not introduce slices, phases, milestones, or reconciliation in this section. #### Section 7: Product Proof Show: * One task definition * One implementation summary * Changed-path evidence * Recorded validation results * One review finding * One explicit acceptance or requested-change action * One derived next action * One continuation example Link to the full demo. #### Section 8: Works With Existing Tools Clarify that Day Shift: * Does not replace coding assistants. * Does not require one model provider. * Does not replace Git. * Does not replace CI. * Does not replace issue tracking. * Does not replace code review. * Does not automatically enforce every declared path. * Adds repository-local planning, evidence, and handoff structure. #### Section 9: Workflow Levels Use: | Level | Public description | | ---------- | ------------------------------------------------ | | Basic | Fastest path for one scoped task | | Structured | Normal path for planned feature work | | Governed | Staged path for formal review and reconciliation | State explicitly: > Structured is the default for specification-backed planning work. Basic is an explicit lower-ceremony choice. #### Section 10: Technical Properties After the product is understood, present: * Local-first * Repository-native * Human-readable * Plain files that teams may version-control * Provider-independent CLI with integration-dependent agent compliance * Explicit read/write boundaries * Deterministic structural validation * Revision-aware evidence * Designed for continuation Each property must link to technical documentation. #### Section 11: Fit Assessment Show strong-fit and weak-fit conditions. #### Section 12: Final Call to Action Primary: > Try one Basic task in a disposable repository. Secondary: > Plan a feature with Structured work. --- ## 11. Product Page Specification The Product page must explain the complete conceptual model without becoming a command reference. ### Required Sections * Problem definition * Product definition * Basic workflow * Structured workflow * Governed workflow * Canonical specification ownership * Task agreement and implementation evidence * Human-Agent-Contract definition * Agent-mode overview * Evidence-profile overview * Review versus disposition * Derived next action * Relationship to existing tools * Local-first architecture * Scope and validation-evidence model * Continuation model * Supported use cases * Weak-fit cases * Product boundaries * Links to demo, installation, documentation, limitations, and architecture ### Human-Agent-Contract Introduction Explain the concrete questions first: * What is being changed? * Why is it being changed? * Which paths may change? * What must remain unchanged? * How will success be evaluated? * What changed? * Which validation evidence was recorded? * What deviations occurred? * What remains unresolved? * Was the result accepted, revised, or blocked? * What should happen next? Then introduce: > Together, this work agreement and implementation evidence form a Human-Agent-Contract. ### Agent-Mode Overview The Product page may describe: * Autonomous * Guided * Interactive It must also state: > Day Shift exposes this policy to compatible agents. The core CLI does not force arbitrary external agents to comply. ### Evidence-Profile Overview Explain: * Runtime * Contract * Hybrid Do not combine evidence profile with agent autonomy. --- ## 12. Demo Specification ### 12.1 Demo Modes The demo must support distinct levels of detail. #### Mode A: Basic Outcome Replay For first-time visitors. Sequence: 1. Task request 2. Allowed scope and completion criteria 3. Agent or human implementation 4. Implementation evidence 5. Explicitly executed, recorded, or imported validation results 6. Explicit implementation completion 7. Read-only review 8. Explicit disposition 9. Continuation in another session The replay must remain understandable without command knowledge. #### Mode B: Structured Planning Replay For visitors evaluating normal feature work. Sequence: 1. Canonical specification creation or import 2. Specification refinement 3. Read-only specification review 4. Explicit planning-readiness disposition 5. Structured work creation 6. Direct task creation 7. Numbered root and direct-task path evidence with stable semantic identities 8. Implementation, canonical summary generation, validation evidence, and explicit implementation completion 9. Read-only project coverage review 10. Explicit `project-review.md` persistence 11. Separate explicit closeout The specification must remain under `.day-shift/specs/` throughout the replay. #### Mode C: Technical Repository Replay May show: * CLI commands * Canonical paths * Specification registry behavior * Planning-readiness review references * Basic, Structured, and Governed roots * Task definitions * Implementation summaries * Agent mode * Evidence profile * Readiness evidence * Implementation baseline * Attempt history * Validation scope * Command-owned validation execution versus manual or imported evidence * Explicit implementation completion * Derived next action * Review and explicit disposition * Promotion * Reconciliation build readiness, read-only review, explicit acceptance, and resolved findings * Lifecycle run manifests and resume guidance * Revision-bound mutation previews and exact receipt apply * Transaction or recovery behavior where relevant ### 12.2 Demo Requirements * State whether the demonstration is synthetic. * Separate shipped behavior from planned behavior. * Identify commands currently available. * Identify when another tool executes validation. * Avoid implying universal direct-agent integration. * Avoid implying agent-mode enforcement beyond compatible integrations. * Show repository state before and after. * Show one unresolved or follow-up item. * Show how a new session discovers current work. * Show review and mutation as separate steps. * Preserve earlier attempt evidence when demonstrating requested changes. * Provide a reproducible fixture when available. * Keep detailed caveats outside the primary outcome flow. --- ## 13. Try Day Shift Specification The Try Day Shift path must produce a useful result without requiring a specification or higher planning layer. ### 13.1 Evaluation Workflow The evaluation guide must explicitly select Basic. Conceptual flow: ```text day-shift init day-shift work create --level basic --implementation-order next --task day-shift --format json task readiness-review --task-definition > day-shift task readiness-authorize --task-definition --review-result day-shift task attempt-open --task-definition --attempt-id --opened-at day-shift task baseline --task-definition --task-cycle-id --checkpoint-id --captured-by --captured-at day-shift implementation-summary build --task-definition day-shift task validation-record --task-definition [-- ] day-shift task implementation-complete --task-definition --attempt-id --task-revision --completed-by --completed-at day-shift task review --task-definition day-shift task disposition --task-definition --disposition day-shift task close --task-definition # accepted outcomes only ``` This is a command-family skeleton, not a copy-and-paste script. Runtime and Hybrid tasks require the baseline step; Contract tasks or explicit runtime-attribution opt-outs do not fabricate a baseline. `changes_requested` routes through a fresh readiness review and `task retry-authorize` rather than closure. Blocking and cancellation use the separate `task block` and `task cancel` commands. Documentation must use actual shipped command names and complete required arguments in executable examples. ### 13.2 Required Sections 1. What will happen 2. Requirements 3. Installation 4. Create or select a disposable repository 5. Initialize Day Shift 6. Select the Basic root implementation order and explicitly create Basic work 7. Define the task while keeping the numeric prefix out of `task_id` 8. Review readiness 9. Explicitly authorize readiness from the complete review result 10. Open the readiness-bound implementation attempt 11. Establish the implementation baseline for Runtime or Hybrid evidence 12. Run the task with an existing coding assistant or manually 13. Build and complete the canonical implementation summary 14. Explicitly execute one selected validation command, record manual evidence, or import verified external evidence 15. Apply the revision-bound implementation-completion transition 16. Run read-only review 17. Explicitly accept, request changes, block, or cancel 18. Close accepted work through a separate explicit action 19. Continue or inspect the task or optional lifecycle run from another session 20. Remove or retain evaluation files 21. Move to Structured work when appropriate ### 13.3 Success Definition The evaluator succeeds when: * A Basic task exists. * The task definition contains explicit scope and acceptance criteria. * Readiness was reviewed and explicitly authorized from the complete revision-bound review result. * A readiness-bound implementation attempt exists. * Runtime or Hybrid evidence has a valid pre-write baseline; Contract or explicit runtime-attribution-opt-out evidence does not fabricate one. * Implementation evidence exists in the implementation summary. * Required validation evidence is visible or explicitly waived, and its execution/import posture is clear. * Implementation completion is explicitly recorded without implying review acceptance or task closure. * Review findings can be inspected. * Acceptance or requested changes are recorded through a separate explicit action. * A second session can discover current state and next action without reading the original chat. ### 13.4 Claims the Guide Must Avoid The guide must not imply: * A specification is required for Basic. * Basic is the default for specification-backed work. * Review automatically closes the task. * Day Shift itself executed validation unless it did. * Agent mode guarantees external-agent behavior. * Every changed path can always be attributed with certainty. ### 13.5 Existing Repository Safety The guide must explain: * Which files will be created. * Which workflow root will be used. * Whether initialization modifies existing files. * How to preview mutations. * How expected revisions protect direct edits. * How dirty-worktree baselines affect attribution. * How uncertain ownership is represented. * Which operational transaction paths may appear. * How incomplete transactions are recovered. * How to remove Day Shift. * How to avoid committing evaluation artifacts. * How repository configuration changes paths. * How nested repositories and symlinks are handled. * How existing legacy layouts remain readable. --- ## 14. Structured Getting Started Create a separate path titled: > Plan a Feature With Structured Work ### Required Flow 1. Initialize Day Shift. 2. Create or import a canonical specification. 3. Refine the specification. 4. Run read-only specification review. 5. Persist the complete review result when recording a ready disposition. 6. Explicitly record planning readiness or a reasoned waiver. 7. Create numbered planning work without specifying a level, demonstrating Structured default resolution and inherited or explicit root-order selection. 8. Inspect `overview.md` and distinguish the numbered directory name from stable `work_id`. 9. Create numbered direct child tasks through `work task create`, deriving prefixes from parent-local `sequence` while keeping dependencies on stable `task_id` values. 10. Review task readiness. 11. Explicitly authorize readiness from each complete review result. 12. Open each implementation attempt and capture a Runtime or Hybrid baseline where required. 13. Implement, build canonical summaries, preserve validation evidence, and explicitly complete each implementation attempt. 14. Review project coverage through read-only `work review`. 15. Persist canonical project-review evidence through `work project-review create`. 16. Explicitly close the project through `work close`. ### Required Explanation The guide must explain: * `spec_id`, `work_id`, and `task_id` at the point each becomes relevant. * Why specification creation does not create planning work. * Why planning readiness is separate from review. * Why the Structured overview references rather than copies the specification. * Why the specification revision is recorded. * What happens when the specification changes after planning. * Why root `implementation_order` and task `sequence` appear in directory names but are not semantic work or task identity. * Why `work review` is read-only, why `work project-review create` is a separate persistence write, and why neither silently closes the work. --- ## 15. Documentation Information Architecture The documentation must be divided by audience and purpose. The tree below is a route and information-architecture model rooted at the canonical authored collection `apps/docs/src/content/docs/`; it is not a new repository-root `docs/` directory. Generated exports under `apps/docs/public/content/` remain derived publication artifacts and must not become an authored second source of truth. ### 15.1 Recommended Structure ```text docs/ ├── start/ │ ├── overview │ ├── try-basic-task │ ├── plan-structured-feature │ ├── existing-repository │ ├── choose-workflow │ └── next-steps ├── workflows/ │ ├── basic/ │ │ ├── overview │ │ ├── create-task │ │ ├── readiness │ │ ├── implement │ │ ├── review-and-disposition │ │ └── promote │ ├── structured/ │ │ ├── overview │ │ ├── specification-lifecycle │ │ ├── planning-readiness │ │ ├── create-work │ │ ├── direct-tasks │ │ └── project-closeout │ ├── governed/ │ │ ├── overview │ │ ├── hierarchy │ │ ├── staged-review │ │ ├── reconciliation │ │ └── project-closeout │ ├── resume-work │ ├── lifecycle-run-context │ ├── recover-from-drift │ └── promotion ├── concepts/ │ ├── human-agent-contract │ ├── canonical-specifications │ ├── workflow-levels │ ├── task-agreement │ ├── implementation-evidence │ ├── readiness │ ├── review-versus-disposition │ ├── continuation │ ├── agent-mode │ ├── evidence-profile │ ├── next-action │ ├── implementation-attempts │ ├── validation-evidence │ ├── validation-execution-and-import │ ├── waivers │ ├── promotion │ ├── mutation-preview-and-receipts │ ├── resolved-findings │ └── reconciliation ├── agents/ │ ├── orientation │ ├── current-work │ ├── agent-mode-policy │ ├── task-instructions │ ├── evidence-requirements │ ├── review-boundaries │ └── stop-and-escalate ├── reference/ │ ├── commands/ │ ├── configuration │ ├── schemas/ │ │ ├── specification │ │ ├── planning-readiness │ │ ├── work-overview │ │ ├── task-definition │ │ ├── implementation-summary │ │ ├── implementation-attempt │ │ └── waiver │ ├── planning-layout │ ├── state-classification │ ├── lifecycle-invariants │ ├── next-action-resolver │ ├── path-semantics │ ├── numbered-planning-roots │ ├── concurrency │ ├── transactions │ ├── lifecycle-run-manifests │ ├── exit-codes │ ├── environment │ └── compatibility ├── troubleshooting/ │ ├── installation │ ├── invalid-state │ ├── specification-review │ ├── stale-planning-readiness │ ├── stale-specification │ ├── missing-artifacts │ ├── lifecycle-conflicts │ ├── validation-evidence │ ├── scope-attribution │ ├── concurrent-write-conflicts │ ├── incomplete-transactions │ ├── unsupported-platform │ └── migration-recovery ├── architecture/ │ ├── overview │ ├── repository-model │ ├── specification-and-planning-boundary │ ├── validation-model │ ├── identifiers │ ├── state-classification │ ├── transaction-model │ ├── migrations │ └── security ├── decisions/ └── contributing/ ``` ### 15.2 Documentation Homepage The documentation homepage must begin with tasks: * Try Day Shift with one Basic task * Plan a feature with Structured work * Add Day Shift to an existing repository * Choose a workflow level * Review completed agent work * Resume selected work * Recover from scope or specification drift * Look up a command * Understand the architecture The sidebar may retain taxonomy-based navigation. --- ## 16. Starting Paths ### 16.1 Path A: Disposable Basic Evaluation For users testing the smallest useful workflow. ### 16.2 Path B: Normal Structured Feature For users planning implementation from one or more canonical specifications. ### 16.3 Path C: Existing Repository For users introducing Day Shift into active work and potentially dirty working trees. ### 16.4 Path D: Technical Evaluation For users reviewing schemas, lifecycle rules, compatibility, transactions, and migration before installation. ### 16.5 First Useful Result The first useful Basic result must not require: * Creating a specification * Creating a `work_id` * Registering planning work * Creating a slice * Creating a phase * Creating a milestone * Creating reconciliation * Creating a Basic overview or planning index * Editing relationship files manually `day-shift init` still creates baseline workspace files such as `.day-shift/specs/index.json`; Basic does not require a specification registry entry or a Basic-specific generated index. Basic creation does require a root `implementation_order` selection (`` or `next`). That directory-order choice does not create a specification, `work_id`, parent overview, or planning dependency, and it does not become part of stable `task_id`. The first Structured result requires a canonical specification and current planning-readiness disposition but does not require: * Slices * Phases * Milestones * Reconciliation Those concepts belong to Governed work. --- ## 17. Workflow Documentation Specification ### 17.1 Basic Workflow Use when: * The work is one coherent implementation-sized task. * Target paths or command surfaces are known. * Dependencies are resolved. * Risk and coordination pressure are low. * Project-level review is unnecessary. Documentation must cover: * Explicit Basic selection * Required Basic root `implementation_order` selection and stable unprefixed `task_id` * Task definition * Agent mode * Evidence profile * Scope * Acceptance criteria * Readiness review * Explicit readiness authorization through `task readiness-authorize` * Explicit implementation-attempt opening through `task attempt-open` * Runtime or Hybrid baseline capture after attempt opening and before implementation writes * Contract and runtime-attribution-opt-out behavior without a fabricated baseline * Canonical implementation-summary build * Explicit command-owned validation execution versus manual or imported evidence * Explicit revision-bound implementation completion * Read-only review * Explicit disposition * Separate accepted-task closure * Continuation * Explicit `--confirm-independent` behavior for a second Basic task * Promotion ### 17.2 Structured Workflow Use when: * A feature benefits from a shared specification. * One or more direct implementation tasks are expected. * Dependencies or multiple contributors may exist. * Project-level review is useful. * Governed hierarchy would add unnecessary ceremony. Documentation must cover: * Canonical specification creation * Specification refinement * Read-only review * Persisted review result * Planning-readiness disposition * Specification revision * Structured default * Numbered Structured work root with stable unprefixed `work_id` * Numbered direct task generation from parent-local `sequence` with stable unprefixed `task_id` * Task dependencies * Default and task-level agent modes * Default and task-level evidence profiles * Canonical implementation-summary build and explicit implementation completion * Evidence aggregation * Read-only project-level review * Explicit `project-review.md` persistence * Separate explicit closeout * Specification drift * Follow-up tasks * Promotion ### 17.3 Governed Workflow Use when: * Work is large or long-running. * Work spans teams, repositories, or major subsystems. * Risk requires staged approval. * Formal planning and review boundaries are required. * Evidence must roll upward through reconciliation. * Partial completion, waivers, or deferred work require explicit disposition. Documentation must cover: * Canonical specification references * Root creation through `work create --level governed`, with `slice new` documented as the layer-specific alternative only when registered specification context already selects that Governed root * Numbered Governed slice root and `slice-overview.md` * The absence of a separate Governed `overview.md` or nested `slices/` layer * Authored target child counts and boundary-based decomposition rationales before full-set child creation * Per-artifact refinement state and ordered, non-executed post-create validation/link handoffs * Phase * Milestone * Task * Implementation summary * Reconciliation build to review-ready evidence, read-only reconciliation review, and explicit receipt-bound `reconciliation accept` * Resolved-finding traceability without suppressing live findings * Exceptions and waivers * Partial completion * Read-only Governed coverage review through `work review` * Explicit `project-review.md` persistence through `work project-review create` * Separate explicit closeout through `work close` ### 17.4 Promotion Documentation must explain: * Supported paths: * Basic to Structured * Basic to Governed * Structured to Governed * Promotion triggers * Required canonical specification references * Preview and expected-revision checks * Exact receipt apply when the selected promotion surface emits a reusable mutation plan receipt * Stable task identity * Numbered-destination allocation without adding prefixes to semantic identities * Preserved implementation attempts * Preserved validation and waiver evidence * New parent artifacts * Ambiguous mapping failures * Transaction and recovery behavior * Lack of initial demotion support --- ## 18. Human and Agent Documentation Separation ### 18.1 Human-Facing Pages Must explain: * Why the step exists * What decision the user must make * What command to run * Whether the command is read-only or mutating * What files may change * What output to inspect * What failure means * How to recover * What the next valid action is ### 18.2 Agent-Facing Pages Must contain: * Exact selected task location * Workflow level * Declared and effective agent mode * Agent-mode source * Evidence profile * Allowed scope * Protected paths * Acceptance criteria * Validation-evidence requirements * Derived next action * Stop conditions * Review/write boundaries * Escalation behavior * Requirements for deviations and blockers ### 18.3 Agent Enforcement Disclaimer Agent pages must state: > These instructions define the Day Shift Agent Collaboration Protocol. Behavioral enforcement depends on the connected agent or integration. ### 18.4 Agent Documentation Requirements Every agent instruction page must be: * Self-contained * Versioned * Machine-readable where practical * Explicit about required and optional fields * Explicit about read and write boundaries * Explicit about stop conditions * Free from marketing language * Linked to the applicable protocol version --- ## 19. Resource Hub Specification The Resource Hub must be grouped by user problem. ### 19.1 Control the Work * Define a good task * Decide between Basic, Structured, and Governed * Create a canonical specification * Restrict allowed paths * Prevent scope expansion * Select agent autonomy * Select evidence requirements * Know when an agent must stop ### 19.2 Review the Result * Review without reading chat history * Understand read-only review * Record explicit acceptance or requested changes * Verify validation evidence * Identify stale validation * Identify deviations * Inspect prior attempts * Record follow-up tasks ### 19.3 Continue Across Sessions * Discover current work * Understand derived next action * Resume in another agent session * Hand work to another contributor * Preserve decisions * Recover from lost chat history * Recover from changes requested ### 19.4 Adopt Safely * Add Day Shift to an existing repository * Use it with Codex * Use it with GitHub Copilot * Use it with local models * Understand agent-integration limits * Use it alongside Jira or Linear * Evaluate repository overhead * Handle dirty worktrees * Recover incomplete transactions * Migrate existing Day Shift work ### 19.5 Resource Display * Show a limited number of featured resources initially. * Provide search. * Provide problem-oriented filters. * Avoid one uninterrupted list. * Link each resource to the canonical workflow or reference page. --- ## 20. Terminology Specification ### 20.1 Public and Technical Terms | Technical term | First public explanation | | ----------------------- | ------------------------------------------------------------------------------------ | | Human-Agent-Contract | The recorded work agreement and implementation evidence | | Canonical specification | The authoritative requirement document used to plan work | | Workflow level | The amount of planning and governance applied to the work | | Basic | The fastest path for one scoped task | | Structured | The normal specification-backed path for planned feature work | | Governed | The staged path with formal hierarchy and reconciliation | | Task definition | The work agreement for one implementation task | | Implementation summary | The canonical record of implementation and evidence | | Agent mode | How independently a compatible agent should work | | Evidence profile | The kind of proof required for completion | | Readiness | Evidence that implementation is authorized to begin | | Implementation attempt | One preserved implementation and review cycle | | Baseline | Repository evidence captured before implementation changes | | Validation evidence | Recorded or imported results for required checks | | Read-only review | Evaluation that produces findings without changing lifecycle state | | Disposition | An explicit write recording acceptance, requested changes, blocking, or cancellation | | Next action | Versioned guidance derived from current repository evidence | | Continuation point | The state another session uses to resume work | | Promotion | Moving work to a more governed organization while preserving identity and evidence | | Reconciliation | Reviewing governed delivery evidence against the plan | | Operational state | Temporary lock, staging, and recovery data used during mutations | ### 20.2 Terminology Rules * Use one term for each canonical concept. * Define technical terms on first use. * Avoid more than one new product-specific term per introductory section. * Do not use “standard workflow” for Governed. * Do not use “lightweight” as a current workflow label. * Use Basic, Structured, and Governed as public workflow names. * State that Structured is the default for specification-backed planning. * Preserve `implementation-summary.md` as the technical artifact name. * Use “implementation evidence” as a plain-language explanation, not a replacement canonical artifact. * Do not use “mode” without identifying workflow, agent, or evidence context. * Do not use “review” to mean acceptance. * Do not use “validation” where “validation evidence” is more accurate. * Keep identifiers, hashes, transaction mechanics, and lifecycle invariants in technical documentation. --- ## 21. Pricing and Licensing Specification The pricing page must explain purchasing behavior through concrete examples. ### Required Questions * What can be evaluated without purchase? * What requires a commercial license? * Is the license perpetual? * Which CLI version or release line is covered? * What happens when a newer version ships? * Is upgrading required? * Does the product require online activation? * What happens to repository artifacts after a license is not upgraded? * What support is included? * How are team sizes measured? * What happens when a license does not cover the installed CLI version? ### Required Concrete Example The page must show: * Purchase of a covered version or release entitlement * Continued perpetual use of that covered version * Optional upgrade behavior * Unlicensed behavior for an uncovered newer version * Repository artifact ownership * Offline license verification * Commercial reminder behavior ### Evaluation Versus Commercial Use Compare: * Evaluation rights * Commercial rights * Team coverage * Support * License verification * Reminder suppression * Version entitlement * Upgrade behavior Pricing copy must remain aligned with the implemented licensing specification and must not simplify away version-entitlement boundaries. --- ## 22. Known Limitations Specification The Known Limitations page must focus on actual engineering and adoption constraints. ### Required Topics * Tested operating systems * Supported architectures * Shell compatibility * Project sizes tested * Repository layouts tested * Monorepo limitations * Nested repository behavior * Symlink boundaries * Direct agent integration status * Agent-mode enforcement status * Multi-agent orchestration status * Path declaration versus enforcement * Changed-path attribution limitations * Dirty-worktree uncertainty * Validation recording versus command execution * Scoped-validation limitations * Unknown dependency conservatism * Read-only review boundaries * Migration guarantees * Compatibility with legacy readiness and evidence formats * Experimental commands * Repository file overhead * Operational transaction-state behavior * Recovery limitations * Performance limitations * Unsupported workflows * Situations where Day Shift adds excessive ceremony * License and distribution limitations * Current workspace-doctor coverage, including whether specifications under `.day-shift/specs/` are inspected Every limitation must distinguish: * Supported * Supported with constraints * Experimental * Untested * Unsupported * Planned but unavailable --- ## 23. Fit Assessment Page Create: > Should We Use Day Shift? ### Strong Fit * Agent work spans multiple sessions. * Work is handed between people or tools. * Scope violations create meaningful cost. * Validation evidence must remain visible. * Reviewers need a durable task agreement. * Requested changes must preserve prior evidence. * The repository should retain implementation history beyond commits. * Several coding assistants or models may be used. * Planned feature work benefits from a canonical specification. * Formal review and reconciliation are sometimes needed. ### Weak Fit * Work is tiny and disposable. * One person completes everything in one session. * No review or handoff occurs. * Existing issue, pull request, and CI records already provide sufficient continuity. * Repository artifacts would cost more than occasional reconstruction. * The user only needs a prompt template. * The team expects the CLI to enforce arbitrary external-agent behavior. * The team expects Day Shift to replace CI or automatically execute all checks. ### Decision Questions * How often is agent context reconstructed? * How often does scope drift occur? * Does another person need to review the work agreement? * Must prior failed attempts remain inspectable? * Are validation results currently easy to find? * Is the repository the desired system of record? * Would one Basic task solve the problem? * Does the work justify a Structured specification? * Is formal Governed reconciliation required? --- ## 24. Product Proof and Adoption Stories Create a reusable case-record format. ### Required Fields ```text Repository type Team context Agent or assistant used Integration support level Work requested Workflow level Agent mode Evidence profile Declared scope Implementation attempts Changed-path attribution Validation evidence Review outcome Explicit disposition Continuation event Observed benefit Observed cost Unresolved limitations ``` ### Requirements * Do not publish unverified claims. * Distinguish synthetic fixtures from actual adoption. * Distinguish CLI policy exposure from agent behavioral enforcement. * Prefer measurable records over broad testimonials. * Show both benefit and overhead. * Preserve requested-change history where relevant. * Include at least one weak-fit example. * Avoid implying compatibility with every model based only on prompt portability. * Identify whether validation was executed by Day Shift or an external system. * Identify when path attribution remained uncertain. --- ## 25. Content Ownership by Surface ### Homepage Recognize the problem, establish the outcome, show Basic, then introduce Structured as normal planned work. ### Product Page Explain the complete conceptual model and workflow levels. ### Demo Prove workflow behavior and repository evidence. ### Try Day Shift Enable one successful Basic evaluation. ### Structured Getting Started Teach normal specification-backed feature planning. ### Documentation Teach operation and provide reference material. ### Resource Hub Answer recurring practical questions. ### Comparison Pages Explain differences from chat history, issue trackers, pull requests, CI, and agent platforms. ### Agent Documentation Define machine-readable collaboration expectations. ### Architecture Explain internal design and tradeoffs. ### Decisions Preserve technical rationale. ### Known Limitations Describe actual operational, compatibility, and enforcement boundaries. ### Pricing Explain purchase and license behavior. No page should attempt to perform all of these jobs. --- ## 26. Search and Discoverability Requirements * Every documentation page must have a unique descriptive title. * Titles must use user language where possible. * Each page must include a concise summary. * Each page must identify its intended audience. * Each page must identify applicable workflow levels. * Workflow pages must identify prerequisites. * Command pages must identify whether commands are read-only or mutating. * Reference pages must list applicable CLI versions. * Planned commands must not be presented as currently executable. * Deprecated pages must redirect to the current equivalent. * Search results must distinguish human guides from agent instructions. * Agent pages must use consistent metadata. * Technical terms must link to canonical concept pages. * Commands must link to canonical reference entries. * Legacy terminology must redirect to migration guidance. * Search results for “lightweight” must explain the Basic versus Structured mapping rather than blindly redirecting everything to Basic. --- ## 27. Documentation Page Templates ### 27.1 Workflow Page Template Every workflow page must contain: 1. Purpose 2. Workflow level 3. When to use it 4. When not to use it 5. Prerequisites 6. Canonical inputs 7. Read-only steps 8. Mutating steps 9. Expected files 10. Expected outputs 11. Validation evidence 12. Failure conditions 13. Recovery 14. Resulting repository state 15. Next action 16. Promotion or escalation conditions 17. Related reference material ### 27.2 Command Reference Template Every command page must contain: 1. Synopsis 2. Purpose 3. Callable availability, including whether the entry is an executable command, a reserved container, or a registry-only descriptor 4. Read-only or mutating classification 5. Arguments 6. Options 7. Inputs 8. Preconditions 9. Outputs 10. Machine-readable fields 11. Files created, modified, moved, or removed 12. Expected-revision behavior 13. Transaction behavior 14. Exit classifications 15. Idempotency behavior 16. Failure cases 17. Recovery 18. Examples 19. Version availability Command availability, exact flags, and write posture must be checked against `day-shift commands inventory` or `day-shift commands describe`. Reserved command-family containers and registry-only descriptors must not be presented as directly executable commands. ### 27.3 Schema Reference Template Every schema page must contain: 1. Canonical owner 2. Artifact type 3. Schema version 4. Required fields 5. Optional fields 6. Machine-safe enum values 7. Cross-field invariants 8. Revision behavior 9. Compatibility aliases 10. Migration behavior 11. Example 12. Invalid examples ### 27.4 Concept Page Template Every concept page must contain: 1. Plain-language definition 2. Technical definition 3. Why it exists 4. What it does not mean 5. Canonical owner 6. Related commands 7. Related artifacts 8. Common misunderstandings --- ## 28. Migration Requirements ### 28.1 Content Migration * Inventory every current page. * Assign each page one primary job. * Mark each page as retain, merge, rewrite, redirect, archive, or remove. * Preserve stable URLs where practical. * Add redirects for renamed workflow language. * Do not leave duplicate canonical explanations active. * Identify pages that describe unimplemented behavior. * Identify pages that conflate review and mutation. * Identify pages that imply automatic all-command validation execution or obscure the selected execution/import posture. * Identify pages that imply direct universal agent enforcement. ### 28.2 Workflow Terminology Migration Do not apply a one-to-one mapping from “Lightweight” to Basic. Use content-aware mapping: ```text Independent task pair with no required parent → Basic Existing lightweight specification, slice, or direct-task project work → Structured Complete specification, slice, phase, milestone, and task hierarchy → Governed ``` Additional public-language mapping: ```text Standard workflow → Structured or Governed, based on actual hierarchy Full hierarchy → Governed Implementation summary → Keep canonical technical name Implementation evidence → Plain-language explanation of implementation-summary content Execution mode → Evidence profile Approval during review → Read-only review followed by explicit disposition ``` ### 28.3 Documentation Migration * Create Basic and Structured entry paths first. * Create the specification-lifecycle documentation before publishing Structured commands. * Move detailed hierarchy material into Governed documentation. * Split pages that mix human instruction, agent policy, and architecture. * Split review instructions from acceptance or closure instructions. * Preserve historical architecture decisions. * Mark obsolete instructions with affected versions. * Preserve compatibility guidance for legacy `readiness: completed`. * Preserve compatibility guidance for implementation summaries without attempt collections. * Document existing-layout inspection before migration. * Add recovery documentation before publishing transaction-backed mutation flows. --- ## 29. Accessibility and Presentation Requirements * Primary actions must remain visible without horizontal scrolling. * Code examples must remain readable on mobile. * Diagrams must include text equivalents. * Navigation must work without pointer input. * Color must not be the only status indicator. * Workflow levels must use text labels. * Agent modes must not rely only on color or icons. * Read-only and mutating commands must use explicit textual labels. * Expandable technical sections must support keyboard and screen-reader use. * Dense tables must provide mobile alternatives. * Marketing animation must not be required to understand the workflow. * Attempt history must be understandable without timeline animation. * Validation status must use text in addition to visual indicators. --- ## 30. Measurement The revamp must be evaluated through observable completion behavior. ### 30.1 Primary Measures * Percentage of visitors who can correctly describe Day Shift after the homepage. * Percentage who understand that Basic is the fastest path but Structured is the normal specification-backed path. * Percentage of evaluators who complete a Basic task. * Time from installation to first useful Basic result. * Percentage who successfully begin Structured work after Basic evaluation. * Percentage who distinguish review from acceptance. * Percentage who understand that Day Shift records validation evidence but may not execute the command. * Percentage who correctly identify agent-mode enforcement limits. * Percentage of documentation visitors entering through task-oriented paths. * Abandonment before first useful result. * Support questions caused by workflow selection. * Distribution of Basic, Structured, and Governed work. * Number and reason for promotions between levels. ### 30.2 Qualitative Evaluation Questions * What did the visitor think Day Shift replaced? * Did the visitor think Basic was the default? * Did the visitor understand why Structured requires a specification? * Which term first caused confusion? * Did the visitor understand what files would be created? * Did the visitor distinguish review from lifecycle mutation? * Did the visitor understand who executes validation? * Did the workflow appear proportionate? * Could the visitor identify strong or weak fit? * Could the visitor find the correct next page? * Could the visitor explain what another session would read? No third-party analytics service is required. Measurement may be privacy-preserving, self-hosted, manual, or research-session based. --- ## 31. Release and Truthfulness Gates ### 31.1 General Rule No public surface may present a specified capability as shipped until its applicable acceptance criteria are satisfied in the CLI. ### 31.2 Basic Evaluation Gate The Try Day Shift Basic flow may launch only after: * Numbered Basic planning-root allocation works while semantic `task_id` remains unprefixed. * Parentless task-pair creation works. * Readiness review and explicit `task readiness-authorize` work. * Readiness-bound attempt opening works. * Runtime and Hybrid baseline capture occurs only after attempt opening and before implementation writes. * Canonical implementation-summary build works. * Implementation attempts are preserved. * One explicitly selected validation command can execute and record its observed result without a second run; manual and verified external evidence can still be recorded or imported. * `task implementation-complete` enforces evidence and revision preconditions without accepting review or closing the task. * Read-only review works. * Explicit disposition and closeout work. * Current-work and next-action discovery work. ### 31.3 Structured Workflow Gate Structured may be described as available only after: * Canonical `spec create` works. * Specification registration is transaction-backed. * Specification review is read-only. * Complete review results can be persisted. * Planning-readiness disposition works. * Structured default resolution works. * Numbered Structured root allocation works while semantic `work_id` remains unprefixed. * Numbered direct child task creation derives prefixes from parent-local `sequence` while semantic task identity and dependencies remain unprefixed. * Specification revision drift is detected. * `work review` remains read-only. * Canonical `project-review.md` persistence works through a separate explicit write. * `work close` requires current accepted project-review evidence and changes only the selected overview. ### 31.4 Governed Workflow Gate Governed may be described as available only after: * Numbered Governed `slice-overview.md` root creation works without an extra work-overview or nested-slice layer. * Full hierarchy creation reports refinement state and non-executed post-create validation and link handoffs. * Reconciliation build produces review-ready evidence; review remains read-only; explicit receipt-bound acceptance owns completion. * Project review and explicit closeout work. ### 31.5 Promotion Gate Public promotion guidance may launch only after at least one complete promotion path supports: * Preview * Expected-revision checks * Stable identity * Evidence preservation * Transaction-backed apply * Recovery guidance Each remaining promotion path must be labeled according to its actual status. ### 31.6 Agent-Mode Gate Agent-mode behavioral claims require: * CLI policy resolution * Human- and machine-readable output * Versioned Agent Collaboration Protocol * At least one conforming reference integration for behavioral examples Until then, pages may document stored policy without claiming behavioral conformance. ### 31.7 Technical Documentation Gate Reference documentation for a command must exist before the command is linked from introductory pages. ### 31.8 Website and Documentation Repository Quality Gate The public experience may be treated as release-ready only when one documented, CI-enforced application gate proves all of the following against the same source revision: * The canonical documentation generation check, complete documentation test suite, guidance verification, production build, and output verification pass without stale command inventory, product-truth, prompt-discovery, or prompt-upgrade fixtures. * Website lint, type checking, content-policy validation, application validation, unit and contract tests, and production build pass without ignored errors. * Accessibility assertions reflect the rendered interaction contract, including modal or dialog semantics where the interface presents a dialog. * First-contact, Basic evaluation, Structured evaluation, link-materialization, content-rollout, and other generated evidence records are regenerated or deliberately revised with their consuming tests in the same change. * GitHub CI runs the website and documentation gate on pull requests rather than relying on local or release-only execution. --- ## Success Criteria The revamp is complete when: * The homepage communicates the problem, outcome, Basic workflow, and normal Structured workflow without requiring knowledge of the full hierarchy. * One stable product definition is used across primary surfaces. * Basic is described as the fastest path, not the default planning workflow. * Structured is described as the normal specification-backed path and actual default where applicable. * Governed is described as the staged formal path. * The primary navigation supports Understand, Try, and Operate. * The Basic evaluation path does not require a specification, slice, phase, milestone, reconciliation, or generated index. * The Structured path accurately represents canonical specifications and planning-readiness disposition. * The documentation homepage is task-oriented. * Basic, Structured, and Governed each have dedicated documentation. * Human and agent documentation are separated. * Agent-mode and evidence-profile concepts are documented independently. * The CLI enforcement boundary for external agents is stated accurately. * Validation recording and execution are distinguished. * Review and explicit disposition are distinguished. * The implementation summary remains the canonical technical evidence artifact. * Attempt history is explained where retries are documented. * The demo provides Basic outcome, Structured planning, and technical replay modes as their release gates allow. * The Resource Hub is grouped by user problem. * Pricing includes a concrete version-entitlement example. * Known Limitations includes operational and enforcement boundaries. * A fit-assessment page exists. * Current pages have migration actions. * Legacy lightweight content is mapped by actual artifact structure rather than automatically renamed Basic. * Duplicate explanations have canonical owners. * Architecture and decisions remain available. * No introductory page implies replacement of coding assistants, Git, CI, issue tracking, or code review. * No page implies review silently mutates lifecycle state. * No page implies automatic all-command validation execution; any command-owned execution is presented as an explicit selected invocation. * No page implies universal external-agent enforcement. * Unsupported and experimental capabilities are labeled accurately. * Workflow pages identify expected outputs, mutation boundaries, failure conditions, and recovery. * Existing public links redirect where necessary. * Public claims are gated by shipped CLI acceptance criteria. * Documentation generation, tests, guidance verification, build, and output verification pass against current generated inventories and ledgers. * Website lint, type checking, content-policy validation, contract tests, application validation, and build pass in the same CI-enforced public-surface gate. * Accessibility, first-contact, Basic and Structured evaluation, link-materialization, and cross-application rollout evidence remain synchronized with their rendered and generated consumers. --- ## Risks ### Risk: Showing Basic first may imply it is the default Mitigation: * Describe Basic as the fastest path. * Describe Structured as the normal planned-feature path. * State the default explicitly in the workflow comparison. ### Risk: Structured may appear too complex after a simple Basic demo Mitigation: * Keep Structured to specification, overview, and direct tasks. * Defer hierarchy and reconciliation to Governed. * Explain why specification-backed work needs stronger traceability. ### Risk: Simplification may appear to reduce technical differentiation Mitigation: * Preserve detailed technical proof. * Link claims to reproducible evidence. * Introduce revision-aware and transaction-safe behavior after the product outcome. ### Risk: Public workflow labels may diverge from artifact names Mitigation: * Treat workflow level and artifact type as separate concepts. * Preserve canonical artifact names in technical documentation. * Use plain-language explanations rather than replacement technical names. ### Risk: The website may promise unavailable CLI behavior Mitigation: * Apply release gates. * Maintain capability-status metadata. * Do not publish executable commands before they ship. * Label planned features explicitly. ### Risk: Validation language may imply execution Mitigation: * Prefer “validation evidence.” * Identify the executor in demonstrations and case records. * Document the initial recording/import boundary. ### Risk: Agent-mode language may imply enforcement Mitigation: * State the CLI/integration boundary. * Link behavior claims to the Agent Collaboration Protocol. * Restrict behavioral demonstrations to conforming integrations. ### Risk: Review language may imply approval Mitigation: * Label review commands read-only. * Show explicit disposition as a separate step. * Use different interface treatments for findings and mutations. ### Risk: Technical documentation may reproduce internal complexity too early Mitigation: * Keep task-oriented entry pages. * Place implementation attempts, concurrency, and transactions in reference and architecture sections. * Use progressive disclosure. ### Risk: Existing users may rely on current navigation Mitigation: * Preserve redirects. * Publish a migration map. * Retain temporary legacy navigation where necessary. ### Risk: Existing “Lightweight” content may be incorrectly mapped Mitigation: * Inspect actual artifact relationships. * Map independent tasks to Basic. * Map specification-backed direct-task work to Structured. ### Risk: Multiple workflow levels create another decision point Mitigation: * Provide a plain-language selection guide. * Recommend based on observable work characteristics. * Never silently change the user’s explicit level. * Explain that Structured is the safe default for specification-backed work. --- ## 34. Dependencies This specification depends on the parent CLI architecture and its child work packages. ### 34.1 Canonical Specification Lifecycle Required for: * Structured onboarding * Specification creation documentation * Read-only specification review * Persisted review evidence * Planning-readiness disposition * Specification revision drift ### 34.2 Progressive Planning Organization Required for: * Basic, Structured, and Governed public descriptions * Canonical planning paths * Structured default * Work creation * Cross-level discovery * Numbered Basic and Structured root allocation * Parent-local numbered Structured task paths with stable semantic identities ### 34.3 Task Lifecycle and Evidence Required for: * Basic evaluation * Readiness * Implementation attempts * Baselines * Canonical implementation-summary generation * Command-owned validation execution and manual or imported validation evidence * Explicit implementation completion * Review and disposition * Derived next action * Shared waivers ### 34.4 Agent Collaboration Protocol Required for: * Agent-mode documentation * Behavioral examples * Conforming integration claims * Machine-readable orientation ### 34.5 Promotion, Transactions, and Migration Required for: * Promotion guidance * Existing repository migration * Expected-revision behavior * Exact mutation-plan receipt apply * Numbered Basic and Structured compatibility reads and explicit migration * Operational-state documentation * Recovery guidance ### 34.6 Workspace Validation The product must either: * Extend workspace structural validation to inspect canonical specification artifacts under `.day-shift/specs/`, or * Document the exact validation boundary and provide the canonical alternative commands. The current CLI takes the second path: `doctor --artifact` accepts planning-root artifacts and rejects canonical specification paths outside that scope. General doctor checks include specification-registry evidence, but canonical specification bodies are reviewed through `spec review`, with readiness recorded separately through `spec disposition`. The website must not claim workspace-wide validation while specification artifacts remain outside the validator’s discovery scope. ### 34.7 Planning Authoring and Handoff Refinements Specification 29 is required for: * Target child counts and boundary-based decomposition rationale * Per-artifact refinement reporting * Ordered post-create validation and link handoffs * Clear separation between creation and later validation or link writes ### 34.8 Lifecycle Stabilization and Continuation Specifications 30 and 31 are required for: * Topology-aware Basic, Structured, and Governed lifecycle descriptions * CLI-only release-gate playthrough evidence * Resumable lifecycle run manifests and deterministic evidence names * Reconciliation readiness, review, explicit acceptance, and resolved findings * Decision-complete compact output and recovery to paged or full detail * Review-bound deterministic metadata synchronization ### 34.9 Numbered Basic and Structured Planning Trees Specification 32 is required for: * Canonical numbered Basic and Structured root paths * Parent-local numbered direct Structured task paths * Stable unprefixed semantic identities * Compatibility reads and explicit transactional migration guidance --- ## 35. Recommended Implementation Order Implementation begins from the shipped `apps/website` and `apps/docs` baselines. Each stage must first classify existing coverage as retain, revise, redirect, remove, or missing, and may create work only for the verified delta. Completed specification 12, 24, or 25 behavior must not be recreated merely because it appears as a requirement below. ### Stage 1: Content Inventory and Truth Audit * Inventory current pages. * Identify duplicated explanations. * Identify incorrect default-workflow language. * Identify review/write conflation. * Identify automatic all-command validation claims and stale record/import-only claims. * Identify external-agent enforcement claims. * Mark content by shipped-and-retain, shipped-but-revise, planned, deprecated, or unsupported status. * Map every executable example to the current command inventory and specifications 29 through 32. ### Stage 2: Shared Language and Navigation * Recertify and consistently adopt the primary definition. * Recertify and consistently adopt Basic, Structured, and Governed language. * Reconcile existing navigation with the Product, Demo, Try, Documentation, and Pricing model. * Create canonical page ownership. * Create redirects. ### Stage 3: Basic Evaluation Experience After the Basic release gate: * Retain or revise the existing Basic Try path rather than recreating satisfied coverage. * Retain or revise the Basic demo replay. * Fill verified gaps in Basic workflow documentation. * Fill verified gaps in readiness, attempt, validation-evidence, implementation-completion, review, and disposition pages. ### Stage 4: Structured Product Experience After the Structured release gate: * Retain or revise the existing Structured homepage explanation. * Fill verified gaps in Structured getting started, specification lifecycle, planning readiness, and specification-drift documentation. * Add or revise the Structured technical replay against numbered root and task paths. ### Stage 5: Agent and Evidence Documentation * Create agent-mode concept and reference pages. * Create evidence-profile pages. * Create Agent Collaboration Protocol pages. * Add machine-readable output examples. * Add enforcement-boundary language. ### Stage 6: Governed and Promotion Experience After applicable gates: * Add Governed workflow documentation. * Add reconciliation documentation. * Add promotion guidance. * Add promotion demo evidence. * Add migration documentation. ### Stage 7: Commercial and Trust Surfaces * Recertify pricing and revise only verified gaps. * Recertify Known Limitations and revise only verified gaps. * Create fit assessment. * Add compatibility matrix. * Add verified case records. ### Stage 8: Validation and Measurement * Repair and lock the documentation command-inventory, product-truth, prompt-discovery, and prompt-upgrade fixtures to their current generated sources. * Repair website lint and content-policy findings and reconcile accessibility, first-contact, Basic, Structured link-materialization, and cross-application rollout evidence with current behavior. * Add a pull-request CI lane that runs the complete website and documentation quality gate against one revision. * Test homepage comprehension. * Test Basic completion. * Test Structured workflow selection. * Test review/disposition comprehension. * Test validation-execution comprehension. * Test agent-enforcement comprehension. * Correct remaining terminology and navigation failures. --- ## 36. Final Product-Language Contract Introductory public language must preserve this hierarchy: > Day Shift keeps coding-agent plans, scope, validation evidence, and handoff records in the repository. > > Basic is the fastest path for one scoped task. > > Structured is the normal path for planned feature work and the default for specification-backed planning. > > Governed is the staged path for formal review and reconciliation. > > Day Shift records the work agreement and implementation evidence. Review is read-only; acceptance and closure are explicit actions. > > Day Shift exposes collaboration policy to compatible agents but does not grant unlimited authority or force unsupported agents to comply. > > The current Day Shift CLI can explicitly execute and record one selected task validation command, or record or import evidence produced elsewhere. It does not automatically run every declared validation command. Internal identifiers, readiness records, attempt history, revision hashes, transaction state, and lifecycle invariants belong in technical documentation rather than introductory product pages.