{
  "package": {
    "name": "Workshop Handover: Single-Device Local Log (Draft)",
    "kind": "software",
    "oneLiner": "A single-browser, single-device handover log (IndexedDB) capturing equipment, issue, owner, next action, status, timestamp, acknowledge and JSON/CSV export—draft for pilot validation.",
    "problemSpace": {
      "who": "Two-shift small workshop staff and supervising manager responsible for safe, unambiguous maintenance handovers.",
      "pain": "Ambiguous ownership, next action and closure at shift handover causes delays and unclear responsibilities (sample synthetic notes show this ambiguity).",
      "context": "A teaching-case proposal: single shared tablet in the workshop capturing a 6-field minimal record to reduce handover ambiguity; no cloud, auth, notifications or integrations. Software justified only after a paper-checklist pilot.",
      "evidenceNodeIds": [
        "handover-question",
        "sample-handover",
        "handover-concept"
      ]
    },
    "solutionIdea": {
      "summary": "A minimal local-browser app on one shared tablet that stores handover items in IndexedDB, presents unresolved items first, supports an acknowledge action, and exports data as JSON and human-readable CSV for supervisor review and archival.",
      "differentiators": [
        "Single-device, local-only IndexedDB persistence to match workshop constraints and privacy.",
        "Strict six-field minimal model (equipment_label, issue_short, current_owner, next_action, status, timestamp) derived from the idea node.",
        "Designed as a lightweight follow-up to a validated paper checklist; no integrations, auth, notifications or automated decisions."
      ],
      "nonGoals": [
        "No backend, cloud, authentication, sync, notifications, AI, machine control or integrations (explicit exclusion).",
        "Does not include safety sign-off, automated fault diagnosis, or supervisor authority within the app."
      ]
    },
    "concept": {
      "userJourney": [
        "Shift-end operator opens the shared tablet app, creates or updates an item with required fields, app stores item to IndexedDB with system timestamp.",
        "Next-shift opens app; the UI sorts unresolved items first; operator can 'acknowledge' an item (records acknowledge timestamp and initials) or edit next_action and owner.",
        "Supervisor periodically exports JSON/CSV from the device and reviews externally; closure decisions are made outside the app."
      ],
      "successCriteria": [
        "App runs entirely in a modern Chromium-based mobile/desktop browser on a single shared device with local storage only.",
        "IndexedDB persists entries across browser restarts and device power cycles on the same device and origin.",
        "Exports produce a JSON file with full records and a readable CSV mapping the six fields plus acknowledge metadata.",
        "UI orders unresolved items first and exposes an acknowledge action that records user-entered initials and timestamp."
      ]
    },
    "data": {
      "entities": [
        {
          "name": "handover_item",
          "fields": [
            "item_id: uuid (system-generated)",
            "equipment_label: string (required)",
            "issue_short: string (<=140 chars, required)",
            "current_owner: string (initials or name, required)",
            "next_action: string (required)",
            "status: enum [open, awaiting_review, closed] (required)",
            "created_at: ISO8601 timestamp (system)",
            "updated_at: ISO8601 timestamp (system)",
            "acknowledged_by: string (optional initials)",
            "acknowledged_at: ISO8601 timestamp (optional)"
          ],
          "source": "Derived from handover-concept and sample-handover"
        }
      ],
      "sources": [
        {
          "nodeId": "handover-question",
          "use": "Defines problem scope and validation goal"
        },
        {
          "nodeId": "sample-handover",
          "use": "Illustrates ambiguity and minimal fields needed"
        },
        {
          "nodeId": "handover-concept",
          "use": "Specifies single-device constraint and required fields"
        }
      ]
    },
    "architecture": {
      "overview": "Single-page web app (PWA-lite not installed) running in-browser on a single shared device/origin, using IndexedDB (via Dexie.js) for persistence, vanilla JS or a compact framework (Svelte/Preact) for UI, CSV/JSON export to file, no network calls.",
      "components": [
        {
          "name": "UI Shell",
          "responsibility": "Render list, item create/edit form, acknowledge action and export buttons; sort unresolved first",
          "technology": "Svelte or Preact, plain CSS"
        },
        {
          "name": "Local Storage Layer",
          "responsibility": "IndexedDB schema, CRUD, migrations, export serialization",
          "technology": "Dexie.js (or direct IndexedDB API)"
        },
        {
          "name": "Export/Serialization",
          "responsibility": "Produce JSON and human-readable CSV and trigger file download",
          "technology": "JSON.stringify, Blob, FileSaver.js or native anchor download"
        }
      ],
      "interfaces": [
        {
          "from": "UI Shell",
          "to": "Local Storage Layer",
          "protocol": "in-browser JS function calls / Promise API",
          "purpose": "CRUD operations and queries (unresolved-first sort)"
        },
        {
          "from": "UI Shell",
          "to": "Export/Serialization",
          "protocol": "in-memory data serialization",
          "purpose": "Export current dataset to JSON/CSV file"
        }
      ],
      "deployment": "Serve static HTML/CSS/JS files on the shared device filesystem or local file server; open index.html in a modern Chromium-based browser that supports IndexedDB."
    },
    "modules": [
      {
        "id": "m1",
        "name": "Core data model & storage",
        "purpose": "Implement IndexedDB schema, migrations, and API for CRUD and queries (unresolved-first).",
        "dependsOn": []
      },
      {
        "id": "m2",
        "name": "UI and acknowledgement flow",
        "purpose": "List view sorted unresolved-first, create/edit form, acknowledge action recording initials and timestamp.",
        "dependsOn": [
          "m1"
        ]
      },
      {
        "id": "m3",
        "name": "Export & pilot tooling",
        "purpose": "JSON and CSV export, simple pilot-mode telemetry (local only), and paper-checklist comparison view for supervisors.",
        "dependsOn": [
          "m1",
          "m2"
        ]
      }
    ],
    "waves": [
      {
        "title": "Wave 1 — Core storage and basic UI",
        "goal": "Deliver M1 and minimal M2 list/create/acknowledge UI; verify persistence and unresolved-first ordering.",
        "moduleIds": [
          "m1",
          "m2"
        ],
        "mode": "parallel"
      },
      {
        "title": "Wave 2 — Export and pilot support",
        "goal": "Deliver M3 export features, pilot view and finalize acceptance checks for supervised trial.",
        "moduleIds": [
          "m3"
        ],
        "mode": "sequential"
      }
    ],
    "prds": [
      {
        "moduleId": "m1",
        "stories": [
          {
            "id": "S1",
            "title": "IndexedDB schema and CRUD",
            "acceptance": [
              "IndexedDB schema implements handover_item with required fields; records persist after browser restart.",
              "Automated test: write 3 items, reload page, query unresolved items and receive same 3 items."
            ]
          },
          {
            "id": "S2",
            "title": "Unresolved-first query and migration",
            "acceptance": [
              "Query API returns items sorted: open and awaiting_review before closed; stable sorting by updated_at desc within status.",
              "Migration test: simulate older record without acknowledged_at; app upgrades schema without data loss."
            ]
          }
        ]
      },
      {
        "moduleId": "m2",
        "stories": [
          {
            "id": "S3",
            "title": "Create / Edit / Acknowledge UI",
            "acceptance": [
              "User can create an item with all required fields; create sets created_at and updated_at automatically.",
              "Acknowledge action records acknowledged_by and acknowledged_at; UI shows acknowledge metadata.",
              "Manual checklist comparison: map a paper checklist entry to a saved item in-app and verify fields align."
            ]
          },
          {
            "id": "S4",
            "title": "Local usage ergonomics",
            "acceptance": [
              "On-screen form uses compact inputs suitable for tablet; required fields validated client-side.",
              "List view shows clear indicators for status and owner initials."
            ]
          }
        ]
      },
      {
        "moduleId": "m3",
        "stories": [
          {
            "id": "S5",
            "title": "JSON export",
            "acceptance": [
              "Export produces a single JSON file containing all handover_item records including metadata (created_at, updated_at, acknowledged_*).",
              "Downloaded JSON loads back into the app when re-imported (file-based import optional for recovery)."
            ]
          },
          {
            "id": "S6",
            "title": "CSV export and pilot view",
            "acceptance": [
              "Export produces a readable CSV mapping six core fields plus acknowledge metadata; column headers are human-readable.",
              "Pilot view shows side-by-side mapping with the one-page paper checklist fields for supervisor comparison."
            ]
          }
        ]
      }
    ],
    "bom": [],
    "designSystem": {
      "principles": [
        "Minimal: show only required fields and unresolved items up-front.",
        "Robust: work offline and tolerate abrupt app/browser restarts.",
        "Transparent: exports are human-readable and directly comparable to the paper checklist."
      ],
      "tone": "Plain, high-contrast, legible for workshop lighting",
      "colors": [
        "High-contrast text (dark on light), stat"
      ],
      "typography": "System UI fonts, large touch targets for tablet use"
    },
    "agentConcurrency": {
      "maxParallelBuilders": 1,
      "sharedFiles": [
        "schema/indexeddb-schema.json",
        "data-model/handover_item.json",
        "storage/migrations.js"
      ],
      "rules": [
        "Only one builder agent works at a time (serial).",
        "All edits to sharedFiles must be done serially and reviewed by a human before committing.",
        "Feature branches are allowed but merges touching sharedFiles require explicit human merge and sanity check on migration tests."
      ]
    },
    "controlsAndTests": [
      {
        "area": "Persistence",
        "check": "Records persist across browser restart and device power cycle on the same origin",
        "method": "Manual test: create items, close browser, restart, verify items present"
      },
      {
        "area": "Export",
        "check": "JSON and CSV exports contain all fields and are syntactically valid",
        "method": "Automated unit test for JSON validity and CSV header/row counts; manual open of CSV in spreadsheet"
      },
      {
        "area": "Ordering and ACK",
        "check": "UI lists unresolved items first and acknowledge records initials+timestamp",
        "method": "End-to-end manual verification with sample dataset (three items) and UI observation"
      },
      {
        "area": "Paper comparison",
        "check": "App fields map 1:1 to the laminated paper checklist",
        "method": "Supervisor-led mapping session: take 5 recent paper checklist entries and confirm mapping to in-app items"
      }
    ],
    "dependencies": [
      {
        "name": "Dexie.js",
        "kind": "library",
        "reason": "Simplifies IndexedDB schema/migrations and is lightweight for single-device apps"
      },
      {
        "name": "FileSaver.js or native Blob download",
        "kind": "library",
        "reason": "Triggering reliable client-side file downloads for JSON/CSV"
      }
    ],
    "risks": [
      {
        "risk": "No real users interviewed; app may not match real ergonomic needs.",
        "mitigation": "Run short supervised pilot using paper checklist mapping before software pilot; keep UI minimal and iterate."
      },
      {
        "risk": "Single-device usage can fail if tablet is unavailable or browser origin changes.",
        "mitigation": "Provide clear device usage policy and local backup via manual JSON export; test recovery via import."
      }
    ],
    "openQuestions": [
      "What exact tablet model and browser will be used in pilot (affects touch layout and IndexedDB behavior)?",
      "Who will enter initials for acknowledge action and how will identity ambiguity be handled (initials vs full name)?",
      "What duration/size of supervised pilot is considered sufficient by stakeholders to decide for a software build?"
    ],
    "geometry": {
      "parts": []
    },
    "evidenceNodeIds": [
      "handover-question",
      "sample-handover",
      "handover-concept"
    ],
    "specRevision": 1,
    "requirements": [
      {
        "id": "R-001",
        "text": "Implement a local-only handover_item schema in IndexedDB with the six fields (equipment_label, issue_short, current_owner, next_action, status, timestamp) plus acknowledge metadata; no network calls.",
        "acceptance": [
          "IndexedDB contains handover_item records with required fields and acknowledge metadata.",
          "No outbound network/XHR/fetch calls are made during normal CRUD operations (validated via devtools network tab)."
        ],
        "decisionRefs": [],
        "evidenceVersionRefs": [
          {
            "canvas": "my",
            "nodeId": "handover-question",
            "contentRevision": 1
          },
          {
            "canvas": "my",
            "nodeId": "sample-handover",
            "contentRevision": 1
          },
          {
            "canvas": "my",
            "nodeId": "handover-concept",
            "contentRevision": 1
          }
        ],
        "assumptions": [],
        "unresolved": [],
        "reviewState": "needs-review",
        "revision": 1
      },
      {
        "id": "R-002",
        "text": "App UI must display unresolved items first and allow create/edit of the six-field model and an acknowledge action that records initials and timestamp.",
        "acceptance": [
          "List view sorts unresolved statuses (open, awaiting_review) above closed and shows updated_at ordering within each status.",
          "Acknowledge action prompts for initials and stores acknowledged_by and acknowledged_at."
        ],
        "decisionRefs": [],
        "evidenceVersionRefs": [
          {
            "canvas": "my",
            "nodeId": "handover-question",
            "contentRevision": 1
          },
          {
            "canvas": "my",
            "nodeId": "sample-handover",
            "contentRevision": 1
          },
          {
            "canvas": "my",
            "nodeId": "handover-concept",
            "contentRevision": 1
          }
        ],
        "assumptions": [],
        "unresolved": [],
        "reviewState": "needs-review",
        "revision": 1
      },
      {
        "id": "R-003",
        "text": "Provide JSON and human-readable CSV export of the full dataset, downloadable from the device without network usage.",
        "acceptance": [
          "Exported JSON is a valid JSON file containing all handover_item records.",
          "Exported CSV has headers mapping to core fields and can be opened in a spreadsheet application."
        ],
        "decisionRefs": [],
        "evidenceVersionRefs": [
          {
            "canvas": "my",
            "nodeId": "handover-question",
            "contentRevision": 1
          },
          {
            "canvas": "my",
            "nodeId": "sample-handover",
            "contentRevision": 1
          },
          {
            "canvas": "my",
            "nodeId": "handover-concept",
            "contentRevision": 1
          }
        ],
        "assumptions": [],
        "unresolved": [],
        "reviewState": "needs-review",
        "revision": 1
      },
      {
        "id": "R-004",
        "text": "The system must be single-device and local-origin only: deploy as static files to the device and require no backend or cloud services.",
        "acceptance": [
          "All functionality works with files served from local filesystem or static server and without network connectivity.",
          "Devtools network panel shows zero network requests during normal use (except optional manual export/import file reads)."
        ],
        "decisionRefs": [],
        "evidenceVersionRefs": [
          {
            "canvas": "my",
            "nodeId": "handover-question",
            "contentRevision": 1
          },
          {
            "canvas": "my",
            "nodeId": "sample-handover",
            "contentRevision": 1
          },
          {
            "canvas": "my",
            "nodeId": "handover-concept",
            "contentRevision": 1
          }
        ],
        "assumptions": [],
        "unresolved": [],
        "reviewState": "needs-review",
        "revision": 1
      },
      {
        "id": "R-005",
        "text": "The build must include a supervisor-facing paper-checklist comparison view and instructions to run a supervised pilot before committing to broader software development.",
        "acceptance": [
          "UI exposes a pilot view that maps in-app fields to the one-page laminated checklist format.",
          "Documentation includes clear pilot instructions: how to run the paper-checklist mapping session and record outcomes locally."
        ],
        "decisionRefs": [],
        "evidenceVersionRefs": [
          {
            "canvas": "my",
            "nodeId": "handover-question",
            "contentRevision": 1
          },
          {
            "canvas": "my",
            "nodeId": "sample-handover",
            "contentRevision": 1
          },
          {
            "canvas": "my",
            "nodeId": "handover-concept",
            "contentRevision": 1
          }
        ],
        "assumptions": [],
        "unresolved": [],
        "reviewState": "needs-review",
        "revision": 1
      },
      {
        "id": "R-006",
        "text": "Provide developer controls and tests proving persistence, export correctness, unresolved-first ordering and acknowledge behavior before pilot start.",
        "acceptance": [
          "Automated and manual tests cover persistence, export validity, ordering and acknowledge metadata; report produced before pilot.",
          "AgentConcurrency rules enforced: single-builder merge for shared schema/storage files."
        ],
        "decisionRefs": [],
        "evidenceVersionRefs": [
          {
            "canvas": "my",
            "nodeId": "handover-question",
            "contentRevision": 1
          },
          {
            "canvas": "my",
            "nodeId": "sample-handover",
            "contentRevision": 1
          },
          {
            "canvas": "my",
            "nodeId": "handover-concept",
            "contentRevision": 1
          }
        ],
        "assumptions": [],
        "unresolved": [],
        "reviewState": "needs-review",
        "revision": 1
      }
    ]
  },
  "recordedBasis": {
    "contract": "recorded-package-basis",
    "version": 1,
    "scope": {
      "canvas": "my",
      "revision": 2
    },
    "materials": [
      {
        "reference": {
          "nodeId": "handover-question",
          "contentRevision": 1
        },
        "title": "What should the next shift know?",
        "kind": "question",
        "attribution": "",
        "evidenceStatus": ""
      },
      {
        "reference": {
          "nodeId": "sample-handover",
          "contentRevision": 1
        },
        "title": "Three sample handover notes",
        "kind": "observation",
        "attribution": "",
        "evidenceStatus": ""
      },
      {
        "reference": {
          "nodeId": "handover-concept",
          "contentRevision": 1
        },
        "title": "A single-device handover log",
        "kind": "idea",
        "attribution": "",
        "evidenceStatus": ""
      }
    ],
    "concepts": [],
    "humanDecisionRecords": [],
    "qualification": "No linked decision is inferred; review the retained records before treating this draft as a commitment."
  },
  "frozenSpecification": {
    "contract": "frozen-specification-export",
    "contractVersion": 1,
    "authority": "export-only",
    "identity": {
      "packageId": "package:b6fe6405-dc60-4da4-befa-c32d15107462",
      "investigationId": "cookbook-workshop-handover",
      "specRevision": 1,
      "specificationDigest": "5aeb57870ef9f453f68a5acc3b21d64a8aab07a0981f76d2c37dd0a2f5ac2058",
      "created": "2026-10-01T17:34:26.505Z"
    },
    "state": "needs-review",
    "approval": null,
    "package": {
      "name": "Workshop Handover: Single-Device Local Log (Draft)",
      "kind": "software",
      "oneLiner": "A single-browser, single-device handover log (IndexedDB) capturing equipment, issue, owner, next action, status, timestamp, acknowledge and JSON/CSV export—draft for pilot validation.",
      "problemSpace": {
        "who": "Two-shift small workshop staff and supervising manager responsible for safe, unambiguous maintenance handovers.",
        "pain": "Ambiguous ownership, next action and closure at shift handover causes delays and unclear responsibilities (sample synthetic notes show this ambiguity).",
        "context": "A teaching-case proposal: single shared tablet in the workshop capturing a 6-field minimal record to reduce handover ambiguity; no cloud, auth, notifications or integrations. Software justified only after a paper-checklist pilot.",
        "evidenceNodeIds": [
          "handover-question",
          "sample-handover",
          "handover-concept"
        ]
      },
      "solutionIdea": {
        "summary": "A minimal local-browser app on one shared tablet that stores handover items in IndexedDB, presents unresolved items first, supports an acknowledge action, and exports data as JSON and human-readable CSV for supervisor review and archival.",
        "differentiators": [
          "Single-device, local-only IndexedDB persistence to match workshop constraints and privacy.",
          "Strict six-field minimal model (equipment_label, issue_short, current_owner, next_action, status, timestamp) derived from the idea node.",
          "Designed as a lightweight follow-up to a validated paper checklist; no integrations, auth, notifications or automated decisions."
        ],
        "nonGoals": [
          "No backend, cloud, authentication, sync, notifications, AI, machine control or integrations (explicit exclusion).",
          "Does not include safety sign-off, automated fault diagnosis, or supervisor authority within the app."
        ]
      },
      "concept": {
        "userJourney": [
          "Shift-end operator opens the shared tablet app, creates or updates an item with required fields, app stores item to IndexedDB with system timestamp.",
          "Next-shift opens app; the UI sorts unresolved items first; operator can 'acknowledge' an item (records acknowledge timestamp and initials) or edit next_action and owner.",
          "Supervisor periodically exports JSON/CSV from the device and reviews externally; closure decisions are made outside the app."
        ],
        "successCriteria": [
          "App runs entirely in a modern Chromium-based mobile/desktop browser on a single shared device with local storage only.",
          "IndexedDB persists entries across browser restarts and device power cycles on the same device and origin.",
          "Exports produce a JSON file with full records and a readable CSV mapping the six fields plus acknowledge metadata.",
          "UI orders unresolved items first and exposes an acknowledge action that records user-entered initials and timestamp."
        ]
      },
      "data": {
        "entities": [
          {
            "name": "handover_item",
            "fields": [
              "item_id: uuid (system-generated)",
              "equipment_label: string (required)",
              "issue_short: string (<=140 chars, required)",
              "current_owner: string (initials or name, required)",
              "next_action: string (required)",
              "status: enum [open, awaiting_review, closed] (required)",
              "created_at: ISO8601 timestamp (system)",
              "updated_at: ISO8601 timestamp (system)",
              "acknowledged_by: string (optional initials)",
              "acknowledged_at: ISO8601 timestamp (optional)"
            ],
            "source": "Derived from handover-concept and sample-handover"
          }
        ],
        "sources": [
          {
            "nodeId": "handover-question",
            "use": "Defines problem scope and validation goal"
          },
          {
            "nodeId": "sample-handover",
            "use": "Illustrates ambiguity and minimal fields needed"
          },
          {
            "nodeId": "handover-concept",
            "use": "Specifies single-device constraint and required fields"
          }
        ]
      },
      "architecture": {
        "overview": "Single-page web app (PWA-lite not installed) running in-browser on a single shared device/origin, using IndexedDB (via Dexie.js) for persistence, vanilla JS or a compact framework (Svelte/Preact) for UI, CSV/JSON export to file, no network calls.",
        "components": [
          {
            "name": "UI Shell",
            "responsibility": "Render list, item create/edit form, acknowledge action and export buttons; sort unresolved first",
            "technology": "Svelte or Preact, plain CSS"
          },
          {
            "name": "Local Storage Layer",
            "responsibility": "IndexedDB schema, CRUD, migrations, export serialization",
            "technology": "Dexie.js (or direct IndexedDB API)"
          },
          {
            "name": "Export/Serialization",
            "responsibility": "Produce JSON and human-readable CSV and trigger file download",
            "technology": "JSON.stringify, Blob, FileSaver.js or native anchor download"
          }
        ],
        "interfaces": [
          {
            "from": "UI Shell",
            "to": "Local Storage Layer",
            "protocol": "in-browser JS function calls / Promise API",
            "purpose": "CRUD operations and queries (unresolved-first sort)"
          },
          {
            "from": "UI Shell",
            "to": "Export/Serialization",
            "protocol": "in-memory data serialization",
            "purpose": "Export current dataset to JSON/CSV file"
          }
        ],
        "deployment": "Serve static HTML/CSS/JS files on the shared device filesystem or local file server; open index.html in a modern Chromium-based browser that supports IndexedDB."
      },
      "modules": [
        {
          "id": "m1",
          "name": "Core data model & storage",
          "purpose": "Implement IndexedDB schema, migrations, and API for CRUD and queries (unresolved-first).",
          "dependsOn": []
        },
        {
          "id": "m2",
          "name": "UI and acknowledgement flow",
          "purpose": "List view sorted unresolved-first, create/edit form, acknowledge action recording initials and timestamp.",
          "dependsOn": [
            "m1"
          ]
        },
        {
          "id": "m3",
          "name": "Export & pilot tooling",
          "purpose": "JSON and CSV export, simple pilot-mode telemetry (local only), and paper-checklist comparison view for supervisors.",
          "dependsOn": [
            "m1",
            "m2"
          ]
        }
      ],
      "waves": [
        {
          "title": "Wave 1 — Core storage and basic UI",
          "goal": "Deliver M1 and minimal M2 list/create/acknowledge UI; verify persistence and unresolved-first ordering.",
          "moduleIds": [
            "m1",
            "m2"
          ],
          "mode": "parallel"
        },
        {
          "title": "Wave 2 — Export and pilot support",
          "goal": "Deliver M3 export features, pilot view and finalize acceptance checks for supervised trial.",
          "moduleIds": [
            "m3"
          ],
          "mode": "sequential"
        }
      ],
      "prds": [
        {
          "moduleId": "m1",
          "stories": [
            {
              "id": "S1",
              "title": "IndexedDB schema and CRUD",
              "acceptance": [
                "IndexedDB schema implements handover_item with required fields; records persist after browser restart.",
                "Automated test: write 3 items, reload page, query unresolved items and receive same 3 items."
              ]
            },
            {
              "id": "S2",
              "title": "Unresolved-first query and migration",
              "acceptance": [
                "Query API returns items sorted: open and awaiting_review before closed; stable sorting by updated_at desc within status.",
                "Migration test: simulate older record without acknowledged_at; app upgrades schema without data loss."
              ]
            }
          ]
        },
        {
          "moduleId": "m2",
          "stories": [
            {
              "id": "S3",
              "title": "Create / Edit / Acknowledge UI",
              "acceptance": [
                "User can create an item with all required fields; create sets created_at and updated_at automatically.",
                "Acknowledge action records acknowledged_by and acknowledged_at; UI shows acknowledge metadata.",
                "Manual checklist comparison: map a paper checklist entry to a saved item in-app and verify fields align."
              ]
            },
            {
              "id": "S4",
              "title": "Local usage ergonomics",
              "acceptance": [
                "On-screen form uses compact inputs suitable for tablet; required fields validated client-side.",
                "List view shows clear indicators for status and owner initials."
              ]
            }
          ]
        },
        {
          "moduleId": "m3",
          "stories": [
            {
              "id": "S5",
              "title": "JSON export",
              "acceptance": [
                "Export produces a single JSON file containing all handover_item records including metadata (created_at, updated_at, acknowledged_*).",
                "Downloaded JSON loads back into the app when re-imported (file-based import optional for recovery)."
              ]
            },
            {
              "id": "S6",
              "title": "CSV export and pilot view",
              "acceptance": [
                "Export produces a readable CSV mapping six core fields plus acknowledge metadata; column headers are human-readable.",
                "Pilot view shows side-by-side mapping with the one-page paper checklist fields for supervisor comparison."
              ]
            }
          ]
        }
      ],
      "bom": [],
      "designSystem": {
        "principles": [
          "Minimal: show only required fields and unresolved items up-front.",
          "Robust: work offline and tolerate abrupt app/browser restarts.",
          "Transparent: exports are human-readable and directly comparable to the paper checklist."
        ],
        "tone": "Plain, high-contrast, legible for workshop lighting",
        "colors": [
          "High-contrast text (dark on light), stat"
        ],
        "typography": "System UI fonts, large touch targets for tablet use"
      },
      "agentConcurrency": {
        "maxParallelBuilders": 1,
        "sharedFiles": [
          "schema/indexeddb-schema.json",
          "data-model/handover_item.json",
          "storage/migrations.js"
        ],
        "rules": [
          "Only one builder agent works at a time (serial).",
          "All edits to sharedFiles must be done serially and reviewed by a human before committing.",
          "Feature branches are allowed but merges touching sharedFiles require explicit human merge and sanity check on migration tests."
        ]
      },
      "controlsAndTests": [
        {
          "area": "Persistence",
          "check": "Records persist across browser restart and device power cycle on the same origin",
          "method": "Manual test: create items, close browser, restart, verify items present"
        },
        {
          "area": "Export",
          "check": "JSON and CSV exports contain all fields and are syntactically valid",
          "method": "Automated unit test for JSON validity and CSV header/row counts; manual open of CSV in spreadsheet"
        },
        {
          "area": "Ordering and ACK",
          "check": "UI lists unresolved items first and acknowledge records initials+timestamp",
          "method": "End-to-end manual verification with sample dataset (three items) and UI observation"
        },
        {
          "area": "Paper comparison",
          "check": "App fields map 1:1 to the laminated paper checklist",
          "method": "Supervisor-led mapping session: take 5 recent paper checklist entries and confirm mapping to in-app items"
        }
      ],
      "dependencies": [
        {
          "name": "Dexie.js",
          "kind": "library",
          "reason": "Simplifies IndexedDB schema/migrations and is lightweight for single-device apps"
        },
        {
          "name": "FileSaver.js or native Blob download",
          "kind": "library",
          "reason": "Triggering reliable client-side file downloads for JSON/CSV"
        }
      ],
      "risks": [
        {
          "risk": "No real users interviewed; app may not match real ergonomic needs.",
          "mitigation": "Run short supervised pilot using paper checklist mapping before software pilot; keep UI minimal and iterate."
        },
        {
          "risk": "Single-device usage can fail if tablet is unavailable or browser origin changes.",
          "mitigation": "Provide clear device usage policy and local backup via manual JSON export; test recovery via import."
        }
      ],
      "openQuestions": [
        "What exact tablet model and browser will be used in pilot (affects touch layout and IndexedDB behavior)?",
        "Who will enter initials for acknowledge action and how will identity ambiguity be handled (initials vs full name)?",
        "What duration/size of supervised pilot is considered sufficient by stakeholders to decide for a software build?"
      ],
      "geometry": {
        "parts": []
      },
      "evidenceNodeIds": [
        "handover-question",
        "sample-handover",
        "handover-concept"
      ],
      "specRevision": 1,
      "requirements": [
        {
          "id": "R-001",
          "text": "Implement a local-only handover_item schema in IndexedDB with the six fields (equipment_label, issue_short, current_owner, next_action, status, timestamp) plus acknowledge metadata; no network calls.",
          "acceptance": [
            "IndexedDB contains handover_item records with required fields and acknowledge metadata.",
            "No outbound network/XHR/fetch calls are made during normal CRUD operations (validated via devtools network tab)."
          ],
          "decisionRefs": [],
          "evidenceVersionRefs": [
            {
              "canvas": "my",
              "nodeId": "handover-question",
              "contentRevision": 1
            },
            {
              "canvas": "my",
              "nodeId": "sample-handover",
              "contentRevision": 1
            },
            {
              "canvas": "my",
              "nodeId": "handover-concept",
              "contentRevision": 1
            }
          ],
          "assumptions": [],
          "unresolved": [],
          "reviewState": "needs-review",
          "revision": 1
        },
        {
          "id": "R-002",
          "text": "App UI must display unresolved items first and allow create/edit of the six-field model and an acknowledge action that records initials and timestamp.",
          "acceptance": [
            "List view sorts unresolved statuses (open, awaiting_review) above closed and shows updated_at ordering within each status.",
            "Acknowledge action prompts for initials and stores acknowledged_by and acknowledged_at."
          ],
          "decisionRefs": [],
          "evidenceVersionRefs": [
            {
              "canvas": "my",
              "nodeId": "handover-question",
              "contentRevision": 1
            },
            {
              "canvas": "my",
              "nodeId": "sample-handover",
              "contentRevision": 1
            },
            {
              "canvas": "my",
              "nodeId": "handover-concept",
              "contentRevision": 1
            }
          ],
          "assumptions": [],
          "unresolved": [],
          "reviewState": "needs-review",
          "revision": 1
        },
        {
          "id": "R-003",
          "text": "Provide JSON and human-readable CSV export of the full dataset, downloadable from the device without network usage.",
          "acceptance": [
            "Exported JSON is a valid JSON file containing all handover_item records.",
            "Exported CSV has headers mapping to core fields and can be opened in a spreadsheet application."
          ],
          "decisionRefs": [],
          "evidenceVersionRefs": [
            {
              "canvas": "my",
              "nodeId": "handover-question",
              "contentRevision": 1
            },
            {
              "canvas": "my",
              "nodeId": "sample-handover",
              "contentRevision": 1
            },
            {
              "canvas": "my",
              "nodeId": "handover-concept",
              "contentRevision": 1
            }
          ],
          "assumptions": [],
          "unresolved": [],
          "reviewState": "needs-review",
          "revision": 1
        },
        {
          "id": "R-004",
          "text": "The system must be single-device and local-origin only: deploy as static files to the device and require no backend or cloud services.",
          "acceptance": [
            "All functionality works with files served from local filesystem or static server and without network connectivity.",
            "Devtools network panel shows zero network requests during normal use (except optional manual export/import file reads)."
          ],
          "decisionRefs": [],
          "evidenceVersionRefs": [
            {
              "canvas": "my",
              "nodeId": "handover-question",
              "contentRevision": 1
            },
            {
              "canvas": "my",
              "nodeId": "sample-handover",
              "contentRevision": 1
            },
            {
              "canvas": "my",
              "nodeId": "handover-concept",
              "contentRevision": 1
            }
          ],
          "assumptions": [],
          "unresolved": [],
          "reviewState": "needs-review",
          "revision": 1
        },
        {
          "id": "R-005",
          "text": "The build must include a supervisor-facing paper-checklist comparison view and instructions to run a supervised pilot before committing to broader software development.",
          "acceptance": [
            "UI exposes a pilot view that maps in-app fields to the one-page laminated checklist format.",
            "Documentation includes clear pilot instructions: how to run the paper-checklist mapping session and record outcomes locally."
          ],
          "decisionRefs": [],
          "evidenceVersionRefs": [
            {
              "canvas": "my",
              "nodeId": "handover-question",
              "contentRevision": 1
            },
            {
              "canvas": "my",
              "nodeId": "sample-handover",
              "contentRevision": 1
            },
            {
              "canvas": "my",
              "nodeId": "handover-concept",
              "contentRevision": 1
            }
          ],
          "assumptions": [],
          "unresolved": [],
          "reviewState": "needs-review",
          "revision": 1
        },
        {
          "id": "R-006",
          "text": "Provide developer controls and tests proving persistence, export correctness, unresolved-first ordering and acknowledge behavior before pilot start.",
          "acceptance": [
            "Automated and manual tests cover persistence, export validity, ordering and acknowledge metadata; report produced before pilot.",
            "AgentConcurrency rules enforced: single-builder merge for shared schema/storage files."
          ],
          "decisionRefs": [],
          "evidenceVersionRefs": [
            {
              "canvas": "my",
              "nodeId": "handover-question",
              "contentRevision": 1
            },
            {
              "canvas": "my",
              "nodeId": "sample-handover",
              "contentRevision": 1
            },
            {
              "canvas": "my",
              "nodeId": "handover-concept",
              "contentRevision": 1
            }
          ],
          "assumptions": [],
          "unresolved": [],
          "reviewState": "needs-review",
          "revision": 1
        }
      ]
    },
    "requirements": [
      {
        "id": "R-001",
        "text": "Implement a local-only handover_item schema in IndexedDB with the six fields (equipment_label, issue_short, current_owner, next_action, status, timestamp) plus acknowledge metadata; no network calls.",
        "acceptance": [
          "IndexedDB contains handover_item records with required fields and acknowledge metadata.",
          "No outbound network/XHR/fetch calls are made during normal CRUD operations (validated via devtools network tab)."
        ],
        "decisionRefs": [],
        "evidenceVersionRefs": [
          {
            "canvas": "my",
            "nodeId": "handover-question",
            "contentRevision": 1
          },
          {
            "canvas": "my",
            "nodeId": "sample-handover",
            "contentRevision": 1
          },
          {
            "canvas": "my",
            "nodeId": "handover-concept",
            "contentRevision": 1
          }
        ],
        "assumptions": [],
        "unresolved": [],
        "reviewState": "needs-review",
        "revision": 1
      },
      {
        "id": "R-002",
        "text": "App UI must display unresolved items first and allow create/edit of the six-field model and an acknowledge action that records initials and timestamp.",
        "acceptance": [
          "List view sorts unresolved statuses (open, awaiting_review) above closed and shows updated_at ordering within each status.",
          "Acknowledge action prompts for initials and stores acknowledged_by and acknowledged_at."
        ],
        "decisionRefs": [],
        "evidenceVersionRefs": [
          {
            "canvas": "my",
            "nodeId": "handover-question",
            "contentRevision": 1
          },
          {
            "canvas": "my",
            "nodeId": "sample-handover",
            "contentRevision": 1
          },
          {
            "canvas": "my",
            "nodeId": "handover-concept",
            "contentRevision": 1
          }
        ],
        "assumptions": [],
        "unresolved": [],
        "reviewState": "needs-review",
        "revision": 1
      },
      {
        "id": "R-003",
        "text": "Provide JSON and human-readable CSV export of the full dataset, downloadable from the device without network usage.",
        "acceptance": [
          "Exported JSON is a valid JSON file containing all handover_item records.",
          "Exported CSV has headers mapping to core fields and can be opened in a spreadsheet application."
        ],
        "decisionRefs": [],
        "evidenceVersionRefs": [
          {
            "canvas": "my",
            "nodeId": "handover-question",
            "contentRevision": 1
          },
          {
            "canvas": "my",
            "nodeId": "sample-handover",
            "contentRevision": 1
          },
          {
            "canvas": "my",
            "nodeId": "handover-concept",
            "contentRevision": 1
          }
        ],
        "assumptions": [],
        "unresolved": [],
        "reviewState": "needs-review",
        "revision": 1
      },
      {
        "id": "R-004",
        "text": "The system must be single-device and local-origin only: deploy as static files to the device and require no backend or cloud services.",
        "acceptance": [
          "All functionality works with files served from local filesystem or static server and without network connectivity.",
          "Devtools network panel shows zero network requests during normal use (except optional manual export/import file reads)."
        ],
        "decisionRefs": [],
        "evidenceVersionRefs": [
          {
            "canvas": "my",
            "nodeId": "handover-question",
            "contentRevision": 1
          },
          {
            "canvas": "my",
            "nodeId": "sample-handover",
            "contentRevision": 1
          },
          {
            "canvas": "my",
            "nodeId": "handover-concept",
            "contentRevision": 1
          }
        ],
        "assumptions": [],
        "unresolved": [],
        "reviewState": "needs-review",
        "revision": 1
      },
      {
        "id": "R-005",
        "text": "The build must include a supervisor-facing paper-checklist comparison view and instructions to run a supervised pilot before committing to broader software development.",
        "acceptance": [
          "UI exposes a pilot view that maps in-app fields to the one-page laminated checklist format.",
          "Documentation includes clear pilot instructions: how to run the paper-checklist mapping session and record outcomes locally."
        ],
        "decisionRefs": [],
        "evidenceVersionRefs": [
          {
            "canvas": "my",
            "nodeId": "handover-question",
            "contentRevision": 1
          },
          {
            "canvas": "my",
            "nodeId": "sample-handover",
            "contentRevision": 1
          },
          {
            "canvas": "my",
            "nodeId": "handover-concept",
            "contentRevision": 1
          }
        ],
        "assumptions": [],
        "unresolved": [],
        "reviewState": "needs-review",
        "revision": 1
      },
      {
        "id": "R-006",
        "text": "Provide developer controls and tests proving persistence, export correctness, unresolved-first ordering and acknowledge behavior before pilot start.",
        "acceptance": [
          "Automated and manual tests cover persistence, export validity, ordering and acknowledge metadata; report produced before pilot.",
          "AgentConcurrency rules enforced: single-builder merge for shared schema/storage files."
        ],
        "decisionRefs": [],
        "evidenceVersionRefs": [
          {
            "canvas": "my",
            "nodeId": "handover-question",
            "contentRevision": 1
          },
          {
            "canvas": "my",
            "nodeId": "sample-handover",
            "contentRevision": 1
          },
          {
            "canvas": "my",
            "nodeId": "handover-concept",
            "contentRevision": 1
          }
        ],
        "assumptions": [],
        "unresolved": [],
        "reviewState": "needs-review",
        "revision": 1
      }
    ],
    "recordedBasis": {
      "contract": "recorded-package-basis",
      "version": 1,
      "scope": {
        "canvas": "my",
        "revision": 2
      },
      "materials": [
        {
          "reference": {
            "canvas": "my",
            "nodeId": "handover-question",
            "contentRevision": 1
          },
          "title": "What should the next shift know?",
          "kind": "question",
          "attribution": "",
          "evidenceStatus": ""
        },
        {
          "reference": {
            "canvas": "my",
            "nodeId": "sample-handover",
            "contentRevision": 1
          },
          "title": "Three sample handover notes",
          "kind": "observation",
          "attribution": "",
          "evidenceStatus": ""
        },
        {
          "reference": {
            "canvas": "my",
            "nodeId": "handover-concept",
            "contentRevision": 1
          },
          "title": "A single-device handover log",
          "kind": "idea",
          "attribution": "",
          "evidenceStatus": ""
        }
      ],
      "concepts": [],
      "humanDecisionRecords": [],
      "qualification": "No linked decision is inferred; review the retained records before treating this draft as a commitment."
    },
    "evidence": [
      {
        "id": "handover-question",
        "kind": "question",
        "title": "What should the next shift know?",
        "url": "",
        "contentRevision": 1
      },
      {
        "id": "sample-handover",
        "kind": "observation",
        "title": "Three sample handover notes",
        "url": "",
        "contentRevision": 1
      },
      {
        "id": "handover-concept",
        "kind": "idea",
        "title": "A single-device handover log",
        "url": "",
        "contentRevision": 1
      }
    ],
    "referenceAvailability": [
      {
        "reference": {
          "canvas": "my",
          "nodeId": "handover-question",
          "contentRevision": 1
        },
        "status": "current"
      },
      {
        "reference": {
          "canvas": "my",
          "nodeId": "sample-handover",
          "contentRevision": 1
        },
        "status": "current"
      },
      {
        "reference": {
          "canvas": "my",
          "nodeId": "handover-concept",
          "contentRevision": 1
        },
        "status": "current"
      }
    ],
    "disclosures": {
      "assumptions": [],
      "unansweredQuestions": [
        "What exact tablet model and browser will be used in pilot (affects touch layout and IndexedDB behavior)?",
        "Who will enter initials for acknowledge action and how will identity ambiguity be handled (initials vs full name)?",
        "What duration/size of supervised pilot is considered sufficient by stakeholders to decide for a software build?"
      ],
      "risks": [
        "No real users interviewed; app may not match real ergonomic needs. — Run short supervised pilot using paper checklist mapping before software pilot; keep UI minimal and iterate.",
        "Single-device usage can fail if tablet is unavailable or browser origin changes. — Provide clear device usage policy and local backup via manual JSON export; test recovery via import."
      ],
      "acceptedRisks": [],
      "missingDecisionRequirementIds": [
        "R-001",
        "R-002",
        "R-003",
        "R-004",
        "R-005",
        "R-006"
      ],
      "pendingRequirementIds": [
        "R-001",
        "R-002",
        "R-003",
        "R-004",
        "R-005",
        "R-006"
      ],
      "hasUnavailablePrivateMaterial": false
    }
  },
  "evidence": [
    {
      "id": "handover-question",
      "kind": "question",
      "title": "What should the next shift know?",
      "url": "",
      "sourceVersionId": null,
      "contentRevision": 1
    },
    {
      "id": "sample-handover",
      "kind": "observation",
      "title": "Three sample handover notes",
      "url": "",
      "sourceVersionId": null,
      "contentRevision": 1
    },
    {
      "id": "handover-concept",
      "kind": "idea",
      "title": "A single-device handover log",
      "url": "",
      "sourceVersionId": null,
      "contentRevision": 1
    }
  ],
  "investigationId": "cookbook-workshop-handover",
  "runId": "b6fe6405-dc60-4da4-befa-c32d15107462",
  "receiptId": "receipt:0e0a02df-5af6-4373-870e-4198b94aedbd",
  "created": "2026-10-01T17:34:26.505Z"
}