From c8e9d5085a49b44dcac8fc3102787ba95e6488ee Mon Sep 17 00:00:00 2001 From: Viwat Vchirawongkwin Date: Fri, 25 Sep 2026 17:01:08 +0700 Subject: [PATCH 1/9] [docs] record strategy and Cycle 1 Scrum delivery baseline Signed-off-by: Viwat Vchirawongkwin --- .../01_Overview_and_Scrum_Framework.md | 144 +++ .../02_Product_Roadmap.md | 142 +++ .../03_Milestones.md | 138 +++ .../04_Sprint_Plan.md | 108 ++ .../05_Product_Backlog_and_Stories.md | 220 ++++ .../06_Sprint_Backlogs.md | 225 +++++ ...E_Implementation_Plan_and_Strategy_v1.0.md | 949 ++++++++++++++++++ 7 files changed, 1926 insertions(+) create mode 100644 docs/developments/2026-q4-reliable-workflow/01_Overview_and_Scrum_Framework.md create mode 100644 docs/developments/2026-q4-reliable-workflow/02_Product_Roadmap.md create mode 100644 docs/developments/2026-q4-reliable-workflow/03_Milestones.md create mode 100644 docs/developments/2026-q4-reliable-workflow/04_Sprint_Plan.md create mode 100644 docs/developments/2026-q4-reliable-workflow/05_Product_Backlog_and_Stories.md create mode 100644 docs/developments/2026-q4-reliable-workflow/06_Sprint_Backlogs.md create mode 100644 docs/planning/PyBLE_Implementation_Plan_and_Strategy_v1.0.md diff --git a/docs/developments/2026-q4-reliable-workflow/01_Overview_and_Scrum_Framework.md b/docs/developments/2026-q4-reliable-workflow/01_Overview_and_Scrum_Framework.md new file mode 100644 index 00000000..bef0dccf --- /dev/null +++ b/docs/developments/2026-q4-reliable-workflow/01_Overview_and_Scrum_Framework.md @@ -0,0 +1,144 @@ + + + +# Cycle 1 — delivery guide and Scrum working agreement + +## Document control + +| Field | Value | +|---|---| +| Package | PyBLE 2026 Q4 reliable workflow, Cycle 1 (`C1`) | +| Prepared | 25 September 2026; Asia/Bangkok | +| Strategy | [Implementation Plan, revision 1.2](../../planning/PyBLE_Implementation_Plan_and_Strategy_v1.0.md) | +| Repository baseline | `23ed764b0ef88dce9720c66fbd1c0655268860cf` | +| Proposed cycle | 28 September–20 December 2026; six two-week Sprints | +| Status | Proposed delivery package; no Sprint Planning, estimates, named assignments, implementation approval, or new physical results are implied | +| Primary audience | Tablet-owning makers, provisionally; confirm one reachable cohort before observation | +| Authoritative contracts | [Contributor rules](../../../AGENTS.md), [App specification](../../specifications/App/specs.md), [App TDD](../../specifications/App/TDD.md), [PBLE/1](../../specifications/protocol.md), and applicable firmware/release specifications | + +This package derives execution views from the strategy. It does not replace normative specifications, expand hardware claims, create GitHub issues, or authorize store/website publication. The strategy file is currently a local document; include it with this package when proposing the documentation for version control. + +## Navigation and ownership of information + +| File | Canonical responsibility in this package | Update trigger | +|---|---|---| +| [01 — Overview and Scrum framework](01_Overview_and_Scrum_Framework.md) | Product Goal, working agreement, quality and evidence rules | Agreement or governing contract changes | +| [02 — Product roadmap](02_Product_Roadmap.md) | Outcomes, horizons, and conditional investments | Product Goal or strategic priority changes | +| [03 — Milestones](03_Milestones.md) | Evidence-based decisions and admission criteria | New evidence or a milestone decision | +| [04 — Sprint plan](04_Sprint_Plan.md) | Sprint Goal forecasts, calendar, and capacity | Sprint Planning or Sprint Review | +| [05 — Product backlog and stories](05_Product_Backlog_and_Stories.md) | Ordered work, parent/child identities, acceptance criteria, and source traceability | Refinement or changed user evidence | +| [06 — Sprint backlogs](06_Sprint_Backlogs.md) | Candidate tasks, local effort allowances, dependencies, and execution status | Developers select/adapt work during a Sprint | + +```mermaid +flowchart LR + Strategy["Strategy revision 1.2"] --> Goal["One Product Goal"] + Goal --> Roadmap["Outcome roadmap and milestones"] + Roadmap --> Product["Ordered Product Backlog"] + Product --> Planning["Sprint Planning"] + Planning --> Sprint["Sprint Goal and Sprint Backlog"] + Sprint --> Increment["Increment meeting Definition of Done"] + Increment --> Review["Sprint Review: inspect evidence"] + Review --> Product + Review --> Roadmap + Sprint --> Retro["Retrospective: improve how we work"] + Retro --> Planning +``` + +## Product Goal and current baseline + +**Proposed Product Goal:** tablet-owning makers can complete useful BLE board work, recover their local work after interruption, and choose PyBLE again for a relevant task using accurately identified app and firmware builds. + +| Active outcome | Main planning parents | Evidence of value | +|---|---|---| +| Know what users install | PYB-001; residual PYB-002 only | Reproducible installation guidance and dated channel/build evidence | +| Preserve users' work | PYB-006, supported by PYB-008/009 | Accepted draft survives the specified restart/failure cases without implicit board writes | +| Complete useful repeat tasks | PYB-003/004/011/012; PYB-005 if observed | Task C attempts, later-day useful work, reasons to choose PyBLE, and support effort | + +| Baseline fact | Consequence | +|---|---| +| Android open-testing copy correction is complete in PR #33 | Do not replan that correction; identify any new discrepancy separately | +| App source is `0.2.0+8`; Play publicly identifies `0.2.0`; iPad remains external TestFlight beta | Source version does not prove the installed store binary or its source commit | +| Firmware v0.6.1 is published on owner confirmation across five exact profiles | Pending automated results stay pending; no automatic PyBLE Ready badge | +| Issue #24 is closed/superseded | Do not resurrect its old release umbrella as a dependency | +| Editor draft is volatile under [ADR-0010](../../decisions/0010-working-loop-in-memory-document.md) | Close an accepted subset of A-24; do not claim full project persistence or Blocks recovery | +| Lifecycle protections, tutorials, imports, and test tools already exist | Reuse them; refine only observed gaps and the documented persistence gap | + +## Applying Scrum to PyBLE + +The [2020 Scrum Guide](https://scrumguides.org/scrum-guide.html) is the framework reference. The Product Backlog is ordered by the Product Owner; Developers select and adapt Sprint work. Product Goal, Sprint Goal, and Definition of Done guide the respective artifacts. A Sprint Review inspects progress and informs adaptation; it is not a mandatory release approval meeting. Roadmaps, milestones, user-story notation, and hour allowances below are PyBLE planning practices, not additional Scrum requirements. + +| Accountability | Proposed PyBLE arrangement | Assignment state | +|---|---|---| +| Product Owner | One maintainer accountable for the Product Goal, backlog order, and stakeholder tradeoffs | Named person TBD | +| Scrum Master | Facilitates effective Scrum, impediment removal, and sustainable delivery | Named person TBD; any combined responsibility must be explicit | +| Developers | Contributors collectively plan and deliver work, including applicable tests and evidence | Actual availability and skills TBD | +| Stakeholders/contributors | Release owner, board operator, pilot coordinator, instructor, and language reviewer supply expertise/access | These contribution responsibilities do not create extra Scrum accountabilities | + +Do not represent a solo-maintainer workflow with missing accountabilities as a fully staffed Scrum Team. Record the practical arrangement and its limits. Role labels in tables are suggestions, not assignments to absent people. A coding agent does not supply independent physical evidence or become the accountable Product Owner. + +| Event/practice | Proposed local cadence | Concrete output | Capacity treatment | +|---|---|---|---| +| Sprint Planning | First working day; initially allow 60 minutes | One Sprint Goal, selected items, task plan, named capacity and dependencies | Inside the Sprint's gross hours | +| Daily Scrum | 15 minutes each working day | Developers inspect the Goal and adapt the immediate plan | Inside the Sprint's gross hours | +| Sprint Review | Last working day; initially allow 60 minutes | Inspect usable Increment and evidence with stakeholders; adapt backlog | Inside the Sprint's gross hours | +| Sprint Retrospective | After Review; initially allow 45 minutes | One improvement to apply in the next Sprint | Inside the Sprint's gross hours | +| Refinement | Up to one hour weekly initially, adjusted to need | Split/clarify upcoming items; Developers size their work | Included within available capacity; no separate approval ceremony | + +These local durations can change with the team; the Daily Scrum remains 15 minutes. The 14-hour reserve per Sprint includes events, refinement, support, additional qualification, and uncertainty. Do not count those hours again as extra delivery capacity. + +## Local readiness and Definition of Done + +| Before selection: local readiness aid | Required clarification | +|---|---| +| User outcome or learning question | Named beneficiary, observed problem, bounded in/out scope | +| Governing contract | Specification/ADR and prior approval required for behavior changes; any carried exception visible | +| Acceptance and evidence | Observable scenarios, relevant tests, physical devices when required, evidence location | +| Feasibility | Developers' estimate, actual owner/access, dependencies, safe rollback/recovery | + +Readiness is a local refinement aid. It does not replace Sprint Planning or add a formal Scrum commitment. Unknowns can be selected as time-boxed discovery items with their own explicit output. + +| Definition of Done: applicable requirement | Evidence required | +|---|---| +| Behavioral scope agrees with the accepted contract | Specification/ADR changed before implementation where required; all selected acceptance scenarios satisfied | +| Behavior is verified | Required `[red]` then `[green]` work, relevant regression checks, and mandatory physical evidence for the selected scope; refactor only while green | +| Repository boundaries hold | DCO-signed commits when committing; no-leak, license, dependency, localization/import, and actual required CI checks as applicable | +| Increment is coherent and usable | Review completed; integration and relevant documentation agree; no unresolved blocking data-loss or unintended-write defect | +| Claims have evidence | Exact artifacts, pass/fail/not-run states, limitations and pending release work recorded truthfully | +| Documentation/discovery scope is complete | Usable reviewed record/guide or agreed findings, source/link checks, and explicit unmet targets; no invented physical results | + +This is the proposed package-wide minimum; accepted normative requirements remain binding. Apply it to the selected item rather than treating a source merge as a finished feature. A documentation or discovery item can be Done with a negative finding, while a required physical-installation task cannot be Done if no installation happened. A usable Sprint 1 documentation increment should help an operator or user perform the current workflow; an internal plan alone is not evidence of improved app behavior. + +| State distinction | Meaning | +|---|---| +| Source complete | Implementation/review work reached its source milestone; required physical or integration work may still prevent Done | +| Done Increment | Selected acceptance and applicable Definition of Done are met; it can be inspected and used in its declared scope | +| Release admitted | All applicable release-level gates, support matrix, provenance and distribution prerequisites pass | +| Submitted / available / installed | Three different distribution observations, each requiring its own evidence | + +Unfinished items return to the Product Backlog for reordering and replanning. Do not count them as Done or convert a blocked result into a pass. A release can happen during any Sprint when its applicable gates pass; recruitment and retention do not block an otherwise qualified maintenance release. + +## IDs, evidence, and change control + +| Convention | Rule | +|---|---| +| `PYB-001` … `PYB-032` | Existing strategy planning parents; not GitHub issue numbers | +| `PYB-006.1`, `PYB-006.2`, etc. | Derived child items in this package; acceptance is maintained in file 05 | +| `A-24` | Existing broader persistence story; a bounded child does not complete all of it | +| `C1-S1` … `C1-S6` | This cycle's Sprints; distinct from historical App TDD Sprint labels | +| `C1-S1-T01`, etc. | Proposed task rows; not new public contracts | +| `M-01`, etc.; `SG0` … `SG6` | Delivery milestones versus strategy gates; neither replaces CI G0/G1 or C3 firmware gates | +| Item/task status | Proposed → Selected at Planning → In progress → Review → Done; Blocked records a reason/owner; later forecasts remain Proposed | +| Private versus public records | Contact/consent, device identifiers and raw logs remain private/ignored; publish only reviewed aggregate findings and redacted evidence | + +When facts or priority change, update the canonical file above and its dependent tables together. Preserve old evidence and dated decisions. New opcode/capability values, hardware support, Ready awards, and publication need their normal specification and authorization paths; none is inferred from this package. + +## Source map + +| Source | Use and precedence | +|---|---| +| [Strategy revision 1.2](../../planning/PyBLE_Implementation_Plan_and_Strategy_v1.0.md) | Scope, targets, six-Sprint capacity, three outcomes, Ready program and conditional horizons | +| [Public roadmap](../../ROADMAP.md), [README](../../../README.md) | Current capability and distribution baseline | +| [App specification](../../specifications/App/specs.md), [App TDD](../../specifications/App/TDD.md), [ADR-0010](../../decisions/0010-working-loop-in-memory-document.md) | Persistence contract and recorded implementation deviation; consult frozen working-loop scope | +| [Firmware roadmap](../../planning/firmware-v0.6.1-v0.7.0-roadmap.md), [PBLE/1](../../specifications/protocol.md) | v0.7 proposals versus frozen wire behavior; old v0.6.1 publication/#24 wording is historical | +| [Android publication review](../../testing/website/android-open-testing-2026-09-25.md), [v0.6.1 publication record](../../testing/firmware-v0.6.1-publication-2026-09-11.md) | Dated evidence; neither establishes a newly installed binary or missing automated qualification | +| [HIL guide](../../../tests/firmware_tests/hil/README.md), [CI workflow](../../../.github/workflows/ci.yml), [CONTRIBUTING](../../../CONTRIBUTING.md) | Reuse existing tools and gates; actual CI requirements govern merges | diff --git a/docs/developments/2026-q4-reliable-workflow/02_Product_Roadmap.md b/docs/developments/2026-q4-reliable-workflow/02_Product_Roadmap.md new file mode 100644 index 00000000..7af8ae80 --- /dev/null +++ b/docs/developments/2026-q4-reliable-workflow/02_Product_Roadmap.md @@ -0,0 +1,142 @@ + + + +# 02 — Product roadmap + +| Control | Value | +|---|---| +| Status | Proposed; product direction and forecasts, not approved feature or release commitments | +| Planning date | 25 September 2026; dates use Asia/Bangkok | +| Source | [Implementation strategy revision 1.2](../../planning/PyBLE_Implementation_Plan_and_Strategy_v1.0.md), particularly §§1, 6–9, 12, 14, and 19 | +| Inspected baseline | `main` at `23ed764b0ef88dce9720c66fbd1c0655268860cf` | +| First cycle | C1: 28 September–20 December 2026; later horizons conditional through September 2028 | +| Planning authority | Product Owner orders the Product Backlog; Developers forecast feasible work during Sprint Planning; names and capacity remain unassigned | +| Related documents | [Framework](01_Overview_and_Scrum_Framework.md), [milestones](03_Milestones.md), [Sprint Plan](04_Sprint_Plan.md), [stories](05_Product_Backlog_and_Stories.md), [Sprint Backlogs](06_Sprint_Backlogs.md) | + +## Product Goal and decision principle + +**Proposed Product Goal:** tablet-owning makers can complete useful BLE board work, +recover local work after interruption, and choose PyBLE again for another relevant +task using accurately identified app and firmware. + +The first cohort remains provisional until recruitment and task selection are +confirmed. The Product Goal guides Product Backlog ordering; individual stories +and forecast dates can change as evidence improves. The [public roadmap](../../ROADMAP.md) +continues to communicate direction without promising release dates. + +| Decision | Product value | Evidence that informs the next choice | +|---|---|---| +| Verify what users install | Users find an accurate installation path and support can identify their environment | Dated channel, installed version/build, provenance limits, and unresolved fields with owners | +| Preserve users' work | An interrupted tablet session does not silently discard the accepted local draft scope | Approved A-24/ADR-0010 persistence boundary, recovery scenarios, and applicable physical evidence | +| Demonstrate useful repeat use | Users accomplish work beyond a demonstration and have a reason to return | First-task and Task C outcomes, previous workflow, opportunity to use, assistance, prompting, and follow-up accounting | + +## Completed baseline and remaining uncertainty + +These records are inputs to planning, not new achievements of this development +cycle. Future work below remains **Proposed** until explicitly selected. + +| Baseline item | Recorded state at the planning date | Consequence for this roadmap | +|---|---|---| +| Android distribution and public copy | Google Play 0.2.0 open testing; README/site correction completed in PR #33 | Preserve accurate copy; PYB-002 covers only newly found discrepancies | +| App source and installed identity | Source `0.2.0+8`; source version alone does not identify an installed Play/TestFlight binary | PYB-001 records actual installed versions/builds and source mapping or explicit unknowns | +| iPad distribution | External TestFlight beta is the recorded channel | Verify the selected installation path and artifact evidence; do not infer production App Store availability | +| Existing workflow | PBLE/1 editing, files, run/stop, console, Blocks, tutorials, and reviewed import already exist | Reuse implementation and tests; improve measured failures rather than rebuild the workflow | +| Firmware v0.6.1 | Owner-confirmed publication for five exact profiles; incomplete automated evidence remains visible | New qualification and compatibility claims require their own applicable evidence | +| Historical issue #24 | Closed as superseded; incomplete checklist was not declared passed | Do not recreate closure as a new dependency or treat historical closure as qualification | +| Durable drafts | A-24/ADR-0010 current-document persistence remains a recorded implementation gap | Select a bounded local recovery increment with explicit text/Blocks scope | +| Adoption and Ready | No measured cohort results or awarded PyBLE Ready badge established by the strategy | Treat outcome targets and badge eligibility as proposals requiring evidence | + +The [Android publication review](../../testing/website/android-open-testing-2026-09-25.md) +and current public roadmap supersede stale publication-status wording in the +older [firmware proposal](../../planning/firmware-v0.6.1-v0.7.0-roadmap.md). +That proposal still informs conditional Reliable Projects scope and compatibility. + +## Roadmap horizons + +The windows are sequencing forecasts measured from the proposed cycle start. +Overlapping windows permit options; they do not create simultaneous commitments +for one maintainer. All rows in this table have status **Proposed**. + +| Horizon / indicative window | Outcome and user value | Planning items / milestone | Admission and dependency | Evidence for continuation | +|---|---|---|---|---| +| H1 — Months 0–3; 28 Sep–20 Dec 2026 | Reliable mobile workflow: identify installations, protect work, and learn from useful tasks | PYB-001/003/004/006/008/009/011/013/014; conditional 005/012 and residual 002; M-01…M-06 | Named capacity and cohort; sized persistence scope and mandatory matrix; use existing release tooling | Qualified bounded maintenance increment, verified channel state, and honest activation/repeat-use assessment | +| H1 supporting rehearsal — Within C1 only if funded | Make an existing profile's setup and recovery reproducible by a second operator | Bounded PYB-009 work; input to M-07 | One existing exact profile, operator availability, and an explicit allocation within PYB-009 or spare planned capacity | Procedure, assistance log, draft Ready record, and visible gaps; no badge or new-port promise | +| H2 — Months 3–6; approximately Dec 2026–Mar 2027 | Reliable Projects addresses a demonstrated multi-file or recovery obstacle | PYB-017 then selected PYB-018…022; M-08 | Relevant pilot evidence; accepted scope, protocol/ADR changes, capability registry, and cross-version plan | One coherent selected capability, legacy fallback, and applicable exact-artifact qualification; complete v0.7.0 is not promised | +| H3 — Months 3–9; approximately Dec 2026–Jun 2027 | PyBLE Ready makes correct selection/setup easier and establishes maintainable outside ownership | PYB-024/025; M-07 | Existing-profile reproduction, reviewed criteria, complete public record, owner/reviewer, then one external maintainer | First eligible exact-configuration record; measured setup/support effort; SG4 before broader expansion | +| H4 — Months 6–12; approximately Mar–Sep 2027 | A reusable supervised lesson helps learners complete safe board work | PYB-026/028; optional 027 only after bundle-contract approval; M-09 | Reliable core, classroom-specific safety/security review, consent arrangements, and multi-board selection evidence | Reviewed lesson and at least two measured sessions; sustainable instructor support and SG5 assessment | +| H5 — Months 6–12; approximately Mar–Sep 2027 | Reproducible research explains measured technical or educational results | PYB-016/030; conditional research stream | Named investigator, suitable contribution, approved study/ethics decision where applicable, and qualified artifacts | Reproducible benchmark or submission-ready package if results justify it; no acceptance/publication promise | +| H6 — Months 12–24; approximately Sep 2027–Sep 2028 | Sustainable compatibility growth and justified richer or secure workflows | Selected PYB-023/029/031/032; M-10 for untrusted/field deployment | Demonstrated demand, external ownership, support capacity, and explicit scope decisions | Reviewed compatibility maintenance; security evidence for untrusted use; bounded data/service experiments only when justified | + +## First-cycle sequencing + +| Sprint | Forecast focus | Principal milestone evidence | Adaptation rule | +|---|---|---|---| +| C1-S1; 28 Sep–11 Oct | Installation baseline, safe primary-cohort task, initial observations, and scope sizing | M-01 / SG0 | Replan estimates and remaining scope when actual capacity, persistence design, or hardware inventory is known | +| C1-S2; 12–25 Oct | First accepted durable-draft increment; observed onboarding fix only if warranted | M-02 progress | Split oversize work into independently reviewable increments without weakening recovery criteria | +| C1-S3; 26 Oct–8 Nov | Complete selected recovery scope, stage qualification, and observe useful second tasks | M-02; inputs to M-03/M-04 | A representative device/profile result is a checkpoint, not full matrix qualification | +| C1-S4; 9–22 Nov | Understand the highest-impact task obstacle and establish follow-up eligibility | M-03 / SG2 | Aim for 20 activated, follow-up-consenting participants by 22 November; preserve failures and recruitment blockers | +| C1-S5; 23 Nov–6 Dec | Freeze candidate, complete applicable evidence, and assess mature follow-ups | M-04 / SG1; M-06 inputs | Release only when relevant evidence passes; qualified maintenance may also ship earlier | +| C1-S6; 7–20 Dec | Verify actual channel/install state and choose one subsequent investment | M-05; M-06 / SG3 | Record pass, iterate, blocked, or inconclusive outcomes; make a dated next-stage decision | + +The [Sprint Plan](04_Sprint_Plan.md) owns detailed dates and capacity. The first +Sprint Backlog is a candidate for Sprint Planning; later allocations are +forecasts. A milestone review neither replaces a Sprint Review nor supplies +missing Definition of Done evidence. + +```mermaid +flowchart TD + B[Recorded baseline and proposed Product Goal] --> P[Select bounded delivery scope] + P --> D[Delivery: identify artifacts and preserve local work] + B --> C[Select primary cohort and useful task] + C --> L[Learning: observe first and useful second tasks] + D --> Q[Applicable candidate qualification] + Q --> V[Release decision and verified installation] + L --> E[Activation and contextual repeat-use evidence] + E --> A[Adapt Product Backlog at Sprint Reviews] + V --> A + A --> N[Select one justified next investment] + D -. Funded existing-profile operator work .-> R[Ready rehearsal and draft record] + R --> RR[Complete criteria and evidence before any badge] + RR --> EP[One external maintenance pilot] + EP --> SG[SG4 assesses broader expansion] + N --> F[Conditional Projects, Ready, classroom, or other outcome] +``` + +## Capacity and ordering rules + +| Constraint | Roadmap consequence | +|---|---| +| Assumed 20 hours/week for 12 weeks; availability uncommitted | 240 gross hours; 156 planned envelope and 84 reserved; confirm during C1-S1 | +| 136 planned hours currently allocated; 20 planned hours unassigned | Optional work requires explicit allocation; spare capacity is not already assigned to every optional item | +| Maximum 26 planned hours per Sprint | Include known specification, implementation, review, and mandatory validation when selecting work | +| One substantial implementation change plus one documentation/release task | Forecast parallel streams do not authorize seven concurrent implementations | +| Existing known data-safety gap | Recruitment delay does not block correcting durable-draft loss | +| Required qualification | Reserve is not a substitute for estimating mandatory tests; reduce optional scope or extend time when necessary | +| Optional export/localization/outreach/research | PYB-007/010/015/016 and early 017 require explicit spare or independent contributor capacity | +| Qualified maintenance delivery | SG2/SG3 cohort targets, Ready awards, new protocols, and complete classroom scope are not release prerequisites | + +## Choices after the cycle + +| Observed evidence | Preferred next investigation or investment | Guardrail | +|---|---|---| +| Users return but repeatedly hit multi-file limitations | Select and approve a Reliable Projects capability | No invented opcodes or implicit approval of the full v0.7.0 proposal | +| Provisioned users succeed while setup prevents others starting | Improve selection/provisioning; evaluate whether a Ready record reduces errors | Distinguish compatibility from firmware installation status | +| One outside maintainer reproduces and sustains a profile | Review SG4 and consider one additional demand-backed profile | A new chip family is not required; retain exact-board qualification | +| Introductory tasks succeed without meaningful subsequent use | Revisit the audience, task, and benefit relative to existing workflows | Missing opportunity to use is context, not proof of rejection or hidden success | +| Supervised use is valuable and support is manageable | Select a bounded lesson/classroom pilot | SG5 and multi-board safety precede broader teaching claims | +| Field/untrusted demand becomes credible | Review ownership/authentication scope and independent evaluation | SG6 precedes untrusted-deployment claims; a compatibility badge is not security certification | +| Support effort exceeds available capacity | Narrow supported work and recruit ownership before expanding | Do not trade away normative evidence or introduce paid/closed app features | + +## Review and traceability + +| Review point | Record and update | +|---|---| +| Each Sprint Review | Inspect usable outcomes and evidence with stakeholders; adapt Product Backlog ordering and forecasts | +| Each Sprint Retrospective | Improve the team's working process and follow up on the selected improvement | +| A strategic decision | Link its milestone, evidence, limitations, and next action; preserve the previous target and observed result | +| Changed release/profile scope | Review affected normative requirements and qualification, rather than treating this roadmap as an exception | +| New expansion commitment | Name capacity, owner/reviewer, user problem, and a bounded outcome before selecting delivery work | + +Follow [repository governance](../../../AGENTS.md), current normative specifications, +and accepted ADRs. This roadmap proposes priorities; it does not authorize a +protocol change, claim physical results, award a badge, or approve a release. diff --git a/docs/developments/2026-q4-reliable-workflow/03_Milestones.md b/docs/developments/2026-q4-reliable-workflow/03_Milestones.md new file mode 100644 index 00000000..e9e06ea7 --- /dev/null +++ b/docs/developments/2026-q4-reliable-workflow/03_Milestones.md @@ -0,0 +1,138 @@ + + + +# 03 — Outcome and evidence milestones + +| Control | Value | +|---|---| +| Status | All milestones Proposed; no milestone is completed by this document | +| Planning date | 25 September 2026; dates use Asia/Bangkok | +| Source | [Implementation strategy revision 1.2](../../planning/PyBLE_Implementation_Plan_and_Strategy_v1.0.md), especially §§4, 8–10, 14, and 19 | +| Inspected baseline | `main` at `23ed764b0ef88dce9720c66fbd1c0655268860cf` | +| Related documents | [Framework](01_Overview_and_Scrum_Framework.md), [roadmap](02_Product_Roadmap.md), [Sprint Plan](04_Sprint_Plan.md), [stories](05_Product_Backlog_and_Stories.md), [Sprint Backlogs](06_Sprint_Backlogs.md) | +| Meaning | Milestones describe inspectable outcomes and decision evidence; they are not additional Scrum events or promised releases | + +## Assessment and evidence states + +Use **Proposed** until work is selected. At a milestone assessment, record one of +the decisions below with a date, responsible person, evidence links, and next +action. A calendar boundary never creates a pass. SG identifiers refer to the +strategy's decision gates; they do not replace repository CI G0/G1 or C3-G0…C3-G6. + +| Decision / state | Meaning | Required follow-up | +|---|---|---| +| Proposed | Outcome has been planned but not accepted as completed work | Refine and select through Product Backlog ordering and Sprint Planning | +| Pass | The milestone's defined evidence supports its bounded outcome | Record scope, limitations, reviewer, and any independently required downstream gate | +| Iterate | Evidence exposes a solvable gap or misses a proposed target | Order the next improvement; preserve the original observation and target | +| Blocked | A named dependency prevents the required work or assessment | Record owner, reason, next check date, and effect on other work | +| Inconclusive | Evidence is insufficient for a defensible outcome decision | Retain descriptive results and identify what further evidence would resolve uncertainty | +| Documented limited-scope decision | A strategic choice is deliberately narrower than the proposed outcome | Record accepted scope and reasons; it cannot convert failed/missing mandatory release evidence into a pass | + +| Distinction | Interpretation | +|---|---| +| Source complete | A scoped implementation may be merged while broader candidate qualification remains pending | +| Done Increment | The usable increment meets its applicable Definition of Done, including required physical evidence; unfinished work is not part of it | +| Release admitted | The immutable selected candidate satisfies all applicable release requirements and sign-off | +| Submitted / available / installed | These are separate distribution observations; store submission alone proves neither availability nor successful installation | +| Sprint Review | Stakeholders inspect outcomes and adapt the Product Backlog; this is not a required release-approval meeting | + +## First-cycle milestone register + +Forecast windows guide coordination. They are not deadlines for removing tests, +waiving evidence, or declaring a target met. Roles require named assignments; +no role in this table implies committed staffing or independent review. + +| ID / status | Outcome and value | Forecast window / stories | Dependencies and evidence | Assessment / accountable contribution | +|---|---|---|---|---| +| M-01 — Proposed | Accepted baseline and bounded cycle scope make installation, pilot, and engineering decisions reproducible | C1-S1, 28 Sep–11 Oct; PYB-001/003/004, residual 002, sizing 006/009 | Dated channel/install/source mapping or explicit owned unknowns; one primary cohort/job; safe task/consent rules; initial observations or recruitment blocker; actual capacity; persistence and physical-matrix estimates | SG0: accept a bounded scope or record gaps; Product Owner with release, pilot, and Developers | +| M-02 — Proposed | A usable, bounded local-draft recovery increment protects accepted user work after interruption | C1-S2–C1-S3, 12 Oct–8 Nov; selected PYB-006 scope, supporting 009/008, observed 005 only if selected | Accepted App specification/TDD and ADR-0010 change; text/Blocks scope; persistence boundary; relaunch, interrupted-write, and corrupt-state scenarios; no implicit board overwrite/run; relevant regression and physical evidence | Review against the selected story acceptance criteria and Definition of Done; Developers with a named review path | +| M-03 — Proposed | Observed first-use and meaningful second-task evidence explains activation and its largest obstacle | C1-S4, 9–22 Nov; PYB-004/011 and justified 005/012 | Safe recorded pilot setup; at least 12 eligible primary-cohort task starts, all outcomes retained; successful unassisted timing; Task C attempts, prior workflow, assistance and reasons | SG2: assess provisional completion/timing targets and severe failures; pilot lead supplies evidence, Product Owner records next investment | +| M-04 — Proposed | A frozen maintenance candidate is qualified for its declared release scope | Normally C1-S5, 23 Nov–6 Dec; PYB-008/009/013 and included fixes | Applicable exact-artifact matrix and normative gates pass; provenance/recovery/instructions; no unresolved release-blocking data-loss, unintended/cross-session write, or critical workflow regression within the accepted threat model | SG1: release or submission decision with required sign-off; release owner and QA/review path | +| M-05 — Proposed | Users can obtain the selected qualified app build through a verified existing channel | C1-S5–C1-S6, 23 Nov–20 Dec; PYB-014 and residual 002 | M-04; distribution-owner access; separate submission, availability, installed build/provenance, and installation outcome records; current user-facing claims | Verified-channel milestone passes only for the stated evidence; store delays are recorded as blockers; release owner | +| M-06 — Proposed | Useful-repeat and support evidence drives one explicit next-stage investment | C1-S6, 7–20 Dec; PYB-011 follow-up, cycle review; Ready inputs only if selected | Mature consented cohort accounting, useful Task C/return outcomes, task opportunity, prompting, missing responses, support burden, and status of candidate/channel evidence; retain blocked outcomes | SG3 assessment plus dated continue/narrow/pause-expansion decision; Product Owner with pilot and Developers | + +M-04 may occur in any Sprint once a maintenance candidate qualifies. M-03 and +M-06 do not block it. M-06 can assess learning and choose a narrower next step +even if release or recruitment remains blocked; the decision must say so. +M-02 is not a claim that every matrix row or the whole A-24 ambition is complete. + +## Measurement rules for M-03 and M-06 + +| Measure | Proposed target | Interpretation and evidence boundary | +|---|---|---| +| Eligible first-task completion | At least 80% unassisted among at least 12 starts; at 12 starts, at least 10 successes | Failures, abandonment, and timeouts stay in the denominator; freeze eligibility/task/assistance rules prospectively | +| First successful run timing | Empirical nearest-rank p90 at or below 10 minutes for successful unassisted Task A runs | Start at first launch; report sample size and raw distribution beside all-start completion; no qualifying runs means unavailable | +| Follow-up eligibility | Aim for 20 activated, primary-cohort participants consenting to follow-up by 22 November | Their day-14 windows close by 6 December; fewer than 20 mature eligible participants makes the retention target inconclusive | +| Useful return | Provisional 40% confirmed useful day-7–14 returns among all mature, consented participants | Include all eligible participants in the denominator; distinguish missing follow-up, respondents, prompting, and task opportunity | +| Product value | Meaningful Task C attempts and reasons to choose or leave PyBLE | A repeated introductory print demonstration or a retention percentage alone does not establish value | +| Additional signals | Aim for 30 non-maintainer activations and five substantive reports | Discovery signals, not maintenance-release gates; distinguish recruitment sources and positive/negative feedback | + +Missing follow-up is not a confirmed non-return. Retain participants who lacked +a relevant new task in the primary denominator and report any opportunity-to-use +subgroup separately. Recalibrate targets/windows only prospectively in a dated +decision that preserves the original results. + +## Conditional future milestone register + +These milestones remain Proposed beyond the base C1 commitment. Their windows +are options from the strategy, not simultaneous assignments. Research and paid +support experiments remain conditional roadmap streams rather than implied +release or publication promises. + +| ID / status | Outcome and value | Indicative window / stories | Admission and evidence | Decision boundary | +|---|---|---|---|---| +| M-07 — Proposed | A complete Ready record and one external maintenance pilot make one exact profile easier to choose, set up, and sustain | Months 3–9; PYB-009 → 024 → 025; funded existing-profile rehearsal may start in C1 | Second operator reproduces published procedure; criteria/use/retest/withdrawal rules reviewed; complete artifact/hardware/workflow/installation/maintenance record; owner/reviewer; one external maintainer and measured setup/support effort | First badge only after its declared criteria pass; SG4 assesses broader expansion after the bounded pilot, not permission to start rehearsal | +| M-08 — Proposed | One selected Reliable Projects capability resolves a demonstrated workflow limitation | Months 3–6, conditional; PYB-017 then selected 018…022; 032 only if separately justified | Approved scope and normative wire/spec/ADR decisions; unchanged legacy behavior; capability fallback; cross-version tests and applicable five-profile physical/release evidence | No approval of the whole v0.7.0 feature set, opcode allocation, or release date by this milestone | +| M-09 — Proposed | A reusable supervised lesson and at least two measured sessions demonstrate sustainable teaching use | Months 6–12; PYB-026/028; 027 only if bundle scope is approved | Reliable core; multi-board selection/interference exercise; classroom safety/security and consent review; accessible lesson, instructor setup/intervention and outcome records | SG5 governs broader classroom use; small supervised evidence cannot establish unrestricted classroom scale | +| M-10 — Proposed | A justified ownership/security design supports an explicitly bounded untrusted or field deployment claim | Months 12–24 through Sep 2028, only on demonstrated demand; PYB-023 | Approved ownership/authentication and versioning scope; independent review; downgrade/reset/recovery evidence; sustainable support | SG6 before untrusted/field claims; a Ready badge does not satisfy security admission | + +| M-07 stage | Required output | What it does not establish | +|---|---|---| +| Existing-profile rehearsal | Procedure, exact setup, operator/assistance record, and explicit gaps | Badge eligibility, a new supported port, or independent reproduction if bespoke help remains necessary | +| First public record | All declared criteria and reproduction pass; maintenance/use rules; visible installation status | Qualification of untested versions, revisions, or an entire chip family | +| One external maintainer pilot | Agreed responsibilities, independently reproduced results, support/retest effort | A partnership before agreement or automatic capacity for another profile | +| SG4 expansion assessment | Demand and sustainable maintenance support the next bounded addition | Permission to waive normal specification or release requirements | + +## Evidence dependencies + +```mermaid +flowchart TD + B[Recorded baseline and available existing workflow] --> M1[M-01 baseline and bounded scope] + B --> S[Accepted technical scope and artifact evidence] + S --> M2[M-02 accepted recovery increment] + M1 --> M3[M-03 activation and useful task evidence] + M2 --> Q[Applicable immutable candidate qualification] + S -. Other selected maintenance scope .-> Q + Q --> M4[M-04 qualified candidate and SG1] + M4 --> M5[M-05 verified distribution] + M3 --> M6[M-06 contextual repeat-use and cycle decision] + S -. PYB-009 funded operator work .-> R[Existing-profile rehearsal] + R --> M7[M-07 complete Ready record and one external pilot] + M7 --> SG4[SG4 reviews wider profile expansion] + M6 -. Select only with relevant evidence .-> M8[M-08 Reliable Projects] + M6 -. Conditional audience and safety .-> M9[M-09 classroom and SG5] + M6 -. Conditional demand and security scope .-> M10[M-10 secure deployment and SG6] +``` + +The delivery and learning branches operate together. Known defects can be fixed +without waiting for recruitment. M-07 requires applicable qualification evidence +for its exact claim; it neither requires every unrelated app release nor waives +an atomic five-profile firmware release gate. + +## Evidence record and maintenance + +| Field | Required content when a milestone is assessed | +|---|---| +| Identity | Milestone ID, dated assessment, source strategy revision, scope, named responsible person and reviewer | +| Decision | Proposed/pass/iterate/blocked/inconclusive or explicit limited-scope decision, with reasons | +| Traceability | Selected PYB stories, actual issue/PR links when they exist, affected specifications/ADRs, and exact candidate identity | +| Results | Applicable pass/fail/not-run/blocked evidence; preserve limitations and historical results | +| Measurements | Cohort and task definitions, denominators, missing data, timing method, assistance and opportunity context where relevant | +| Next action | Product Backlog adaptation, responsible owner, target review, and impact on forecast windows | +| Privacy | Public redacted summaries and evidence hashes; personal contact/consent and raw sensitive records stored separately | + +Reuse existing qualification reports and release schemas. The [strategy's +verification entry points](../../planning/PyBLE_Implementation_Plan_and_Strategy_v1.0.md#106-verification-entry-points) +identify relevant tools; document creation itself does not rerun their checks +or supply hardware evidence. Follow the [framework](01_Overview_and_Scrum_Framework.md) +for Scrum accountabilities, Definition of Done, and review/adaptation practice. diff --git a/docs/developments/2026-q4-reliable-workflow/04_Sprint_Plan.md b/docs/developments/2026-q4-reliable-workflow/04_Sprint_Plan.md new file mode 100644 index 00000000..198839dd --- /dev/null +++ b/docs/developments/2026-q4-reliable-workflow/04_Sprint_Plan.md @@ -0,0 +1,108 @@ + + + +# Cycle 1 — Sprint plan and capacity forecast + +| Field | Value | +|---|---| +| Status | Proposed; goals and selection are confirmed at each Sprint Planning | +| Cycle | `C1`, 28 September–20 December 2026, Asia/Bangkok | +| Basis | [Strategy revision 1.2, §8](../../planning/PyBLE_Implementation_Plan_and_Strategy_v1.0.md#8-twelve-week-implementation-schedule) | +| Product Goal and quality rules | [Working agreement](01_Overview_and_Scrum_Framework.md) | +| Acceptance criteria | [Product backlog and stories](05_Product_Backlog_and_Stories.md) | +| Task-level proposal | [Sprint backlogs](06_Sprint_Backlogs.md) | + +## Forecast and commitment boundary + +| Planning element | Treatment | +|---|---| +| `C1-S1` | Candidate selection for the next Sprint; not a committed Sprint Backlog before Planning | +| `C1-S2` … `C1-S6` | Forecasts revised using preceding results, capacity and learning | +| Sprint Goal | One coherent outcome confirmed by the Scrum Team at Planning | +| Scope and task details | Developers select feasible items and adapt their plan with the Product Owner as learning changes scope | +| Milestones | Inspectable evidence/decision points; not mandatory release ceremonies or waterfall phases | +| Estimates | Task hours are initial capacity allowances, not measured velocity, story points, or promises | +| Missing people/devices/access | Explicit blockers; do not invent availability or lower the Definition of Done | + +## Capacity model + +The source assumes one primary maintainer at 20 hours/week. Confirm real availability and any contributor capacity at Planning; extra roles do not create extra hours. + +| Sprint | Gross assumed hours | Base planned allowance | Unallocated planned headroom | Reserve | Planned ceiling | +|---|---:|---:|---:|---:|---:| +| C1-S1 | 40 | 22 | 4 | 14 | 26 | +| C1-S2 | 40 | 24 | 2 | 14 | 26 | +| C1-S3 | 40 | 24 | 2 | 14 | 26 | +| C1-S4 | 40 | 22 | 4 | 14 | 26 | +| C1-S5 | 40 | 24 | 2 | 14 | 26 | +| C1-S6 | 40 | 20 | 6 | 14 | 26 | +| **Total** | **240** | **136** | **20** | **84** | **156** | + +The reserve covers events/refinement, support, additional qualification and uncertainty. Known tests/reviews belong in each selected item's estimate. Rehearsal or optional work may consume explicitly assigned headroom; do not count it twice. The 26-hour ceiling is a local planning assumption, not a Scrum rule. If required work does not fit, reduce scope or revise the forecast, preserving quality and the fixed Sprint timebox. + +## Sprint Goals, usable results, and evidence + +| Sprint / dates | Proposed Sprint Goal | Candidate parents / child items | Intended usable result | Review evidence and milestone link | +|---|---|---|---|---| +| **C1-S1** — 28 Sep–11 Oct | Make the current installation and primary-cohort task reproducible, and determine a feasible draft-recovery scope | PYB-001.1/.2, 003.1, 004.1/.2, 006.1, 009.1; 011.2 when follow-up is due; residual 002 only if found | Reviewed installation/evidence record and reusable current-workflow task/operator guidance; accepted recovery design if review completes | [M-01](03_Milestones.md): installed-state evidence/unknowns, named cohort, five baseline starts or explicit recruitment blocker, sized persistence and applicable matrix | +| **C1-S2** — 12–25 Oct | Enable recovery of the smallest accepted current-text draft scope while preserving safe board/session behavior | PYB-006.2; continue 009.1 and start 008.1; rolling 011.2; PYB-005.1 only for a real observed blocker | Usable bounded recovery increment when all selected acceptance and DoD checks pass | [M-02](03_Milestones.md): persisted boundary, relaunch, interrupted/corrupt storage and stale-completion evidence; visible carried A-24/Blocks scope | +| **C1-S3** — 26 Oct–8 Nov | Make the recovery increment reproducibly testable on selected devices and observe useful second tasks | PYB-008.1/.2, 011.1/.2; 006.2 only if replanned unfinished; optional 009.2 | Candidate-specific operator evidence and task findings; qualified maintenance changes may release now | [M-02/M-04](03_Milestones.md): completed versus pending matrix rows, Task C outcomes, optional existing-profile rehearsal with assistance/gaps | +| **C1-S4** — 9–22 Nov | Improve the highest-impact observed task obstacle and establish interpretable activation/follow-up cohorts | PYB-011.1/.2; 012.1 or 005.1 only if evidence selects it; affected 008 reruns | An observed improvement if a defect is selected; otherwise usable findings and existing-workflow guidance | [M-03](03_Milestones.md): at least 12 primary-cohort starts including failures; reasons to choose PyBLE; aim for 20 activated consenting participants by 22 Nov | +| **C1-S5** — 23 Nov–6 Dec | Reach a justified release decision for the candidate and account for mature follow-up windows | PYB-008.2, 013.1, 014.1 when admitted, 011.2 | Release-ready candidate if every applicable gate passes; otherwise explicit blocker and recovery plan | [M-04](03_Milestones.md): immutable artifacts and required gates; follow-up accounting by 6 Dec; submission recorded separately from approval | +| **C1-S6** — 7–20 Dec | Verify actual distribution and choose one next investment from useful-repeat and support evidence | PYB-014.1/.2 as needed, 011.2; cycle decision; optional 015.1 | Verified delivery record or documented external blocker, usable support guidance, evidence-based next backlog order | [M-05/M-06](03_Milestones.md): installed identity, complete denominator and missing-data report, support effort, one next-stage decision | + +These are whole-product goals, not separate analysis, coding, testing and release departments. Every delivered increment includes its applicable design, implementation, verification and documentation. S3/S5 qualification work does not postpone tests needed to make earlier increments Done. + +The full safe recovery slice may exceed the initial S2 allowance. PYB-006.1 must expose that before selection. Replan a smaller independently safe increment or later delivery; never label happy-path-only persistence Done or count the whole A-24 umbrella as complete. + +## Calendar + +The diagram shows forecast timeboxes, not guaranteed feature delivery. Reviews and Retrospectives are proposed for the last working Friday; Sprints end on Sunday so the next timebox begins immediately on Monday. + +```mermaid +gantt + title Proposed Cycle 1 Sprint timeboxes + dateFormat YYYY-MM-DD + axisFormat %d %b + section Cycle 1 forecasts + C1-S1 Reproducible baseline :s1, 2026-09-28, 14d + C1-S2 Bounded draft recovery :s2, 2026-10-12, 14d + C1-S3 Reproducible evidence and useful tasks :s3, 2026-10-26, 14d + C1-S4 Observed task improvement :s4, 2026-11-09, 14d + C1-S5 Candidate release decision :s5, 2026-11-23, 14d + C1-S6 Verify delivery and choose next work :s6, 2026-12-07, 14d +``` + +| Sprint | Planning | Review and Retrospective | Important observation window | +|---|---|---|---| +| C1-S1 | Mon 28 Sep | Fri 9 Oct | First comparable baseline observations | +| C1-S2 | Mon 12 Oct | Fri 23 Oct | Continue recruitment alongside known persistence work | +| C1-S3 | Mon 26 Oct | Fri 6 Nov | Task C attempts and recorded-build cohorts | +| C1-S4 | Mon 9 Nov | Fri 20 Nov | Aim for 20 activated follow-up-consenting participants by Sun 22 Nov | +| C1-S5 | Mon 23 Nov | Fri 4 Dec | Latest target cohort's day-14 window closes Sun 6 Dec; include final late-weekend accounting in S6 if needed | +| C1-S6 | Mon 7 Dec | Fri 18 Dec | Cycle closes Sun 20 Dec; late observations remain clearly dated | + +## Replanning and release rules + +| Trigger | Action | +|---|---| +| Store/device access is unavailable | Mark the installation task Blocked and assign an owner; continue independent contract/tool work | +| Recruitment is insufficient | Record the gap; preserve the denominator and report outcomes inconclusive where required; continue qualified maintenance work | +| A severe observed defect appears | Order the smallest safe fix against the Sprint Goal; renegotiate selected scope rather than silently adding hours | +| A candidate or relevant input changes | Identify affected evidence and rerun/revalidate applicable checks; do not reuse old hashes as current results | +| All release gates pass before S5 | Release through the authorized normal process; retain dated records and revise later forecasts | +| Release gates do not pass by S5/S6 | Hold the release claim and show the blocker; the calendar does not waive a gate | +| No second operator is available | Keep PYB-009.2 pending; no independent-reproduction claim or Ready award; unrelated delivery continues | +| Cohort has no new task during days 7–14 | Keep it in the full eligible denominator; report opportunity separately and use only prospectively agreed additional windows | +| A future forecast item remains too large or vague | Return to refinement, split by usable outcome and size with Developers; do not fill a Sprint with an unresolved epic | + +## Review record template + +| Field | Record at each Review/Retrospective | +|---|---| +| Sprint Goal | Achieved, partially achieved or not achieved, with evidence | +| Increment | Demonstrable changes meeting DoD; unfinished items listed separately | +| Quality/release | Applicable test/physical results, exact artifacts, limitations, release state | +| Useful work | Tasks attempted/completed, assistance, opportunity, prompting and missing responses | +| Capacity | Actual delivery/support/event effort compared with allowances; no invented velocity | +| Adaptation | Updated ordered backlog, next proposed Goal, one process improvement | diff --git a/docs/developments/2026-q4-reliable-workflow/05_Product_Backlog_and_Stories.md b/docs/developments/2026-q4-reliable-workflow/05_Product_Backlog_and_Stories.md new file mode 100644 index 00000000..00f27938 --- /dev/null +++ b/docs/developments/2026-q4-reliable-workflow/05_Product_Backlog_and_Stories.md @@ -0,0 +1,220 @@ + + + +# 05 — Product Backlog and Stories + +| Control | Value | +|---|---| +| Product Goal | Make the existing tablet workflow trustworthy enough for useful repeat tasks by the selected primary audience | +| Source | [Implementation strategy revision 1.2](../../planning/PyBLE_Implementation_Plan_and_Strategy_v1.0.md), reviewed 25 September 2026 | +| Cycle | Proposed 28 September–20 December 2026; Asia/Bangkok | +| Baseline | `23ed764b0ef88dce9720c66fbd1c0655268860cf`; completed publication work is evidence, not a new commitment | +| Status | Proposed ordered Product Backlog and refinement candidates; no new story is selected, approved, implemented, or Done by this document | +| Accountabilities | Product Owner orders the backlog; Developers size and select work in Sprint Planning; named people and capacity remain to be assigned | +| Navigation | [Overview and Scrum](01_Overview_and_Scrum_Framework.md) · [Roadmap](02_Product_Roadmap.md) · [Milestones](03_Milestones.md) · [Sprint plan](04_Sprint_Plan.md) · [Sprint Backlogs](06_Sprint_Backlogs.md) | + +## 1. How to use this backlog + +| Rule | Application | +|---|---| +| Parent identity | `PYB-001` through `PYB-032` retain the strategy's planning identities; they are not GitHub issue numbers | +| Leaf identity | Decimal suffixes identify proposed slices, such as `PYB-006.2`; link an actual issue when accepted rather than inventing its number | +| Existing identity | `A-24` remains the broader existing persistence story; the bounded PYB-006 increment does not complete all A-24 obligations | +| Sprint identity | `C1-S1` through `C1-S6` name this cycle; App TDD references to historical S1–S7 remain unchanged | +| Backlog order | The first-cycle order below is provisional; dependencies, evidence and the Product Goal guide refinement, rather than treating every P0 as simultaneous work | +| Type | User stories express an end-user outcome; engineering, research, governance and release enablers identify the actual work without an artificial persona | +| State and sizing | Every new leaf is `proposed`; named owner/reviewer and estimates are TBD. Forecast sprints are planning candidates. No story points or velocity are asserted | +| Acceptance and Done | Story acceptance criteria supplement the shared Definition of Done; apply the source contract, repository gates and required physical evidence to the selected change | +| Research outcome | A completed, reviewed observation can find that a target failed. That does not pass the corresponding milestone or turn missing participants into completed observations | +| Scope change | Split an oversized item into a coherent, safe increment and replan before implementation; preserve carried requirements and record any approved deviation | + +## 2. Ordered first-cycle Product Backlog + +| Order | Parent / source priority | Intended outcome | Proposed slices | Forecast / dependency | Current state | +|---|---|---|---|---|---| +| 1 | PYB-001 / P0 | Know what users can install and which artifacts they receive | 001.1, 001.2 | C1-S1; existing publication review | Proposed; physical installation and provenance remain unverified | +| — | PYB-002 / P0 accuracy | Keep maintained availability claims correct | Residual discrepancy task only if discovered | PR #33 already corrected Android copy; new discrepancies follow 001 | Original correction complete; no new residual task asserted | +| 2 | PYB-003 / P0 | Conduct a safe, consented pilot with bounded data collection | 003.1 | C1-S1; 001 informs setup | Proposed | +| 3 | PYB-004 / P0 | Observe one reachable audience completing reproducible, useful tasks | 004.1, 004.2 | C1-S1; 001, 003 | Proposed | +| 4 | PYB-006 / P0 | Recover the current text draft after process restart | 006.1, 006.2 | Size in C1-S1; bounded delivery C1-S2–S3; known defect does not wait for recruitment | Proposed; contract and sizing required | +| 5 | PYB-009 / P0 | Make existing validation reproducible by an operator | 009.1; optional 009.2 | Inventory C1-S1, recipe C1-S2; reproduction only with assigned capacity | Proposed | +| 6 | PYB-005 / P0 if observed | Remove a demonstrated first-use blocker | 005.1 | C1-S2 candidate; actual 004 findings | Conditional; no defect invented | +| 7 | PYB-008 / P0 for claims | Establish the exact candidate's applicable compatibility evidence | 008.1, 008.2 | Representative checks C1-S2; staged matrix C1-S3–S5; 001, 009.1, artifacts | Proposed; hardware and mandatory workload must be costed | +| 8 | PYB-011 / P0 usability | Understand useful first and repeat tasks in the primary cohort | 011.1, 011.2 | Main activation collection C1-S3–S4; rolling follow-up from the first consented activation through C1-S6; 003, 004, recorded tested setup | Proposed; recruitment and follow-up are not assumed | +| 9 | PYB-012 / P0 if severe | Resolve the highest-impact observed failure | 012.1 | C1-S4 candidate or earlier when evidence warrants | Conditional; reorder promptly when a real severe failure appears | +| 10 | PYB-013 / P0 release | Make a candidate-specific release decision with applicable evidence | 013.1 | C1-S5 forecast; applicable 008/009 and included fixes | Proposed; maintenance candidates may qualify earlier | +| 11 | PYB-014 / P0 when ready | Make the qualified app build installable through the selected existing channel | 014.1, 014.2 | C1-S5 submission/C1-S6 verification forecast; 013 and owner access | Proposed; external review may extend calendar | +| 12 | PYB-007 / P1 | Share a previewed, privacy-preserving support record | 007.1 | Optional capacity; 003 and approved export contract | Proposed; manual template is the base fallback | +| 13 | PYB-010 / P1 | Read accurate setup and recovery guidance in Simplified Chinese | 010.1 | Optional capacity and named language reviewer | Proposed | +| 14 | PYB-015 / P1 | Discover the verified release through accurate supporting material | 015.1 | C1-S6 optional; verified claims, 002/013 | Proposed | +| 15 | PYB-016 / P1 | Prepare a defensible benchmark and research evaluation | 016.1 | Optional independent capacity; 003/004 | Proposed | + +The completed portion of PYB-002 is [PR #33](https://github.com/PyBLE-dev/PyBLE/pull/33). A fresh mismatch needs its own accepted scope and evidence; do not restart the original correction or count it as this cycle's delivery. + +## 3. Detailed first-cycle stories and enablers + +All acceptance criteria below describe future verification. They do not report tests, recruitment, approvals or releases already performed. Role names identify needed skills; assignment and sizing remain TBD. + +### 3.1 Distribution and pilot preparation + +| ID / type / role | Outcome | Testable acceptance criteria | Dependencies and verification | +|---|---|---|---| +| PYB-001.1 / Release enabler / Release | Establish a reviewed channel and artifact ledger | Separate publication, installation, provenance and qualification fields; record evidence/date/platform/channel/build; each unknown has an owner and next action; distinguish uploaded AAB/IPA identity from installed or re-signed artifacts | Existing dated publication review; reviewer checks ledger against first-party evidence. A completed ledger does not make an unknown installation pass | +| PYB-001.2 / User story / Release + QA | As a tablet-owning maker, I can follow the existing channel's installation path so I can start using PyBLE | Perform enrollment/install on eligible physical Android and iPad devices for the declared scope; record served version/build, observed restrictions and installation outcome; source mapping is evidenced or explicitly unresolved; instructions reproduce observed steps | 001.1 and channel/device access; dated physical installation records. Missing access or a failed install remains blocked/failed, not a completed successful installation | +| PYB-003.1 / Governance enabler / Lead + QA | Approve a bounded pilot that protects participants and their data | Identify trusted setting, harmless loads and wrong-board containment; explain STOP limitations and lack of authenticated ownership; approve consent, assistance/safety rules, contact separation and deletion policy; review a manual support template excluding sensitive content by default | Recorded 001 setup; named pilot decision-maker signs the scoped decision before collection. No background analytics or automatic source/console upload | +| PYB-004.1 / Research enabler / Pilot lead | Define one reachable cohort and tasks that reveal product value | Name primary audience, recruitment owner, reference setup and previous-workflow questions; separate Tasks A/B/C; fix eligibility, written guidance, assistance, timeout and exclusions prospectively; define follow-up linkage, prompting and opportunity-to-use questions | 001 and 003.1; reviewed task/observation protocol. Instructor cohort may replace the maker default by a recorded prospective choice | +| PYB-004.2 / Research enabler / Pilot lead | Observe five baseline participants before choosing a first-use change | Record five eligible started Task A outcomes, including failures, abandonment and assistance; retain build/task/OS/profile identity; record useful Task C attempts and reasons to choose PyBLE; identify actionable friction or no observed blocker | 004.1 and recorded tested setup; redacted observations and synthesis. Recruitment shortfall is reported as a blocker, not five completed observations | + +| Measurement boundary | Required interpretation | +|---|---| +| Task A | Provisioned-board activation, timed from first app launch; record installation separately | +| Task B | Full self-service setup, including installation, provisioning and recovery decisions; report duration separately | +| Task C | Meaningful adaptation or own task using safe existing features; an unchanged introductory print rerun is insufficient | +| First-session Task C | Evidence of useful adaptation; it is not later-day repeat use | +| Support information | Use the reviewed manual template until optional 007.1 is delivered; participants do not depend on a new export feature | + +### 3.2 Preserve work and repair demonstrated friction + +| ID / type / role | Outcome | Testable acceptance criteria | Dependencies and verification | +|---|---|---|---| +| PYB-005.1 / User story / App | As a first-time maker, I can resolve the observed setup obstacle so I reach a ready board without live assistance | Cite the observed obstacle; distinguish provisioning, permission, discovery and readiness as relevant; make recovery actionable; preserve working session behavior; test the changed path and repeat a comparable task observation | Sufficient 004 evidence; selected contract, regression and relevant physical/task evidence. Not Ready until a real problem and bounded fix are selected | +| PYB-006.1 / Engineering enabler / App | Freeze and size a safe, bounded durable-draft design | Define persisted content, accepted write boundary and observable failure behavior; define recovery/discard choice, board association, interrupted-write/corrupt/full-storage handling and migration approach; explicitly include or defer Blocks; map carried A-24 obligations; follow Drift decision or approve a superseding ADR; size validation before implementation | [ADR-0010](../../decisions/0010-working-loop-in-memory-document.md), App specs/TDD and current code; reviewed specification/ADR and acceptance scenarios. Does not wait for 004 | +| PYB-006.2 / User story / App | As a maker, I can recover my current text draft after the app process restarts so an interruption does not erase my work | Restore accepted persisted content according to 006.1 after termination/relaunch; recovery requires no network/board operation; recovery/discard is explicit as specified; interrupted/corrupt/full storage follows the approved non-destructive outcome; restore never silently uploads, runs or authorizes a write to a newly selected board; stale transfer completion cannot clear newer edits; text/Blocks scope is truthful | Approved 006.1; meaningful failing-then-passing persistence/controller tests, migrations and applicable widget/lifecycle/physical regressions. Deliver safe failure behavior with the slice, not as optional later hardening | +| PYB-012.1 / User story placeholder / Maintainer | As an affected participant, I can complete the task interrupted by the highest-impact observed failure | Replace this placeholder with the actual failure, expected outcome and contract; reproduce it; verify the minimal fix and affected regressions; compare recorded task/build cohorts where applicable; close or retain the specific evidence gap truthfully | Sufficient 004 or 011 observations; selection need not wait for the whole cohort. No invented defect, implementation estimate or readiness before refinement | + +| A-24 scope guard | Required treatment | +|---|---| +| Existing implementation | [EditorDocument](../../../app/lib/editor/editor_document.dart) is volatile; [data barrel](../../../app/lib/data/data.dart) remains a placeholder. Navigation survival is not restart survival | +| Persistence design | [App TDD](../../specifications/App/TDD.md) §9 describes the broader Drift model; its frozen working-loop contract records the current deviation. Do not interpret the target architecture as shipped code | +| Backend | Preserve Drift and the single settings-store direction; ADR-0010 rejects an ad-hoc scratch-file substitute. A different design requires an explicit superseding decision | +| Completion boundary | A bounded current-text recovery story does not complete full project management, all six content tables, saved boards, console history, import provenance, durable settings or Blocks recovery | +| Safe slicing | Replan an oversized 006.2; do not declare a happy-path-only build releasable while required corruption, interruption or board-write protections remain absent | +| Protocol boundary | No new PBLE operation, automatic reconnect guarantee, automatic board write or full project system is approved by these stories | + +### 3.3 Qualification and reusable operator evidence + +| ID / type / role | Outcome | Testable acceptance criteria | Dependencies and verification | +|---|---|---|---| +| PYB-009.1 / Engineering enabler / Protocol + QA | Make existing suites and physical procedures runnable without a new parallel harness | Inventory host/app/conformance/HIL tools; map applicable normative gates and exact profiles; document prerequisites, commands, expected evidence and safe setup/recovery; cost the required matrix; identify missing hardware/operators and boundaries between host, physical and usability evidence | 001 and source inventory; review against [HIL guide](../../../tests/firmware_tests/hil/README.md), [host fixtures](../../../tests/firmware_tests/host/conformance/README.md) and qualification tooling. Recipe starts before the full matrix | +| PYB-008.1 / Qualification enabler / QA | Expose candidate/setup failures with representative iPad and Android runs | Select and name representative exact-profile/device combinations; record immutable app/firmware/suite identity and provenance limits; run applicable core and interruption checks; record pass/fail/not_run/blocked and retain defects/evidence | 001, initial 009.1 recipe and recorded artifacts; physical results. Representative success cannot imply ten-combination qualification | +| PYB-008.2 / Qualification enabler / QA + Firmware | Complete every matrix row required for the selected compatibility claim | Cover the selected claim's required profiles/platforms and normative scenarios/counts; target five exact profiles × two app platforms for the cycle; attach candidate-bound evidence, reviewer, limitations and state per row; rerun affected evidence after relevant changes; unresolved required rows block that claim | 009.1, candidate artifacts and 008.1 findings; applicable physical/qualification gates. Explicitly replan unavailable hardware or underestimated workload without weakening requirements | +| PYB-009.2 / Engineering enabler / Second operator + QA | Reproduce one existing profile and expose gaps in a draft PyBLE Ready record | Name one existing exact profile/operator; follow published setup/core/recovery recipe; log assistance and failures; update gaps and rerun affected steps without bespoke help before claiming reproduction; draft version-bound evidence and installation status; award no badge | 009.1, suitable artifacts/hardware and explicit capacity. Optional rehearsal; missing second operator leaves reproduction pending without blocking an unrelated maintenance release | + +| Qualification rule | Acceptance boundary | +|---|---| +| Exact profiles | `esp32-4mb`, `esp32-s3-n16r8`, `waveshare-esp32-s3-lcd-147b`, `esp32-c3-4mb`, `rpi-pico2-w`; preserve revision/memory constraints | +| App/firmware combinations | Name immutable supported baselines and applicable cross-version scenarios; do not use a mutable branch as artifact identity | +| Claims | A passing subset supports only its declared scope; an existing-profile rehearsal never waives an atomic five-profile firmware release gate | +| Existing publication | v0.6.1 owner confirmation does not complete pending automated evidence or confer PyBLE Ready status | +| Evidence status | `not_run` and `blocked` describe evidence rows, not a passing outcome. No simulator or host result substitutes for a required physical measurement | + +### 3.4 Useful use and contextual follow-up + +| ID / type / role | Outcome | Testable acceptance criteria | Dependencies and verification | +|---|---|---|---| +| PYB-011.1 / Research enabler / Pilot lead | Learn whether the primary cohort can start and adapt useful work | Record at least 12 eligible primary-cohort Task A starts, retaining all failures/timeouts/abandonment; report unassisted success and successful-only nearest-rank p90 with sample size; record Task C attempts, reasons, prior workflow and assistance; stratify changed build/task/audience cohorts | 003, 004 and recorded tested setup; public aggregates/private consented records. Initial five count only if comparable; full 008 completion and 005 are not prerequisites | +| PYB-011.2 / Research enabler / Pilot lead | Learn whether participants return for useful work when a task arises | Aim for at least 20 activated, consenting primary-cohort participants by 22 November; record consent and the day-7–14 window at activation and collect follow-up as each window arrives, including early cohorts; account for mature windows through 6 December; retain all mature eligible participants in the primary denominator; report useful returns, respondents, missing responses, prompting, task opportunity and alternatives separately | 004 prospective follow-up rules and 011 activation records; reviewed aggregate analysis. Below 20 is inconclusive; missing follow-up is not confirmed non-return; participants with no new task remain in the primary denominator | + +| Target in the strategy | How the story review uses it | +|---|---| +| At least 80% unassisted completion | At 12 starts, at least 10 successes; failing/abandoned starts remain in the denominator | +| Successful-only observed p90 ≤10 minutes | Report alongside all-start outcomes and the raw small-sample distribution; no qualifying successes means unavailable | +| At least 40% useful day-7–14 returns | A provisional indicator only with at least 20 mature eligible participants and meaningful-task/context evidence | +| Participant totals | Thirty non-maintainer activations is a discovery aim, not a maintenance-release gate; recruited and independently arriving participants remain distinguishable | +| Missed targets | Report observed results and select iterate, blocked or a documented limited-scope decision; explanation alone does not pass SG2/SG3 | + +### 3.5 Release and channel verification + +| ID / type / role | Outcome | Testable acceptance criteria | Dependencies and verification | +|---|---|---|---| +| PYB-013.1 / Release enabler / Release + QA | Decide whether an immutable candidate can be published under its declared scope | Identify included changes/artifacts and applicable normative gates; attach passing required evidence, known limitations, provenance, recovery and accurate guidance; resolve release-blocking loss, unintended/wrong-session writes and critical workflow regressions; record review/sign-off or blocker | Applicable 008/009 and included fixes; [repository rules](../../../AGENTS.md), specifications and release evidence. Full pilot/retention cohorts and future authenticated ownership are not blanket maintenance prerequisites | +| PYB-014.1 / Release operation / Release | Submit the qualified app artifact to the selected existing channel | Match submitted artifact to 013 decision; record uploaded identity, target channel, submission receipt and current processing/review state; record owner/access and update/rollback route; preserve testing-channel wording | 013.1 and distribution-owner access; submission evidence. Submission is distinct from availability and production promotion requires its own decision | +| PYB-014.2 / User story / Release + QA | As an eligible tablet user, I can install the qualified update through the declared channel | Verify actual channel availability and eligible-device installation; record installed version/build and available provenance; exercise the applicable installation smoke path; update instructions/status with observed restrictions; retain unresolved review or installation failures explicitly | 014.1 and actual external availability; dated physical installation evidence. Waiting for store review remains a blocker, not successful installation | + +### 3.6 Optional capacity: support, documentation and future design + +| ID / type / role | Outcome | Testable acceptance criteria | Dependencies and verification | +|---|---|---|---| +| PYB-007.1 / User story / App + QA | As a user seeking help, I can preview a diagnostic export before sharing it | User explicitly initiates export; preview/redaction precedes sharing; observed, supplied and unknown identity fields stay distinct; omit source, file/console contents, secrets and persistent device identifiers by default; no automatic upload; current HELLO is not treated as an artifact hash | 003 and approved export contract; privacy/serialization/UI tests and relevant device checks. Manual template remains usable if this story is not selected | +| PYB-010.1 / User story / Docs + language reviewer | As a Simplified Chinese reader, I can understand verified setup and recovery steps | Named reviewer checks identity, distribution, exact compatibility and recovery guidance; preserve code/protocol tokens; link authoritative English/versioned references; translated claims match actual support status | Current guidance and reviewer/capacity; language, link and relevant publication checks; incorporate 005 if that flow changed | +| PYB-015.1 / Documentation enabler / Community | Prepare accurate evidence for release discovery | Release kit identifies actual capabilities, support limits and verified channel; screenshots/demonstration have reviewed provenance; coverage register deduplicates syndication and separates publication/discovery dates; awareness counts are not adoption claims | 002/013 and verified availability for availability claims; editorial/source review. This preparation does not assert outreach or publication occurred | +| PYB-016.1 / Research enabler / Research lead | Prepare an evaluation before collecting research data | State question, baseline/comparison, artifact identity, metrics, limitations and analysis plan; distinguish usability from efficacy; record ethics/review decision before relevant collection; define reproducible benchmark procedure | 003/004 and named independent capacity; reviewed protocol. No result, novelty, manuscript or approval is presumed | +| PYB-017.1 / Engineering enabler / Protocol | Decide whether one Reliable Projects capability is justified and ready for implementation planning | Cite measured problem; approve selected v0.7.0 scope/ADR or defer it; define capability advertisement, legacy fallback, registry changes and cross-version vectors before implementation; size one coherent slice and show what capacity it replaces | Normally cycle decision; earlier only explicit scope/capacity allocation. Approved design is not implementation, new opcode approval or v0.7.0 release qualification | + +## 4. Conditional expansion backlog and complete parent traceability + +Parents PYB-001–016 map to the first-cycle table. PYB-017 has a design leaf above; PYB-018–032 remain proposed epics needing refinement, named ownership, sizing and admission. Future-stage P0 does not interrupt the current cycle automatically. + +| Parent / source priority | Proposed outcome | Admission and dependencies | Refinement / evidence before claim | +|---|---|---|---| +| PYB-017 / P0 future | Select Reliable Projects scope | Cycle evidence; explicit scope/capacity decision | 017.1 above; no implementation by roadmap alone | +| PYB-018 / P0 future | Query run/session state without stale reconnect assumptions | 017 approved contract | Split user/agent/app slices; reconnect/autorun and cross-version evidence | +| PYB-019 / P0 future | Inspect or abort a transfer while preserving the prior destination | 017 approved contract | Define idempotent abort and disconnect/resume semantics; fault and compatibility vectors | +| PYB-020 / P0 future | Obtain complete directory enumeration | 017 approved contract | Define mutation behavior; unchanged directory returns every entry exactly once | +| PYB-021 / P0 future | Execute files with consistent project semantics | 017 approved contract | Sibling imports, path restoration, module cleanup and fresh-run parity; preserve completed v0.6.1 hardening | +| PYB-022 / P1 future | Explain bounded console/input loss and recovery | 017/018 | Bound queues and loss reporting; floods do not silently redefine STOP | +| PYB-023 / P0 before untrusted deployment | Establish authenticated ownership and safe recovery | 003 refreshed threat model; approved security/versioning scope | Independent design review; bootstrap, replay/downgrade, reset/revocation and legacy behavior before implementation | +| PYB-024 / P0 before badge | Award a version-bound PyBLE Ready claim with a complete public record | 009 reproduction, applicable qualification, named maintainer/reviewer | Publish criteria/use/revalidation/withdrawal rules; exact hardware/software/results and visible installation status; every declared criterion passes | +| PYB-025 / P1 future | Have one external maintainer sustain a useful exact profile | 024, demand, named owner/capacity | Existing profile is sufficient; independent results and support/retest effort recorded; new ports require normal gates | +| PYB-026 / P1 future | Supply a safe, usable offline lesson pack | Core workflow gate | Reviewed wiring, expected result, recovery and accessibility; select one actual lesson | +| PYB-027 / P1 future | Import a lesson safely through a bounded bundle/QR flow | 026 and approved bundle specification | Parse limits, preview, explicit overwrite consent and separate Run; no implied atomic project deployment | +| PYB-028 / P1 future | Validate two supervised classroom sessions | 026 and classroom-specific 003 review | Setup/completion, wrong-board events, support burden and consent; no coercive reviews or participation | +| PYB-029 / P2 future | Evaluate sensor plotting/export for a demonstrated task | Stable execution/console and demand | Approved data format; rate, units, timestamps and loss/export bounds | +| PYB-030 / P1 future | Produce a reproducible research package when results justify it | 016 and qualified artifacts | Measured contribution, matched comparisons, limitations and reproducible evidence; publication not guaranteed | +| PYB-031 / P2 future | Test one bounded support/vendor service | Demand and support capacity | Record delivery cost/support effort; retain free open application features and evidence-based badge eligibility | +| PYB-032 / P2 future | Decide atomic project-deployment semantics | 019/021 and measured multi-file need | RFC and interruption model; no implementation promise before contract approval | + +| PyBLE Ready guard | Required backlog treatment | +|---|---| +| Visible installation status | Distinguish **firmware installation required** from **firmware preinstalled** for the actual supplied board/kit; a profile's compatibility does not identify a seller's shipped firmware | +| Badge maintenance | Public record includes exact versions, owner, review date, support/retest duties and active/under-review/withdrawn state; unsupported claims are suspended or withdrawn with history retained | +| Open access | Compatible PBLE agents remain usable without a badge, payment, registration or app-side board allowlist | +| Early rehearsal | 009.2 may prepare a draft record within assigned capacity; 024 award and 025 external expansion remain separate decisions | + +## 5. Dependency model + +```mermaid +flowchart TD + BASE["001: installed-build evidence"] --> QUAL["008: applicable candidate qualification"] + RECIPE["009.1: operator recipe"] --> QUAL + DESIGN["006.1: accepted draft contract"] --> FIX["006.2: safe durable-draft increment"] + FIX --> QUAL + QUAL --> RELEASE["013: candidate decision"] + RELEASE --> SUBMIT["014.1: channel submission"] + SUBMIT --> INSTALL["014.2: verified installation"] + SAFE["003 and 004: safe cohort and tasks"] --> PILOT["011: useful-task observations"] + BASE --> PILOT + PILOT --> NEXT["SG2 and SG3: next investment"] + PILOT -. "Observed defect can reprioritize work" .-> OBSFIX["005 or 012: selected fix"] + OBSFIX --> QUAL + RECIPE --> REPRO["009.2: optional existing-profile rehearsal"] + REPRO --> READY["024: later evidence-backed badge decision"] +``` + +| Reading the model | Meaning | +|---|---| +| Maintenance path | Applicable candidate evidence gates release; a completed cohort or passing retention target does not | +| Learning path | Use a recorded tested setup; new pilot work need not wait for the whole candidate matrix or optional onboarding changes | +| Feedback | Actual severe failures can change order before the cohort completes; known durable-draft loss needs no rediscovery | +| Diagram limit | This diagram shows major dependencies, not a waiver of the applicable source contract or a commitment to run all paths simultaneously | + +## 6. Refinement and handoff + +| Before selecting a leaf | Required record | +|---|---| +| Ownership | Actual issue link, named Developer/owner, reviewer and needed physical operator | +| Sprint fit | Accepted goal contribution, estimate including known spec/review/tests, hardware/access, dependencies and remaining capacity | +| Contract | Normative references, selected in/out scope, accepted scenarios and any explicit carried requirement | +| Evidence | Expected automated/physical/documentary proof and location; privacy/retention handling; no fabricated result | +| Delivery | Applicable source/release gates, channel impact, recovery/rollback and public-claim boundary | +| Review | Acceptance outcome, shared Definition of Done, unresolved findings and next ordering decision; unselected work remains in the Product Backlog | + +| Authoritative / related source | Use | +|---|---| +| [Implementation strategy](../../planning/PyBLE_Implementation_Plan_and_Strategy_v1.0.md) §§4, 8–10, 12, 14, 19 | Outcomes, parent backlog, capacity, pilot/Ready rules and strategic decisions | +| [App specification](../../specifications/App/specs.md) and [App TDD](../../specifications/App/TDD.md) | Current contracts and explicit implementation deviations; proposed stories do not silently amend them | +| [ADR-0010](../../decisions/0010-working-loop-in-memory-document.md) | Volatile document boundary, Drift direction and carried A-24 requirements | +| [PBLE/1 specification](../../specifications/protocol.md) | Wire behavior and compatibility; no new opcode is defined here | +| [Public roadmap](../../ROADMAP.md) | Current published availability and owner-confirmed firmware status | +| [Firmware roadmap](../../planning/firmware-v0.6.1-v0.7.0-roadmap.md) | Proposed Reliable Projects direction; its historical unpublished-v0.6.1/open-#24 notes are superseded by the strategy's dated baseline | +| [Sprint plan](04_Sprint_Plan.md) and [Sprint Backlogs](06_Sprint_Backlogs.md) | Forecast timing and task-level selection; do not convert forecast work into a commitment automatically | diff --git a/docs/developments/2026-q4-reliable-workflow/06_Sprint_Backlogs.md b/docs/developments/2026-q4-reliable-workflow/06_Sprint_Backlogs.md new file mode 100644 index 00000000..8ac3d40e --- /dev/null +++ b/docs/developments/2026-q4-reliable-workflow/06_Sprint_Backlogs.md @@ -0,0 +1,225 @@ + + + +# Cycle 1 — candidate Sprint Backlog and later forecasts + +| Field | Rule | +|---|---| +| Status | C1-S1 is a candidate; C1-S2–C1-S6 are forecasts. Every task below is Proposed, with no named assignee or actual effort recorded | +| Product/Sprint Goals | [Framework](01_Overview_and_Scrum_Framework.md) and [Sprint plan](04_Sprint_Plan.md) | +| Acceptance authority | [Product backlog and stories](05_Product_Backlog_and_Stories.md); task completion never overrides a parent story's acceptance criteria | +| Selection | Developers confirm scope, ownership, estimates and task plan at each Sprint Planning | +| Hours | Initial task allowances totaling the source plan's 136 hours; not story points or validated effort estimates | +| Dependencies | Same-Sprint `Txx` references refer to that Sprint's task. Cross-Sprint dependencies name their full item/task ID | +| Evidence | Record artifact identity and actual results; unavailable access/recruitment leaves the affected task Blocked, not Done | +| Privacy | Keep private consent/contact/device records outside Git; link only reviewed public aggregates and redacted evidence | + +The initial tasks are small planning units, generally 1–4 hours. If a task or safe story is larger after inspection, split/reforecast before selection. A time allowance does not limit a required test's counts or justify declaring partial qualification complete. The actual Sprint Backlog includes its confirmed Goal, selected items, and the Developers' current plan; update this document as that plan changes. + +Record optional follow-up consent and the prospective day-7–14 window at each activation. Collect follow-up as windows arrive, starting with the first cohort; do not postpone early cohorts until S5. S1 observation allowances include any follow-up due within S1; S2-T11, S3-T10 and later follow-up rows continue it. Developers must reallocate headroom or other selected work if actual pilot effort exceeds these allowances, preserving required recovery review and tests. Record missed windows as missing/late evidence rather than reconstructing an on-time response. + +## C1-S1 — reproduce the current workflow and size recovery + +| Sprint control | Value | +|---|---| +| Dates / allowance | 28 September–11 October 2026 / 22 planned hours | +| Proposed Goal | Make current installation and one primary-cohort task reproducible; identify a feasible safe draft-recovery increment | +| Usable output | Reviewed installation record/guidance and task/operator procedure; the recovery contract is a separately reviewed enabler | +| Before selecting | Named channel/device access and pilot owner; cohort/task choice; known A-24 gap can proceed independently of recruitment | +| Review | M-01/SG0 evidence, including honest unknowns and any recruitment blocker; unmet physical tasks remain unfinished | + +| Task ID | Parent child item | Proposed task and expected output | Dependency | Contribution role | h | Status | +|---|---|---|---|---|---:|---| +| C1-S1-T01 | PYB-001.1 | Assemble the dated channel/install/provenance/qualification ledger from existing records; assign unresolved fields | Current source/publication records | Release | 1 | Proposed | +| C1-S1-T02 | PYB-001.2 | Verify eligible Android enrollment/install and record build/version, restrictions and available source mapping | T01; Play/device access | Release + QA | 2 | Proposed | +| C1-S1-T03 | PYB-001.2 | Verify current TestFlight installation and record its actual build and provenance limitations | T01; TestFlight/device access | Release + QA | 2 | Proposed | +| C1-S1-T04 | PYB-003.1 | Review harmless hardware/pilot boundaries, consent/retention rules, and manual support template | Recorded pilot setup; named pilot owner | Pilot + QA | 2 | Proposed | +| C1-S1-T05 | PYB-004.1 | Confirm primary cohort and Tasks A/B/C, assistance/timeout rules, previous workflow and prospective follow-up | T04; recorded app/setup | Pilot | 2 | Proposed | +| C1-S1-T06 | PYB-004.2 / PYB-011.2 | Observe the first baseline batch; record every eligible start, assistance, consent/window and any due follow-up | T05; consenting participants | Pilot | 2 | Proposed | +| C1-S1-T07 | PYB-004.2 / PYB-011.2 | Observe the next baseline batch under the same task/build rules; record windows and collect due follow-up | T05; consenting participants | Pilot | 2 | Proposed | +| C1-S1-T08 | PYB-004.2 / PYB-011.2 | Complete planned observation/follow-up slots toward five baseline starts; retain failures, missing responses and recruitment gaps | T05; participant access | Pilot | 2 | Proposed | +| C1-S1-T09 | PYB-004.2 | Summarize baseline outcomes and actual observation cost; identify an observed obstacle without inventing one | T06–T08 actual records | Pilot + Product Owner | 1 | Proposed | +| C1-S1-T10 | PYB-006.1 | Draft the bounded Drift recovery contract: write boundary, restore/discard, board association, failure handling and carried Blocks/A-24 scope | ADR-0010 and App contracts; no recruitment dependency | App | 3 | Proposed | +| C1-S1-T11 | PYB-006.1 | Review acceptance scenarios and size the safe increment including required tests; record approval or unresolved design questions | T10; review path | App + reviewer | 1 | Proposed | +| C1-S1-T12 | PYB-009.1 | Inventory existing suites, hardware/operators, applicable gates and matrix cost; draft the next operator recipe | T01 and current tools/specs | QA + firmware | 2 | Proposed | +| **C1-S1 total** | | | | | **22** | | + +Five baseline starts is a target, not the implied result of reserving six hours. If access or session duration prevents it, report the actual sample and replan. A completed findings record does not mark an unperformed installation or observation task Done. Missing store source mapping remains an owned limitation under the applicable gate. + +## C1-S2 — deliver a bounded safe recovery increment + +| Sprint control | Value | +|---|---| +| Dates / allowance | 12–25 October 2026 / 24 planned hours | +| Proposed Goal | Recover the smallest accepted current-text draft scope across process restart without unintended board actions | +| Usable output | Safe recovery increment only when the selected acceptance criteria and DoD pass | +| Before selecting | PYB-006.1 contract accepted and safe slice sized; data migration/dependencies and text/Blocks boundary agreed | +| Review | M-02 evidence and carried obligations; if the safe slice exceeds capacity, replan instead of dropping failure cases | + +| Task ID | Parent child item | Proposed task and expected output | Dependency | Contribution role | h | Status | +|---|---|---|---|---|---:|---| +| C1-S2-T01 | PYB-009.1 | Complete the scoped restart/setup/operator recipe and expected evidence for this increment | 006.1 scope; initial 009.1 inventory | QA + App | 2 | Proposed | +| C1-S2-T02 | PYB-006.2 | Add meaningful failing tests for the accepted write boundary, relaunch recovery and absence of implicit board/network actions | Approved 006.1; specification-first sequence | App | 2 | Proposed | +| C1-S2-T03 | PYB-006.2 | Add failing tests for interrupted/corrupt/full local storage and stale completions against newer edits | Approved 006.1 | App | 2 | Proposed | +| C1-S2-T04 | PYB-006.2 | Implement the minimal accepted durable storage/migration behavior until relevant tests pass | T02/T03 red evidence | App | 4 | Proposed | +| C1-S2-T05 | PYB-006.2 | Implement hydration and specified recovery/discard behavior through existing providers | T04 and accepted UI contract | App | 4 | Proposed | +| C1-S2-T06 | PYB-006.2 | Complete non-destructive error handling, truthful scope and localized recovery guidance | T04/T05 | App | 2 | Proposed | +| C1-S2-T07 | PYB-006.2 | Run affected controller/widget/lifecycle regressions and repository gates; resolve scoped failures | T04–T06 | App + QA | 2 | Proposed | +| C1-S2-T08 | PYB-008.1 | Run representative Android restart/interruption scenarios on the recorded candidate; retain actual results | T01/T07; device/candidate | QA | 2 | Proposed | +| C1-S2-T09 | PYB-008.1 | Run representative iPad restart/interruption scenarios on the recorded candidate; retain actual results | T01/T07; device/candidate | QA | 2 | Proposed | +| C1-S2-T10 | PYB-006.2 | Review integration/evidence and update user guidance plus carried A-24/Blocks limitations | T07–T09 and all applicable acceptance | App + reviewer | 1 | Proposed | +| C1-S2-T11 | PYB-011.2 | Collect due consented follow-up and account for early windows, missing responses and task opportunity | 004 prospective method; actual activation dates | Pilot | 1 | Proposed | +| **C1-S2 total** | | | | | **24** | | + +These allowances do not assert that persistence fits 24 hours. Developers must confirm the estimate or change the forecast at Planning. Required corruption/recovery protections remain part of the usable slice. Representative runs cannot complete the whole five-profile release matrix. + +## C1-S3 — establish reproducible evidence and useful tasks + +| Sprint control | Value | +|---|---| +| Dates / allowance | 26 October–8 November 2026 / 24 planned hours | +| Proposed Goal | Make selected recovery behavior reproducibly testable and observe useful second tasks | +| Usable output | Candidate-specific operator records, task findings and any increment meeting its full DoD | +| Before selecting | Record available artifact(s), operator/device access, applicable matrix and per-batch cost | +| Review | Actual matrix coverage and gaps; Task C outcomes; optional Ready rehearsal only if explicitly funded | + +| Task ID | Parent child item | Proposed task and expected output | Dependency | Contribution role | h | Status | +|---|---|---|---|---|---:|---| +| C1-S3-T01 | PYB-008.1 | Bind candidate/build/provenance and safe setup to the selected qualification plan | 001; 009.1; candidate available | QA + release | 2 | Proposed | +| C1-S3-T02 | PYB-008.2 | Execute the first costed batch of required profile/platform scenarios; retain results and defects | T01; exact devices; agreed batch | QA + firmware | 4 | Proposed | +| C1-S3-T03 | PYB-008.2 | Execute the next costed batch; preserve every required unrun row explicitly | T01; exact devices; agreed batch | QA + firmware | 4 | Proposed | +| C1-S3-T04 | PYB-008.2 | Execute the next risk-prioritized batch or affected rerun; record immutable evidence | T01; previous findings | QA + firmware | 4 | Proposed | +| C1-S3-T05 | PYB-011.1 | Observe a scheduled primary-cohort activation/Task C batch on a recorded tested setup | 003/004; participant access | Pilot | 2 | Proposed | +| C1-S3-T06 | PYB-011.1 | Observe the next useful-task batch and reasons to choose another workflow or return | 003/004; participant access | Pilot | 2 | Proposed | +| C1-S3-T07 | PYB-011.1 | Analyze task outcomes, assistance and comparable cohorts; reconcile activation records | T05/T06; existing observations | Pilot | 1 | Proposed | +| C1-S3-T08 | PYB-009.1 | Correct operator instructions and evidence index from actual execution | T02–T04 findings | QA | 2 | Proposed | +| C1-S3-T09 | PYB-008.2 | Review matrix states, blockers and remaining cost; determine which bounded claims are supported | T02–T04/T08 | QA + reviewer | 2 | Proposed | +| C1-S3-T10 | PYB-011.2 | Collect rolling follow-up in each due window and account for missing responses/opportunity | Consented activation records; prospective method | Pilot | 1 | Proposed | +| **C1-S3 total** | | | | | **24** | | + +At Planning, map each batch to exact rows among `esp32-4mb`, `esp32-s3-n16r8`, `waveshare-esp32-s3-lcd-147b`, `esp32-c3-4mb`, and `rpi-pico2-w`, on iPadOS and Android as required. The twelve-hour execution allowance is not a prediction that all ten combinations and every normative repetition fit. Completing a batch is not completing PYB-008.2 while required rows remain unrun or failing. + +## C1-S4 — improve the observed task and mature the cohort + +| Sprint control | Value | +|---|---| +| Dates / allowance | 9–22 November 2026 / 22 planned hours | +| Proposed Goal | Understand and address the highest-impact observed task obstacle while establishing interpretable follow-up | +| Usable output | A qualified bounded fix if justified, or reviewed useful-task findings and improved current-workflow guidance | +| Before selecting | Comparable cohort rules; real observed problem before selecting 012.1/005.1; actual recruitment cost from earlier observations | +| Review | M-03/SG2; at least 12 started-task target and progress toward 20 activated consenting participants by 22 November | + +| Task ID | Parent child item | Proposed task and expected output | Dependency | Contribution role | h | Status | +|---|---|---|---|---|---:|---| +| C1-S4-T01 | PYB-011.1 | Reconcile eligibility/build/task cohorts and remaining observation slots | 004; earlier 011 records | Pilot | 1 | Proposed | +| C1-S4-T02 | PYB-011.1 | Observe the next scheduled activation/useful-task batch, including failures | T01; consenting participants | Pilot | 3 | Proposed | +| C1-S4-T03 | PYB-011.1 | Observe a further batch within agreed capacity; record unfilled recruitment needs | T01; consenting participants | Pilot | 3 | Proposed | +| C1-S4-T04 | PYB-011.2 | Collect due follow-up, reconcile consent/windows and account for missing responses and task opportunity | Activated participants; approved method | Pilot | 2 | Proposed | +| C1-S4-T05 | PYB-011.1 | Calculate completion/timing and summarize Task C reasons, assistance and severe failures | T02/T03 and comparable prior records | Pilot + QA | 3 | Proposed | +| C1-S4-T06 | PYB-012.1 | If warranted, select and specify the highest-impact bounded failure and required evidence | Sufficient 004/011 evidence | Maintainer | 2 | Proposed | +| C1-S4-T07 | PYB-012.1 | Add a failing regression for the selected failure | T06 accepted contract | App or firmware | 2 | Proposed | +| C1-S4-T08 | PYB-012.1 | Implement the minimum safe fix and run affected tests | T07 red evidence | App or firmware | 4 | Proposed | +| C1-S4-T09 | PYB-012.1 | Review the fix, required physical/task evidence, and user guidance | T08; all applicable verification | QA + reviewer | 2 | Proposed | +| **C1-S4 total** | | | | | **22** | | + +T06–T09 are a conditional ten-hour allocation, not an instruction to invent a defect. If no justified fix fits, Developers and the Product Owner reallocate it to useful observation, required qualification or unselected backlog work consistent with the Goal; retain the revised estimate. Severe defects can be selected in earlier Sprints without waiting for this slot. Reforecast recruitment effort from actual session durations; the sample targets are not guaranteed by these allowances. + +An analysis task can finish with fewer than 12 starts, but PYB-011.1 remains unfinished until its minimum collection criterion is met or its scope is prospectively revised. With at least 12 starts, a reviewed negative finding can complete the research item while leaving SG2 unmet. Fewer than 20 mature eligible follow-up participants makes the retention assessment inconclusive; it does not create completed observations. + +## C1-S5 — decide whether the candidate is releasable + +| Sprint control | Value | +|---|---| +| Dates / allowance | 23 November–6 December 2026 / 24 planned hours | +| Proposed Goal | Reach an evidence-backed release decision and account for mature follow-up windows | +| Usable output | Admitted candidate if gates pass; otherwise a truthful blocker/evidence package with recovery guidance | +| Before selecting | Immutable candidate and included scope; actual remaining qualification cost; authorized distribution owner/access | +| Review | M-04/SG1; submission is separate from availability; late day-14 windows can be finalized in C1-S6 | + +| Task ID | Parent child item | Proposed task and expected output | Dependency | Contribution role | h | Status | +|---|---|---|---|---|---:|---| +| C1-S5-T01 | PYB-013.1 | Freeze candidate identity/included changes and map applicable release requirements | Selected source/increment; 001/009 evidence | Release + QA | 2 | Proposed | +| C1-S5-T02 | PYB-008.2 | Execute a costed remaining required matrix batch or invalidated-evidence rerun | T01; exact devices | QA + firmware | 4 | Proposed | +| C1-S5-T03 | PYB-008.2 | Execute the next required batch and retain outstanding rows honestly | T01; exact devices | QA + firmware | 4 | Proposed | +| C1-S5-T04 | PYB-008.2 | Complete applicable cross-version/affected regressions and review unresolved defects | T01; named baselines; prior findings | QA + App/firmware | 3 | Proposed | +| C1-S5-T05 | PYB-013.1 | Assemble immutable evidence index, limitations and accurate release notes | T02–T04 actual results; prior accepted evidence | Release | 3 | Proposed | +| C1-S5-T06 | PYB-013.1 | Review release admission and record sign-off or blocking conditions | T05/T09; all mandatory gates | Release + reviewer | 2 | Proposed | +| C1-S5-T07 | PYB-014.1 | If admitted and authorized, submit exact artifact to selected existing channel and retain receipt/state | T06 pass; owner access/authorization | Release | 2 | Proposed | +| C1-S5-T08 | PYB-011.2 | Collect follow-up in due windows and account for closed windows; label immature windows and missing responses | Consented activation records; agreed method | Pilot | 2 | Proposed | +| C1-S5-T09 | PYB-013.1 | Verify update/recovery instructions against selected artifacts and accepted scope | T01; current operator/distribution guide | Release + QA | 2 | Proposed | +| **C1-S5 total** | | | | | **24** | | + +The required matrix may cost more than these batches. Use the S1/Planning estimate to revise the forecast before committing; a Sprint end never shortens normative tests. If release admission is blocked, T07 is not Done and submission does not proceed. Participants activated on 22 November mature on 6 December, after the proposed Friday Review; finalize that accounting in C1-S6 without inventing early results. + +## C1-S6 — verify delivery and choose one next investment + +| Sprint control | Value | +|---|---| +| Dates / allowance | 7–20 December 2026 / 20 planned hours | +| Proposed Goal | Verify actual distribution and use meaningful-repeat/support evidence to choose one next investment | +| Usable output | Accurate delivery/support record and evidence-based next Product Backlog order; blocked external outcomes stay visible | +| Before selecting | Actual store state, mature consented records, candidate evidence, and current support observations | +| Review | M-05/M-06; SG3 assessment is contextual and independent of maintenance-release admission | + +| Task ID | Parent child item | Proposed task and expected output | Dependency | Contribution role | h | Status | +|---|---|---|---|---|---:|---| +| C1-S6-T01 | PYB-014.1 | Verify submission/processing/availability state and remaining distribution actions | 013 admission; submission/access as applicable | Release | 2 | Proposed | +| C1-S6-T02 | PYB-014.2 | If Android is selected, verify eligible installation of its qualified candidate, installed build and applicable smoke behavior | Actual selected-candidate Android availability | Release + QA | 2 | Proposed | +| C1-S6-T03 | PYB-014.2 | If iPad is selected, verify eligible installation of its qualified candidate, installed build/provenance and applicable smoke behavior | Actual selected-candidate TestFlight availability | Release + QA | 2 | Proposed | +| C1-S6-T04 | PYB-014.2 | Reconcile user-facing installation/update/support guidance with actual channel outcomes | T01 and selected-channel T02/T03 results | Release + Docs | 2 | Proposed | +| C1-S6-T05 | PYB-011.2 | Complete scheduled optional follow-up and closed-window accounting | Consented activation records | Pilot | 2 | Proposed | +| C1-S6-T06 | PYB-011.2 | Analyze full mature denominator, useful returns, prompting, opportunity and missing data | T05 and earlier observations | Pilot | 3 | Proposed | +| C1-S6-T07 | PYB-011.2 | Summarize task/support effort and reasons to choose or leave PyBLE | Observations and support records | Pilot + Developers | 2 | Proposed | +| C1-S6-T08 | Cycle decision — strategy §19 | Prepare the evidence-based next-investment recommendation and proposed backlog order for Review | T06/T07; milestone states | Product Owner + Developers | 3 | Proposed | +| C1-S6-T09 | PYB-009.1 | Close the operator/evidence index with current limits and any explicitly funded Ready rehearsal status | Actual 008/009 records | QA | 2 | Proposed | +| **C1-S6 total** | | | | | **20** | | + +T08 prepares a product decision; the Sprint Review/Retrospective meetings remain within the event reserve. A closed observation record may report an inconclusive target. A blocked app installation is not a completed installation, even when its blocker is documented. + +Declare release channel/platform scope at Planning. Reallocate any unselected T02/T03 allowance explicitly; an unchanged or unselected channel does not block M-05. Existing availability of an older binary is not evidence that the selected candidate is available. + +## Optional selection and spare capacity + +These options are not extra committed tasks. Use only the stated headroom, a reallocation approved through normal Sprint planning, or separately confirmed contributor capacity. Do not assume a second operator's time is free or included in the primary maintainer's estimate. + +| Option | Earliest candidate window | Selection condition | Capacity / evidence boundary | +|---|---|---|---| +| PYB-005.1 observed onboarding repair | Any Sprint after sufficient observation | Real bounded blocker and accepted contract | Size it; use up to the available headroom or replace another selected item | +| PYB-009.2 existing-profile rehearsal | C1-S3 onward, or earlier if ready | Published recipe, second operator, exact hardware and explicit estimate | C1-S3 has only 2 unallocated planned hours; larger work needs replanning/confirmed added capacity; pending reproduction awards no badge | +| PYB-007.1 previewable diagnostics | After privacy/export contract is accepted | Evidence that manual support records are insufficient | Manual template remains the base plan; no automatic upload | +| PYB-010.1 reviewed localization | After current guide and reviewer are available | Actual language need and named reviewer | Separate estimate; no dependency on an unneeded onboarding fix | +| PYB-015.1 release kit | Once corresponding claims have evidence | Qualified/verified facts; actual preparation need | Creation does not authorize outreach or claim publication | +| PYB-016.1 research design or PYB-017.1 protocol design | Only explicitly assigned spare/contributor capacity | Relevant question/problem and responsible owner | No implementation, study result or new opcode by planning alone | + +| Capacity reconciliation | Hours | +|---|---:| +| Base task rows across C1-S1–C1-S6 | 136 | +| Unassigned planned headroom across Sprints | 20 | +| Event/support/additional-qualification reserve | 84 | +| Gross assumed cycle capacity | 240 | + +## Execution states and unfinished work + +```mermaid +flowchart LR + P["Proposed task or future forecast"] --> S["Selected at Sprint Planning"] + S --> W["In progress"] + W --> R["Review evidence and acceptance"] + R --> D["Done task; assess parent separately"] + W --> B["Blocked with reason and owner"] + B --> W + R --> W + B --> U["Unfinished at Sprint end"] + W --> U + U --> PB["Product Backlog: reorder and replan"] + PB --> S +``` + +| During execution, add | Purpose | +|---|---| +| Named assignee and current estimate | Replace role placeholders with real responsibility and feasible effort | +| Actual/remaining effort | Adapt capacity without inventing historical velocity | +| Evidence link and result | Distinguish task completion, story acceptance, usable Increment and milestone outcome | +| Blocker, owner and next check | Keep access, recruitment, hardware and external review constraints actionable | +| Dated scope adjustment | Preserve why work changed; keep acceptance in file 05 synchronized | +| End-of-Sprint outcome | Retain unfinished items and replan them; do not automatically count or carry them as Done | diff --git a/docs/planning/PyBLE_Implementation_Plan_and_Strategy_v1.0.md b/docs/planning/PyBLE_Implementation_Plan_and_Strategy_v1.0.md new file mode 100644 index 00000000..871f3c6a --- /dev/null +++ b/docs/planning/PyBLE_Implementation_Plan_and_Strategy_v1.0.md @@ -0,0 +1,949 @@ + + + +# PyBLE: Implementation Plan and Development Strategy + +> **North Star:** Make a tablet a first-class development tool for nearby MicroPython hardware through a reliable, open, BLE-first workflow. +> +> **Execution principle:** Prove successful use before expanding features; prove repeatable compatibility before expanding the ecosystem. + +## Document control + +| Field | Value | +|---|---| +| Document version | 1.2 — product-value and PyBLE Ready revision; original filename retained | +| Prepared | 25 September 2026 | +| Last reviewed | 25 September 2026; strategy and PyBLE Ready feedback incorporated after the PR #33 baseline review | +| Status | Proposed execution plan for maintainer review; not approval to implement new protocol behavior | +| Product | PyBLE — Python over Bluetooth Low Energy | +| Organization | SciLabPro | +| Planning horizon | Immediate 12-week delivery cycle, followed by conditional expansion through September 2028 | +| Proposed first cycle | 28 September–20 December 2026; all dates use Asia/Bangkok | +| Accountable role | Project owner / lead maintainer; role assignment does not imply availability has been committed | +| Repository baseline inspected | `PyBLE-dev/PyBLE`, `main` at `23ed764b0ef88dce9720c66fbd1c0655268860cf` | +| Repository location | `docs/planning/PyBLE_Implementation_Plan_and_Strategy_v1.0.md` | +| Review cadence | Sprint review every two weeks; strategic review after each stage gate | + +**Scope of this document.** This plan converts the preceding PyBLE strategy discussion into executable workstreams, priorities, acceptance criteria, and decision gates. Existing repository specifications and contributor rules remain authoritative. Proposed features, names, metrics, staffing, and dates below are planning choices—not claims that those features exist or that resources and approvals are secured. + +**Evidence boundary.** The baseline review inspected repository source, specifications, test entry points, publication records, and the GitHub state of PR #33 and issue #24 on 25 September. Revision 1.2 incorporates the subsequent strategy and PyBLE Ready feedback. The dated Android review establishes the official listing's open-testing status; it does not identify the installed store binary or prove a signed-in installation. Installation counts, traffic, media engagement, participant outcomes, and new physical-board results have not been measured for this revision. Previously reported publicity and GitHub counts are not proof of product-market fit.[^android-review] + +**Continuation decision.** Carry forward the completed Android publication/copy correction. Concentrate weekly execution on three outcomes: verify what users install, preserve their work through interruptions, and observe useful repeat tasks in one primary audience. Reuse existing lifecycle handling, tutorials, conformance fixtures, and release tooling. A bounded PyBLE Ready rehearsal can reuse one existing profile's evidence work; new ports, broad badge promotion, classroom bundles, and new protocol behavior remain conditional. + +| Revision | Change | +|---|---| +| 1.0 | Initial strategy and proposed 12-week program | +| 1.1 | Updated baseline after PR #33; separated publication from installed-build evidence; mapped remaining work to current code; bounded the schedule and corrected release/pilot dependencies | +| 1.2 | Focused pilot selection and useful second tasks; contextualized retention; defined one version-bound PyBLE Ready badge, installation labels, maintenance rules, and a staged existing-profile/partner pilot | + +## Contents + +1. [Strategic decision](#1-strategic-decision) +2. [Starting point and evidence gaps](#2-starting-point-and-evidence-gaps) +3. [Target users and positioning](#3-target-users-and-positioning) +4. [Objectives and measurement](#4-objectives-and-measurement) +5. [Architecture and engineering boundaries](#5-architecture-and-engineering-boundaries) +6. [Release and protocol strategy](#6-release-and-protocol-strategy) +7. [Workstreams and deliverables](#7-workstreams-and-deliverables) +8. [Twelve-week implementation schedule](#8-twelve-week-implementation-schedule) +9. [Prioritized implementation backlog](#9-prioritized-implementation-backlog) +10. [Quality, compatibility, and release gates](#10-quality-compatibility-and-release-gates) +11. [Security and physical safety](#11-security-and-physical-safety) +12. [Pilot and adoption strategy](#12-pilot-and-adoption-strategy) +13. [Documentation and international reach](#13-documentation-and-international-reach) +14. [PyBLE Ready and partner development](#14-pyble-ready-and-partner-development) +15. [PyBLE Classroom](#15-pyble-classroom) +16. [Research and publication program](#16-research-and-publication-program) +17. [Sustainability and commercial validation](#17-sustainability-and-commercial-validation) +18. [Team, capacity, and operating process](#18-team-capacity-and-operating-process) +19. [Risks and strategic decision gates](#19-risks-and-strategic-decision-gates) +20. [Immediate execution checklist and handoff](#20-immediate-execution-checklist-and-handoff) +21. [Source references](#21-source-references) + +--- + +## 1. Strategic decision + +### 1.1 The direction + +Develop PyBLE as an **open, vendor-neutral mobile development platform for MicroPython over BLE**, while keeping the tablet application the primary product and the main source of user feedback. + +The long-term platform consists of three essential layers: the PyBLE app, the PBLE protocol, and the board-side agent. Conformance tooling, example collections, classroom resources, and partner ports support those layers. They do not justify a premature rewrite, repository split, or new collection of standalone products. + +The first commercial and educational hypothesis is deliberately narrow: + +> After an instructor, vendor, or user provisions a compatible board, a learner or maker can repeatedly edit, transfer, run, and inspect MicroPython code from a tablet without a cable or Wi-Fi setup in the normal development loop. + +The initial provisioning and recovery steps remain part of the complete user journey. “Wireless development” must never become a promise of “no computer or cable ever required.” + +### 1.2 Priorities in order + +1. **Reliable first use:** make the existing installation-to-first-program journey understandable and repeatable. +2. **Trustworthy execution and recovery:** preserve files, drafts, and clear connection/run state when things fail. +3. **Repeat use:** establish whether people return to PyBLE for a second real task. +4. **Reproducible compatibility:** turn existing tests and hardware evidence into a reusable conformance process. +5. **Selective expansion:** add classroom workflows and partner ports only after the core workflow is demonstrated. + +### 1.3 What the strategy does not assume + +Media coverage is evidence of attention, not necessarily use. Stars and forks indicate repository interest, not successful hardware sessions. An app-store download bucket does not establish the number of independent, active, or retained users. CSDN article volume and aggregate read counters do not establish technical validity, unique readers, or adoption. + +Likewise, an open protocol is a potential ecosystem foundation—not automatically a defensible moat or emerging standard. The platform hypothesis becomes credible when another engineer can implement or maintain a compatible component and another user can operate it successfully. + +### 1.4 Explicit non-goals for the first cycle + +Do not build a desktop IDE replacement, GDB/JTAG/SWD debugger, mandatory cloud account system, cloud project storage, plugin marketplace, or AI-first coding experience. Do not undertake universal BLE firmware flashing, broad board-family expansion, or industrial remote maintenance. Do not introduce paid or closed application features; that would conflict with the current contributor rules.[^agents] + +Revisit deferred ideas only with a demonstrated user problem, an owner, a maintenance budget, and an approved design. + +### 1.5 Three active outcomes + +Use this table for weekly prioritization; the remaining workstreams are reference material and conditional options. + +| Active outcome | Evidence of progress | Existing backlog | +|---|---|---| +| Verify what users install | Dated channel/build record and a reproducible installation path; unresolved provenance has an owner | PYB-001 and any residual 002 | +| Preserve users' work | Bounded A-24 draft recovery and applicable interruption/recovery checks on recorded artifacts | PYB-006, supported by 008/009 | +| Demonstrate useful repeat use | One primary cohort completes a meaningful task, attempts another, and explains the benefit or obstacle relative to its previous workflow | PYB-003/004/011/012; 005 if observations justify it | + +Required qualification accompanies delivery. PyBLE Ready preparation should reuse PYB-009's operator work and an existing profile. Additional reporting, new infrastructure, translations, research, and partner intake need an explicit capacity allocation; document completeness is not the product outcome. + +## 2. Starting point and evidence gaps + +### 2.1 Repository-grounded baseline + +The inspected repository already contains the following capabilities and development direction.[^readme][^public-roadmap] + +| Area | Existing baseline | Consequence for implementation | +|---|---|---| +| Tablet app | Flutter app; inspected source identifies `0.2.0+8` | Improve and qualify the existing app rather than create a new client | +| Distribution | Android 0.2.0 published on Google Play for open testing; iPad external TestFlight beta | Verify installed build identity separately; production-track availability is not claimed | +| Normal workflow | BLE discovery, PBLE/1 connection, editor, files, run/stop, soft reboot, console | Measure and repair the complete workflow, not isolated features | +| Mobile state | Session ownership and connection retirement protections already implemented; editor document remains in memory | Preserve lifecycle fixes; close the recorded process-restart persistence gap | +| Learning | Blockly, tutorials, reviewed screenshots, official examples repository | Improve discoverability and completion; do not duplicate the Learning Center | +| Import | Reviewed, SHA-pinned public GitHub `.py` import | Preserve preview, explicit overwrite approval, and non-execution on import | +| Firmware | Public v0.6.1 recorded as owner-confirmed | Preserve the distinction between publication and complete automated qualification | +| Release profiles | Five exact hardware profiles, including four ESP profiles and Pico 2 W | Treat exact configurations—not chip-family names—as the support unit | +| Architecture | Monorepo with app, firmware, protocol, tests, website, and documentation | Keep changes atomic across components | +| Governance | Specification-first, red/green/refactor, DCO, clean-room and license gates | Integrate the plan with existing contribution rules | +| Next firmware direction | v0.7.0 “Reliable Projects” is proposed, not approved | Select and approve scope before implementing new behavior | + +The existing five profiles are `esp32-4mb`, `esp32-s3-n16r8`, `waveshare-esp32-s3-lcd-147b`, `esp32-c3-4mb`, and `rpi-pico2-w`. Preserve their documented flash, PSRAM, revision, and exact-board constraints. Board image identity is not physical-board detection or authorization.[^readme] + +### 2.2 Completed work and remaining verification + +Use the following dated baseline instead of restarting the publication correction: + +| Item | Status as reviewed on 25 September 2026 | Remaining work | +|---|---|---| +| Android listing | Official Google Play listing for `dev.pyble.pyble` identifies 0.2.0 and open testing | Verify eligible-device enrollment/install and record version code, source mapping, and restrictions actually observed | +| Maintained public copy | PR #33 merged at `23ed764`; README, roadmap, website copy/metadata, setup guidance, and distribution contract now agree | Maintain those checks; search-engine recrawl timing remains outside project control | +| iPad channel | Maintained first-party guidance identifies the external TestFlight beta | Record the currently installable version/build and a fresh eligible-device installation; do not infer it from source | +| Firmware v0.6.1 | Published on owner confirmation; five exact profiles; original artifact/evidence records preserved | New qualification must cite exact tested bytes; pending automated rows remain pending | +| Issue #24 | Closed on 13 September 2026 as superseded (`NOT_PLANNED`) | Create a focused successor only for selected new work; do not reopen the obsolete release umbrella or mark its checklist complete | +| Product usage | No measured activation or retention baseline in this revision | Collect the bounded, consented evidence defined in §§4 and 12 | + +The public listing supports an **availability claim**; a successful installation supports an **installation claim**; source/build mapping supports an **artifact-provenance claim**; physical tests support a **compatibility claim**. Do not substitute one for another. A prepared `0.2.0+8` artifact does not prove that a store currently serves that artifact or includes later lifecycle fixes.[^android-review][^pr33][^publication] + +Historical release-roadmap statements about an unpublished v0.6.1 or an open #24 are superseded by the dated publication record, current public roadmap, and issue closure. Preserve historical evidence when adding a supersession note; do not change old outcomes retrospectively.[^public-roadmap][^issue24] + +**Output:** extend this baseline into a dated channel/artifact matrix with evidence links, owner, verification date, and separate publication/install/provenance/qualification fields. Mark unresolved fields `unverified`, and physical scenarios `not_run` or `blocked`. + +### 2.3 Baseline metrics to collect + +Record current store channels, download buckets where visible, repository engagement, issue authorship, and existing third-party demonstrations. Establish separate counts for maintainers, project-recruited testers, classroom participants, and independently arriving users. + +Do not spend the first sprint rebuilding a large analytics dashboard. A small private pilot register plus a public aggregate status report is sufficient. + +### 2.4 Implementation map: reuse first, then close the gap + +| Area and inspected source | Already present | Remaining work for this plan | +|---|---|---| +| [Connection manager](../../app/lib/pble/connection_manager.dart) | Session ownership, stale acquisition protection, serialized connection retirement | Observe failures and extend targeted regressions; preserve the existing `Connection` seam | +| [Editor document](../../app/lib/editor/editor_document.dart), [ADR-0010](../decisions/0010-working-loop-in-memory-document.md), [data placeholder](../../app/lib/data/data.dart) | One document survives navigation in memory; A-24 persistence explicitly deferred | Specify and implement a bounded durable-draft increment; distinguish process eviction/relaunch from a BLE disconnect | +| [PBLE connection](../../app/lib/pble/pble_connection.dart) | Transfer fails on link loss; a subsequent PUT can consume a firmware-provided resume offset | Measure user retry/reconnect behavior; do not claim automatic continuation from protocol resumability alone | +| [First-program tutorial](../../tools/web/src/app/learn/first-program/page.tsx) | Console-only `print("Hello from PyBLE!")` task without wiring | Reuse it for baseline observation and improve only demonstrated friction | +| [Device information types](../../app/lib/pble/types.dart) | Negotiated chip, agent version, and capabilities | A support export must distinguish observed data from operator-supplied profile/provenance; current HELLO does not prove an artifact hash | +| [Host conformance fixtures](../../tests/firmware_tests/host/conformance/README.md), [HIL guide](../../tests/firmware_tests/hil/README.md) | Shared vectors, compiled-native/portable tests, physical benches and release evidence tools | Add a coverage map and operator recipe before creating another harness or schema | + +**First engineering candidate:** PYB-006, the carried A-24 persistence gap. Complete its specification and sizing while collecting first-use observations; an already documented loss condition does not need rediscovery by participants. Start with durable recovery of the current text document and explicitly scope Blocks recovery. The existing ADR selects Drift and rejects an ad-hoc scratch-file workaround; any different design needs an explicit superseding decision. This does not approve a full project manager, automatic board writes, or new protocol operations.[^app-contract] + +## 3. Target users and positioning + +| Segment | Job to be done | Initial offer | Evidence needed before expansion | +|---|---|---|---| +| Tablet-owning makers | Program a nearby compatible board without recurring cable setup | Reliable app, recovery guide, small verified example set | Successful first session and repeat use | +| Educators | Run a supervised physical-computing activity with less repeated setup work | Pre-provisioned boards and one bounded lesson | Completion rate, support burden, and correct board selection | +| Hardware vendors | Make a specific board usable from tablets | Porting guide and repeatable compatibility evidence | Partner can run the process without bespoke maintainer intervention | +| Researchers | Reproduce and evaluate a mobile-to-hardware workflow | Versioned software, protocols, test artifacts, citation metadata | Reproducible experiments and a defensible research question | +| Field technicians | Maintain equipment without a laptop | Deferred discovery interviews only | Authenticated ownership, safe recovery, and operational support requirements | + +**Positioning:** “An open, offline-first MicroPython development workflow for tablets and nearby compatible boards.” + +“Offline-first” applies to core editing, BLE, files, and execution. App installation, initial firmware acquisition, optional GitHub import, and online documentation can require network access. Avoid confusing that boundary in marketing. + +**Provisional first-cycle audience:** tablet-owning makers with a specific nearby-board task. This is a planning default, not a claim that participants have been recruited. In S1, name the reachable cohort, recruitment owner, reference hardware, and task. If an instructor-led group is the accessible cohort instead, record that choice before observations and use instructor-provisioned boards. Choose one primary audience for the cycle; keep other participants' results separately exploratory rather than pooling different setup responsibilities and task schedules. + +The first job to test is whether a participant can modify, run, and revisit a small useful program on a nearby board from a tablet. Record the participant's previous workflow and reason to choose PyBLE. Chemistry may provide a later teaching context, but the core remains discipline-neutral. Use low-risk temperature or light measurements with reviewed hardware, not unattended pumps, heaters, or safety-critical experiments. + +## 4. Objectives and measurement + +### 4.1 North-Star outcome + +**Non-maintainer users who complete a real board session and return for another task.** + +An activated participant must install a recorded app build, select the correct provisioned board, establish PBLE/1 communication, transfer or open the intended example, and obtain its expected result. An installation, star, connection alone, or maintainer-generated test is not activation. + +A repeat user completes another useful session on a different day. Here, independent means outside the implementation/release team, not necessarily unrecruited. Report recruited participants, classroom participants, and independently arriving users separately; never combine them into a claim of organic adoption. First-program completion is onboarding evidence. Product-value evidence also needs a meaningful second task, the participant's reason for choosing PyBLE, and the obstacles or alternatives encountered. Separate participant-initiated use from prompted demonstrations and instructor-assigned work. + +### 4.2 Proposed 12-week targets + +These are planning targets, not forecasts or statistical claims. Recalibrate after the first observed sessions. + +| Objective | Proposed target | Measurement and qualification | +|---|---|---| +| Accurate public status | All maintained entry points agree on verified distribution and support status | Dated channel/build matrix; automated copy/link checks where practical | +| First-use success | At least 80% unassisted completion among at least 12 eligible primary-cohort participants who start the task | At 12 starts, at least 10 must succeed unassisted; failed and abandoned starts remain in the denominator | +| Time to first successful run | Observed p90 at or below 10 minutes for successful, unassisted Task A runs | Starts at first app launch; report alongside all-start completion, failures/timeouts, and raw small-sample distribution; never present successful-only p90 as all-user experience | +| Early repeat use | Provisional indicator: at least 40% complete another useful session in days 7–14, once at least 20 participants are eligible for follow-up | Show all mature eligible participants, confirmed useful returns, respondents, missing follow-up, and prompting/assignment separately; interpret against opportunity to use | +| Useful second task | Record attempts and outcomes beyond the introductory demonstration | Task C in §12: previous workflow, meaningful adaptation or own task, reason to choose PyBLE, assistance, and reason for return/non-return; a repeated print demo alone is insufficient | +| Compatibility evidence | Target a candidate-bound core workflow matrix for five profiles × iPadOS/Android | Ten minimum combinations; stage execution by risk and capacity; incomplete rows cannot support new qualification claims | +| Data safety | Zero unexplained file/draft loss or silent corruption in the defined release suite | A gate for that suite, not a universal reliability guarantee | +| Actual adoption | Aim for 30 non-maintainer activations by cycle end | Report recruitment source; optional consent-based evidence; discovery target, not a release blocker | +| Independent feedback | At least five substantive reports, demonstrations, or walkthroughs | Count positive and negative feedback; no requirement to publish identity or praise | + +Before the first observation, fix the task version, eligibility, equipment, permitted written guidance, assistance rule, and maximum session duration. Proposed Task A timeout is 30 minutes, subject to the pilot lead's review before collection. Live hints or intervention count as assistance; a safety intervention always takes priority. Keep failures, abandonment, and timeouts in the completion denominator; document pre-task exclusions. For successful unassisted runs, compute the empirical p90 by the nearest-rank method and report its sample size. If no runs qualify, report it as unavailable. + +The 12-person first-use cohort is not enough to assess the 20-person retention indicator. Aim to activate at least 20 primary-cohort follow-up-consenting participants by **22 November**, allowing day-14 windows to close by **6 December**. Report the day-7–14 return fraction among all mature, consented follow-up participants in that cohort, with respondents and missing responses separately. Missing follow-up is not a confirmed non-return. If the denominator is below 20, classify the retention target as **inconclusive**, retain the descriptive results, and defer the broad expansion decision; do not block an otherwise qualified maintenance fix or a bounded existing-profile rehearsal. + +At follow-up, record whether a relevant task arose, whether the board/tablet was available, what was attempted, and the reason for returning or choosing another workflow. Retain participants without a new task in the primary denominator; an opportunity-to-use subgroup is supplementary and must disclose its denominator and missing answers. Keep the 7–14-day window for comparability. If the selected audience has a different task cadence, define an additional observation window before follow-up begins and report it separately. A numeric threshold alone does not establish product value, and an infrequent task schedule alone does not establish rejection of PyBLE. + +### 4.3 Privacy-preserving evidence + +Keep no-telemetry-by-default. Do not introduce background identifiers or silent transmission to satisfy a KPI. + +Use explicit pilot observation, optional follow-up, store-console aggregates available to the owner, and a user-initiated diagnostic export if PYB-007 is delivered. Until then, use a reviewed manual support template with the same exclusions. A local measurement record can include a random pilot-session ID, app build, firmware artifact, profile, task outcome, elapsed time, assistance count, broad failure category, task opportunity, and prompting/assignment status. Summarize task purpose, prior workflow, and reasons for return/non-return without recording private project details. Do not include MAC addresses, source code, console contents, student identifiers, or account details by default. + +Retention measurement needs a consented way to link two observations. An anonymous single-session report cannot establish retention. Keep contact/consent records separate from technical observations and adopt an explicit retention/deletion policy before collection. + +## 5. Architecture and engineering boundaries + +### 5.1 Preserve the current component separation + +The intended dependency chain remains: **PyBLE app → PBLE contract → agent implementation → MicroPython and board resources**. The application should consume negotiated capabilities rather than route behavior through a hard-coded chip-family allowlist.[^readme] + +| Component | Existing location | Planned change | +|---|---|---| +| Tablet application | `app/` | A-24 durable drafts, measured onboarding/retry fixes, optional diagnostics; keep UI behind `Connection` and `FakeConnection` tests | +| Agent and board ports | `firmware/` | Approved reliability work and exact-profile qualification | +| Wire contract | `docs/specifications/protocol.md`, existing `protocol/` assets | Compatibility rules, vectors, approved additive capabilities | +| Validation | `tests/` | Package existing coverage into reproducible operator-facing runs | +| Website and Learning Center | `tools/web/` | Maintain corrected release state and static Next.js export; reuse existing tutorials and add reviewed localization only when resourced | +| Public examples | Separate `PyBLE-dev/examples` repository | Small reviewed tasks with board/wiring/provenance metadata | +| Decisions and planning | `docs/decisions/`, `docs/planning/` | ADRs, this plan, stage decisions, and scope changes | + +New filenames and formats proposed in this plan are not existing interfaces. Preserve the root layout mandated by `AGENTS.md`.[^agents] + +### 5.2 Non-negotiable technical boundaries + +- BLE remains the normal interactive transport; USB/BOOTSEL remain explicit provisioning and recovery paths. +- No automatic execution on import, no implicit overwrite, and no silent formatting of nonblank storage. +- File integrity, session ownership, and bounded memory take precedence over transfer speed. +- Existing upstream dependency boundaries, licensing, and clean-room rules remain intact. +- App version, firmware version, protocol compatibility, and store build identity remain separate. +- A valid hash proves integrity relative to a manifest, not that a publisher or nearby device is trustworthy. +- Device labels and advertised identifiers help selection but do not authenticate ownership. + +## 6. Release and protocol strategy + +### 6.1 Separate three decisions + +**Maintenance release:** fixes existing behavior and improves onboarding without requiring new wire operations. + +**Firmware feature release:** implements approved, capability-gated additions with exact cross-version semantics. + +**Distribution release:** publishes a particular app artifact to a particular store/testing channel. A merge or version bump does not establish availability. + +Do not require the complete v0.7.0 feature program before stabilizing the existing app. Conversely, do not call an incomplete implementation “v0.7.0” merely to meet the calendar. + +**Maintenance lane:** release a bounded fix whenever its applicable specification, regression, physical, provenance, and distribution gates pass. Recruitment, retention, translated pages, and the full strategic program are not prerequisites. Record which requirements apply to an app-only, firmware, website, or documentation change; do not waive a normative requirement simply because the change is small. + +**Cycle candidate lane:** aggregate the selected changes, qualification evidence, and user observations for the twelve-week review. Pilot findings determine wider acquisition and next investment. They can inform a maintenance release without making every release depend on a completed cohort. Website/docs corrections can ship through their own checks and deployment process without waiting for a store submission. + +### 6.2 PBLE/1 policy + +Preserve established operation numbers and payload encodings. “Stable PBLE/1” means compatibility stability, not a prohibition on all additive improvements. New operations require specification approval, explicit capability advertisement, fallback behavior, and conformance vectors before implementation. A genuinely incompatible change requires a separate version decision; PBLE/2 is not a scheduled deliverable.[^firmware-roadmap] + +### 6.3 Integrate Reliable Projects rather than invent a parallel roadmap + +The existing v0.7.0 proposal already identifies the next reliability foundations.[^firmware-roadmap] + +| Proposed capability | User outcome | Sequencing decision | +|---|---|---| +| Queryable run/session state | Reconnect without guessing whether code is still running | Early candidate if pilot failures show state ambiguity | +| Transfer status and explicit abort | Understand or cancel a transfer without damaging the prior destination | Prioritize when transfer recovery is a measured blocker | +| Complete directory enumeration | Never mistake a truncated list for a complete workspace | Prioritize before large example collections | +| Project-aware file execution | Portable `__file__`, working directory, sibling imports, and module cleanup | Build on v0.6.1 fresh globals/stdin isolation; do not count that implemented hardening as a new v0.7.0 feature | +| Loss-aware console/input | Distinguish missing output from program behavior | Add only with bounded queues and cross-port parity | +| Diagnostics and recovery ladder | Recover with explicit, explainable steps | Validate current mechanisms before proposing additional reset behavior | + +**First-cycle rule:** review and size one proposed capability only if the core backlog leaves capacity. Protocol implementation is not in the base 12-week commitment. An explicit scope decision can substitute one coherent slice for other work after the contract is approved. The complete feature set remains conditional work for a later cycle, not a promised 3–6-month delivery. + +**Dependencies:** atomic multi-file deployment follows transfer status/abort and project semantics; classroom bundle import must not imply atomic project publication before that foundation exists. Sensor plotting follows reliable execution and an explicit data-format design. Authenticated ownership has its own threat-model and compatibility gate. + +## 7. Workstreams and deliverables + +Map these ownership areas to the three active outcomes in §1.5. W1–W3 contain the core delivery work; W4 supports observations with a manual template unless export implementation fits. W5 localization needs reviewer capacity. W6 permits an early existing-profile rehearsal within PYB-009, while badge launch and partner intake remain conditional. W7 contributes pilot preparation only if the selected audience needs it. These are not seven simultaneous implementation commitments. + +### W1 — Distribution and release truth + +**Owner:** release maintainer, supported by documentation owner. + +Extend the existing publication review into one reviewed channel/artifact record. Distinguish prepared, submitted, processing, testing, production, paused, and unavailable states. Record the source of each state and its last verification date. Document country, account, and device restrictions when known; do not imply universal availability from a single successful store-page fetch. Keep existing website copy/link checks; introduce a generated shared data source only if repeated drift warrants that extra machinery. + +Deliverables: channel/build matrix, verified installation instructions, maintained README/store/site consistency, store-artifact provenance, and an update/rollback procedure. Accept the listing-status row from dated first-party publication evidence. Accept the installation row only after installation through that channel on an eligible physical device. Record uploaded AAB/IPA identity separately from store-delivered/re-signed or split binaries; equal version names or unequal upload/install hashes alone do not resolve provenance. + +### W2 — First use and mobile resilience + +**Owner:** app maintainer. + +Observe users before redesigning screens. Concentrate on permissions, unsupported firmware, ambiguous board names, read-only paths, disconnected sessions, background/resume behavior, keyboard interaction, and error messages. Retain existing readiness and session handling. Specify the persisted draft, write boundary, recovery choice, failure handling, and board association before closing A-24's process-restart gap. Recovering local text must never silently overwrite or run code on a newly selected board. + +Deliverables: an observed path through the existing console-only first-program tutorial, improved where evidence warrants; one useful task adapted by participants; a bounded durable-draft increment; and recovery guidance reachable at the relevant failure. Evaluate text-document and Blocks workspace recovery separately. Do not claim a full persistent project system, automatic reconnect, or an unavailable firmware capability from these narrower changes. + +### W3 — Reliability and reusable conformance + +**Owner:** protocol/firmware maintainer with QA reviewer. + +Inventory existing tests before adding a second framework. Start with `tests/firmware_tests/run_tests.sh`, the Python host/conformance suites, Flutter tests, the HIL operator guide, and `firmware/qualification/`. Document prerequisites, exact commands, expected evidence, and safe hardware selection. Publish the operator recipe before or alongside the first matrix run; a fully completed matrix is not a prerequisite for writing that recipe. Distinguish protocol conformance from app usability and physical qualification. + +Deliverables: capability/test coverage map, reference failure cases, bounded fault-injection scenarios, profile matrix, and an operator guide that a second engineer can execute. A failing or absent row blocks the corresponding compatibility claim. + +### W4 — Feedback without surveillance + +**Owner:** QA/pilot coordinator. + +Begin with a manual support template. If capacity permits, implement a user-initiated, previewable export of observed app/agent versions, bounded error codes, and optional diagnostic summaries. Label exact profile/build information as operator-supplied or unknown when the current contract cannot report it. Do not infer an exact profile, firmware hash, or source commit from `chip` and agent SemVer. Remove secrets, source, file contents, and persistent device identifiers by default. Console text is excluded unless the user explicitly reviews and includes it. + +Deliverables: pilot protocol for one primary cohort, reviewed support template, private participant register, and public aggregate findings on activation, meaningful second tasks, opportunity to use, and support burden; previewable export is optional PYB-007. Do not add automatic upload or background analytics. + +### W5 — Authoritative documentation and discoverability + +**Owner:** documentation/community lead; native-language review required for localized safety guidance. + +Maintain the corrected English identity and existing Learning Center. If a reviewer is assigned, begin with a small Simplified Chinese entry point covering setup, compatibility, and recovery; expand into separate pages after observing demand. Prepare reviewed Thai lesson support where a local pilot needs it. Existing app locale strings are not evidence that website translations or classroom materials are complete. Translations must follow the verified release state rather than introduce additional capability claims. + +Deliverables: reviewed localized core pages, a corrections/FAQ page, an evidence-based media kit, and a deduplicated coverage register. Article count and recommendation-panel read counters remain awareness metrics only. + +### W6 — Selective ecosystem enablement + +**Owner:** lead maintainer, later shared with an external profile maintainer. + +Use one existing exact profile to rehearse the published operator procedure with a second engineer. Reuse the five-profile tooling and evidence formats; record assistance and gaps. Prepare a compact PyBLE Ready evidence page and the installation-status distinction in §14. Pilot one external maintainer only after the record and support responsibilities are usable; the pilot can maintain an existing profile. + +Early deliverable: one reproducible existing-profile procedure and draft compatibility record, if funded within PYB-009's estimate. Later deliverables: reviewed badge/revalidation rules, the first complete public record, and one external maintenance pilot. New ports require demonstrated demand and capacity. Track setup failures and support effort; keep broad program promotion outside the first-cycle commitment. + +### W7 — Classroom and research validation + +**Owner:** instructor/research lead with an independent evaluator where feasible. + +Start with one low-risk lesson, pre-provisioned exact-profile boards, and a backup workflow. Evaluate both teaching utility and setup/support costs. Run research preparation in parallel, but do not make a manuscript or student project a prerequisite for the initial product release. + +Deliverables: lesson pack, teacher runbook, pilot report, reproducible technical benchmark, and a publication decision based on measured contributions. + +## 8. Twelve-week implementation schedule + +### 8.1 Capacity assumptions + +The schedule assumes one primary maintainer can allocate approximately **20 hours per week**, with limited help for physical testing, participant coordination, and translation. This is an explicit planning assumption, not a known commitment. + +This gives **240 total hours**, provisionally split into **156 planned hours** and **84 hours reserved** for support, additional qualification, release work, and uncertainty: at most 26 planned hours per two-week sprint. Estimates must include each selected change's known specification, implementation, review, and test effort. The reserve is not a substitute for budgeting mandatory tests. If availability is lower or required physical work exceeds the estimate, reduce optional scope or extend the schedule; do not remove evidence gates. + +The draft allocation below uses 136 planned hours and leaves 20 planned hours unassigned. It is a capacity limit to refine in S1, not a claim that A-24 or the full hardware matrix fits a predetermined estimate. Size the persistence design and required matrix first. If either exceeds one sprint, split it into independently reviewable increments and replan before implementation. + +The cycle intentionally excludes a complete new protocol version, full classroom product, security implementation, and multiple new ports. + +### 8.2 Sprint plan + +| Sprint | Proposed dates / planned-hour cap | Selected work | Review evidence / exit condition | +|---|---|---|---| +| S1 | 28 Sep–11 Oct 2026 / 22 h | PYB-001/003/004; residual PYB-002; size PYB-006 and inventory PYB-009 | One primary cohort/task selected; channel unknowns assigned; five baseline observations or recruitment blocker; persistence scope and costed matrix; name a second operator if available | +| S2 | 12–25 Oct 2026 / 24 h | First bounded PYB-006 increment; PYB-005 fix if warranted by observations; operator recipe PYB-009 | Durable-draft contract and regression evidence for delivered scope; existing lifecycle behavior preserved; first representative iPad/Android runs | +| S3 | 26 Oct–8 Nov 2026 / 24 h | Complete selected core increment; staged PYB-008; continue PYB-011 | Exact-artifact results; owners/dates for remaining rows; Task C attempts on a recorded build; optional existing-profile reproduction within 009's budget | +| S4 | 9–22 Nov 2026 / 22 h | PYB-011 and PYB-012 improvement if warranted by observations | At least 12 primary-cohort started-task outcomes, including failures; reasons to choose PyBLE and second-task outcomes; aim for 20 activated follow-up participants by 22 November | +| S5 | 23 Nov–6 Dec 2026 / 24 h | PYB-013/014; finish applicable matrix and mature follow-ups | Frozen candidate, applicable compatibility gates, provenance and recovery evidence; day-14 follow-up accounting; release or documented blocker | +| S6 | 7–20 Dec 2026 / 20 h | Verify PYB-014; cycle review; optional PYB-015 | Actual channel/install state; useful repeat tasks, opportunity-to-use and support findings; any Ready rehearsal results; one explicit next-stage decision | + +PYB-007 export, PYB-010 localization, PYB-015 outreach, PYB-016 research preparation, and PYB-017 protocol design use only explicitly allocated spare or independent contributor capacity. They do not displace data safety, required compatibility, or observed onboarding fixes. Qualified maintenance releases can ship in any sprint under §6.1. External store review and recruitment may extend the calendar. Submission is not approval, and approval is not proof of successful activation. + +A second-operator rehearsal and draft Ready criteria must fit the existing PYB-009 estimate or use an explicitly assigned part of the 20 unallocated planned hours. Do not add an uncosted program beside the 136-hour allocation. If no second operator is available, retain the procedure and pending result without claiming independent reproduction or blocking unrelated maintenance delivery. + +### 8.3 Critical path + +**Delivery path:** installed-build/provenance check and scope selection → contract/regression → bounded fix → applicable candidate-bound qualification → release decision → verified distribution. + +**Learning path, running alongside delivery:** select one audience/job → baseline observation → useful second task on a recorded build → follow-up with opportunity-to-use context → expansion decision. Significant pilot failures feed back into delivery priority. Recruitment delays are not a dependency for correcting known defects. + +Localization and research preparation can run beside this path when independent help exists. New firmware features must not become accidental dependencies for releasing a reliable existing workflow. + +### 8.4 Twelve-to-twenty-four-month horizons + +| Horizon from start | Direction | Admission condition | Bounded outcome | +|---|---|---|---| +| Months 0–3 | Reliable mobile product | Selected scope and capacity assigned | Qualified maintenance candidate and useful-task evidence; optional existing-profile Ready rehearsal within assigned capacity | +| Months 3–6 | Reliable Projects | Pilot shows a relevant problem; v0.7.0 scope approved | Selected additive capabilities with full compatibility evidence | +| Months 3–9 | PyBLE Ready and partner pilot | Existing-profile procedure reproduced; first complete record and maintenance rules reviewed | One external maintainer/profile pilot; an existing profile is valid; add a new profile only with demonstrated demand | +| Months 6–12 | Classroom workflow | Core app reliable; security review accepts supervised deployment | One reusable lesson workflow and at least two measured pilot sessions | +| Months 6–12 | Research outputs | Reproducible results and a defensible contribution | Technical/software manuscript; education study only with suitable evidence | +| Months 12–24 | Ecosystem and secure deployment | Sustained demand, external ownership, and support capacity | Reviewed compatibility program; authenticated mode or richer data workflow only if justified | + +These horizons overlap where staffing permits. They are not simultaneous commitments for a solo maintainer. + +## 9. Prioritized implementation backlog + +**Planning IDs below are not GitHub issue numbers or approval to implement.** The 25 September review found no open GitHub issues; recheck before creating/linking an accepted work item. Preserve existing story/ADR identities such as A-24 and ADR-0010. P0 means required for the selected stage, P1 means valuable but negotiable, and P2 means discovery or optional expansion. A future-stage P0 is not permission to interrupt the current cycle. Owners below are unassigned roles until a named person accepts them. + +### 9.1 First-cycle backlog + +| ID | Priority / owner | Deliverable and acceptance criterion | Dependency | +|---|---|---|---| +| PYB-001 | P0 / Release | Extend §2.2 into channel/install/provenance/qualification records; capture actual installed version/build and source mapping, or an explicit unknown with owner | Existing publication review | +| PYB-002 | P0 for accuracy / Docs | Android README/site/metadata correction **complete in PR #33**; retain checks and resolve only newly identified discrepancies or historical supersession notices | 001 for new discrepancies; completed copy is not a blocker | +| PYB-003 | P0 / Lead + QA | Threat model, pilot boundaries, safe hardware scope, consent/data-handling procedure, and signed-off pilot decision | 001 | +| PYB-004 | P0 / QA | One primary cohort/job; repeatable activation task and useful Task C; previous workflow, baseline timing, assistance, failure categories and prospective follow-up rules | 001, 003 | +| PYB-005 | P0 if observed blocker / App | Improve the existing tutorial/readiness flow at the measured failure; novice distinguishes provisioning, permissions, discovery, and ready state | 004 | +| PYB-006 | P0 / App | A-24/ADR-0010 durable current-document recovery: accepted persistence boundary, relaunch recovery, interrupted-write/corrupt-state behavior, no implicit board overwrite/run; explicit Blocks scope; preserve session/lifecycle regression coverage | Current recorded gap; App specification/TDD and ADR review; 004 informs priority but is not a prerequisite | +| PYB-007 | P1 / App + QA | Optional user-initiated diagnostic export with preview/redaction and observed/supplied/unknown identity fields; manual template is the first-cycle fallback | 003; export contract approved; no dependency on completing 006 | +| PYB-008 | P0 for selected release claims / QA + Firmware | Staged exact-artifact five-profile × two-platform workflow matrix; pass/fail/not-run/blocked per row; map applicable normative gates before running | 001, initial 009 recipe, recorded candidate artifacts; rerun affected rows after relevant changes | +| PYB-009 | P0 / Protocol + QA | Inventory existing suites; add operator recipe and coverage map; within assigned capacity, a second operator rehearses one existing exact profile and supplies a draft Ready record with assistance/gaps | 001 and source inventory; starts before 008; reproduction stays pending without an operator; no new port or badge award required | +| PYB-010 | P1 / Docs | Reviewed Simplified Chinese identity, setup, compatibility, and recovery guidance; code tokens remain unchanged | Verified current guidance and language reviewer; incorporate 005 if selected | +| PYB-011 | P0 for usability decision / Pilot lead | At least 12 primary-cohort started-task outcomes plus useful second-task attempts/reasons; target 20 activated participants for mature follow-up; distinguish prompting, task opportunity, and missing responses | 003, 004, recorded tested pilot setup; start on the current release without waiting for every 008 row or 005 | +| PYB-012 | P0 when a severe failure is observed / Maintainer | Fix the highest-impact observed failure; use regression evidence and comparable task cohorts; no invented issue if observation finds no blocker | Sufficient evidence from 004 or 011; no dependency on completing the cohort | +| PYB-013 | P0 for release / Release + QA | Immutable candidate evidence and sign-off; applicable matrix passes; no unresolved release-blocking data loss, unintended/cross-session writes, or critical workflow regression under the accepted threat model | Applicable 008/009 evidence and included fixes; full 011/012 cohorts are not release prerequisites | +| PYB-014 | P0 when a release is ready / Release | Submit the qualified next app build to the selected existing channel; record submission, availability, installed identity, and installation outcome separately | 013; distribution-owner access; production promotion requires a separate decision | +| PYB-015 | P1 / Community | Accurate release kit and coverage register; pitch only verified capabilities and availability | 002, 013; verified channel before availability claims | +| PYB-016 | P1 / Research lead | Benchmark protocol, pilot analysis plan, and ethics-review decision before research data collection | 003, 004 | + +### 9.2 Conditional expansion backlog + +| ID | Stage / owner | Deliverable and acceptance criterion | Dependency | +|---|---|---|---| +| PYB-017 | P0 / Protocol | Approved v0.7.0 scope, ADRs, capability registry, and cross-version test plan before implementation | Default after first-cycle review; earlier design only by explicit capacity/scope decision | +| PYB-018 | P0 / Firmware + App | Queryable run/session state; reconnect and autorun tests show no stale-state assumption | 017 | +| PYB-019 | P0 / Firmware + App | Transfer inspection/abort; old destination survives failure, abort is idempotent, ordinary disconnect still permits defined resume | 017 | +| PYB-020 | P0 / Firmware + App | Complete directory enumeration with documented mutation behavior; every entry returned once for an unchanged test directory | 017 | +| PYB-021 | P0 / Firmware | Project-aware execution; sibling imports, path restoration, module cleanup, and fresh runs agree across agents | 017 | +| PYB-022 | P1 / Firmware + App | Bounded loss reporting and explicit recovery UX; console floods cannot silently redefine STOP semantics | 018, 017 | +| PYB-023 | P0 before untrusted deployment / Security lead | Ownership/authentication RFC, independent review, downgrade/reset/recovery tests; implement only after versioning decision | 003; approved security scope | +| PYB-024 | P0 before badge award / Protocol + QA | Reviewed Ready criteria/use/revalidation/withdrawal rules and first complete public exact-profile record; visible installation status; reuse evidence formats; award only when every declared criterion passes | 009 reproduction, applicable qualification evidence, named owner/reviewer; not an app-release dependency | +| PYB-025 | P1 / Partner owner | One external maintainer sustains an existing or justified new exact profile; independent results, agreed support/retest responsibilities, and setup/maintenance effort recorded | 024, demonstrated user need, named owner/capacity; new port optional and subject to normal gates | +| PYB-026 | P1 / Education lead | Offline lesson pack with reviewed wiring, expected outcome, recovery path, and accessibility review | Core workflow gate | +| PYB-027 | P1 / App + Education | Safe lesson import/QR flow; bounded parsing, preview, explicit overwrite consent and separate Run action; no implicit atomic-deployment claim | 026; approved bundle specification | +| PYB-028 | P1 / Education + QA | Two supervised classroom sessions with measured setup, completion, wrong-board events, and support burden | 026; 003 refreshed for classroom use | +| PYB-029 | P2 / Research + App | Sensor-data/plotting experiment with bounded rate, units, timestamps, loss reporting, and explicit export | Stable execution/console; demonstrated demand | +| PYB-030 | P1 / Research lead | Reproducible technical benchmark and submission-ready research package if results justify it | 016, qualified artifacts | +| PYB-031 | P2 / Project owner | One scoped paid-support or vendor-integration pilot with recorded delivery/support effort and no closed app features | Demonstrated demand and support capacity | +| PYB-032 | P2 / Protocol | Atomic project-deployment RFC and interruption model, not an implementation promise | 019, 021; measured multi-file deployment need | + +Split any issue that combines several independently releasable behaviors or cannot fit into one sprint. Do not assign opcode numbers, capabilities, schemas, or release numbers in issue text without linking their approved specification. + +Before scheduling each selected item, add its named owner/reviewer, estimate including validation, normative references, evidence location, release lane, and current state (`completed`, `ready`, `in_progress`, `blocked`, or `proposed`). Status belongs to a specific deliverable: PR #33 completion does not complete installed-build verification, and an approved design does not complete its implementation. + +## 10. Quality, compatibility, and release gates + +### 10.1 Definition of Ready + +An implementation issue requires an owner, user problem, affected contract, explicit in/out scope, dependencies, acceptance scenarios, test approach, and rollback/recovery considerations. Protocol changes require an approved specification and compatibility decision. Hardware claims require named physical devices and an evidence plan. + +### 10.2 Definition of Done + +A behavioral change is done when its relevant specification is updated; the required failing test and minimal passing implementation are recorded; applicable regression, dependency, license, DCO, and clean-room gates pass; documentation matches behavior; and required hardware evidence is attached. Documentation-only planning revisions need source/link/consistency review and applicable repository gates, not artificial behavioral tests. A merged change may be complete as source work while remaining unqualified for release. Preserve that distinction.[^agents] + +No screenshot, AI-generated report, mock test, or maintainer assertion substitutes for a physical measurement that a release gate explicitly requires. Record `not_run`, `blocked`, or a reviewed exception instead of manufacturing a pass. + +### 10.3 Minimum regression coverage + +| Test area | Required scenarios | +|---|---| +| First use | Permissions denied/retried, incompatible firmware, no board, multiple similarly named boards, writable-path guidance | +| Connection lifecycle | Disconnect during transfer/run, background/resume, explicit retry/reconnect, stale acquisition/completion, invalid or missing capability | +| Local recovery | Process termination/relaunch distinguished from in-process suspension; accepted write boundary; interrupted/corrupt local state; text versus Blocks scope; restore never writes/runs on a board implicitly | +| Files | Empty and boundary-size files, Unicode names, full storage, failed overwrite, conflicting mutation, interrupted transfer | +| Execution | Sequential isolated runs, errors, tight loops, console flood, STOP, documented escalation and recovery | +| Compatibility | Name exact released-app/firmware baselines; run released app against changed firmware and candidate app against declared supported firmware; do not treat mutable branch names as artifact identity | +| Import | Immutable source preview, explicit destination/overwrite review, no automatic execution, network failure and rate limit | +| Privacy | No unexpected background requests; exports omit sensitive content by default; offline core workflow still works | +| Provisioning | Correct exact profile, wrong-profile refusal where detectable, erase warning, ESP recovery, Pico BOOTSEL recovery | + +Use the current normative latency, resource, and payload limits. Where limits are absent, measure a baseline, propose a bound, and approve it before using it as a gate. Do not invent a faster number and silently weaken an existing guarantee. + +### 10.4 Hardware evidence design + +For each of the ten minimum app-platform/profile combinations, record app delivery channel/version/build and available artifact provenance, exact firmware bytes, physical board revision and memory, operating system/device, test-suite revision, negotiated BLE conditions, operator, and time. Where installed-byte identity cannot be extracted, record the evidence limitation and whether the applicable gate accepts that provenance; never invent a matching hash. Run controlled and representative interference scenarios separately. + +Inventory the existing normative counts, reset/transfer limits, release schemas, and profile-specific gates before estimating the matrix. Start with representative iPad and Android rows to expose harness/setup failures, then execute every row required for the selected claim. A representative subset is an engineering checkpoint, not a substitute for five-profile qualification. Missing hardware or operator capacity becomes a dated blocker; reduce optional work, extend the schedule, or explicitly review the release scope without weakening normative gates. + +Additional endurance counts are optional experiments to size after that inventory; this plan adds no arbitrary 100-operation/30-recovery floor on top of existing suites. Include the required interruption/fault cases, not only successful repetition. Zero observed corruption in a finite suite is not proof that corruption can never occur. + +Reuse the existing manifests and `firmware/qualification/` reports for release admission. The following is an **illustrative supplemental observation record**, not a new authoritative release schema, completed test, or replacement for required HIL receipts. Map its fields to existing evidence before introducing a maintained format. + +```yaml +record_kind: "proposed-pilot-observation" +record_id: "replace-with-unique-test-record-id" +profile: "esp32-4mb" +app: + platform: "android" + delivery_channel: null + version: null + build_number: null + source_commit: null + uploaded_artifact_sha256: null + installed_artifact_evidence: null +firmware: + version: null + source_commit: null + artifact_sha256: null +hardware: + profile_evidence: null # provisioning/operator evidence, not inferred from chip + board_revision: null + flash_mib: null + psram_mib: null +suite_commit: null +os_version: null +started_at: null +scenario: "interrupted-upload-preserves-existing-file" +result: "not_run" +evidence_paths: [] +reviewer: null +``` + +Raw logs belong in appropriate artifact storage, not automatically in Git. Publish redacted manifests and hashes; retain the supporting raw records under the agreed access/retention policy. + +### 10.5 Release admission + +A new qualification claim requires candidate-bound passing evidence for that claim, an approved support matrix, known limitations, reproducible build/provenance records, recovery instructions, and the applicable installation checks. Publication wording uses the separate evidence levels in §2.2; an official listing can establish open-testing availability without proving installed build identity. Regenerate or explicitly revalidate evidence when relevant code, dependencies, build inputs, or hardware change. + +Existing v0.6.1 publication history remains recorded as owner-confirmed with incomplete automated evidence. This plan neither retracts that history nor relabels it fully automated-qualified. New evidence-backed badges and releases must satisfy their declared criteria.[^readme] + +**Release-blocking write failures** mean unintended writes, wrong-session completion, jail bypass, or behavior outside the approved contract and accepted deployment threat model. PBLE/1 currently trusts the connected client. This plan does not silently add authenticated ownership as a prerequisite for every maintenance release; untrusted deployment remains a separate security gate. Known exceptions/deviations must be linked and visible, not converted into passing test results. + +### 10.6 Verification entry points + +Use [.github/workflows/ci.yml](../../.github/workflows/ci.yml) for the current pinned environments and mandatory PR checks. The table identifies existing tools, not a claim that they were rerun for this plan or that every command is needed for every edit. + +| Change / evidence | Existing starting point | Limit | +|---|---|---| +| Documentation | `python3 tools/ci/docs_links.py`; publication tests under `tests/publication/` | Normal link discovery uses tracked Markdown; explicitly include a new untracked plan when reviewing it | +| Contributor/source gates | `tools/ci/no_leak.sh`, `tools/ci/spdx_lint.sh`, DCO and affected import/locale gates | Checks do not establish physical behavior | +| App | Locked dependency resolution, analyze/unit/widget/golden/WebView jobs in CI | FakeConnection and emulator results do not replace iPad/Android BLE evidence | +| Firmware/protocol host | `tests/firmware_tests/run_tests.sh`; `python3 -m unittest discover -s tests/firmware_tests/host -p 'test_*.py'` | Host/conformance success is not hardware qualification | +| Physical/release | [HIL operator guide](../../tests/firmware_tests/hil/README.md), `firmware/qualification/`, exact-profile specs | Select actual devices and immutable candidates; report unrun or unavailable rows | +| Website | `npm run check` in `tools/web/` with the pinned Node version; deployment smoke/rollback procedure | Build success does not prove public deployment or search-index refresh | + +## 11. Security and physical safety + +Security work starts in the first sprint, not when industrial customers arrive. The existing planning documents state that PBLE/1 trusts a connected client and place authenticated ownership behind a separate design milestone.[^firmware-roadmap] + +### 11.1 Immediate boundaries + +Operate early pilots only in a supervised environment with trusted participants, non-sensitive scripts, and harmless loads. Explicitly explain that nearby device names, pairing UI, and a connected session do not by themselves establish authorized ownership under the current contract. + +Measure wrong-board selection and interference in a multi-board setting. If cross-user control cannot be acceptably contained, reduce the pilot to isolated stations or postpone it. Never describe untrusted-network, public-lab, or unattended industrial use as secure without the relevant authentication design and tests. + +STOP is software program control, **not an emergency-stop mechanism**. Independent hardware protections and physical disconnects are required wherever actuation creates hazards. The first classroom pilot should avoid motors, pumps, heaters, and mains-powered loads. + +### 11.2 Authenticated-owner design gate + +Before implementation, define physical-presence bootstrap, identity/key storage, replay and downgrade protection, expiry, revocation, lost-tablet recovery, credential reset, rate limiting, and legacy fallback. Determine which operations may remain public and how a device refuses privileged operations before authentication. + +Use established cryptographic constructions and obtain independent review; do not invent a custom cryptographic protocol. Decide explicitly whether the design can be optional and backward-compatible or needs PBLE/2. No security-sensitive fallback may silently turn a failed authenticated connection into an unrestricted one. + +### 11.3 Diagnostic and import boundaries + +User code is executable content even when supplied as an educational example. Preview source and destination; require a separate Run action. A signature or official-source label does not remove that requirement. Local lesson archives need limits on size, decompression, paths, filenames, and content types before extraction or transfer. + +## 12. Pilot and adoption strategy + +### 12.1 Separate onboarding from useful work + +**Task A — provisioned-board activation.** Provide an installed app or record app installation separately; start the timed task at first app launch with a powered, correctly provisioned board. The participant handles permissions, selection, connection, example transfer, and execution. Do not hide failed attempts or assistance. + +**Task B — complete self-service setup.** Start with the actual store invitation/listing and an unprovisioned supported board. Include finding the correct firmware, obtaining a compatible host/browser and cable, backup/erase decisions, flashing or BOOTSEL copying, and the first successful mobile program. Report this duration separately from Task A. + +These tasks answer different questions. A fast classroom experience with pre-provisioned hardware does not prove that a new maker can complete self-service setup. + +**Task C — meaningful adaptation and return.** After first use, ask the participant to identify a small result they want: for example, adapt a reviewed light/temperature script to change a threshold or sampling interval and inspect the output. Use existing features and a safe exact-board setup. Record the goal, previous workflow, reason to choose PyBLE, attempted change, outcome, assistance, and any alternative chosen. An unchanged rerun of the introductory print example is not sufficient evidence of useful adaptation. + +A Task C attempt in the first session measures ability to do useful work; repeat use requires a later-day session. Invite an optional follow-up when a relevant task arises, and label whether it was participant-initiated, researcher-prompted, or instructor-assigned. Assigned work can demonstrate usability and teaching utility without being counted as spontaneous demand. Capture failures and abandoned attempts as well as successful returns. + +### 12.2 Recruitment and rollout + +Begin with five observed baseline participants in the selected primary audience; extend to at least 12 eligible started tasks for the first usability gate. Include both Android and iPad users and different experience levels where recruitment permits; state any platform/sample limitation. The initial five may count toward the twelve only when task, eligibility, build, and observation rules are comparable; report changed-build/task cohorts and other audiences separately. Aim for 20 activated, consenting participants by 22 November for the retention indicator, or report it inconclusive. A small usability sample is not a population-level efficacy study. + +Use the existing console-only first program, then a useful Task C appropriate to the exact board and participant's goal. Record assistance, failures, and abandonment before asking for feedback. Invite—not require—follow-up use during days 7–14, with the task-opportunity and prompting distinctions in §4. + +Do not ask students to post positive reviews or use grades to secure participation. Do not reward stars, ratings, or favorable testimonials. Any compensation should be independent of outcome, disclosed, and compatible with the relevant platform rules at the time. + +### 12.3 Interpret the outcome + +Use observed outcomes to choose the next investment: + +| Observation | Next decision | +|---|---| +| Provisioned-board users succeed but self-service users cannot start | Improve board/firmware selection, provisioning and distribution; test whether a Ready record reduces the observed confusion | +| Users return for useful work but repeatedly struggle with several files | Review the relevant Reliable Projects slice and cross-version contract | +| Users complete onboarding but choose another workflow for subsequent tasks | Investigate task fit, project continuity, interaction and examples before adding capabilities | +| No relevant task arose, equipment was unavailable, or follow-up is missing | Record the reason/unknown; continue the prospective observation plan without treating absence as proven rejection | +| Wrong-board control occurs in group use | Contain the pilot and address selection/ownership boundaries before classroom expansion | +| An outside maintainer reproduces a profile, reaches users and accepts maintenance | Consider the bounded PyBLE Ready partner pilot; review support effort before another profile | + +If users return but create no public content, private successful use still counts. If public engagement rises without successful sessions, investigate discoverability and technical misinformation. A successful tutorial alone does not establish that the tablet workflow is preferred for real work. + +A support issue can be a positive usage signal; a quiet issue tracker can mean either reliability or non-use. Interpret it alongside observed sessions and follow-up, not in isolation. + +## 13. Documentation and international reach + +### 13.1 Establish one accurate technical identity + +Publish a concise fact sheet describing the Flutter tablet client, PBLE/1, compatible agent, current exact profiles, normal offline workflow, and provisioning/recovery boundaries. Explicitly distinguish PyBLE from GDB, JTAG/SWD tunneling, a desktop `bleak` client, Web Bluetooth IDEs, and universal BLE firmware OTA. + +Only correct claims that have been directly checked against the specification. Do not amplify inaccurate articles by reproducing their detailed invented interfaces. + +### 13.2 Simplified Chinese entry point + +Propose a reviewed `/zh-cn/` entry point with four essentials: what PyBLE is, setup and distribution, exact compatibility, and troubleshooting/recovery. Link back to the authoritative versioned English specification. Preserve protocol names, code, UUIDs, and identifiers verbatim. + +Treat Simplified Chinese as a targeted discoverability experiment prompted by the preceding CSDN discussion—not a claim that China is already the largest active user market. Measure consented activation/support outcomes where possible. If a reviewer is unavailable, publish a short reviewed page rather than extensive unreviewed safety instructions. + +A verified project-controlled CSDN presence may republish this reference with attribution. Do not assume an account already exists or create/post through it without separate authorization. + +### 13.3 Coverage register and outreach + +Maintain one record per canonical article with URL, outlet, language, first publication date, first discovery date, upstream source, technical accuracy notes, and evidence of hands-on use. Mark syndication and translations as such. Deduplicate recommendation links and mobile/desktop variants. + +This avoids repeatedly calling older FabScene or Open Source For You coverage “new,” and prevents publication-date and discovery-date confusion. + +Prepare a release kit containing a short real-device demonstration, reviewed screenshots, exact support table, setup guide, known limitations, and verified installation links. Pitch a follow-up to relevant existing outlets only when there is a real new result—such as a verified distribution milestone, independently reproduced port, or measured classroom pilot. + +Do not infer a paid campaign from a “Sponsored” page label, campaign termination from a few missing page renders, or article readership from an undocumented trending algorithm. Record observed placement only. + +## 14. PyBLE Ready and partner development + +### 14.1 Purpose and proposed promise + +PyBLE Ready should help users choose the correct board and firmware, complete setup, and find continuing support. It is a proposed compatibility program; this plan does not award a badge or establish an existing certification. + +The proposed public promise is: + +> This exact board configuration, running the listed firmware, passed PyBLE's published workflow checks with the listed app/platform versions and has a named maintenance owner. + +The claim belongs to an exact configuration and tested software matrix. It does not extend automatically to a chip family, another board revision, every peripheral, or later app/firmware releases. A compatibility label is not a security certification. Badge eligibility and use rules must be published and reviewed before the first award. + +### 14.2 One badge with visible installation status + +Use one public **PyBLE Ready** badge for a maintained, hardware-validated profile. Keep the intermediate evidence states in technical reports: + +| Evidence state | Meaning | Public Ready badge | +|---|---|---| +| Experimental | Source/build work with explicit limitations | No | +| Conformance-tested | Named implementation passes a versioned protocol suite | No; host results alone do not establish physical workflow | +| Hardware-validated | Exact board/software matrix passes the applicable physical checks | Not until maintenance, reproduction, and public-record requirements are met | +| Maintained and reviewed | Required checks and second-operator reproduction recorded; named owner and complete public record | Eligible after review against the published program rules | + +“Ready” can imply a board arrives already provisioned. Display one of these installation statements prominently beside the listing or badge: + +- **Firmware installation required:** the compatible board must first receive the listed firmware; link the exact installation and recovery instructions. +- **Firmware preinstalled:** the particular supplied board or kit includes the identified firmware; state the delivered version/artifact and first-use checks. Do not infer this from the model's compatibility record. + +Unknown installation status must be resolved before using the badge on a board/kit offer. A project profile page can state that it makes no claim about a seller's shipped firmware. Preinstalled status never removes the need for recovery instructions. + +### 14.3 Public evidence record and review + +Every badge must link to a stable public record. A packaging or product-page link must identify the exact configuration and claimed software version, and expose current support status. + +| Record field | Required content | +|---|---| +| Hardware | Model, revision, flash/PSRAM and other relevant configuration constraints; no inference from chip identity alone | +| Software | Firmware artifact hash/source and protocol/capabilities; tested app builds, devices, and OS versions with provenance limitations explicit | +| Workflow | Applicable provisioning, connection, file integrity, run/stop, interruption, and recovery results; links to versioned reports and existing release evidence | +| Reproduction | Test date, operator, second operator's reproduction result, suite revision, reviewer, and declared scope | +| Installation and limitations | Installation status as defined above; setup/recovery guide; known limitations and untested combinations | +| Maintenance | Named owner, support route, agreed response/retest responsibilities, review date, and current badge status | + +Publish redacted evidence and hashes using the existing release formats; do not expose device identifiers or participant records. Reuse qualification reports rather than create a parallel source of truth. A second operator should reproduce the published provisioning and core/recovery procedure, logging any maintainer assistance. Undocumented instructions or maintainer interventions are procedure gaps: update the recipe and have the second operator rerun the affected steps without bespoke help before the reproduction criterion passes. Assisted rehearsals remain useful pending evidence. Every mandatory release/program gate still needs its own required evidence. + +Owner-confirmed v0.6.1 publication **does not automatically confer PyBLE Ready status**. Each profile must meet the badge's declared evidence rules. An existing profile may be used for rehearsal while gaps remain explicitly pending. Reviewing one profile for a bounded compatibility claim does not waive an atomic five-profile release gate or qualify a new firmware release. + +### 14.4 Maintenance, corrections, and open access + +Assign the program reviewer and maintenance owner before an award. The public rules must define badge use, correction requests, a review interval, and suspension/withdrawal decisions. Use active, under-review (badge claim suspended), and withdrawn states with dated reasons; keep historical records accessible. + +Relevant firmware, app, dependency, board-revision, or provisioning changes trigger a documented impact review and the required retesting before extending the claim. New versions are untested until assessed; older passing results remain historical evidence. Missing an agreed review deadline, losing the maintenance owner, or discovering a material compatibility defect triggers review and suspension of the active badge claim as appropriate. Correct or withdraw unsupported claims and update the public record; do not silently rewrite previous results. + +Keep conformance tools and criteria openly available. Compatible PBLE agents must remain usable without a badge, program registration, payment, or an app-side board allowlist. The app continues to negotiate capabilities. Paid porting, testing assistance, or support cannot purchase a badge or bypass its evidence requirements. + +### 14.5 Phased introduction and outcome measures + +| Phase | Bounded work | Evidence needed to advance | +|---|---|---| +| Existing-profile rehearsal | Select one of the five existing exact profiles; reuse PYB-009's operator recipe; have a second operator reproduce it | Recorded results and assistance, reproducible setup/recovery, and explicit remaining gaps; no new port required | +| First public record | Complete the evidence and maintenance record and review the badge rules | All applicable criteria pass; users can distinguish compatibility from installation status; only then award the first badge | +| External maintenance pilot | Work with one outside maintainer on an existing or demand-backed new profile | Agreed ownership, independently reproduced results, and observed setup/support effort | +| Selective expansion | Add one justified profile at a time | User demand, sustainable maintenance, and the normal specification, qualification, and release gates | + +A short criteria draft and existing-profile rehearsal may start in the first cycle if included in PYB-009's estimate and a second operator is available. They do not create a new mandatory certification project or displace durable drafts and user observations. Broad promotion and external intake follow the first usable record and demonstrated support capacity. The initial partner pilot has one maintainer/profile; consider a second new profile only after reviewing that pilot. + +Measure correct board/firmware selection, provisioning success, setup duration, assistance count/support time, and maintainer effort per update. Compare like tasks, equipment, and starting installation states; report small samples and failures. Partner and badge counts alone do not demonstrate value. + +Choose a partner by access to exact hardware, willingness to publish evidence and maintain the profile, and access to users with a relevant task. Maintaining an existing profile is a valid first contribution. No partnership is claimed before agreement, and new chip-family coverage is not a prerequisite for testing the program. + +## 15. PyBLE Classroom + +### 15.1 Stage A: lesson packs before new application features + +Start with a versioned repository release containing readable `.py` examples, a teacher guide, wiring diagram, bill of materials, exact board profile, tested app/firmware versions, expected results, and recovery instructions. A ZIP may distribute teacher materials, but current app import does not imply ZIP ingestion. Reuse the existing reviewed, SHA-pinned import of a bounded public GitHub folder; keep files and categories within its current limits. Offline local lesson-archive import is future work, not a prerequisite for the first lesson. + +Pre-provision boards, label stations physically, verify safe selection, and retain a wired recovery station. Prepare a fallback lesson when radio conditions or device eligibility prevent participation. + +### 15.2 Stage B: optional structured bundle + +Design a `.pyble` lesson bundle only after repeated pilots identify a problem that ordinary lesson packs cannot solve. The extension and schema are proposals until approved. A minimal manifest should identify lesson/version, supported capabilities, tested hardware, source-file hashes, entry-point choices, safety notes, and minimum compatible app behavior. + +A QR code should identify a reviewed lesson or link, not silently execute code. Remote retrieval must be explicit; provide an offline file-sharing alternative. Do not add student accounts, mandatory cloud storage, arbitrary package installation, or a new learning-management system. + +Bundle validation must reject path traversal, symlinks, unsupported file types, excessive size/decompression, and conflicting destinations. Preview exact files and destinations before transfer; confirm overwrites separately. Until atomic project deployment exists, clearly report partial transfers and never imply that a multi-file project committed atomically. Do not automatically run a partially transferred lesson. + +### 15.3 Classroom admission gate + +Complete a multi-board interference/selection exercise and a security review before a class pilot. Begin with small groups; larger class sizes are a separate capacity and radio-validation task. Record instructor setup time, intervention count, completion, accessibility issues, wrong-board events, and lesson outcomes. Expand only if support effort is sustainable. + +## 16. Research and publication program + +### 16.1 Investigator-led technical study + +Frame the initial contribution around reliable, recoverable mobile interaction with constrained MicroPython devices—not simply “an IDE exists.” Use released, traceable artifacts and publish the experimental protocol, scripts, configurations, negative results, and analysis. + +Compare appropriate USB serial, Wi-Fi, or simple BLE workflows only where they can perform a comparable task on compatible hardware. Document differences in firmware, host, security model, file-integrity behavior, and initial setup. Do not declare victory by comparing unmatched workloads or excluding provisioning from only one condition. + +Measure task completion, latency distributions, throughput by payload size, reconnect/recovery time, data integrity under interruption, memory/resource bounds, and control behavior during console load. Energy measurements are optional and require calibrated equipment and a defined measurement boundary. + +### 16.2 Education study + +Separate exploratory usability work from claims of improved learning. Before collecting research data, determine institutional review and consent requirements. Use equivalent tasks, a counterbalanced or otherwise justified design, prespecified outcomes, and an independent evaluator where feasible. Report prior experience, device access, assistance, attrition, and missing follow-up. + +A chemistry-focused lesson could examine temperature acquisition or calibration on safe hardware. A later student project may build on the stable platform, but the first product cycle and technical manuscript should not depend on a future student cohort. + +### 16.3 Publication decision + +Select a venue after identifying the actual contribution: research software, embedded systems, computing education, or chemistry education. Re-check current submission and software-review requirements before submission. A DOI, license, media story, or extensive test suite helps reproducibility but does not guarantee publishable novelty or acceptance. + +Advance a manuscript when the contribution and evidence are sufficient. Otherwise publish an honest technical report and use the findings to improve the product. + +## 17. Sustainability and commercial validation + +Maintain the free, open core and existing prohibition on paid/closed PyBLE features.[^agents] Test revenue around work and support, not restrictions on basic use. + +Candidate offers are vendor porting, validation assistance, instructor training, classroom deployment support, openly maintained lesson development, and hardware kits with documented support. Propose partner-funded improvements that can be maintained upstream. Do not create a proprietary protocol extension or closed reference client to capture revenue. + +Before productizing an offer, conduct approximately five discovery conversations and one tightly scoped service pilot. Record engineering hours, recurring maintenance, hardware/logistics cost, support load, and whether someone will pay for the defined outcome. These are experiments, not revenue forecasts. + +Keep PyBLE Ready separate from payment for services. Porting, testing assistance, training, and ongoing support may be paid work, but payment cannot buy the badge, change a result, or unlock compatible app use. Keep self-run conformance tools and criteria openly available; define any future administrative funding model through a separate governance decision that preserves these boundaries. Funding through grants, sponsorship, donations, or services should not alter test outcomes or editorial honesty. + +## 18. Team, capacity, and operating process + +### 18.1 Role allocation + +| Role | Responsibility | Minimum practical arrangement | +|---|---|---| +| Project owner / product lead | Scope, prioritization, resources, stage decisions | Lead maintainer; fixed weekly decision slot | +| App maintainer | Flutter workflow, accessibility, lifecycle, diagnostics | Initially may be the lead maintainer | +| Firmware/protocol maintainer | Contracts, agent parity, compatibility | Initially may be the same person; limits parallel work | +| QA/release reviewer | Evidence, physical matrix, recovery, artifact identity | Separate reviewer for high-risk changes wherever feasible | +| Pilot/instructor lead | Recruitment, consent, safe lesson delivery, observation | Named helper or deliberately reduced cohort | +| Documentation/localization reviewer | Release accuracy and language review | Bounded review contribution, not assumed full-time staff | +| Partner port owner | Port maintenance and retesting | Required before accepting a new supported profile | + +Multiple roles can belong to one person, but this does not multiply capacity. Record missing independent review; do not disguise self-review as independent validation. + +### 18.2 Capacity and budget discipline + +Use existing boards/devices first and buy hardware only to close an identified matrix gap. Budget separately for physical test fixtures, spare boards/cables, app distribution, participant logistics, translation, and independent security review. Obtain actual costs before committing a funded milestone; this plan does not assume an approved budget. + +Limit work in progress to one substantial implementation change plus one documentation/release task. Hold weekly triage, a two-week evidence review, and a monthly decision review. Track time spent supporting each profile before accepting another. + +### 18.3 Issue-to-release workflow + +1. Select an issue and verify that it is not already implemented or tracked. +2. Approve scope and update the normative specification/ADR where required. +3. For behavior, add the repository-required failing test and implement the smallest passing change; use applicable document checks for documentation-only work. +4. Run relevant cross-component and clean-room/license gates; sign off commits. +5. Review behavior, evidence, privacy, compatibility, and recovery. +6. Merge only through the repository's actual rules and required checks. +7. Qualify the exact release artifact and update user-facing documentation. +8. Publish or submit, then verify the claimed installation path and record the result. + +Do not assume that a plan author, coding assistant, or passing simulator can approve hardware support, submit stores, or authorize a new protocol contract. + +## 19. Risks and strategic decision gates + +### 19.1 Risk register + +| Risk | Early warning | Mitigation / stop condition | +|---|---|---| +| Publicity without use | Articles rise but first-use/return metrics do not | Fix activation or reconsider the job to be done; stop feature expansion | +| Technical assurance without useful work | Reports grow while participants only repeat demonstrations | Keep the three active outcomes visible; observe Task C and reasons to choose PyBLE before expanding scope | +| Inaccurate third-party claims | Users expect GDB, desktop clients, or OTA | Maintain canonical fact sheet and targeted corrections | +| Release-state confusion | README, store, and app build disagree | Separate verified publication, installation, provenance, and qualification fields; date each source | +| Evidence debt | Owner confirmation or old tests reused as fresh qualification | Preserve history; require exact-artifact records for new claims | +| Nearby unauthorized control | Wrong-board access or untrusted-client writes | Restrict environment; stop unsafe pilots; advance ownership-security design | +| File or draft loss | Recorded volatile drafts remain unresolved; overwrite, stale state, or silent corruption appears | Prioritize A-24; reproduce release-blocking regressions; never claim durable recovery before its evidence passes | +| Solo-maintainer overload | Support consumes reserved capacity; fixes accumulate | Reduce new scope and parallel work; review support changes explicitly; recruit ownership before expansion | +| Board fragmentation | Every release requires bespoke fixes | Exact profiles, explicit capability tests, bounded partner intake | +| Misleading or stale Ready badge | Claim spreads to another revision/version, implies preinstalled firmware, or loses its owner | Link exact evidence and installation status; review, suspend or withdraw unsupported claims | +| Store/distribution delay | Rejections, inaccessible beta, regional/device mismatch | Preserve truthful beta path; revise calendar, not evidence | +| Misleading research | Novelty claims depend on unmatched comparisons | Prespecify tasks, report limitations, separate usability from efficacy | +| Premature monetization | Support commitments exceed demand/capacity | One bounded service experiment before productizing | + +### 19.2 Stage gates + +`SG` identifies strategic gates in this document. These do not rename or replace repository CI G0/G1 or firmware C3-G0…C3-G6 gates. Record each strategic decision as `pass`, `iterate`, `blocked`, or a documented limited-scope decision. Explaining a missed target is useful evidence, not an automatic pass. + +| Gate | Decision | Required evidence | +|---|---|---| +| SG0 — Baseline accepted | Commit the selected cycle scope | One primary audience/job and recruitment owner; dated status/unknowns, pilot boundaries, named capacity, sized work, and prioritized failures | +| SG1 — Core release ready | Submit/publish the candidate | Applicable normative matrix, no unresolved release-blocking safety/data-loss defect, recovery, provenance, accurate instructions | +| SG2 — Activation demonstrated | Invest in wider acquisition | At least 12 eligible primary-cohort starts; ≥80% unassisted completion and reported timing target met; no unresolved severe failure; otherwise iterate or explicitly limit scope | +| SG3 — Repeat value demonstrated | Consider broader product investment | At least 20 activated, consented primary-cohort participants whose day-14 windows have closed; ≥40% confirmed useful day-7–14 returns among that full denominator as a provisional indicator; Task C outcomes/reasons, opportunity, prompting and missing data reported; otherwise inconclusive/iterate or a dated limited-scope decision | +| SG4 — Maintained compatibility demonstrated | Expand partner-profile support | Existing-profile procedure independently reproduced; first public record meets Ready criteria; one external maintainer's responsibilities and setup/support effort demonstrated; additional demand and capacity identified | +| SG5 — Classroom ready | Expand supervised teaching | Safe multi-board selection, sustainable support, consent/review, measured pilot outcomes | +| SG6 — Secure deployment ready | Consider untrusted/field use | Approved ownership design, independent review, recovery and downgrade evidence | + +SG1 and SG2 can be assessed in the same review, but technical correctness does not substitute for usability. SG2 and SG3 do not gate a qualified maintenance release. The retention percentage alone cannot pass SG3 without meaningful-task evidence, and inadequate opportunity to use calls for interpretation rather than an automatic rejection of the product. Recalibrate proposed thresholds/windows only in a dated prospective decision that preserves the original target and observed results. SG4 governs expansion after a bounded pilot; it does not block the existing-profile rehearsal or criteria draft in §14. + +### 19.3 Continue, narrow, or pause + +**Continue** when activation and repeat tasks improve and support remains manageable. **Narrow** when one device/profile/use case succeeds and broader claims create failures. **Pause expansion** when users cannot complete the core workflow, evidence remains incomplete, safety is unresolved, or maintenance exceeds capacity. + +At cycle end, choose one principal next investment: Reliable Projects, partner portability, or classroom usability. Keep the other tracks at discovery level until staffing permits. Avoid starting all three because the platform vision sounds attractive. + +## 20. Immediate execution checklist and handoff + +### 20.1 First working week + +- [x] Inspect current `main` at `23ed764`, the current public roadmap, implementation seams, and existing validation tools. +- [x] Carry forward PR #33's completed Android open-testing correction and #24's closed/superseded state; preserve pending evidence. +- [x] Identify A-24/ADR-0010 durable drafts as a concrete remaining engineering gap. +- [ ] Confirm one reachable primary audience, recruitment owner, previous workflow and meaningful Task C; keep other audiences exploratory. +- [ ] Assign actual capacity and accept a bounded first sprint; size persistence and mandatory physical work before promising the full cycle. +- [ ] Complete PYB-001's installed-build/provenance fields for Google Play and TestFlight, or name the blocker and responsible owner. +- [ ] Create or link accepted PYB-001/003/004/006/009 tasks; PYB-002 needs a new issue only for a remaining discrepancy. Preserve existing A-24/ADR identities. +- [ ] Assign one owner and one review path for each initial issue. +- [ ] Inventory exact test boards, tablets, cables, and available recovery equipment. +- [ ] Freeze Task A/B/C definitions, assistance/timeout rules, prospective follow-up windows and task-opportunity questions, consent procedure, and manual support template; observe initial eligible participants. +- [ ] Review the durable-draft contract and choose its first testable increment; escalate any newly observed release blocker ahead of optional work. +- [ ] If operator/capacity is available, include one existing-profile Ready rehearsal and draft record in PYB-009; show installation status and pending evidence explicitly. + +### 20.2 Issue template + +```markdown +## User problem and evidence +Describe the observed failure or validated need. Link its evidence. + +## Scope +In scope: +Out of scope: + +## Contract and dependencies +Affected specification / ADR: +Existing story / issue (for example A-24): +App / firmware / protocol compatibility: +Required prior issues: +Estimate including validation / sprint allocation: + +## Acceptance criteria +- [ ] Observable user outcome is demonstrated. +- [ ] Failure, interruption, and recovery cases are tested. +- [ ] Existing compatible clients/firmware behave as specified. +- [ ] Privacy and hardware-safety boundaries are preserved. +- [ ] Required exact-artifact hardware evidence is attached or explicitly pending. + +Source-complete and release-qualified status must be recorded separately; +pending required evidence does not pass the release gate. + +## Verification +Automated tests: +Physical devices / profiles: +Release artifacts and hashes: +Delivery channel / installed-build provenance: +Limitations / not-run cases: + +## Ownership and release +Implementation owner: +Reviewer: +Release lane / current work state: +Rollback / recovery: +Documentation and distribution changes: +``` + +### 20.3 Coding-agent handoff + +Use the following task framing for each accepted issue. Work within the maintainer's existing task authorization and repository rules; this plan alone does not approve proposed wire contracts, new hardware claims, or store publication. + +```text +Work on one accepted PyBLE issue only. + +1. Read AGENTS.md, CONTRIBUTING.md, the affected specification, existing + tests, and relevant release/architecture decisions. +2. Check for an existing implementation and linked issues before adding code. +3. Identify any contract change. Do not invent opcodes, capabilities, + firmware support, or release status. Obtain the required approval first. +4. Follow specification-first and red/green/refactor for behavior changes; + validate documentation-only changes with the relevant document gates. +5. Preserve BLE-first, offline-core, open-source, and no-telemetry boundaries. +6. Run the relevant tests and repository gates. State what was not run. +7. Never fabricate hardware evidence, user adoption, store approval, or a + successful install. Keep pending hardware/release work explicit. +8. Summarize changed files, observed behavior, compatibility, evidence, + remaining risks, and the next review decision. +``` + +### 20.4 Decision record for every sprint + +Record shipped versus proposed work; exact tested artifacts; pass/fail/not-run results; the selected audience and useful-task outcomes; reasons to choose PyBLE; opportunity-to-use and prompting context; maintenance/support burden; and one explicit next-sprint priority. Include Ready rehearsal/record status only when that work is selected. Store identities and participant data separately from public aggregate reports. + +**Next action:** confirm one primary audience and useful task, finish the installed-build record, and specify the first A-24 durable-draft increment. Observe useful work and follow-up alongside delivery of the smallest qualified maintenance change. Reuse operator work for a bounded existing-profile Ready rehearsal if capacity is assigned. Let task failures, repeat value, and support effort determine subsequent protocol, partner, or classroom investment. + +## 21. Source references + +The strategy supplies the proposed direction. The sources below ground the existing implementation, governance, and firmware-roadmap constraints. They were inspected on 25 September 2026 at `main` commit `23ed764b0ef88dce9720c66fbd1c0655268860cf`. Footnote source links are pinned to that revision; convenient relative links in the implementation map follow the working tree. GitHub issue/PR links are dated workflow evidence, not immutable test receipts. Current normative specifications and accepted ADRs govern implementation; this planning document cannot override them. + +[^readme]: + PyBLE README, sections on application behavior, app source version, firmware v0.6.1 publication, five exact profiles, provisioning, and imports. + +[^agents]: + PyBLE contributor guidelines, including specification-first and test-first development, hardware evidence, DCO sign-off, clean-room/license boundaries, repository layout, and prohibition on paid or closed features. + +[^public-roadmap]: + PyBLE public roadmap, including current capabilities, owner-confirmed v0.6.1 status, reusable conformance-kit direction, and future-port requirements. + +[^firmware-roadmap]: + Firmware v0.6.1/v0.7.0 roadmap, including proposed Reliable Projects capabilities, cross-version constraints, HIL acceptance criteria, separate security design, and deferred atomic project deployment. Some release-state text is historical and requires reconciliation with newer publication records; this plan does not treat it as current distribution truth. + +[^android-review]: + Dated Android open-testing publication review, including the official Google Play listing observation, package/version, account/device limitations, and absence of signed-in installation or exact installed-build evidence. The [website specification](https://github.com/PyBLE-dev/PyBLE/blob/23ed764b0ef88dce9720c66fbd1c0655268860cf/docs/specifications/website.md) defines the maintained distribution wording. + +[^pr33]: + PR #33, merged on 25 September 2026 at `23ed764b0ef88dce9720c66fbd1c0655268860cf`; source/specification/tests for coordinated Android open-testing copy. Its merge is source-delivery evidence, not proof of a store-installed app or search-engine recrawl. + +[^publication]: + Firmware v0.6.1 publication record: owner-confirmed release, firmware source `c8f549eeabe6d2b8c2766eab022517944bb09c8c`, artifact checks, and preservation of incomplete automated HIL evidence. + +[^issue24]: + Issue #24, inspected closed with reason `NOT_PLANNED` and closure date 13 September 2026; [closure explanation](https://github.com/PyBLE-dev/PyBLE/issues/24#issuecomment-5652537345). Supersession does not complete its historical checklist. + +[^app-contract]: + Current App specification, [App TDD](https://github.com/PyBLE-dev/PyBLE/blob/23ed764b0ef88dce9720c66fbd1c0655268860cf/docs/specifications/App/TDD.md), and [ADR-0010](https://github.com/PyBLE-dev/PyBLE/blob/23ed764b0ef88dce9720c66fbd1c0655268860cf/docs/decisions/0010-working-loop-in-memory-document.md). FR-EDIT-7, FR-PROJ-2/6, and NFR-REL-3 remain carried persistence requirements; A-24 re-freezes the deferred implementation. Protocol behavior remains governed by [PBLE/1](https://github.com/PyBLE-dev/PyBLE/blob/23ed764b0ef88dce9720c66fbd1c0655268860cf/docs/specifications/protocol.md). + +--- + +**End of document — PyBLE Implementation Plan and Development Strategy, revision 1.2** From e03ecbc2ecbb84f7f97485f7dafc5a0ef95905e9 Mon Sep 17 00:00:00 2001 From: Viwat Vchirawongkwin Date: Fri, 25 Sep 2026 17:09:32 +0700 Subject: [PATCH 2/9] [docs] prepare C1-S1 pilot protocol and observation kit Signed-off-by: Viwat Vchirawongkwin --- .../02_Pilot_Protocol_and_Observation_Kit.md | 424 ++++++++++++++++++ 1 file changed, 424 insertions(+) create mode 100644 docs/developments/2026-q4-reliable-workflow/c1-s1/02_Pilot_Protocol_and_Observation_Kit.md diff --git a/docs/developments/2026-q4-reliable-workflow/c1-s1/02_Pilot_Protocol_and_Observation_Kit.md b/docs/developments/2026-q4-reliable-workflow/c1-s1/02_Pilot_Protocol_and_Observation_Kit.md new file mode 100644 index 00000000..4c1586ca --- /dev/null +++ b/docs/developments/2026-q4-reliable-workflow/c1-s1/02_Pilot_Protocol_and_Observation_Kit.md @@ -0,0 +1,424 @@ + + + +# C1-S1 — pilot protocol and observation kit + +## 1. Control, evidence and collection decision + +| Field | Prepared state, 25 September 2026 | +|---|---| +| Protocol | `C1-PILOT-1`; prospective procedure, not observed results | +| Scope | C1-S1-T04/T05 preparation; executable procedures and empty templates for T06–T09 and rolling PYB-011.2 follow-up | +| Acceptance | [PYB-003.1/004.1/004.2/011.2](../05_Product_Backlog_and_Stories.md), [Sprint Backlog](../06_Sprint_Backlogs.md), [strategy §§4 and 12](../../../planning/PyBLE_Implementation_Plan_and_Strategy_v1.0.md) | +| Inspected source | `d039db09779ed45124874721f88b2e0931664743`; source inspection does not identify the installed app | +| Primary cohort | Provisionally adult tablet-owning makers; human owner must confirm a reachable cohort before collection | +| Pilot decision-maker / recruitment owner / data custodian | TBD; no assignment, participant contact, consent, or approval inferred | +| Reference app and hardware | Must be bound to a dated installation record and the exact setup table below; no setup has been physically verified for this pilot | +| T04 / PYB-003.1 | Protocol/support template prepared for review; scoped human collection decision pending | +| T05 / PYB-004.1 | Tasks and measurement rules prepared for review; cohort, owner and reference setup confirmation pending | +| T06–T08 / PYB-004.2 | Blocked: collection decision, tested setup and consenting participants absent | +| T09 | Synthesis template prepared; actual baseline analysis blocked without observations | +| Results | Not collected. Success rate, timing, support cost and retention are unavailable; no trial, consent or physical result is claimed | + +This kit is a manual, explicitly consented pilot procedure. It changes neither +the app's data handling nor the [public privacy policy source](../../../../tools/web/src/app/privacy/page.tsx) +and its [offline counterpart](../../../../app/lib/app/pages/privacy_policy_page.dart). +No analytics service, app export feature or automatic upload is added. The named +pilot owner must review the separate participant notice and deletion arrangements +below before collection. Recruitment and any required institutional review are +human responsibilities; this document makes no legal or ethics-approval claim. + +Complete this decision record before asking anyone to participate. Preserve the +original protocol and record a new version before changing future sessions; +do not change eligibility, tasks or thresholds retrospectively to improve results. + +| Required decision | Value to record before collection | +|---|---| +| Named accountable pilot owner and reviewer | — pending | +| One primary audience and recruitment source | — pending; confirm maker default or prospectively replace it, for example with instructors | +| Task purpose and previous workflow question | — pending; use §5 prompts without recording private project details | +| Exact reference setup and physical smoke evidence | — pending; complete §2 | +| Protocol version, permitted written guidance and language | — pending; freeze §4–§6 task cards and guidance revisions | +| Assistance, Task A 30-minute timeout and other task limits | — pending; approve prospective rules in §4 | +| Private storage, access, backup exclusions and deletion owner | — pending; verify §3 operationally | +| Participant notice, withdrawal contact and required review decision | — pending; attach reviewed notice privately, without asserting review that did not occur | +| Follow-up consent, contact route and window convention | — pending; freeze §7 before the first activation | +| Decision and date | — pending: approve this bounded collection / revise / defer; record actual decision-maker, not an automated signature | + +```mermaid +flowchart TD + Kit["Prepared protocol and empty templates"] --> Decision["Named owner reviews cohort, setup and data rules"] + Decision --> Gate{"Collection approved and setup verified?"} + Gate -- No --> Hold["Keep observation tasks blocked"] + Gate -- Yes --> Consent["Voluntary consent and eligibility"] + Consent --> A["Task A: retain every eligible start"] + A --> C["Optional meaningful Task C and prior workflow"] + A --> Link{"Activated and follow-up consented?"} + Link -- Yes --> Window["Record window immediately; collect as due"] + Window --> Review["Review full denominator and missing evidence"] + C --> Review + Review --> Delete["Publish reviewed aggregates; delete private records on schedule"] +``` + +## 2. Operator setup and harmless hardware boundary + +Use a supervised trusted workbench, one powered pilot board and one tablet at a +time. Keep other pilot boards unpowered and other centrals disconnected. Record +unexpected advertisements, competing connections and mistaken selection as +observations; stop before a write when identity is uncertain. Isolate the station +or defer the session if another nearby device cannot be acceptably excluded. +Do not run a multi-user interference experiment inside the first-use task. + +| Required reference field | Operator entry before a session | +|---|---| +| App identity | Platform/OS version, device model class, distribution channel, actual installed app version/build and dated evidence; source commit only when mapped | +| Exact board selection | Select one existing profile and its matching physical revision/memory configuration; candidate default `rpi-pico2-w` only if a verified Pico 2 W is available. A different verified profile needs a separately recorded setup, not a guessed substitute | +| Other eligible profiles | `esp32-4mb`, `esp32-s3-n16r8`, `waveshare-esp32-s3-lcd-147b`, `esp32-c3-4mb`; match the [setup tutorial source](../../../../tools/web/src/app/learn/setup/page.tsx), installer selection and physical markings | +| Firmware identity | Release, exact profile, asset/hash and source mapping if available; separately record observed agent/MicroPython versions and provenance gaps | +| Board identity check | Privately compare physical board and installer record with connected Board info before writes; retain only match/mismatch/missing in observation data, not device IDs or MAC addresses | +| Harmless configuration | No attached sensors, motors, pumps, heaters, actuators, external circuits or mains-powered loads; Tasks A/C use only finite console output and timing | +| Power and files | Accessible low-voltage board power disconnect; owner-approved disposable child folder with no valuable files; no changes to boot files or autorun | +| Tablet starting state | App installed but not yet launched for this participant's Task A; no pre-granted PyBLE permission or saved connection silently carried from a prior participant. Record any reused state as a separate cohort | +| Operator smoke check | On a separate preparation session, perform connect → board identity check → disposable file → Save to board → Run → Console; record actual date/result or remain blocked | +| Permission to reset preparation state | Owner agrees before clearing app storage/reinstalling or altering board files; never erase someone else's work to create a clean pilot state | + +PBLE/1 trusts a connected client and has no authenticated ownership gate. +Bluetooth names, labels, connected status and displayed identity are selection +aids, not authorization. Pairing/encryption is not mandatory for access; no +participant secrets belong in the program. These limits follow [PBLE/1 §10](../../../specifications/protocol.md#10-security-note-v1). + +**Stop is software program control, not an emergency stop.** A disconnect does +not itself stop a running program. Finite console-only tasks limit this pilot's +exposure; they do not validate safety for other hardware. If output or state is +unexpected, stop the task timer, mark the intervention and retain the failure. +Request **Stop**; if it fails, the operator may use **Soft-reboot**, which can +drop BLE, or disconnect board power for the harmless setup. Reconnect and +recheck identity before further writes. Do not promise a response deadline or +that Stop resets hardware state. Safety intervention always takes priority over +an unassisted score. A recovery demonstration is separate from the timed result. + +## 3. Consent, private records and deletion + +Explain this participant notice in the agreed language before collecting data: + +> This optional session evaluates PyBLE's workflow, not your ability. You may +> decline a task or stop without giving a reason. We record the task outcome, +> elapsed time, help needed, broad setup details and a brief non-sensitive +> description of useful work. We do not record your screen, audio, source code, +> console contents, account information or board identifiers. Follow-up is a +> separate choice. Reports contain reviewed aggregates, not named testimonials. +> The pilot owner will explain where records are kept, when they are deleted, +> and how to withdraw identifiable records before they are aggregated. + +Add the actual owner/contact, storage/access arrangement, deletion dates and +any applicable approved notice before use. Participants receive a copy. Do not +condition participation on a positive review, quote or public identity, and do +not use grades or favorable ratings as incentives. No incentive is approved by +this kit. Declining follow-up does not prevent the first session. + +| Record | Minimum content and separation | Proposed retention, to approve before collection | +|---|---|---| +| Private consent register | Random session and withdrawal codes, notice/protocol version, initial consent choice/date, separate optional follow-up choice, and expiry; add a participant linkage code only with follow-up consent; no account credentials or source | Use the same deadline as private technical observations below | +| Private contact register | Only the participant's chosen follow-up contact and participant code; separate access-controlled file from technical observations; collect no contact for people declining follow-up | Delete contact and routing copies within 7 days after that person's day-14 window closes, or earlier on withdrawal | +| Private technical observations | Random session code; linked participant code only with follow-up consent; fields in §8; no direct identity or private project detail | Delete identifiable/pseudonymous observations and consent records within 30 days after the day-14 window closes, or within 30 days of the session without follow-up; earlier withdrawal handled below | +| Public findings | Reviewed aggregates, broad categories, methods and limitations; combine/suppress identifying small cells and remove identifying free text | May remain in Git indefinitely; disclose this before consent because a published unlinked aggregate cannot later be reliably attributed to one participant | +| Deletion audit | Deletion date, record class and count, custodian confirmation; no destroyed participant codes or contact data | Keep only the non-identifying audit with the aggregate review record | + +The consent-register row uses the technical-observation deletion deadline. For +the proposed cycle, private records also have an absolute deletion ceiling of +**19 January 2027**, even if the rolling deadline would be later. A later cohort +requires a prospectively reviewed protocol and notice, not a silent extension. +Before rolling deletion, reconcile the person's mature outcome into reviewed +aggregate counts so the final full denominator includes early cohorts. Preserve +only aggregate counts after deletion; do not recreate participant links later. + +Store populated records outside Git and outside the public website, on a named +access-controlled encrypted location. Do not attach them to issues or PRs. An +ignored folder alone is not privacy protection. The custodian must verify +whether sync, exports, trash and backups create copies and choose a storage +arrangement in which the approved deletion schedule can actually be met; if +that cannot be established, collection remains blocked. Do not promise deletion +of copies beyond the custodian's control. Share only the minimum reviewed data +with the named reviewer. + +On a withdrawal request, stop further contact immediately. Using the private +withdrawal code, remove linkable records and controlled copies within 7 days; +recompute unpublished aggregates when possible. Record a non-identifying +withdrawal count and the resulting analysis limitation. A revoked consent cannot +be overridden to preserve a denominator. Already published unlinked aggregates +remain as disclosed. Ordinary missing follow-up and no task opportunity remain +in the denominator; they are not withdrawals. + +The blank tables here may be copied to the approved private store. Never fill +the repository copy with participant or contact records. + +## 4. Eligibility, assistance and timing rules + +| Prospective rule | Required treatment | +|---|---| +| Provisional primary eligibility | Adult (self-declared 18+; do not collect birth date), non-maintainer, owns/regularly uses a tablet, identifies a plausible board-work task, voluntarily consents; no minimum coding experience | +| Reachable cohort | Confirm recruitment source and owner; instructors or another audience replace the default only before their cohort starts. Report different audiences separately | +| Pre-task exclusions | Record broad reason/count only: declined consent, out-of-cohort, inaccessible eligible equipment, setup not verified. No task timer started; do not collect identity for screening failures | +| Primary unit | One first eligible Task A start per participant on the frozen task/build/setup; retain retries inside that same started outcome. Later coached retries are supplementary, not new successful participants | +| Clock start / finish | Start at first app launch after installation; finish when participant sees the exact expected first-program output after explicit Run. Installation has its own interval. Use monotonic elapsed timing; do not subtract in-task permissions, waiting, errors or support | +| Task A limit | 30 minutes from launch; stop at the limit and mark timeout. A participant may stop earlier; preserve elapsed time and abandonment/failure reason. Do not remove those starts from the denominator | +| Permitted written guidance | Fixed Task A card below plus pinned/reviewed setup and first-program instructions in the agreed language, available to every participant. Record the exact revision; do not silently add hints mid-cohort | +| Assistance | Any task-specific live hint, pointing, permission help, editing, operator action or safety intervention after the clock starts is assistance; record count/type/time. Re-reading the written prompt verbatim without a hint can be logged as procedural clarification | +| Outcome classification | Unassisted success / assisted success / failed / abandoned / timeout / safety-stopped. A successful assisted retry remains assisted. Record the first obstacle and all important interventions | +| External disruption | Record and retain interrupted starts with reason; any supplementary analysis excluding a clearly external interruption must show both the original full denominator and the exclusion rule | +| Task C / B limits | Proposed 15 minutes for C and 60 minutes for B, with actual stop/abandonment retained; owner may change limits prospectively before either cohort begins | +| Comparable cohorts | Same task/guidance/version, eligibility and starting state. Stratify platform/profile and experience; do not pool changed builds/tasks as if unchanged. Baseline five can contribute to twelve only when comparable | + +## 5. Participant task cards + +### Task A — first run with a provisioned board + +The operator supplies the safe, correctly provisioned board and an installed +app. Installation and any assistance before first launch are recorded separately; +the participant handles permissions, discovery, connection, file transfer and +execution. Supply the disposable folder's non-identifying name on the card. + +1. Launch PyBLE. Allow the permissions described by the written setup guide, + scan and connect to the station's board. Compare the physical/installer + record with Board info. If it is missing or inconsistent, stop and report it. +2. In **Files**, enter the supplied disposable child folder. Choose **New file**, + name it `hello.py`, and enter the one line below in **Editor**. If the path + already exists, stop rather than overwrite it; the operator records the setup + failure and any intervention. +3. Review the code and destination. Choose **Save to board** (called Save in + the tutorial), wait for completion, then choose **Run** explicitly. +4. Open **Console** and report when the expected line appears. The timer ends + here; optional editing/recovery practice is recorded separately. + +```python +print("Hello from PyBLE!") +``` + +Success means the participant sees `Hello from PyBLE!` once after their explicit +Run on the intended board. Saving or creating a file alone is insufficient. +The task reuses the [first-program tutorial source](../../../../tools/web/src/app/learn/first-program/page.tsx). +The current [UI labels](../../../../app/lib/localization/arb/app_en.arb) and +[working-loop contract](../../../specifications/App/specs.md) distinguish +Save to board from Run. The current in-memory editor draft does not survive +process termination reliably; do not ask participants to test destructive +restart recovery or present PYB-006 as implemented. + +### Task B — separate full self-service setup + +Task B is optional and separately recruited/reported. Begin from the actual +channel invitation/listing and an unprovisioned, exactly identified board; +measure from opening those instructions through the first successful mobile +program. A participant who already completed A is a trained Task B participant, +not an independent first-use setup observation. + +| Step | Participant action / stop condition | +|---|---| +| Installation | Follow the current recorded Play/TestFlight path; record availability, eligibility or installation failure without collecting account details | +| Equipment | Find the exact profile, compatible computer/browser and data cable; record missing equipment and search/support time | +| Backup decision | Board owner identifies valuable files, makes and verifies a backup when needed, and explicitly authorizes erase/write for this board. Record yes/no and broad outcome, never file content. No authorization or unverified backup means stop before flashing | +| Provisioning | Follow the current profile-specific setup/installer instructions; no guessed image or scripted erase in this kit. Pico 2 W uses its exact UF2/BOOTSEL method; the ESP profiles use their documented wired method | +| Completion | After provisioning, verify physical/installer/runtime identity and perform the console-only first program over BLE. Retain failure, assistance, total elapsed time and installation/provisioning subtimes | + +This procedure does not authorize flashing or destructive preparation in the +current automated work. Task B results never replace or shorten Task A timing. + +### Task C — choose and make a useful, bounded change + +Ask: “What small board-work result would be useful to you? How do you do it now, +and why might a tablet help?” Record a broad purpose and previous workflow +(computer editor/serial, another mobile workflow, or none), without project +names or private content. The participant can decline or choose their existing +workflow; that is useful evidence, not a failed personal assessment. + +For the console-only reference task, offer a **sampling-cadence rehearsal**: +choose a useful observation interval before adding a real sensor, change the +interval/count, and compare the printed elapsed times with the intended cadence. +It uses synthetic timing only; it does not read temperature/light or validate a +sensor. Count useful completion only when the participant states an actual goal, +changes the relevant values and can interpret the result. Do not label an +unchanged rerun or an unwanted scripted exercise as useful work. + +1. In the disposable folder create a distinct `cadence.py`; confirm it does not + overwrite a file. Read the code below. No extra hardware is connected. +2. State a target interval and observation count within the written bounds. + Change `interval_ms` and/or `samples`; leave the hard bounds intact. Inspect, + **Save to board**, then explicitly **Run**. +3. Inspect **Console** and explain whether the observed cadence fits the goal + and whether PyBLE is preferable to the previous workflow. Report assistance, + errors or an alternative chosen. Record outcome/category, not console text. + +```python +# SPDX-License-Identifier: MIT +import time + +interval_ms = 500 +samples = 6 + +# Keep this rehearsal finite: 3–10 samples and 250–1000 ms intervals. +interval_ms = min(1000, max(250, interval_ms)) +samples = min(10, max(3, samples)) +started = time.ticks_ms() +for index in range(samples): + elapsed_ms = time.ticks_diff(time.ticks_ms(), started) + print("sample", index + 1, "elapsed_ms", elapsed_ms) + if index + 1 < samples: + time.sleep_ms(interval_ms) +``` + +The loop contains at most nine one-second waits; that is a bound on requested +sleep, not a hardware timing or Stop guarantee. A different useful task is +exploratory until reviewed for the same harmless scope and given its own task +version. Do not add sensor wiring or actuators during the session. First-session +Task C demonstrates adaptation only; it is never counted as a later-day return. + +## 6. Operator sequence and baseline analysis + +| When | Operator action and evidence | +|---|---| +| Before each session | Check signed collection decision, exact setup, disposable paths, app starting state, permitted guidance and private storage; record preparation/support minutes separately | +| Before first launch | Explain notice; record voluntary consent and eligibility privately. Ask broad previous workflow and experience level. Installation time stays separate | +| During A | Start clock at launch; record every eligible start, retries/interventions, elapsed time, result and broad failure category. Safety always overrides measurement | +| After A | Ask Task C purpose/attempt/outcome and reason to choose or leave PyBLE. Offer follow-up separately; record activation/window immediately if consented | +| End of session | Stop bounded work if active; disconnect, verify harmless state and clear only owner-approved disposable files. Do not erase private app/board work. Record support and cleanup effort | +| T06 / T07 / T08 batches | Schedule within actual capacity toward five baseline starts; reconcile every start, due follow-up, unfilled slot and blocker after each batch | +| T09 analysis | Reconcile records, calculate descriptive outcomes below, report true observation/support cost and observed friction or “no blocker observed.” Without records, leave analysis blocked rather than invent a finding | + +| Metric | Manual calculation and required context | +|---|---| +| Completion | `unassisted successful first starts / all eligible first starts`; retain assisted success, failures, timeout, abandonment and safety stops in the denominator. If no starts were observed, report unavailable, not 0% | +| Successful-only p90 | Sort elapsed minutes for the `n` unassisted successes; choose the value at 1-based rank `ceil(0.90 × n)`. Report `n` and the sorted small-sample distribution alongside all-start outcomes; `n = 0` means unavailable | +| Baseline | Five eligible first starts for PYB-004.2; fewer leaves collection unfinished. A completed synthesis with a shortfall does not complete T06–T08 or PYB-004.2 | +| Later SG2 | At least twelve comparable primary starts, at least 80% unassisted success and successful-only p90 ≤10 minutes, plus severe-failure assessment. At twelve starts, ten unassisted successes are needed. Five baseline participants alone cannot pass SG2 | +| Task C | Eligible offers, attempts, useful completed adaptations, declines/failures/assistance, purpose and alternatives. Count each participant's relevant outcome once, and report meaningful-task interpretation | +| Actual effort | Separate recruitment, installation/preparation, observation, intervention, follow-up, analysis and administration minutes. The six-hour S1 observation allowance does not predict sample achievement | + +## 7. Rolling follow-up and denominator + +Activation means the first completed provisioned-board program on the recorded +setup, whether assisted or unassisted; report that distinction. A later coached +completion may establish activation but never upgrades the original failed or +timed-out Task A outcome; record it separately. Follow-up consent is separate. At activation, record local date/time and timezone privately. This +protocol proposes an inclusive elapsed-time window from activation plus seven +days through activation plus fourteen days; freeze that convention before use. +Record exact window open/close times immediately, including early S1 activations. + +| Prospective follow-up rule | Treatment | +|---|---| +| Contact | Offer a participant-initiated response route; with permission, send at most one neutral request during the window and one closing reminder only if that was consented. The named human pilot owner performs any outreach | +| Questions | Did a relevant task arise? Were board/tablet available? Was a useful task attempted/completed, and on what relative day? What changed, which workflow was chosen, and why? Any help needed? Use broad categories, not source or logs | +| Return origin | Participant-initiated / researcher-prompted / instructor-assigned / unknown. A response to a request is not itself a useful return. Ask whether the work occurred before or because of the request | +| Numerator | Confirmed useful later-day sessions during the window, satisfying the Task C or separately reviewed own-task definition; count people once, with origin and assisted/unassisted subtotals | +| Primary denominator | All activated, follow-up-consenting primary-cohort participants whose day-14 windows have closed and whose consent remains valid; keep missing responses and no-task/no-equipment opportunity in this denominator | +| Missing/late | Missing is unknown, not confirmed non-return. Record late responses and out-of-window work separately; do not backdate them or reconstruct an on-time observation | +| Interpretation | Report respondents, missing responses, useful returns, prompting/assignment, assistance, no opportunity and alternatives. Any opportunity-only subgroup is supplementary and states its denominator | +| Strategy indicator | Aim for twenty activated consenting primary-cohort participants by 22 November, with windows closed by 6 December; fewer than twenty mature eligible people makes the 40% indicator inconclusive. A percentage alone does not pass SG3 | +| Rolling accounting | Check windows after every batch and during S2/S3, not only in S5. Reconcile mature early cohorts into aggregate counts before private records expire; do not drop them from the cycle denominator | + +No participants or windows are currently recorded. Calendar targets do not +authorize contact or claim retention. Task C in the first session, assigned +work and participant-initiated later use remain separately visible. + +## 8. Empty operational templates + +These are field definitions and blank forms, not observations. Copy them into +the approved private store only after the collection decision. No numeric +example participant or synthetic success is included. + +### Private consent/contact record — restricted separately + +| Field | Blank value | +|---|---| +| Random session code / withdrawal code; participant linkage code only with follow-up consent | — | +| Notice/protocol version and consent date | — | +| Initial observation consent | — | +| Follow-up consent / permitted contact and reminder | — | +| Chosen contact route | — keep only in separate contact register | +| Activation time, timezone, window open/close | — | +| Contact deletion deadline / observation and consent deletion deadline | — | +| Withdrawal or deletion request / action date | — | +| Custodian and controlled-copy deletion confirmation | — | + +### Private observation record — one eligible first start + +| Field | Blank value | +|---|---| +| Random session code / consented linkage code if applicable | — | +| Cohort, recruitment category, protocol/task/guidance revision, language | — | +| Eligibility and starting-state check / prior PyBLE experience | — | +| App channel, installed version/build, OS and broad device model | — | +| Exact board profile/revision, firmware artifact/hash/version and provenance limits | — | +| Identity check match/mismatch/missing; wrong-selection/interference category | — no device identifier | +| Installation outcome/time and pre-task help | — | +| Task A start, end, elapsed seconds, outcome, retries | — | +| Assistance count/type/minutes; first obstacle and other broad failures | — | +| Task C purpose, previous workflow, attempted adaptation and outcome | — no project content | +| Reason to choose PyBLE/alternative; Task C assistance | — | +| Activated yes/no; follow-up consent and window reference | — | +| Recruitment/setup/observation/support/follow-up/analysis effort | — | +| Operator record/review date and deletion due date | — | + +### Private follow-up record — link only with consent + +| Field | Blank value | +|---|---| +| Participant linkage code; activation and window reference | — | +| Window mature / consent valid / denominator inclusion or exclusion reason | — | +| Response received date; work relative day; in-window/late/missing | — | +| Relevant task arose; board/tablet available; unknowns | — | +| Useful attempt/completion and broad purpose; assistance | — | +| Participant-initiated / prompted / assigned / unknown; contact timing | — | +| Alternative chosen / reason for non-return or unknown | — | +| Aggregate reconciliation and deletion due/completed date | — | + +### Manual support record — participant-reviewed before any sharing + +| Field | Blank value / boundary | +|---|---| +| App platform/channel/version/build and broad OS/device model | — | +| Firmware version/artifact and exact board profile | — no MAC, board/device ID, serial, label or account | +| Broad operation | — permission / discovery / connect / file creation / Save to board / Run / Console / other reviewed category | +| Expected versus observed behavior | — brief original summary, no copied source, filename/path, console line, stack trace or personal/project detail | +| Reproduction | — generic steps using disposable sample files only; do not include private original content | +| Frequency / assistance / recovery tried | — descriptive observations, no guessed cause | +| Sharing decision | — participant previews all fields; named reviewer redacts before public issue use; no automatic submission | + +Screenshots, recordings, logs, source and identifiers are excluded by default. +If a support case genuinely needs more, obtain a separate explicit decision, +minimal content and redaction/retention plan first; consent to this baseline +pilot is not permission to upload raw diagnostic material. No support record +exists until a participant or operator actually supplies one. + +### Public baseline and follow-up synthesis — no result entered yet + +| Field | Current entry | +|---|---| +| Collection decision / setup / observation dates | Pending; no collection performed | +| Protocol/build/cohort comparability and platform coverage | Not observed | +| Eligible starts, exclusion categories and baseline shortfall | Unavailable; five-start target remains unmet | +| Unassisted/assisted successes, failures, abandonment, timeout, safety stops | Unavailable | +| Completion fraction and successful-only p90 with `n` | Unavailable | +| Task C attempts/useful outcomes, prior workflow and alternatives | Unavailable | +| Actual effort and observed blocker or absence of blocker | Unavailable; do not infer a product defect from absent participants | +| Mature follow-up denominator, valid-consent withdrawals and reconciliation | Unavailable | +| Respondents, useful returns, missing, opportunity and prompting subgroups | Unavailable | +| Gate interpretation | SG2/SG3 not assessed; no activation or retention claim | +| Next action | Human owner confirms collection decision, reference setup and recruitment; run T06–T08 before T09 analysis | +| Reviewer / privacy review / aggregate publication date | Pending | + +## 9. Verification and update boundary + +The task cards were checked against current [setup](../../../../tools/web/src/app/learn/setup/page.tsx), +[first-program](../../../../tools/web/src/app/learn/first-program/page.tsx), +[UI labels](../../../../app/lib/localization/arb/app_en.arb), +[App specification](../../../specifications/App/specs.md), and +[PBLE/1](../../../specifications/protocol.md). Repository link/license checks and +a local syntax/deterministic-clock check of the teaching snippet are document +validation only; they are not pilot runs, independent hardware qualification, +or human approval. Retain the actual check outcome in the implementation record. + +When the owner completes the decision and observations, update this control +record, the [story states](../05_Product_Backlog_and_Stories.md), +[task statuses](../06_Sprint_Backlogs.md), [milestones](../03_Milestones.md), +and the source strategy consistently. Private populated templates remain outside +Git. Correct user-facing policy text only if app/site data handling actually +changes, keeping the bundled/public disclosures synchronized. From aae7ca4d4ef2d2200cd778f069cc691bc746565f Mon Sep 17 00:00:00 2001 From: Viwat Vchirawongkwin Date: Fri, 25 Sep 2026 17:12:37 +0700 Subject: [PATCH 3/9] [docs] specify and size C1-S1 current-draft recovery Signed-off-by: Viwat Vchirawongkwin --- .../0010-working-loop-in-memory-document.md | 12 + ...048-bounded-current-text-draft-recovery.md | 72 +++++ docs/decisions/README.md | 3 + .../c1-s1/03_Recovery_Design_and_Sizing.md | 189 ++++++++++++ docs/specifications/App/TDD.md | 41 ++- .../App/current-draft-recovery.md | 285 ++++++++++++++++++ docs/specifications/App/specs.md | 16 +- 7 files changed, 615 insertions(+), 3 deletions(-) create mode 100644 docs/decisions/0048-bounded-current-text-draft-recovery.md create mode 100644 docs/developments/2026-q4-reliable-workflow/c1-s1/03_Recovery_Design_and_Sizing.md create mode 100644 docs/specifications/App/current-draft-recovery.md diff --git a/docs/decisions/0010-working-loop-in-memory-document.md b/docs/decisions/0010-working-loop-in-memory-document.md index f7dc5331..c59f341e 100644 --- a/docs/decisions/0010-working-loop-in-memory-document.md +++ b/docs/decisions/0010-working-loop-in-memory-document.md @@ -57,3 +57,15 @@ Unchanged: the `Connection` seam (D1), neutral types (D2), Riverpod as the one s - Extends [ADR-0007](0007-riverpod-state-management.md) (Riverpod / D3) and [ADR-0009](0009-runtime-connection-manager.md) (runtime session facade); honors [ADR-0008](0008-signal-design-system.md) (`SignalCodeColors` for the editor/console surfaces). - Ratifies App [TDD.md §11.6](../specifications/App/TDD.md#116-working-loop-provider-contract-frozen) and the scoping freeze notes in [TDD.md §11.1](../specifications/App/TDD.md#111-editor)/[§11.4](../specifications/App/TDD.md#114-console--error-explanation) and [specs.md §4.5](../specifications/App/specs.md)/§4.6/§4.7/§4.8. - Scopes App stories **A-20 / A-21 / A-16 / A-30** (working-loop subset); defers FR-EDIT-7, NFR-REL-3/FR-PROJ-6, and the rich-editor part of FR-EDIT-1 to **A-24** ([OI-1](../specifications/App/specs.md)). + +## 2026-09-25 follow-up — bounded current-text recovery specified + +The historical decision and its original context above remain unchanged. +[ADR-0012](0012-flutter-code-editor-behind-editorsurface.md) already superseded +the rich-editor deferral. [ADR-0048](0048-bounded-current-text-draft-recovery.md) +now specifies the bounded current-text recovery successor, with its +[write/failure/board-authority contract](../specifications/App/current-draft-recovery.md) +and [C1-S1 review and sizing](../developments/2026-q4-reliable-workflow/c1-s1/03_Recovery_Design_and_Sizing.md). +The inspected source is still volatile; implementation and acceptance evidence +are pending. The remaining A-24 project, settings, console, import and Blocks +obligations are carried, not satisfied by the successor design. diff --git a/docs/decisions/0048-bounded-current-text-draft-recovery.md b/docs/decisions/0048-bounded-current-text-draft-recovery.md new file mode 100644 index 00000000..0b1e99df --- /dev/null +++ b/docs/decisions/0048-bounded-current-text-draft-recovery.md @@ -0,0 +1,72 @@ + + + +# ADR 0048 — Recover one current text draft through the planned Drift store + +**Status:** Specified for implementation (2026-09-25) under the user's request +to execute C1-S1. Source implementation and physical acceptance remain pending; no named human +sign-off is claimed and this is not release admission. + +## Context + +[ADR-0010](0010-working-loop-in-memory-document.md) recorded an intentionally +volatile current document and deferred Drift persistence to A-24. That +limitation remains in the inspected source. Its old rich-editor deferral has +already been superseded by [ADR-0012](0012-flutter-code-editor-behind-editorsurface.md), +so the persistence problem must be scoped against the current rich Editor, +Blocks handoff and file-backed Run implementation. + +The current provider has a mutation epoch, but Save/Run/Files completion guards +still compare document values. A stable Connection facade also makes object +identity insufficient to bind a multi-step text action to one attached board. +Recovery must not amplify either gap by restoring a historical target as +current write authority. + +C1-S1 requests a bounded contract and an honest estimate, not the full A-24 +implementation. The [design review and sizing](../developments/2026-q4-reliable-workflow/c1-s1/03_Recovery_Design_and_Sizing.md) +records this distinction and the proposed reforecast. + +## Decision + +Adopt [the bounded current-draft contract](../specifications/App/current-draft-recovery.md) +for the next implementation slice: + +1. Use one current-text slot in the planned Drift `projects`/`project_files` + subset and single SettingsStore. Commit its content and recovery metadata + atomically. No scratch file or separate preferences backend. +2. Distinguish local checkpoint state from board-dirty state. A saved-local + indication acknowledges a successful transaction for that exact revision. +3. Offer explicit offline Restore/Discard with nondestructive failure handling. + A local recovery panel is a narrow extension of + [ADR-0011](0011-connection-gated-shell.md); it does not implement the complete + offline IDE. +4. Restore text without board authority. Require a current-session destination + decision before a recovered document can be saved, uploaded or run on a + board; use document epochs and the existing neutral session stamp across + asynchronous boundaries. +5. Include interrupted-write, corrupt/full storage, version handling, stale + completions and applicable platform evidence in the same usable increment. + Keep Blocks graph recovery and the rest of A-24 explicitly carried. + +This decision supersedes only ADR-0010's volatile-only current-text design for +the future accepted slice. It does not retroactively claim that released builds +persist drafts, change PBLE/1 or remove the existing provider/Connection seams. + +## Alternatives considered + +| Option | Decision | +|---|---| +| Ad-hoc text/JSON scratch file or separate preferences | Rejected: duplicates the accepted Drift direction and leaves another migration/storage boundary | +| Complete all A-24 projects, histories, imports and Blocks state together | Deferred: exceeds the first bounded outcome and needs separate contracts | +| Infer the old board from a recovered path or advertised name | Rejected: path and display identity do not authorize a new session | +| Restore automatically over a fresh empty provider | Rejected: races hydration, user edits and pending replacement decisions | +| Ship only successful restart recovery, add failure handling later | Rejected: cannot meet the recovery story's minimum safety acceptance | + +## Consequences + +The implementation needs the actual Drift/native database dependencies, +versioned schemas, local recovery UI and stronger completion guards. None of +these exist merely because this ADR is written. The estimate exceeds the +original C1-S2 recovery allowance; future Sprint selection must be reforecast +without weakening the failure cases. The narrower feature can eventually +protect useful current text, while full project persistence remains unfinished. diff --git a/docs/decisions/README.md b/docs/decisions/README.md index 4bc44cd5..2b541e85 100644 --- a/docs/decisions/README.md +++ b/docs/decisions/README.md @@ -51,5 +51,8 @@ Each ADR captures one significant decision: its context, the choice, and the con | [0045](0045-adopt-ios-15-deployment-floor.md) | Adopt iOS and iPadOS 15 as the maintained source and compiled distribution floor while preserving build 5 as historical evidence | Accepted | | [0046](0046-publish-release-bound-static-learning-center.md) | Publish a static `/learn` center whose app, firmware, examples, validation, privacy, and deployment claims remain release-bound | Accepted | | [0047](0047-standardize-official-workspaces-on-lfs2.md) | Standardize all five official firmware workspaces on explicit, fail-closed LFS2 mounting and provisioning | Accepted | +| [0048](0048-bounded-current-text-draft-recovery.md) | Specify bounded Drift current-text recovery with explicit local durability, recovery choices and session-bound board authority; implementation pending | Specified | Decided 2026-06-30 (0001–0005); 0006 accepted 2026-07-01; 0007, 0008, 0009 and 0010 accepted 2026-07-02; 0011 accepted 2026-07-03; 0012 accepted 2026-07-25; 0013 accepted 2026-07-27; 0014, 0015, 0016, and 0017 accepted 2026-07-28; 0018–0022 accepted 2026-07-29; 0023 and 0024 accepted 2026-08-01; 0025 and 0026 accepted 2026-08-02; 0027–0029 accepted 2026-08-03; 0030 accepted 2026-08-11; 0031–0033 accepted 2026-08-12; 0034 accepted 2026-08-13; 0035 and 0036 accepted 2026-08-16; 0037 and 0038 accepted 2026-08-20; 0039 accepted 2026-08-21; 0040 accepted 2026-08-22; 0041 accepted 2026-08-25; 0042–0045 accepted 2026-08-27; 0046 accepted 2026-08-28; 0047 accepted 2026-09-03. + +0048 specified for implementation on 2026-09-25 during C1-S1; this status does not claim delivered persistence or release acceptance. diff --git a/docs/developments/2026-q4-reliable-workflow/c1-s1/03_Recovery_Design_and_Sizing.md b/docs/developments/2026-q4-reliable-workflow/c1-s1/03_Recovery_Design_and_Sizing.md new file mode 100644 index 00000000..635b85df --- /dev/null +++ b/docs/developments/2026-q4-reliable-workflow/c1-s1/03_Recovery_Design_and_Sizing.md @@ -0,0 +1,189 @@ + + + +# C1-S1 — current-text recovery design, source review and sizing + +| Field | Result | +|---|---| +| Recorded | 25 September 2026; preparatory execution ahead of the forecast Sprint dates | +| Tasks | C1-S1-T10 and C1-S1-T11; parent PYB-006.1 | +| Authority | User request to implement C1-S1; no named human sign-off or completed Scrum ceremony is inferred | +| Design result | Bounded contract specified and reviewed against current source; implementation pending | +| Normative deliverable | [Current-draft recovery](../../../specifications/App/current-draft-recovery.md), [ADR-0048](../../../decisions/0048-bounded-current-text-draft-recovery.md) | +| Existing contract updated | [App requirements](../../../specifications/App/specs.md), [App TDD](../../../specifications/App/TDD.md), dated [ADR-0010 follow-up](../../../decisions/0010-working-loop-in-memory-document.md) | +| Runtime / physical results | None produced by this design task; current released/source behavior remains volatile | +| Effort records | Original S1 allowance: 3h + 1h. These are planning allowances, not an assertion of four elapsed hours or a team velocity | + +## 1. Source-grounded findings + +| Source inspected | Observed behavior | Design consequence | +|---|---|---| +| [EditorDocument](../../../../app/lib/editor/editor_document.dart) | Single `name/content/dirty/boardPath` value; mutations bump `editorDocumentEpochProvider`; no durable backend | Observe every mutation, preserve the public provider seam and use epoch identity rather than value equality | +| [Data barrel](../../../../app/lib/data/data.dart) and [pubspec](../../../../app/pubspec.yaml) | Persistence placeholder; no admitted Drift/database packages | Dependency/native opening/schema/migration work has real cost; TDD architecture is not existing implementation | +| [Save controller](../../../../app/lib/editor/save_controller.dart) | Normalizes source, writes through ProgramActions, then compares document values before `markSaved` | Keep normalization out of recovery serialization; add epoch and session checks to completion | +| [Run controller](../../../../app/lib/editor/run_controller.dart) and [ProgramActions](../../../../app/lib/editor/program_actions.dart) | Text run performs PUT then rereads Connection to run; bundle actions already pin a neutral session stamp | Carry the established session check into the affected text action; stable facade identity is insufficient | +| [Files controller](../../../../app/lib/files/file_explorer_controller.dart) | Open uses an open-operation epoch plus document equality; Upload uses equality; existing delete/list logic already has session protection | Strengthen the affected document-adoption and completion guards without rebuilding the file explorer | +| [Blocks controller](../../../../app/lib/blocks/blocks_document.dart) | In-memory retained JSON and generated Python; explicit one-way `openGenerated` handoff; existing sidecar behavior is board-backed | Persist only text after explicit handoff; no claim of local workspace/graph recovery | +| [Shell](../../../../app/lib/app/shell.dart) and [ADR-0011](../../../decisions/0011-connection-gated-shell.md) | IDE appears only after connection | A board-independent local recovery panel is necessary; a full offline IDE remains separate | +| [ADR-0010](../../../decisions/0010-working-loop-in-memory-document.md) and [ADR-0012](../../../decisions/0012-flutter-code-editor-behind-editorsurface.md) | Volatile persistence deviation remains; the old rich-editor deferral has already been superseded | Address the actual persistence gap without treating rich editing as missing | + +This is source inspection, not a reproduction of a released-build defect. The +edit-away/back and stable-facade cases are required implementation regressions; +the design does not claim a device incident or a test result that was not run. + +## 2. Decisions and bounded acceptance + +| Question | Specified answer | Trace | +|---|---|---| +| What is protected? | One exact current-text copy, including untitled text and explicit Blocks-to-Editor text; up to 1 MiB UTF-8 | DR-01; contract §2 | +| When is it protected? | Successful atomic content/metadata commit for that exact revision; local status is separate from board dirty/upload status | DR-02; §3 | +| How is a copy scheduled? | 500ms idle debounce, maximum 2s active scheduling interval, explicit Save recovery copy and best-effort lifecycle flush; pending text is not falsely guaranteed | §3 | +| What happens on launch? | Local preview and explicit Restore/Discard before board workflows; restored text remains viewable offline | DR-03; §4 | +| What authorizes a board write? | A new explicit destination/action decision in the current session; historical path never becomes live authorization | DR-05; §5 | +| What if storage fails? | Preserve current memory and previous committed store; report failure, Retry or explicit volatile session; no reset-on-error | DR-04; §6 | +| What handles races? | Editor epochs, document identity, serialized durable generations, discard barriers and neutral connection-session stamps | DR-06; §5 | +| What migrates? | First real schema starts at v1; tested forward migrations later, unsupported versions refused; no fictional released v0 store | §6 | +| What remains outside? | Full projects/settings/saved boards, history/console, durable import provenance, Blocks graph, reconnect guarantees | DR-07; §8 | + +The schema reuses the planned `projects`/`project_files` subset and one +SettingsStore. The design does not add a new content-table family or use a +scratch-file substitute. Exact package versions, platform database opening +adapter and generated column names belong to implementation admission with the +existing toolchain/license checks; they are not unsupported dependency pins in +a design document. + +## 3. Acceptance scenario review + +| Concern reviewed | Required scenario and oracle | Result of C1-S1 review | +|---|---|---| +| Durability boundary | DR-T01–03: exact content and old-or-new atomic state on real file-backed reopen/interruption | Specified; execution pending | +| Local failure | DR-T04–06: full/corrupt/unavailable storage and version refusal preserve state | Specified; execution pending | +| User choice and source loss | DR-T07/09: Restore/Discard/Cancel/replacement keep explicit consent and cannot resurrect a discarded slot | Specified; execution pending | +| Concurrency | DR-T08: delayed hydration/commit and edit-away/back cannot publish stale success | Specified; execution pending | +| Board safety | DR-T10/11: no implicit verb, consent invalidation, session swap between PUT and Run | Specified; execution pending | +| Blocks scope | DR-T12: copied Python recovers while retained/invalid workspace semantics stay unchanged | Specified; execution pending | +| Usability and platform parity | DR-T13/14: localized offline panel, separate local/board status, keyboard/large text, actual iPad and Android process restart | Specified; execution pending | + +Existing tests provide seams to extend rather than justify another framework: +[editor document](../../../../app/test/unit/editor_document_test.dart), +[Save](../../../../app/test/unit/save_controller_test.dart), +[Run](../../../../app/test/unit/run_controller_test.dart), +[ProgramActions](../../../../app/test/unit/program_actions_test.dart), +[Files](../../../../app/test/unit/file_explorer_controller_test.dart), +[Blocks](../../../../app/test/unit/blocks_document_test.dart), and the +[shell widget suite](../../../../app/test/widget/app_shell_test.dart). + +**Independent agent review resolution (25 September 2026).** The pilot-worktree +review identified that Files `openInEditor` does not currently capture a session +stamp and its connection-state handler does not invalidate `_openEpoch`. +Editor epoch plus open generation alone would therefore admit a delayed GET +from board A after the stable facade attached board B. The contract now requires +capturing `connectionSessionStampOf` before GET and matching it immediately +before adoption; DR-T11 explicitly tests the swap with an unchanged editor +epoch. This is a reviewed design correction, not a claim that the runtime gap +has been fixed or tested on hardware. + +No runtime tests were added or run for this specification-only task. Future +implementation must show meaningful failing tests before the passing change, +including file-backed persistence; a fake repository alone is insufficient. +An independent package review may still refine the design; neither this record +nor a commit signature impersonates a named human reviewer or release approver. + +## 4. Bottom-up implementation estimate + +These are engineering estimates from the inspected code and mandatory scenarios, +not measured velocity. They assume a developer familiar with Riverpod and the +existing seams, a working pinned Flutter toolchain, and timely access to both +physical platforms. Store review, recruitment, full five-profile qualification, +new features and unrelated defects are excluded. + +| Work package | Low h | High h | Included acceptance / uncertainty | +|---|---:|---:|---| +| Database dependency admission, platform opening, initial schema and version fixtures | 4 | 7 | New native dependency closure, persistent private path, schema fixture/version refusal | +| Atomic repository, content validation and nondestructive failure behavior | 6 | 10 | Real transactions, generation guards, hash/size validation, error seams | +| Recovery coordinator and mutation/lifecycle queue | 4 | 7 | Debounce, coalescing, revision status, discard barriers and stale reads | +| Startup Restore/Discard and replacement flow | 5 | 8 | Disconnected panel, volatile-mode Retry, epochs and replacement choices | +| Target consent and affected board completion/session guards | 6 | 10 | Editor Save/Run, Files Upload/Open, Blocks handoff; partial Run result | +| Localized UI, accessibility and affected layouts | 3 | 5 | Distinct recovery/board states, error guidance, keyboard and 2× text | +| Required red/green failure, migration and race tests | 7 | 11 | Real file-backed tests plus recording-seam/controller/widget coverage | +| Integration regressions, review and scope/user documentation | 3 | 5 | Existing affected suites/gates and honest remaining A-24 scope | +| **PYB-006.2 engineering subtotal** | **38** | **63** | Original C1-S2-T02–T07/T10 allowance was **17h** | +| Operator recipe completion (PYB-009.1) | 2 | 2 | Existing C1-S2-T01 allowance; exact artifacts and safe test data | +| Representative Android + iPad recovery observations (PYB-008.1) | 4 | 6 | Build installation, interruptions and session/target observations; devices available | +| C1-S2 due follow-up (PYB-011.2) | 1 | 1 | Existing pilot allowance; not persistence implementation | +| **Comparable first-delivery workload** | **45** | **72** | Original full C1-S2 base allowance was **24h**, ceiling **26h** | + +The range is deliberately wider than the original task allowances. Even the +lower bound exceeds one Sprint's ceiling by 19h. Corruption, migration, session +and replacement guards cannot be removed to make the story appear to fit. +Physical access delays are calendar blockers, not hidden zero-hour passes. + +## 5. Reforecast proposal for Sprint Planning + +Use **50 engineering hours** as a working planning figure within the range; +re-estimate after the database and race tests expose actual complexity. The +following is a concrete capacity-safe proposal, not a silently adopted change +to future Sprint commitments or an assertion that extra people are assigned. + +| Sprint | Proposed allocation | Planned h | Consequence | +|---|---|---:|---| +| C1-S2 | 23h recovery foundations/meaningful tests, 2h operator recipe, 1h due pilot follow-up | 26 | Uses its existing 2h headroom; prioritize repository/coordinator and fail-closed tests. A tested engineering enabler may finish, but user recovery is not Done or exposed as complete | +| C1-S3 | 21h recovery UI/consent/integration and remaining failure scenarios, 1h rolling follow-up | 22 | Replaces the original matrix/activation batch forecast; 4h below ceiling remains available only after actual progress. M-02 remains pending if any required criterion is unfinished | +| C1-S4 | 6h finishing/review, 5h representative platform evidence, 1h rolling follow-up | 12 | Leaves 14h below ceiling for explicitly reselected work. Only then can PYB-006.2/M-02 be accepted if all scoped evidence passes | +| **Total** | **50h engineering + 2h recipe + 5h physical + 3h rolling follow-up** | **60** | Two additional follow-up hours are included because delivery spans three Sprints | + +This proposal consumes 60 of the 78 planned-ceiling hours across S2–S4. It does +not fit alongside all 70h of their original base tasks: matrix runs, activation +collection and conditional repairs must be reordered into the remaining 18h, +later capacity or separately confirmed contributor capacity. Keep prospective +follow-up windows; an inability to recruit/observe still remains an explicit +research limitation. Do not quietly use the 14h-per-Sprint event/support reserve +or count the same headroom twice. Root planning documents own the adopted +forecast and must preserve this proposal's status until selection is recorded. + +If the estimate trends toward 63 engineering hours, replan again; the 50h +working figure is not an acceptance waiver. An unexposed tested foundation is +an engineering increment, not a finished recovery user story. An earlier safe +end-to-end result can be accepted earlier when its complete evidence passes. + +```mermaid +flowchart LR + S1["S1: contract and estimate"] --> S2["S2: tested storage and coordination"] + S2 --> S3["S3: recovery choices and session guards"] + S3 --> S4["S4: remaining tests and platform evidence"] + S4 --> G{"All recovery acceptance passes?"} + G -->|Yes| DONE["Bounded recovery accepted; A-24 remainder carried"] + G -->|No| REPLAN["Keep unfinished work visible and replan"] +``` + +## 6. Decisions still needed during implementation + +| Item | Current disposition | When it matters | +|---|---|---| +| Exact Drift/native dependency versions and OS opening adapter | Select against the actual pinned toolchain; record licenses, minimums, lockfile and platform floors | Before admitting new implementation dependencies | +| Named Developer/operator and device access | Not assigned by a design document; root execution/evidence record tracks actual availability | Before selecting implementation and platform runs | +| Revised future Sprint order | Proposal above is sized; existing matrix and research work cannot all retain its old allocation | Next Sprint Planning/reforecast | +| Broader A-24 and Blocks persistence | Explicitly deferred; needs later contract and budget | Separate accepted slice | + +These are implementation planning inputs, not a request to stop authorized S1 +design work. T10 delivers the contract; T11 delivers this source review, +scenario matrix and estimate. Neither task closes PYB-006.2 or marks M-02, +platform qualification or a release complete. + +## 7. Documentation validation performed + +| Check | Actual result on 25 September 2026 | +|---|---| +| Canonical local-link checker, extended to include new Markdown files | 127 tracked + 3 new documents checked; zero broken local links | +| Mermaid rendering | Both new diagrams rendered with Mermaid CLI 11.16.0 and installed Chrome; generated SVGs stayed in a temporary directory | +| Estimate / scenario consistency | Engineering subtotal 38–63h, conditional allocation 60h, all 14 distinct DR-T scenarios verified | +| `git diff --check` and new-document whitespace/fences | Passed | +| `tools/ci/no_leak.sh` | Passed in the isolated recovery worktree | +| `tools/ci/spdx_lint.sh` | Passed in the isolated recovery worktree | +| `tests/firmware_tests/test_governance_files.sh` | Seven checks passed | + +The CLI's first default-browser launch could not find its expected cached +headless binary; explicitly selecting the already-installed Chrome completed +both renders. No browser/package installation or generated diagram asset was +needed. These are documentation/source-governance results, not evidence of +implemented persistence, runtime tests or physical recovery. diff --git a/docs/specifications/App/TDD.md b/docs/specifications/App/TDD.md index 95548199..ca295208 100644 --- a/docs/specifications/App/TDD.md +++ b/docs/specifications/App/TDD.md @@ -1,6 +1,6 @@ # PyBLE App — Technical Design Document (TDD) -Status: **DRAFT** · Owner: project maintainer · Last updated: 2026-08-27 +Status: **DRAFT** · Owner: project maintainer · Last updated: 2026-09-25 ## 0. Naming note (acronym clash) @@ -684,7 +684,7 @@ The label is UTF-8 and **bounded** — the client enforces a length cap before s ## 9. Persistence design (`lib/data/`) -The Drift schema models exactly the six content tables of [specs.md §8](specs.md) / [PRD §12.1](../prd.md), plus a lightweight settings store. No managed-fleet/lab/calibration tables (DAT-8, CON-7). — *(satisfies DAT-1..8, FR-PROJ-1..7, IF-3.)* +The full target Drift schema models exactly the six content tables of [specs.md §8](specs.md) / [PRD §12.1](../prd.md), plus a lightweight settings store. This is target architecture, not a claim that the current `lib/data/` placeholder implements it; the bounded first subset is specified in [§9.3](#93-bounded-current-text-recovery-specified). No managed-fleet/lab/calibration tables (DAT-8, CON-7). — *(satisfies DAT-1..8, FR-PROJ-1..7, IF-3.)* ### 9.1 Schema @@ -703,6 +703,36 @@ Saved-board reconnect is a lightweight `board_ref` app setting, **not** a relati Drift schema versions with explicit `MigrationStrategy` step migrations (forward-only); a schema-version test guards every bump. On launch the app hydrates the last-opened project and `board_ref` from Drift before any network/board activity (offline-first, NFR-OFF-1). Project export/import is a local archive (zip of files + metadata), no cloud (FR-PROJ-5, NFR-OFF-3). On disconnect, open buffers / files / run-and-console state are already in Drift, so nothing is lost across a dropped link (FR-PROJ-6, NFR-REL-3). +### 9.3 Bounded current-text recovery (specified) + +**C1-S1 / PYB-006.1, 2026-09-25 — implementation pending.** +[ADR-0048](../../decisions/0048-bounded-current-text-draft-recovery.md) and +[current-draft-recovery.md](current-draft-recovery.md) own the bounded successor +to ADR-0010. Start with the necessary `projects`/`project_files` subset and the +single SettingsStore; one current draft is not a completed project system. +The contract fixes atomic content/metadata commits, persisted generations, +explicit startup choices, nondestructive storage/version failures, and a local +recovery panel reachable before connection. An accepted revision is protected +only after its transaction commits; the existing board-dirty flag remains +separate from local checkpoint status. + +The coordinator must observe all document mutations, including `setContent`, +`newDocument` and `openGenerated`, rather than treating `openFromBoard` and +`markSaved` as sufficient hooks. A recovered path is context, never current +board-write authority. Affected Editor/Files/Blocks-handoff actions need the +existing editor mutation epoch and neutral connection-session stamp to reject +stale adoption/completion, including edit-away/back and a stable facade changing +attachments. The text PUT-to-Run sequence must pin and recheck its session. + +[Required scenarios](current-draft-recovery.md#7-required-evidence-before-acceptance) +include real file-backed restart/failure tests and actual iPad/Android evidence. +[The S1 estimate](../../developments/2026-q4-reliable-workflow/c1-s1/03_Recovery_Design_and_Sizing.md) +exceeds the original one-Sprint recovery allowance and proposes reforecasting; +safety cases remain required. Blocks graph recovery, full projects/history, +console state, saved boards, durable settings and import provenance remain +carried to their existing A-24/related stories. No runtime behavior or new +protocol operation is implemented by this specification change. + ## 10. GitHub import design (`lib/github_import/`) — *(implements the connected subset frozen by @@ -1826,6 +1856,13 @@ board display. Two UX surfaces: **FROZEN (working-loop increment · `[docs]` 2026-07-02, [ADR-0010](../../decisions/0010-working-loop-in-memory-document.md)).** This is the shared Riverpod contract the edit→run→watch→manage loop implements to, across A-20 (editor), A-21 (console), A-16 (run-control toolbar) and A-30 (files). Ownership is **disjoint** so the feature engineers work in parallel. Every provider binds only to the neutral `Connection` seam + neutral types ([§5](#5-the-connection-api-design)) — **no UI package imports `lib/ble`** (CON-8, FR-UI-7); app-layer packages MAY cross-import each other's **public** providers (`files → editor`, shell → run-control). API sketches are illustrative; the frozen interface is whatever the `[red]` tests pin ([§15](#15-test-design)). +**Specified successor (2026-09-25).** The volatile behavior below remains the +current implemented baseline. [§9.3](#93-bounded-current-text-recovery-specified) +and [the current-draft contract](current-draft-recovery.md) define its bounded +persistence replacement, including stronger epoch/session checks for affected +asynchronous actions. Do not read either the older illustrative API or the +successor design as evidence that persistence has shipped. + **(a) Current document — `lib/editor` (owner: app-editor-console-engineer).** A single volatile in-memory document; survives navigation, not restart (persistence deferred to A-24, [§11.1](#111-editor)): ```dart diff --git a/docs/specifications/App/current-draft-recovery.md b/docs/specifications/App/current-draft-recovery.md new file mode 100644 index 00000000..bb5a4757 --- /dev/null +++ b/docs/specifications/App/current-draft-recovery.md @@ -0,0 +1,285 @@ + + + +# Current-text draft recovery — bounded implementation contract + +| Field | Value | +|---|---| +| Design baseline | 25 September 2026; C1-S1-T10/T11, PYB-006.1 | +| Status | Specified for implementation under the requested C1-S1 work; implementation and acceptance evidence pending | +| Decision | [ADR-0048](../../decisions/0048-bounded-current-text-draft-recovery.md) | +| Parent obligations | A-24; FR-EDIT-7, FR-PROJ-2/6, NFR-REL-3; their broader acceptance remains carried | +| Delivery and sizing | [C1-S1 design review](../../developments/2026-q4-reliable-workflow/c1-s1/03_Recovery_Design_and_Sizing.md) | + +This is the normative contract for the proposed PYB-006.2 current-text slice. +It does not describe shipped behavior. The current implementation remains the +volatile provider documented in [ADR-0010](../../decisions/0010-working-loop-in-memory-document.md). +No PBLE/1 change or board-identity allowlist is introduced. + +## 1. Scope and observable promise + +| ID | Required behavior | +|---|---| +| DR-01 | Retain one current text document in an on-device Drift database, including an untitled buffer and Python explicitly copied from Blocks into the Editor. Persist exact accepted text, its filename and bounded recovery metadata. | +| DR-02 | A revision is protected only after the matching database transaction commits successfully. Show local recovery status separately from whether the document was uploaded to a board. | +| DR-03 | After process restart, present the last valid committed revision for explicit Restore or Discard without requiring network, BLE permission, scanning or a board. No restore action writes or runs board code. | +| DR-04 | Preserve the previous committed revision when an attempted update fails or is interrupted before commit; never claim newer uncommitted text is protected. Detect unusable storage and fail without silently resetting it. | +| DR-05 | Treat recovered board-path information as historical context. Every recovered draft starts without an authorized board target and must receive explicit current-session target consent before an Editor Save, Run or Files Upload can write it. | +| DR-06 | An old asynchronous read, write, confirmation or board completion must not overwrite newer editor content, clear newer edits, resurrect a discarded draft or authorize another board session. | +| DR-07 | State explicitly that Blocks workspaces, multiple projects/files, console/run history, saved boards, import provenance and durable display settings are outside this slice. | + +The guarantee covers an acknowledged recovery checkpoint in the app's retained +private storage across ordinary app termination and relaunch. Text still marked +pending, an uninstalled app, cleared app data, device loss, unrecoverable media +failure and OS restore/backup behavior are outside that guarantee. Copy must not +promise that every keystroke survives immediate termination or that this is a +backup/export service. + +## 2. Content and storage model + +Use the planned Drift database in `lib/data/`, behind Riverpod-injected typed +repositories. Do not create a scratch-file store, a second preferences store or +a transport dependency. Database work runs outside the UI isolate through one +owned connection/writer. Widgets receive neutral state and commands. + +Implement the necessary `projects` and `project_files` subset of the existing +[TDD §9](TDD.md#9-persistence-design-libdata) model plus its single `SettingsStore`. +One internal project and one file form the current-draft slot; this does not +expose a project browser or imply that all six content tables are implemented. +Reserve an internal local key for that project rather than a user-visible +project name. The remaining content tables can be added by tested migrations. + +| Stored value | Contract | +|---|---| +| Internal project/file identity | Local opaque identifiers; never board identifiers or an authentication decision | +| Current filename | Exact accepted display leaf; nonempty, no separators, control characters, `.` or `..`; at most 128 UTF-8 bytes. Invalid metadata produces a recoverable validation error, not a silently renamed write target | +| Content | Exact well-formed Unicode text encoded as UTF-8; preserve whitespace, newlines, comments and smart punctuation. Storage must not apply the board Save/Run normalization | +| Size and content hash | Exact UTF-8 byte length and SHA-256 of those bytes; verify before offering Restore. Hash detects accidental content mismatch, not authenticity or a board checksum | +| Recovery metadata in SettingsStore | Versioned draft-slot record: document ID, monotonically increasing persisted generation, filename, optional origin path, checkpoint time and content identity; updated atomically with the content row | +| Origin path | Optional validated historical board path, at most PBLE/1's 128 UTF-8 bytes; shown as context only, never loaded into active `boardPath` authority | +| Empty slot | Explicit committed empty state/tombstone at a newer generation after confirmed Discard or New; pending older writes cannot repopulate it | +| Never stored by this slice | BLE address, board label/identity, session stamp, board-write consent, `Connection`, runtime operation state, console text, Blocks JSON or import credentials/provenance | + +Content admission is bounded at **1 MiB of UTF-8 text**. The limit applies to the +recovery copy, not a new silent truncation of the Editor. Larger or malformed +text remains in memory, shows a localized “recovery copy not saved” reason and +leaves the prior committed copy intact. No code is normalized, truncated, +executed or uploaded to make it fit. Snapshot comparison and the byte bound must +not block the UI isolate for large buffers. Boundary tests cover zero bytes, one byte, +the exact limit, one byte over, multibyte text and unpaired UTF-16 surrogates. + +Store the database and its journal files in app-private persistent application +storage, never a cache directory or repository. No app-managed remote sync or +telemetry is added. Do not log source, origin paths or database contents in +ordinary diagnostics. The implementation must document actual platform +storage/backup settings without presenting OS-managed backups as a PyBLE feature. + +The schema name/column spelling is an implementation detail frozen by the first +schema fixture. Content, recovery metadata and generation must be committed in +one transaction; a row and its metadata can never be accepted separately. +SQLite WAL with `synchronous=FULL` is the specified starting configuration; verify +it on each production connection. This uses SQLite's commit guarantees subject +to functioning filesystem/OS synchronization, not an absolute media-loss +promise. [SQLite WAL documentation](https://www.sqlite.org/wal.html) and +[SQLite atomic commit](https://www.sqlite.org/atomiccommit.html) describe those +boundaries. + +## 3. Write boundary and local status + +Observe all document mutations, not only `openFromBoard` and `markSaved`: +`setContent`, `newDocument`, `openFromBoard`, `openGenerated`, restore/discard and +successful board-binding changes must go through one recovery coordinator. +Keep the existing document provider readable by Editor, Files and run controls; +keep recovery status in a separate typed provider. Existing `dirty` remains a +board-upload comparison, not proof of durable local storage. + +| Local state | User-visible meaning | +|---|---| +| Loading / recovery decision pending | Storage has not yielded a usable current draft; no default empty buffer may overwrite it | +| Pending | Current revision differs from the last acknowledged recovery copy | +| Saving | Its captured snapshot is being committed; newer edits can remain pending | +| Saved locally | The exact current document identity and revision have committed successfully | +| Unavailable / failed | Current text is in memory only, or newer than the saved copy; offer Retry and show the reason without claiming a successful save | + +Queue after 500 ms of edit inactivity, with a maximum two-second scheduling +interval during continuous editing while the app is active. These are scheduling +rules, not promised disk completion times. Use one active commit and at most +one coalesced latest pending snapshot. Lifecycle inactive/pause requests an +immediate flush, but a lifecycle callback is never the only persistence trigger +and process termination need not deliver it. + +Provide an explicit localized **Save recovery copy** action with completion/error +feedback. It waits for the captured revision's commit; a later edit remains +pending even when that request succeeds. Existing board **Save** and **Run** +retain their explicit board semantics and separate result feedback; a successful +board upload must not be called a successful local checkpoint. The local copy +can succeed while BLE is unavailable, and a board failure cannot delete it. + +Do not drop a committed copy merely because the document is clean relative to +a board. Restoring a clean or dirty prior document follows the same local-only +choice and starts with `dirty=true`, `boardPath=null` and no target consent. +A genuinely empty untitled slot produced by confirmed New/Discard does not +prompt at the next launch; a deliberately empty named file is still recoverable. + +## 4. Startup, replacement and recovery interaction + +Resolve local storage before mounting any recovery-dependent Editor mutations +or auto-starting connection workflows. Show a bounded loading/error surface; +never wait indefinitely behind an unresponsive spinner. After ten seconds without +completion, offer Retry and Continue without recovery. Cancelling a wait advances +the operation epoch; a late completion cannot change the current UI or replace +text. Do not delete or reopen storage underneath a still-running database task. + +A local recovery panel is reachable from the disconnected shell as well as the +Editor. This is a narrow exception to the connection-gated shell in +[ADR-0011](../../decisions/0011-connection-gated-shell.md), not a complete offline +IDE. It may preview and copy recovered text locally; the normal IDE still appears +when connected. Restore itself happens before any connection and places text in +the shared document provider; the panel keeps the restored text visible offline. + +| Choice / trigger | Required outcome | +|---|---| +| Restore | Preview filename, checkpoint time and text; explain that a board target must be chosen again. Explicit Restore loads the validated copy, resets target authority and increments the editor epoch. It does not delete the durable copy | +| Discard | Confirm deletion of this local recovery copy. Commit the empty-slot tombstone first; only success closes the prompt and installs a fresh buffer. Cancel or failed commit preserves the copy and prompt | +| Dismiss / Back | Leaves the decision unresolved and the committed copy intact; return to the recovery surface, not an empty auto-saving Editor | +| Storage unreadable / migration unsupported | Offer Retry or Continue without recovery with a persistent warning. Preserve the database/journal files; do not auto-delete, recreate or migrate downward | +| Continue without recovery | Allow a clearly volatile session; keep old storage untouched. Retrying later requires an explicit choice between existing local text and recovered text, with preview/copy, never automatic replacement | +| Replace by New, board Open or Blocks-to-Editor | Ask before replacing nonempty/current meaningful content when it is dirty, locally pending/failed, or awaiting recovery. Existing Blocks confirmation must use the same captured editor epoch. Do not require the user to discover which surface owns the previous copy | +| Confirmed replacement | Serialize the replacement/tombstone after cancelling obsolete queued writes. Commit the replacement before acknowledging local protection. If storage fails, retain current content and offer Cancel or explicit continuation in volatile mode; do not silently lose both versions | + +Confirmation is bound to the captured editor epoch, not merely equal text or a +filename. A delayed board download or Blocks snapshot must recheck that epoch +and any operation/session guard before replacing the buffer. A changed epoch +requires a new decision. There is one current slot, no history or version browser; +confirmed replacement may remove its prior committed content and must say so. + +All new copy, error, status, confirmation and semantics strings are ARB-backed. +Dialogs/panels must remain usable at 2× text, with a keyboard present and through +screen-reader focus; technical filenames, source and board paths stay verbatim. +No automatic copying to the clipboard or export/sharing occurs. + +```mermaid +flowchart TD + START["Open local store"] --> CHECK{"Valid committed draft?"} + CHECK -->|No draft| FRESH["Fresh current buffer"] + CHECK -->|Yes| CHOICE["Local preview: Restore or Discard"] + CHECK -->|Unreadable| ERROR["Preserve store; Retry or volatile session"] + CHOICE -->|Restore| RESTORED["Current text; no board authority"] + CHOICE -->|Confirmed discard| TOMBSTONE["Commit newer empty slot"] + TOMBSTONE -->|Success| FRESH + TOMBSTONE -->|Failure| CHOICE + RESTORED --> EDIT["Edit; pending recovery copy"] + FRESH --> EDIT + EDIT --> WRITE["Serialized atomic checkpoint"] + WRITE -->|Commit current revision| SAVED["Saved locally"] + WRITE -->|Failure| PENDING["Keep text and prior copy; show failure"] + SAVED --> EDIT +``` + +## 5. Document identity, board authority and stale work + +Allocate durable generations from the stored high-water mark after opening the +store; never reset them to zero on relaunch. The coordinator is the sole writer +for this slot in the app process; database locking and the transaction guard +reject an unexpected competing writer rather than overwriting a newer copy. + +Use the existing `editorDocumentEpochProvider` as an in-process mutation guard +and add explicit current-document identity/recovery generation where needed. +Do not equate equal `EditorDocument` values with the same operation: editing +away and back is still a newer revision. Capture the appropriate identity, +epoch and generation before every asynchronous operation. + +| Boundary | Required guard | +|---|---| +| Database startup/read | Startup/retry operation epoch and expected editor epoch; older hydration cannot replace newer text | +| Checkpoint queue | Single serial writer; each mutation or discard has a newer generation. Commit must not regress the durable generation; completion only acknowledges the captured revision | +| Discard/replacement | Cancel obsolete queued snapshots, order a newer tombstone/replacement after an active write, and fence late completions; no resurrection after confirmed success | +| Board Open | Capture expected editor epoch, open-operation generation and `connectionSessionStampOf` before GET; recheck all three immediately before adoption. A stable facade changing from board A to B invalidates the download even when the editor never changed | +| Blocks-to-Editor | Expected editor epoch plus snapshot/operation generation; recheck after snapshot/confirmation and before adopting; preserve any existing board-session guards on a board-backed preparation | +| Save / Files Upload completion | Captured document identity and editor epoch **and** current opaque connection-session stamp; only matching completion may mark the document saved/bound | +| Editor Run upload → run | Capture the session before PUT and recheck it before `runFile`; refuse the second verb on a replacement attachment. Preserve truthful partial outcome: upload may have succeeded but Run did not occur | +| Post-Run completion | Recheck document epoch and session before clearing board-dirty state or persisting binding metadata | +| Board target consent | Bind to current document identity, opaque session stamp, resolved target and action; changing session, document, target or displayed source revision invalidates the pending confirmation | + +A `Connection` facade can keep the same object identity across attachments. +Reuse the neutral `connectionSessionStampOf` mechanism already used for Blocks +bundles and Files multi-delete. Do not persist a session stamp or infer the same +physical board from an advertising name, chip, SemVer or a recovered path. + +For a recovered draft, show the actual current-session destination and whether +the operation writes only or writes and runs; confirm its ability to overwrite +that path before the first mutation. Cancellation sends no board verb. A +successful explicitly confirmed action may bind that document to the same +session/path for later explicit actions; disconnect or a new attachment revokes +that binding. Files Upload uses its actual `cwd/name` destination, not the +historical path. No board listing or probe happens as a side effect of local +recovery. Existing filesystem-jail, path and capability restrictions still apply. + +## 6. Failure and migration rules + +| Scenario | Required result | +|---|---| +| Termination before transaction commit | Next launch offers the previous complete committed copy, or no copy if none was ever committed; never partial content/metadata | +| Termination after commit but before UI acknowledgement | New revision may be recoverable; caller uncertainty must not trigger a duplicate board action or rollback to an older revision | +| Full storage, permission loss or write I/O error | Keep current in-memory edits and last committed copy; show a local error and explicit Retry. Do not clear board-dirty/local-pending flags as if the save succeeded | +| Invalid length/hash/metadata or truncated/corrupt database | Refuse automatic hydration, preserve storage, show a bounded error and volatile-mode option. Do not silently choose an empty draft or treat corrupt text as valid | +| Temporarily unavailable protected app storage | Same nondestructive error path; Retry when available. Do not rewrite the store merely because opening failed | +| Unsupported newer schema or recovery format | Fail closed without writing, reset or downgrade; tell the user a compatible app version is needed | +| First install / current volatile release upgrade | Create schema version 1 only when no database exists; start empty. No old disk draft exists to migrate and no pre-upgrade volatile text can be promised recovered | +| Supported future schema migration | Transactional explicit forward steps; preserve the current slot and its identity. Check exported old/new schemas and round-trip fixtures before accepting the version bump | +| Migration interruption/failure | Retain a usable prior schema or report preserved-but-unreadable state. Never catch migration failure by deleting user storage | + +Version both the database schema and draft metadata format. Export the first +schema and test fresh creation, reopening, supported fixture migration where +one exists, unsupported-version refusal and interrupted failure paths. A made-up +“v0 disk draft” fixture must not imply earlier released persistence. Follow the +[Drift migration guide](https://drift.simonbinder.eu/migrations/) and +[schema exports](https://drift.simonbinder.eu/migrations/exports/). + +A database full/corrupt failure injection is local storage evidence, separate +from a PBLE `ENOSPC` board response. Preserve journal/WAL companions as part of +storage; do not copy only the main file and claim a recoverable checkpoint. +Automatic repair, database reset UI and recovery of arbitrary damaged storage +are not included. Their absence must not cause hidden deletion or a startup loop. + +## 7. Required evidence before acceptance + +All rows below are required for the behavior they cover. Unit fakes cannot prove +process durability, and a passing physical happy path cannot replace failure +injection. Evidence links/statuses belong in the implementation record; every +row is **Not run for this design-only increment**. + +| Scenario ID | Exercise and oracle | Required evidence | +|---|---|---| +| DR-T01 | Exact UTF-8, filenames, empty/named text, size limits and invalid metadata round-trip without normalization | Pure validation + file-backed database tests | +| DR-T02 | Await committed revision, close/reopen the actual file-backed store, obtain identical text/metadata | Real database integration, not an in-memory fake only | +| DR-T03 | Terminate before/during/after checkpoint; reopened content is the permitted whole old/new revision | Fault-controlled child process/database tests; Android and iPad termination/relaunch observations | +| DR-T04 | Full/permission/I/O failure leaves prior committed copy and live text, never false success | Store error injection + UI/controller assertions | +| DR-T05 | Corrupt row, bad hash, truncated store and unsupported schema preserve files and offer honest recovery choices | File fixtures + startup/widget tests | +| DR-T06 | Create/reopen v1; exported-schema validation; unsupported version and future supported migrations | Drift schema fixtures and migration tests; no invented released v0 | +| DR-T07 | Restore, Cancel/Back, Discard success/failure and volatile-mode Retry never overwrite newer text or invoke board/network actions | Widget/controller tests with recording seams | +| DR-T08 | Continuous edits, coalescing, pause without callback, late hydration, delayed commit and edit-away/back | Deterministic clock/epoch tests plus lifecycle regression | +| DR-T09 | Discard/New/replacement racing an active write cannot resurrect prior content | Real transaction + coordinator tests | +| DR-T10 | Recovered draft requires current target consent; cancel, path/session/document changes invalidate it | Save/Run/Files tests with recording connections | +| DR-T11 | Board swap after text PUT refuses Run; stale Save/Run/Upload and board Open completions preserve newer edits. A delayed GET from board A cannot replace the Editor after the same facade attaches board B, even with an unchanged editor epoch | Controller/session tests including stable facade, GET across attachments and edit-away/back | +| DR-T12 | Explicit Blocks handoff text is recoverable, workspace JSON is not; same-process Blocks retention and sidecar behavior remain intact | Blocks-to-Editor regression + representative device checks | +| DR-T13 | Separate local/board statuses, ARB parity, errors, disconnected panel, keyboard and 2× text | Localization/widget/semantics tests and affected goldens | +| DR-T14 | Recorded Android and iPad candidates restore offline and demand board-target consent; no invisible board write/run | Physical platform records tied to exact installed builds, test boards and actual observations | + +Required source gates, dependency/license records, DCO and red → green commits +remain as defined in [AGENTS.md](../../../AGENTS.md). Device/profile release +qualification is additionally governed by the selected release matrix; two +representative recovery runs do not qualify five firmware profiles. + +## 8. Carried scope + +| A-24 / related obligation | Treatment after this bounded slice | +|---|---| +| Current text after process restart | Only the acknowledged, bounded copy and failure semantics above can become accepted | +| Full FR-EDIT-7 Save-to-project | Still carried: board Save plus one recovery slot is not a project-management UI | +| FR-PROJ-2 and complete six-table model | Still carried: multiple projects/files and their complete DAOs/flows are absent | +| FR-PROJ-6 / NFR-REL-3 all user state | Still carried for console/run state, project collections and uncommitted edits; maintain existing same-process link-loss behavior | +| Blocks workspace/invalid graph recovery | Deferred separately; restoring generated Python cannot reconstruct the graph, revisions, warnings or target. Existing board sidecar reopen is a different, explicit operation | +| Saved boards, locale/font settings | Deferred within the single future SettingsStore; no second settings backend | +| Snapshots/history, GitHub import provenance, export/import | Deferred to their existing stories; local recovery is neither history nor a project backup | +| Automatic reconnect/resume or board ownership | No new guarantee; no new protocol operation or identity proof | diff --git a/docs/specifications/App/specs.md b/docs/specifications/App/specs.md index 6716610b..b81956a8 100644 --- a/docs/specifications/App/specs.md +++ b/docs/specifications/App/specs.md @@ -1,6 +1,6 @@ # PyBLE App — Requirements Specification -Status: **DRAFT** · Owner: project maintainer · Last updated: 2026-08-27 +Status: **DRAFT** · Owner: project maintainer · Last updated: 2026-09-25 ## 1. Purpose, Scope & Document Role @@ -167,6 +167,20 @@ The client implements the PBLE/1 wire contract; it references [protocol.md](../p **Working-loop increment — FROZEN (A-20 subset · `[docs]` 2026-07-02, amended 2026-08-22 by [ADR-0012](../../decisions/0012-flutter-code-editor-behind-editorsurface.md), [ADR-0010](../../decisions/0010-working-loop-in-memory-document.md), [TDD §11.1](TDD.md#111-editor)/[§11.6](TDD.md#116-working-loop-provider-contract-frozen); run path superseded 2026-07-27 by [ADR-0013](../../decisions/0013-clean-room-blockly-one-way-file-backed.md)).** In scope: the ADR-0012 `EditorSurface` seam with `flutter_code_editor` 0.3.5 as the default rich adapter and the existing plain `TextField` as a live fallback; Python highlighting, always-visible one-based line numbers, safe auto-indent/Tab handling, and an editor-only 10–24 sp font adjustment in one-point steps (default 14 sp). Code and gutter resize together, platform text scaling still applies, and resizing MUST NOT modify the document, selection, dirty state, or board path. The size is app-session state, independent of file and board, until A-24's single Drift `SettingsStore` makes it durable; a second preferences store MUST NOT be introduced. The single volatile in-memory current document (name/content/dirty/boardPath), **New**, and board-backed Save/Run behavior remain as frozen by ADR-0010/0013. Save and Run capture one normalized document snapshot; transfer completion marks it saved/bound only when the live document still equals that snapshot, so mid-transfer edits or a replacement document remain dirty. The editor binds to `Connection` only (FR-EDIT-6, CON-8), and editor source MUST NOT reach a network analyzer. **Still deferred to A-24 or later:** multi-file tabs, app-owned localized find/replace, the remaining external-keyboard shortcuts, durable display settings, Save-to-project, and buffers-survive-restart. The document provider's `openFromBoard`/`markSaved` and the session display provider are the A-24 persistence hooks (RECORDED deviations, ADR-0010/0012). +**Current-text recovery successor — SPECIFIED, implementation pending +(`[docs]` 2026-09-25, C1-S1/PYB-006.1, +[ADR-0048](../../decisions/0048-bounded-current-text-draft-recovery.md)).** +The [bounded recovery contract](current-draft-recovery.md) defines DR-01–07: +one atomic Drift current-text checkpoint, explicit offline Restore/Discard, +separate local/board save status, nondestructive interrupted/corrupt/full-storage +handling and current-session target consent. It strengthens affected asynchronous +Editor/Files actions from document-value equality to epoch and session guards. +A local recovery panel extends the connection-gated shell without claiming a +complete offline IDE. Blocks JSON and the remaining A-24 project/settings/history +requirements stay carried. The working-loop text above remains the implemented +baseline until this successor's automated and applicable physical evidence passes; +writing the contract does not satisfy FR-EDIT-7, FR-PROJ-2/6 or NFR-REL-3 in full. + ### 4.7 Console Panel (`lib/console/`) — FR-CONSOLE - **FR-CONSOLE-1** — The console MUST render the live `console` stream (`CONSOLE_DATA`) and MUST visually distinguish `stdout`, `stderr`, and `system` streams. MUST (*source: PRD §9.4; verify: widget/golden; story: A-21*) From 0b8286165b3d63d667fe6fb4fc56349536b6eba9 Mon Sep 17 00:00:00 2001 From: Viwat Vchirawongkwin Date: Fri, 25 Sep 2026 17:12:09 +0700 Subject: [PATCH 4/9] [docs] inventory C1-S1 validation gates and operator procedure Signed-off-by: Viwat Vchirawongkwin --- ...alidation_Inventory_and_Operator_Recipe.md | 216 ++++++++++++++++++ .../firmware/ports/esp32-c3-4mb.md | 9 + .../firmware/ports/rpi-pico2-w.md | 8 + docs/specifications/hardware.md | 14 +- tests/firmware_tests/hil/README.md | 7 + .../firmware_tests/host/conformance/README.md | 6 +- 6 files changed, 255 insertions(+), 5 deletions(-) create mode 100644 docs/developments/2026-q4-reliable-workflow/c1-s1/04_Validation_Inventory_and_Operator_Recipe.md diff --git a/docs/developments/2026-q4-reliable-workflow/c1-s1/04_Validation_Inventory_and_Operator_Recipe.md b/docs/developments/2026-q4-reliable-workflow/c1-s1/04_Validation_Inventory_and_Operator_Recipe.md new file mode 100644 index 00000000..7721d3b0 --- /dev/null +++ b/docs/developments/2026-q4-reliable-workflow/c1-s1/04_Validation_Inventory_and_Operator_Recipe.md @@ -0,0 +1,216 @@ + + + +# C1-S1 — validation inventory and operator recipe + +| Field | Recorded state | +|---|---| +| Task / story | C1-S1-T12 / PYB-009.1; initial inventory and recipe, with scoped recovery completion planned in C1-S2-T01 | +| Inspection date / source | 25 September 2026; `d039db09779ed45124874721f88b2e0931664743` before this documentation change | +| Worktree | Branch `work/c1-s1-qualification`; isolated from the app/research worktrees | +| Result | Existing tools, normative counts, missing access, operator procedure and initial cost range inventoried; 110 focused host tests passed | +| Physical result | No board, app installation, BLE session, flash operation or physical qualification performed for this task | +| Review boundary | Documentary source/command checks are complete; named physical operator, reviewed candidate and actual timed rehearsal remain required before execution | +| Related evidence | [Execution record](00_Execution_Record.md), [channel/artifact ledger](01_Channel_and_Artifact_Ledger.md), [pilot procedure](02_Pilot_Protocol_and_Observation_Kit.md), [recovery design](03_Recovery_Design_and_Sizing.md) | + +This is an operator entry point to maintained suites, not a new harness or release schema. Follow the selected candidate's versioned contracts and the current [HIL guide](../../../../tests/firmware_tests/hil/README.md). A host test proves the tested software contract; a physical run proves only its recorded artifact, device and scenario. Neither supplies participant-observation evidence or a PyBLE Ready award. + +## 1. Evidence and gate selection + +| Proposed claim | Required evidence and authority | What remains separate | +|---|---|---| +| Documentation task complete | Source/link/command review and applicable contributor gates | PYB-009.1 also needs the scoped recovery procedure completed/reviewed in S2; second-operator reproduction is PYB-009.2 | +| App source change works | Specification-first change, meaningful red/green tests, locked app CI, affected physical app scenarios and the accepted Definition of Done | Fake BLE, emulators and source version strings do not establish store installation or firmware qualification | +| Candidate app supports the five existing profiles | At least the ten platform/profile rows below, affected lifecycle/recovery cases and declared exact firmware baselines; qualify the claimed capability on both platforms | An unchanged released firmware is a named compatibility input; an app-only increment does not automatically require rebuilding/requalifying all firmware bytes | +| New automated-qualified v0.6.1 firmware release | Fresh atomic five-profile build/provenance/license/OI-1/hardening/provisioning/recovery matrix; both physical app rows in every V5 record; all applicable C3, Pico and Waveshare gates | A representative pair of app runs, a completed build or one Ready rehearsal cannot admit the release | +| Firmware v0.6.1 is publicly distributed | The dated [owner-confirmed publication record](../../../testing/firmware-v0.6.1-publication-2026-09-11.md) | Its incomplete automated HIL remains incomplete; retained v0.6.0 qualification is historical, not a fresh v0.6.1 result | +| User can perform/repeat a useful task | Prospective observation/assistance/follow-up records under the pilot procedure | Bench success is not activation, usability, retention or consent evidence | + +The normative authorities are [App specifications](../../../specifications/App/specs.md), [firmware specifications §5.3](../../../specifications/firmware/specs.md#53-footprint-gates-nfr-fp), [V5 release evidence](../../../specifications/firmware/browser-flashing.md#95-pyble_hil_records_v5-five-profile-heterogeneous-release), the exact-profile contracts and the candidate-bound [OI-1 policy](../../../../firmware/qualification/oi1-gates.json). Use the source era selected by the candidate validator. Do not copy historical policy numbers or edit a policy to fit a failing run. + +```mermaid +flowchart TD + I["Record candidate, claim, operator and access"] --> S["Run applicable source and host checks"] + S --> A["Run exact physical app rows"] + I --> F{"New firmware qualification claim?"} + F -->|Yes| H["Fresh five-profile build, OI-1, hardening and recovery evidence"] + A --> R["Review evidence against declared gates"] + H --> R + F -->|No| B["Name unchanged firmware baseline and its limitations"] + B --> R + R --> P["Record passed, failed, blocked or not run"] + P --> N["Replan gaps; release admission is a separate decision"] +``` + +## 2. Existing tools and reproducible entry points + +Unless a row names another directory, commands run from the repository root in a clean, candidate-specific checkout. Record command, start/end time, exit status, source commit and full retained log. For new Markdown files, the normal tracked-file link gate must be supplemented with explicit discovery before staging. Do not initialize submodules or substitute toolchains merely to turn an unavailable check green. + +| Layer / maintained entry point | Environment and command | Expected evidence / limits | +|---|---|---| +| Contributor/document checks | `tools/ci/no_leak.sh`; `tools/ci/spdx_lint.sh`; `python3 tools/ci/docs_links.py`; `python3 -m unittest discover -s tests/publication -p 'test_*.py'`; `tests/firmware_tests/test_governance_files.sh` | Successful exits and actual counts. DCO requires `git commit -s`; `tools/ci/dco_check.sh` checks the selected range. A source gate is not a device result | +| App unit/widget/conformance | In `app/`, Flutter **3.44.1 stable**: `flutter pub get --enforce-lockfile`, `flutter gen-l10n`, `dart format --output=none --set-exit-if-changed lib test integration_test`, `flutter analyze`, `flutter test --exclude-tags golden` | Match tracked `app/pubspec.lock`; preserve failure output. Import and locale gates also apply to affected app source | +| App pixel goldens | Same app prerequisites; `flutter test --tags golden` on CI's pinned **macos-15 Apple Silicon** environment | Reviewed renderer-specific baselines. A different local OS can provide diagnostics but must not silently replace reference images | +| Actual Android WebView integration | Reproduce the complete `android-webview` job in [CI](../../../../.github/workflows/ci.yml): Ubuntu 24.04; API 34 AOSP x86_64 emulator; compile API 36; build-tools 36.0.0; NDK 28.2.13676358; Flutter 3.44.1 | The job checks production packaging and drives `integration_test/android_smoke_test.dart` using the integration flavor. Reuse its AVD setup, app build and `flutter drive` arguments together. Real WebView success remains emulator evidence, not physical BLE HIL | +| Complete firmware host suite | CI initializes pinned MicroPython host dependencies `lib/micropython-lib` and `lib/cyw43-driver`; then `tests/firmware_tests/run_tests.sh` and `python3 -m unittest discover -s tests/firmware_tests/host -p 'test_*.py'` | Shell/native/portable/release tests. No connected board required; compiler/submodule availability still matters. Historical `DEFERRED-HIL` output remains unfinished physical work | +| Focused shared conformance | `python3 tests/firmware_tests/host/conformance/test_hil_wire.py`; active fixtures described in [host conformance guide](../../../../tests/firmware_tests/host/conformance/README.md) | Byte agreement with shared PBLE/1 corpus; current semantic vectors are `v061_session_vectors.json`, `v061_payload_grammar_vectors.json` and `v061_label_vectors.json`. Archived byte-less ledgers are not current blockers | +| Focused bench contracts | `python3 tests/firmware_tests/host/test_target_hil_benches.py`; `python3 tests/firmware_tests/host/test_oi1_profile_bench.py`; `python3 tests/firmware_tests/host/test_oi1_rp2_profile_bench.py` | Host-only identity, orchestration, threshold, integrity and evidence-shape contracts; no physical pass | +| BLE identity / lifecycle diagnostics | `target_smoke.py`, `target_run_stop.py`, `file_roundtrip_bench.py` under `tests/firmware_tests/hil/`; command sequence below | Exact expected chip/agent; raw results retained privately. They do not synthesize complete release records | +| OI-1 final-candidate measurement | `tests/firmware_tests/hil/oi1_profile_bench.py --mode verify` with exact policy, profile/artifacts, private address, identity and reset inputs from the HIL guide | Canonical `oi1_observation` plus exclusive-created raw log. Baseline mode derives engineering inputs; it is not final verify qualification | +| v0.6.1 workspace and hardening | `v061_workspace_acquire.py`, then `v061_hardening_bench.py`; use the guide's complete candidate/receipt/binding arguments | Two measured sacrificial-media acquisitions plus seven live scenarios per profile. Requires separate explicit disposable-media authority and backups; never use an owner's working board as a fixture | +| Release evidence writers/gates | `firmware/scripts/release_bundle.py create-hil-completion` and `assemble-hil-report`; `firmware/qualification/v060_profile_release_gate.py`, `v061_hardening_release_gate.py`, `waveshare_lcd147b_release_gate.py` | Candidate-specific canonical fragments and validator-derived summaries. A `--passed-gate` argument attests already retained evidence; it does not execute or waive the gate | + +### Environment and artifact binding + +| Input | Required record / available source | +|---|---| +| Firmware source and tools | [versions.lock](../../../../firmware/versions.lock): MicroPython v1.28.0 / `e0e9fbb17ed6fd06bb76e266ae554784c9c80804`; ESP-IDF v5.5.1 / `fcae32885b0296b32044cb99ecbdc50d98dddb83`; ARM GNU 14.2.Rel1 / GCC `14.2.1 20241119`; picotool 2.3.0 with locked archive/executable hashes. These are inspected pins, not newly built binaries | +| HIL collector environment | Dedicated environment, OS/Python/BLE backend/adapter and package versions retained. Current macOS workspace acquisition specifies Bleak **3.0.2**, pyserial **3.5**, esptool **4.12.0** for ESP, plus the repository-pinned picotool for Pico. Do not modify the compiler environment | +| Candidate identity | Selected source/qualification commits; protected candidate `release.json` hash; exact install bytes/hash, manifest/component hashes for ESP; UF2 and bound raw BIN for Pico; policy and suite hashes. Keep candidate directories immutable | +| Current inspected policy | Schema 3 / `v0.6.0-five-profile` scope reused by the admitted v0.6.1 contract. Current policy binds `docs/validation/firmware/oi1/96497b9cf642ab2078842ce8a321c3c84b6714b2.json` with SHA-256 `007e19f0c0281801a3c065f01742ba9606e340bce07b5e67920f036cea375c76`; older `a8be631…` guide examples remain historical. The candidate-bound validator selects the actual admissible policy | +| App identity | Platform, delivery channel, displayed version/build, OS/device and actual source/upload/install provenance from the channel ledger. V5's `app_version`, `app_build`, `os_major` and `status` fields do not replace fuller supplemental provenance. Unknown installed-byte identity stays unknown | +| Private evidence | New access-controlled paths outside candidate/qualification checkouts for addresses, serial/UID bindings, raw capture and generated receipts; do not paste identifiers, user files or console content into Git | +| Public evidence | Reviewed redacted output, hashes, timestamps, exact scope and failed/not-run rows; link existing release formats rather than creating competing result files | + +## 3. Physical inventory and ten app rows + +Historical release evidence establishes which exact profiles exist, not whether the required bench hardware is presently available. No physical board inventory was performed in this task. The root session's read-only device discovery on 25 September found no ADB device; a paired iPad16,10 reported iPadOS 26.6.2/build 23G90, but app inspection was blocked because the device had not been unlocked recently. Host discovery found no `/dev/cu.usbmodem*`, `/dev/cu.usbserial*`, `/dev/cu.SLAB*` or `/dev/cu.wch*` endpoint; that does not exclude separately powered BLE boards. Pairing is not an app-install or HIL pass. + +| Resource | Current execution state | Required owner action before a physical batch | +|---|---|---| +| Five exact boards, revisions/memory/module markings | Historical profiles recorded; current possession, condition and firmware identity unverified | Physical operator assigned at Planning checks and privately records each exact unit | +| Android tablet / Play access | No device in current ADB discovery; eligible account/enrollment and installed build unverified | Device/channel owner supplies an eligible unlocked tablet and records installation evidence; no enrollment or account access assumed | +| iPad / TestFlight access | Paired device found; locked app query blocked | Device/channel owner unlocks and confirms actual TestFlight install/build; pairing alone is insufficient | +| USB data cables, reset adapters, power isolation, known backups | Not inventoried; serial endpoint discovery alone would not prove exact-board identity | Physical operator checks wiring, reliable power/data path and recoverability before operations | +| Disposable workspace media / spare boards | Availability and erase authority unconfirmed | Owner supplies an independently verified backup and explicitly disposable target for each required acquisition | +| Physical operator / independent reviewer | No named assignment or confirmed availability | Assign actual people/time; an assistant-authored recipe does not supply physical sign-off | +| Second operator for PYB-009.2 | Unassigned | Optional separately costed reproduction; no existing-profile Ready badge or partner claim | + +All ten rows below are **not run for C1-S1**. An unchanged historical pass must retain its date/artifact instead of becoming a current pass. Platform rows reference one exact firmware digest per selected profile; they do not require duplicating the host OI-1 workload as though it were a tablet test. + +| Row | Exact provisioning profile | Platform | Required profile distinction | Current blocker | +|---|---|---|---|---| +| Q01 | `esp32-4mb` | iPadOS | Classic ESP32, 4 MiB flash; PBLE chip `esp32` | Exact board/candidate/operator unassigned; app query locked | +| Q02 | `esp32-4mb` | Android | Same declared firmware bytes as Q01 | Exact board/candidate/operator and tablet/install evidence unavailable | +| Q03 | `esp32-s3-n16r8` | iPadOS | Lean S3, 16 MiB flash / 8 MiB Octal PSRAM; PBLE chip `esp32-s3` | Exact board/candidate/operator unassigned; app query locked | +| Q04 | `esp32-s3-n16r8` | Android | Same declared firmware bytes as Q03; no bundled TFT-runtime claim | Exact board/candidate/operator and tablet/install evidence unavailable | +| Q05 | `waveshare-esp32-s3-lcd-147b` | iPadOS | Exact B board, 16 MiB / 8 MiB; distinct image despite PBLE chip `esp32-s3` | Exact board/candidate/operator unassigned; app query locked | +| Q06 | `waveshare-esp32-s3-lcd-147b` | Android | Same declared firmware bytes as Q05; exact-board display/splash gates separate | Exact board/candidate/operator and tablet/install evidence unavailable | +| Q07 | `esp32-c3-4mb` | iPadOS | C3 revision v0.3 or newer, 4 MiB flash; C3-G0…C3-G6 required for fresh firmware qualification | Exact board/candidate/operator unassigned; app query locked | +| Q08 | `esp32-c3-4mb` | Android | Same declared firmware bytes as Q07; separate C3-G5 real app run | Exact board/candidate/operator and tablet/install evidence unavailable | +| Q09 | `rpi-pico2-w` | iPadOS | Exact Pico 2 W; bound UF2/raw BIN; RP2 resource facts and GP2 | Exact board/candidate/operator unassigned; app query locked | +| Q10 | `rpi-pico2-w` | Android | Same declared firmware bytes as Q09; separate physical Android workflow | Exact board/candidate/operator and tablet/install evidence unavailable | + +Every selected row covers the applicable edit/save/run/stdout/STOP/file-readback/disconnect/reconnect workflow plus the increment's affected scenarios. C3-G5 expressly requires both tight-loop and print-flood STOP through the real UI, and GP2 includes both physical platforms. Use [C3 gates](../../../specifications/firmware/ports/esp32-c3-4mb.md), [Pico gates](../../../specifications/firmware/ports/rpi-pico2-w.md), and [Waveshare exact-board requirements](../../../specifications/hardware.md#12-waveshare-esp32-s3-lcd-147b-qualification-contract) without replacing them with this summary. + +## 4. Frozen repetitions and thresholds to preserve + +| Gate | Required workload / limit | Interpretation | +|---|---|---| +| OI-1 reset | **10** scanner-before-reset samples per profile; **1,000 ms** reset hold; **15,000 ms** discovery health timeout; all samples ≤ **3,000 ms** ESP or ≤ **7,000 ms** Pico | Exact service callback endpoint; no trimming/replacement/retry/widening. Include the separate fresh physical all-power-off advertising check | +| OI-1 transfer | **5 × 65,536-byte PUT/GET round trips** per profile; every PUT and GET ≥ **6,600 B/s** | Whole-file bytes, size, offsets and CRC; frozen integer timing formula permits at most **9,929,696,969 ns** per sample. Success-only reporting cannot omit a failure | +| OI-1 reliability/heap | Separate **20 × 16,384-byte** reliability run; **10** post-HELLO, **5** post-roundtrip and **1** post-reliability heap samples | Profile-specific static/heap floors come from the selected policy. Waveshare largest-block floor is **98,304 bytes**; Pico raw-image hard ceiling **1,572,864 bytes**, with tighter candidate-policy bounds also applicable | +| Link facts | ATT MTU **247**, chunk **229**; ESP PUT window **8**, Pico **4** | Unknown backend MTU stays unknown; require agreement when exposed. Preserve ESP epoch/DLE/PHY settlement and disconnect facts. Pico BTstack refill horizon is **103 ms**, not the ESP Notify wait budget | +| v0.6.1 hardening | Seven ordered scenarios: transport/session, fragment hardening, RUN isolation, resource stability, stdin isolation, configuration durability, filesystem hardening; resource stability exactly **50 sequential RUNs** | One fresh candidate-bound result per exact profile; not another arbitrary endurance experiment | +| Workspace first boot | Two separately measured receipts per profile: erased-media creation and nonblank incompatible-media refusal | Complete private pre/post readback, actual sealed boot observation, fresh advertisement watch and candidate binding; a source inference or manually entered summary is not a receipt | +| RUN/STOP diagnostic and C3-G2 | Busy loop and print flood; exactly one matching `RSP OK` before idle, terminal idle in **less than 500 ms**, followed by bounded same-link recovery | A tablet UI observation without the required timing evidence does not prove the protocol deadline | +| Real-app release records | **2 physical platforms × 5 exact profiles = 10 app rows** in V5; six separately observed operator checks plus derived OI-1 and v0.6.1 hardening checks | The six are provisioning install, provisioning recovery, advertising/INFO/HELLO, PBLE workflow, safe boot/reconnect, and filesystem resume/reliability | +| App performance/recovery | NFR-PERF-4 first connect **<10 s** and saved-board connect **<5 s** are SHOULD targets; console ceilings need measured/frozen HIL bounds | Do not turn unknown timing into a pass, invent new millisecond gates, or infer automatic reconnect/resume from firmware resumability | + +Across five fresh firmware profiles the fixed minimum OI-1 work therefore includes 50 reset samples, 25 PUT/GET pairs, 100 reliability files and 5 physical power cycles; v0.6.1 adds 250 sequential RUNs and 10 workspace acquisitions. Those totals exclude setup, retries as new retained attempts, manual provisioning/recovery, profile-specific observations and ten tablet rows. No additional 100-operation or 30-recovery floor is introduced. + +## 5. Operator procedure for the next authorized run + +| Step | Action | Expected output / stop condition | +|---|---|---| +| 1 — Bind scope | Choose one exact profile and explicit app/candidate pairing; select required gates and nominal/interference conditions separately. Record operator, suite revision, device/OS and artifact provenance | A populated setup record, no inferred store/source hash. Missing exact unit or candidate blocks the run | +| 2 — Prepare safe bench | Use a controlled board with no actuators or external hazardous loads; preserve existing user files/autorun/labels, verify backup and power/reset wiring; close competing BLE clients and serial monitors | Confirm test-owned scratch namespace is unused. Do not delete a colliding owner's file to make a bench pass | +| 3 — Check host prerequisites | Use the pinned app/build tools where applicable; run focused harness/conformance checks; inspect full CI requirements for the selected change | Exit-zero host logs permit proceeding to physical execution only; failures stay visible | +| 4 — Identify over BLE | Use service-filtered discovery, select the physically verified exact unit, run identity smoke with explicit chip and agent version | HELLO/DEVICE_INFO/INFO agree; no chip-family inference of board profile or flash size. Keep scan identities private | +| 5 — Core physical app run | On each platform separately, record actual install/build; connect and inspect identity; create/edit/save a harmless named test file; run and verify output; STOP tight-loop/print-flood cases under the applicable gate; upload/read back exact bytes; disconnect/reconnect and verify workspace | Retain actual outcomes and timing evidence. Permission denial, wrong selection, timeout and stale session behavior are findings, not success | +| 6 — Recovery regression | For the current app, distinguish navigation/disconnect from OS process termination. Preserve user content before termination. For the later recovery candidate, execute the accepted write-boundary/restore/discard/failure/board-isolation scenarios from the [recovery design](03_Recovery_Design_and_Sizing.md) | Current source does not yet guarantee durable draft recovery. S2 supplies the executable recovery suite; this recipe does not mark proposed behavior passed | +| 7 — Firmware-specific qualification if selected | Follow the maintained OI-1 verify command, profile overrides, private workspace acquisitions, seven-scenario bench and profile-specific gates against one protected candidate | Fresh, immutable, exclusive-created results. Destructive acquisition requires a separately authorized disposable target, not routine app qualification | +| 8 — Recover a failed attempt | Stop running code where the link remains serviceable; disconnect/reconnect explicitly. If needed use documented safe boot/power reset, then the exact board's ESP bootloader or Pico BOOTSEL recovery procedure with a verified image | Preserve the first failed log. Reset is not evidence of recovery unless observed. Never erase/reflash user storage as an automatic troubleshooting step | +| 9 — Close the record | Confirm only test-owned files are cleaned up and original reviewed configuration restored; retain every attempt with result and duration; redact logs before public use | Failed/unrun rows remain explicit; no handwritten passing HIL map. Re-run affected steps after a recipe correction before an independent reproduction claim | + +The following host commands reproduce the focused checks run during this task: + +```sh +python3 tests/firmware_tests/host/conformance/test_hil_wire.py +python3 tests/firmware_tests/host/test_target_hil_benches.py +python3 tests/firmware_tests/host/test_oi1_profile_bench.py +python3 tests/firmware_tests/host/test_oi1_rp2_profile_bench.py +``` + +Physical diagnostics below are **instructions only, not executed evidence**. Use a private shell session, fill in the reviewed values, and run from the repository root. Scanning exposes local identifiers; avoid recording them in public terminal transcripts. Lifecycle/roundtrip benches write test files: check that `/target_hil_run.py` and `/bench_roundtrip.bin` are not owner data before use; inspect the current tool's fixture names before execution if its revision changes. + +```sh +python3 tests/firmware_tests/hil/target_smoke.py --scan + +# Set these privately from the reviewed exact unit and selected artifact. +PYBLE_HIL_ADDRESS='' +PYBLE_HIL_CHIP='esp32-c3' +PYBLE_HIL_AGENT='0.6.1' + +python3 tests/firmware_tests/hil/target_smoke.py \ + --address "$PYBLE_HIL_ADDRESS" \ + --expect-chip "$PYBLE_HIL_CHIP" --expect-agent "$PYBLE_HIL_AGENT" +python3 tests/firmware_tests/hil/target_run_stop.py \ + --address "$PYBLE_HIL_ADDRESS" \ + --expect-chip "$PYBLE_HIL_CHIP" --expect-agent "$PYBLE_HIL_AGENT" +python3 tests/firmware_tests/hil/file_roundtrip_bench.py \ + --address "$PYBLE_HIL_ADDRESS" --expect-chip "$PYBLE_HIL_CHIP" --size 12190 +``` + +For release measurements, use the complete **verify-mode** example and exact profile substitutions in the HIL guide; these diagnostic commands do not replace it. Do not run `--allow-disposable-erase`, `create-result --passed-gate`, completion assembly or finalization to fill an evidence gap. The first changes physical storage; the remaining commands validate/encode already acquired evidence. + +## 6. Initial cost model and Sprint implications + +These are bottom-up **planning ranges in operator hours**, not measured durations or commitments. They assume one known candidate, functioning exact hardware, preinstalled tools and no product defects. Tool download/build/store waiting time, obtaining hardware/access, participant work and substantive defect repair are additional. Multiple people can reduce elapsed time but do not make their effort free. Retain actual preparation, active execution, passive wait and rerun times separately in the first representative pair. + +| Work package | Quantity × allowance | Initial effort range | +|---|---|---:| +| Shared app/candidate provenance, device setup, prerequisites | One setup at 2–4 h | 2–4 h | +| Ten physical app core/recovery rows | 10 × 0.75–1.5 h | 7.5–15 h | +| Two representative cross-version/affected regression sessions | 2 × 1–2 h; exact pairings chosen at Planning | 2–4 h | +| Evidence review, redaction and unresolved-row reconciliation | One pass at 2–3 h | 2–3 h | +| **App qualification subtotal** | Baseline coverage before defects/repetition | **13.5–26 h** | +| Additional firmware install/recovery and two sacrificial-media acquisitions per profile | 5 × 1.5–3 h | 7.5–15 h | +| Additional OI-1 + hardening execution per profile | 5 × 1–2 h including physical intervention/log handling | 5–10 h | +| Additional profile-specific observations, release evidence and operator review | C3/Pico/Waveshare plus shared completion | 4–8 h | +| **Full fresh firmware qualification subtotal** | App subtotal plus additional firmware work; excludes clean builds/license audit and defect repair | **30–59 h** | + +The app subtotal includes ten total rows: the S2 representative iPad/Android runs can contribute two of them if artifacts, scope and applicable acceptance remain valid. Do not double-count those rows or reuse them after a relevant change without impact review. Cross-version session estimates are placeholders; a broader supported-baseline claim increases the count. + +| Planned allowance in [Sprint Backlogs](../06_Sprint_Backlogs.md) | Assessment / required planning action | +|---|---| +| S1-T12 2 h inventory; S2-T01 2 h scoped recipe | Documentation allowances; not physical qualification. S2 must bind executable recovery cases and the chosen candidate before implementation is declared Done | +| S2-T08/T09 4 h representative physical runs | Plausible initial checkpoint if access exists. Record actual setup/run cost and invalidating changes before projecting the other rows | +| S3-T02–T04 12 h execution | May cover a portion of the 7.5–15 h app-row estimate after setup; cannot promise all five firmware profiles with sacrificial-media work | +| S5-T02–T04 11 h remaining/cross-version work | Together with S3 yields 23 execution hours, plus separately planned setup/review. App scope may fit without major failure; full fresh firmware qualification is not supported by that assumption | +| 20 h cycle headroom and 84 h event/support/additional-qualification reserve | Not an automatic qualification allocation. Replan explicitly against actual event/support demand; do not consume reserve twice or shorten normative counts | +| PYB-009.2 second-operator rehearsal | Initially allow a separately confirmed 2–4 h for one already provisioned profile/core/recovery recipe, plus repair/rerun time; not included above and not a complete release/badge gate | + +Before S3/S5 selection, Developers must replace these ranges with the first measured batch and named access, choose app-only versus fresh-firmware claim, assign exact Q rows to batches, and reforecast anything exceeding capacity. A failed required row blocks the relevant claim; the Sprint calendar never changes its pass threshold. + +## 7. Checks actually performed and remaining work + +The following focused suites ran on macOS 26.6.2 arm64, Python 3.13.5, at source `d039db09779ed45124874721f88b2e0931664743`. All use host fixtures/fakes; they open no physical BLE or serial connection. + +| Suite | Actual result | Reported test runtime | +|---|---:|---:| +| `host/conformance/test_hil_wire.py` | 6 passed | 0.001 s | +| `host/test_target_hil_benches.py` | 4 passed | 0.057 s | +| `host/test_oi1_profile_bench.py` | 85 passed | 2.259 s | +| `host/test_oi1_rp2_profile_bench.py` | 15 passed | 0.029 s | +| **Focused total** | **110 passed** | Host runtime only; not a matrix estimate | + +The full firmware suite, app suite, cross-builds and hardware tests were not run by this task. A separate `test_v061_hardening_release_gate.py` invocation was stopped during this bounded inspection before a result was collected; it supplies no pass. The [execution record](00_Execution_Record.md) records integrated document/source checks separately. + +| Remaining action | Owner assignment / next checkpoint | +|---|---| +| Confirm exact boards, safe fixtures, backups, candidate and physical operator | Product Owner/Developers name the actual operator at Planning; until then Q01–Q10 remain not run | +| Unlock iPad; provide eligible Android tablet and current install evidence | Device/channel owner; reconcile with the channel ledger before any physical app batch | +| Bind executable recovery cases and revise estimate from the accepted contract | App + QA during C1-S2-T01; proposed current-draft behavior has no physical result yet | +| Time the first representative pair; allocate remaining rows and reruns | QA/Developers before C1-S3 scope selection | +| Independently review and reproduce the recipe if PYB-009.2 is selected | Named second operator with separately allocated time; assistance remains visible and triggers an affected-step rerun | diff --git a/docs/specifications/firmware/ports/esp32-c3-4mb.md b/docs/specifications/firmware/ports/esp32-c3-4mb.md index 4afff695..cd4f4989 100644 --- a/docs/specifications/firmware/ports/esp32-c3-4mb.md +++ b/docs/specifications/firmware/ports/esp32-c3-4mb.md @@ -1,6 +1,15 @@ # PyBLE — `esp32-c3-4mb` engineering qualification Status: **C3-G0–C3-G7 FROZEN (`[docs]` 2026-08-12); all results PENDING**. + +**Status clarification — 25 September 2026:** the line above records the +original engineering freeze. v0.6.0 subsequently became the qualified +five-profile baseline. v0.6.1 is publicly distributed under the dated +[owner-confirmed publication](../../../testing/firmware-v0.6.1-publication-2026-09-11.md), +whose incomplete automated HIL records remain unchanged. These normative gates +still govern a fresh automated-qualified C3/candidate claim; this note adds no +new passing result and does not rewrite the historical freeze. + This is the derived engineering contract for the existing ESP32-family native agent on one matching physical reference. It implements [ADR-0032](../../../decisions/0032-qualify-generic-esp32-c3-4mb-on-reference-hardware.md) diff --git a/docs/specifications/firmware/ports/rpi-pico2-w.md b/docs/specifications/firmware/ports/rpi-pico2-w.md index 682f4a61..e294a66c 100644 --- a/docs/specifications/firmware/ports/rpi-pico2-w.md +++ b/docs/specifications/firmware/ports/rpi-pico2-w.md @@ -2,6 +2,14 @@ Status: **P1–P9 FROZEN (v0.6.1 hardening amended 2026-09-02)**; P10 gates and P11 open items are living, and every new v0.6.1 result remains **PENDING**. Derived per [firmware/specs.md §1.1](../specs.md); [ADR-0030](../../../decisions/0030-pico2w-portable-python-agent-first.md) records the portable-Python-first deviation, while [ADR-0033](../../../decisions/0033-qualify-v060-as-five-profile-heterogeneous-release.md) defines only the historical heterogeneous v0.6.0 release admission. Cited upstream facts refer to the pinned MicroPython v1.28.0 submodule. +**Publication clarification — 25 September 2026:** v0.6.1 is publicly available +under the dated [owner-confirmed publication](../../../testing/firmware-v0.6.1-publication-2026-09-11.md). +Its incomplete automated qualification records remain unchanged. References +below to pending qualification or a qualified selector concern standard +automated-qualified admission, not the existence of that owner-confirmed +distribution. v0.6.0 remains the historical qualified baseline; this note +supplies no new GP2 or physical result and changes no gate. + ## P1. Identity & caps (FROZEN) - `chip` token: **`rpi-pico2-w`** (protocol.md §7 open identifier; ADR-0021 — no protocol amendment needed, additive under §9). diff --git a/docs/specifications/hardware.md b/docs/specifications/hardware.md index e58324b0..e97818c3 100644 --- a/docs/specifications/hardware.md +++ b/docs/specifications/hardware.md @@ -58,9 +58,13 @@ different flash size or Quad/no PSRAM, are not covered by Matching the N16R8 memory tuple also does not imply that an onboard display or other peripheral exists. The Waveshare row is separate even though ESP Web Tools reports the same family for both S3 images and cannot distinguish them. -All five qualified v0.6.0 profiles are active. Their source-selected v0.6.1 -successors remain unavailable while fresh exact-byte qualification is pending; -owning or building a target is not a substitute for candidate-bound HIL. The +All five qualified v0.6.0 profiles remain the historical automated-qualified +baseline. As recorded in the +[11 September 2026 publication report](../testing/firmware-v0.6.1-publication-2026-09-11.md), +all five v0.6.1 profiles are publicly available through the explicitly +owner-confirmed release mode. Their incomplete automated HIL evidence remains +unchanged; availability does not establish a fresh automated-qualified pass. +Owning or building a target is not a substitute for candidate-bound HIL. The ESP32-C3-MINI-1-N4 v0.4/4 MiB/no-PSRAM module remains the selected physical engineering reference for that generic profile. Its gates passed for v0.6.0 and must be rerun for v0.6.1 under @@ -76,7 +80,9 @@ not qualify v0.6.0. The atomic five-profile v0.6.0 release selected by ADR-0033 generated and passed its schema-3 resource policy and V5 HIL evidence for every row. Pre-split or earlier-candidate evidence did not qualify it and cannot qualify v0.6.1. C3-G0…C3-G6 and Pico GP2 remain mandatory for the fresh v0.6.1 -candidate; either pending or failed profile blocks that entire increment. +candidate; either pending or failed profile blocks standard automated-qualified +admission of that entire increment. The dated owner-confirmed publication is +not a waiver for a future candidate or a PyBLE Ready qualification claim. These are **provisioning image profiles**, not board-routing profiles. They exist solely to keep destructive flash layouts honest. They do not define GPIO diff --git a/tests/firmware_tests/hil/README.md b/tests/firmware_tests/hil/README.md index 4e191add..7f4c12b9 100644 --- a/tests/firmware_tests/hil/README.md +++ b/tests/firmware_tests/hil/README.md @@ -8,6 +8,13 @@ firmware-test-author**; none of this ships in the firmware image. A milestone gate is green **only on a real-hardware HIL demo**, not on merged code (PRD §1B.7). These drivers are that demo, made repeatable. +The [C1-S1 operator inventory](../../../docs/developments/2026-q4-reliable-workflow/c1-s1/04_Validation_Inventory_and_Operator_Recipe.md) +maps these tools to current app/profile rows, initial cost and missing access. +The [v0.6.1 owner-confirmed publication](../../../docs/testing/firmware-v0.6.1-publication-2026-09-11.md) +is a separate dated distribution outcome; its incomplete automated HIL remains +unchanged. Release qualification requirements below still govern a fresh +automated-qualified claim. + Every valid outbound `CMD`, including no-response `FILE_PUT_DATA`, uses a request ID in 1–255. Transfer data and controls share a wrapping allocator; each Go-Back-N resend obtains another valid ID without waiting for a data diff --git a/tests/firmware_tests/host/conformance/README.md b/tests/firmware_tests/host/conformance/README.md index f1398986..98d59df2 100644 --- a/tests/firmware_tests/host/conformance/README.md +++ b/tests/firmware_tests/host/conformance/README.md @@ -22,6 +22,10 @@ made that every old idea was copied into `corpus.json`. Host success is not physical qualification. v0.6.1 still requires fresh exact-byte HIL on all five profiles, including the iPadOS and Android rows, -before release admission or publication. +before standard automated-qualified release admission or publication. Its +separate [owner-confirmed publication](../../../../docs/testing/firmware-v0.6.1-publication-2026-09-11.md) +preserves incomplete automated records and supplies no substitute pass. +The [C1-S1 operator inventory](../../../../docs/developments/2026-q4-reliable-workflow/c1-s1/04_Validation_Inventory_and_Operator_Recipe.md) +maps host evidence to the physical work and access still required. From cf3b26238d6f157243f2ce7f6db69b801e8f764b Mon Sep 17 00:00:00 2001 From: Viwat Vchirawongkwin Date: Fri, 25 Sep 2026 17:21:43 +0700 Subject: [PATCH 5/9] [docs] record C1-S1 execution and reconcile delivery forecasts Record live channel evidence and explicit device/pilot blockers, prepare the residual TestFlight metadata correction, and update strategy, Scrum views, architecture, roadmap and discovery links. Preserve four completed repository tasks and eight blocked tasks. Carry forward the reviewed recovery contract and its larger estimate without claiming runtime persistence, installations, participant results or release admission. Signed-off-by: Viwat Vchirawongkwin --- CHANGELOG.md | 16 ++- README.md | 2 + docs/README.md | 25 +++-- docs/ROADMAP.md | 10 ++ docs/decisions/0011-connection-gated-shell.md | 10 ++ .../01_Overview_and_Scrum_Framework.md | 17 ++-- .../02_Product_Roadmap.md | 14 +-- .../03_Milestones.md | 8 +- .../04_Sprint_Plan.md | 21 +++- .../05_Product_Backlog_and_Stories.md | 35 +++++-- .../06_Sprint_Backlogs.md | 30 +++--- .../c1-s1/00_Execution_Record.md | 98 +++++++++++++++++++ .../c1-s1/01_Channel_and_Artifact_Ledger.md | 96 ++++++++++++++++++ .../05_TestFlight_Metadata_Correction.md | 41 ++++++++ ...E_Implementation_Plan_and_Strategy_v1.0.md | 46 ++++++--- .../firmware-v0.6.1-v0.7.0-roadmap.md | 21 ++-- docs/specifications/app.md | 14 ++- docs/specifications/architecture.md | 2 +- 18 files changed, 430 insertions(+), 76 deletions(-) create mode 100644 docs/developments/2026-q4-reliable-workflow/c1-s1/00_Execution_Record.md create mode 100644 docs/developments/2026-q4-reliable-workflow/c1-s1/01_Channel_and_Artifact_Ledger.md create mode 100644 docs/developments/2026-q4-reliable-workflow/c1-s1/05_TestFlight_Metadata_Correction.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 0429fc6e..a0fd42ef 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,8 +6,9 @@ are released independently from this monorepo. ## Unreleased These app, website, and repository-source changes do not designate a new app -or firmware release. The qualified firmware release remains v0.6.0, built from -its annotated tag rather than from the newer branch tip. +or firmware release. Firmware v0.6.1 is published on the owner's confirmation; +incomplete automated evidence remains pending. The qualified v0.6.0 release +remains a separate historical baseline built from its annotated tag. The current compatible app feature set now targets `0.2.0`; build `5` was handed off through Transporter for TestFlight. This candidate identity improves @@ -81,6 +82,17 @@ and submission packet do not claim Play submission, approval, or rollout. Vitest 4.1.12, with patched Sharp, Undici, source-map-js and supporting dependencies. Refreshed the reviewed license notices and dependency regression assertions while retaining the high/critical audit gate. +- Added the reviewed Cycle 1 roadmap, milestones, Scrum working agreement, + stories and Sprint Backlogs, plus C1-S1 execution evidence and operational + pilot/validation procedures. Physical installation and participant work + remain blocked; no pilot results or new release are claimed. +- Specified bounded Drift current-text recovery, local restore/discard, + failure handling and document/session guards in ADR-0048 and the App + contracts. Implementation remains pending; sizing requires revising the + original S2 forecast. +- Verified live Android open-testing wording and prepared correction of the + older public TestFlight description. Store-installed build identities remain + unverified and the TestFlight metadata change remains pending. - Prepared Google Play open-testing listing text, reviewer hardware setup, tester instructions, data-use assessment, and reproducible store artwork with authentic screenshot provenance. Store availability remains a separate diff --git a/README.md b/README.md index 7fc6ed33..6edd1fb7 100644 --- a/README.md +++ b/README.md @@ -311,6 +311,8 @@ publish new firmware or replace the live site. - [App contract](docs/specifications/app.md) - [Hardware and compatibility](docs/specifications/hardware.md) - [Public roadmap](docs/ROADMAP.md) +- [Cycle 1 delivery plan](docs/developments/2026-q4-reliable-workflow/01_Overview_and_Scrum_Framework.md) +- [C1-S1 execution and remaining evidence](docs/developments/2026-q4-reliable-workflow/c1-s1/00_Execution_Record.md) - [Architecture decisions](docs/decisions/README.md) - [Validation evidence index](docs/validation/README.md) - [Security policy](SECURITY.md) diff --git a/docs/README.md b/docs/README.md index ecfd75e9..061eb8ae 100644 --- a/docs/README.md +++ b/docs/README.md @@ -16,13 +16,22 @@ maintainer guidance beside the source they govern. ## Proposed release plans - [Firmware v0.6.1 and v0.7.0 roadmap](planning/firmware-v0.6.1-v0.7.0-roadmap.md) - — v0.6.1 hardening is approved for implementation; the Reliable Projects - v0.7.0 scope remains proposed + — v0.6.1 is published on owner confirmation; incomplete automated evidence + remains pending, and Reliable Projects v0.7.0 remains proposed +- [Implementation strategy](planning/PyBLE_Implementation_Plan_and_Strategy_v1.0.md) + — current outcomes, evidence gates and conditional expansion +- [Cycle 1 Scrum delivery package](developments/2026-q4-reliable-workflow/01_Overview_and_Scrum_Framework.md) + — roadmap, milestones, stories and capacity forecasts +- [C1-S1 execution record](developments/2026-q4-reliable-workflow/c1-s1/00_Execution_Record.md) + — channel evidence, pilot kit, recovery contract/sizing and validation recipe; + physical installation and participant work remain blocked ## Detailed specifications - [`specifications/App/`](specifications/App/) — app requirements, test design, and the Signal visual system +- [Bounded current-text recovery contract](specifications/App/current-draft-recovery.md) + — specified in C1-S1; implementation and acceptance evidence remain pending - [`specifications/firmware/`](specifications/firmware/) — firmware requirements, test design, browser flashing, release integrity, and HIL gates @@ -64,7 +73,11 @@ bundled offline examples required by its own product contracts. plan](testing/testflight/0.2.0-build-5.md) - [PyBLE 0.1.0 (4) TestFlight description and test plan](testing/testflight/0.1.0-build-4.md) - -Internal sprint notes and automated-agent orchestration are intentionally kept -outside the public source repository. Public work is planned through the -roadmap and GitHub issues. +- [Current channel and artifact ledger](developments/2026-q4-reliable-workflow/c1-s1/01_Channel_and_Artifact_Ledger.md) +- [TestFlight metadata correction packet](developments/2026-q4-reliable-workflow/c1-s1/05_TestFlight_Metadata_Correction.md) + — prepared replacement for the stale public description; store update pending + +Reviewed delivery plans and redacted execution evidence live under +`developments/`. Raw observations, contact/consent records, device identifiers, +local worktree state and automated-agent orchestration remain outside Git. +Planning IDs are not GitHub issue numbers; link actual issues when created. diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index f4a79c72..bebd0f95 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -31,6 +31,16 @@ v0.7.0 remains non-normative and requires separate maintainer approval. ## Near term +- Complete the [C1-S1 remaining evidence](developments/2026-q4-reliable-workflow/c1-s1/00_Execution_Record.md): + physical store installations, confirmed pilot ownership/setup and five real + baseline observations. The channel ledger, pilot kit, recovery design and + validation inventory are prepared; this does not complete the Sprint. +- Implement the [bounded current-text recovery contract](specifications/App/current-draft-recovery.md) + after replanning against its 45–72 hour working estimate for engineering, + recipe, representative platform checks and follow-up. Current drafts remain + volatile; full A-24 and Blocks persistence remain separate scope. +- Correct the [stale public TestFlight description](developments/2026-q4-reliable-workflow/c1-s1/05_TestFlight_Metadata_Correction.md) + through the distribution owner; replacement copy is prepared, not published. - Continue the app 0.2.0 beta train; source is currently `0.2.0+8`. The [Android publication review](testing/website/android-open-testing-2026-09-25.md) records live open-testing availability. The diff --git a/docs/decisions/0011-connection-gated-shell.md b/docs/decisions/0011-connection-gated-shell.md index eb01042a..9c9f1405 100644 --- a/docs/decisions/0011-connection-gated-shell.md +++ b/docs/decisions/0011-connection-gated-shell.md @@ -28,3 +28,13 @@ The Signal landscape shell renders a fixed three-pane IDE frame — **Files side - The change is confined to the shell + providers; the `Connection` seam (D1/D2), the import boundary (no UI package imports `lib/ble`, CON-8), Riverpod (ADR-0007), and every §1A.3 rejection are unchanged. Unchanged rejection list, seam, and layering as in [ADR-0009](0009-runtime-connection-manager.md)/[ADR-0010](0010-working-loop-in-memory-document.md). + +## Follow-up — 25 September 2026 + +[ADR-0048](0048-bounded-current-text-draft-recovery.md) and the +[bounded recovery contract](../specifications/App/current-draft-recovery.md) +specify a narrow successor exception: a local recovery preview/Restore/Discard +panel must be reachable without a board, permission prompt or network access. +The normal IDE remains connection-gated; this is not a full offline IDE or an +authorization to restore board-write authority. Implementation is pending, so +the current shell behavior above remains the recorded runtime baseline. diff --git a/docs/developments/2026-q4-reliable-workflow/01_Overview_and_Scrum_Framework.md b/docs/developments/2026-q4-reliable-workflow/01_Overview_and_Scrum_Framework.md index bef0dccf..7ee16d95 100644 --- a/docs/developments/2026-q4-reliable-workflow/01_Overview_and_Scrum_Framework.md +++ b/docs/developments/2026-q4-reliable-workflow/01_Overview_and_Scrum_Framework.md @@ -9,14 +9,14 @@ |---|---| | Package | PyBLE 2026 Q4 reliable workflow, Cycle 1 (`C1`) | | Prepared | 25 September 2026; Asia/Bangkok | -| Strategy | [Implementation Plan, revision 1.2](../../planning/PyBLE_Implementation_Plan_and_Strategy_v1.0.md) | +| Strategy | [Implementation Plan, revision 1.3](../../planning/PyBLE_Implementation_Plan_and_Strategy_v1.0.md) | | Repository baseline | `23ed764b0ef88dce9720c66fbd1c0655268860cf` | | Proposed cycle | 28 September–20 December 2026; six two-week Sprints | -| Status | Proposed delivery package; no Sprint Planning, estimates, named assignments, implementation approval, or new physical results are implied | +| Status | C1-S1 execution initiated on 25 September; repository deliverables prepared and physical/pilot work blocked. Later Sprints require replanning against new sizing; no staffed-team ceremony is inferred | | Primary audience | Tablet-owning makers, provisionally; confirm one reachable cohort before observation | | Authoritative contracts | [Contributor rules](../../../AGENTS.md), [App specification](../../specifications/App/specs.md), [App TDD](../../specifications/App/TDD.md), [PBLE/1](../../specifications/protocol.md), and applicable firmware/release specifications | -This package derives execution views from the strategy. It does not replace normative specifications, expand hardware claims, create GitHub issues, or authorize store/website publication. The strategy file is currently a local document; include it with this package when proposing the documentation for version control. +This package derives execution views from the strategy. It does not replace normative specifications, expand hardware claims, create GitHub issues, or authorize store/website publication. The strategy and original package were recorded together in planning baseline `d039db0`. The [C1-S1 execution record](c1-s1/00_Execution_Record.md) owns actual results and blockers. ## Navigation and ownership of information @@ -27,11 +27,12 @@ This package derives execution views from the strategy. It does not replace norm | [03 — Milestones](03_Milestones.md) | Evidence-based decisions and admission criteria | New evidence or a milestone decision | | [04 — Sprint plan](04_Sprint_Plan.md) | Sprint Goal forecasts, calendar, and capacity | Sprint Planning or Sprint Review | | [05 — Product backlog and stories](05_Product_Backlog_and_Stories.md) | Ordered work, parent/child identities, acceptance criteria, and source traceability | Refinement or changed user evidence | -| [06 — Sprint backlogs](06_Sprint_Backlogs.md) | Candidate tasks, local effort allowances, dependencies, and execution status | Developers select/adapt work during a Sprint | +| [06 — Sprint backlogs](06_Sprint_Backlogs.md) | Task allowances, dependencies, C1-S1 execution status and later forecasts requiring replanning | Developers select/adapt work during a Sprint | +| [C1-S1 — Execution and evidence](c1-s1/00_Execution_Record.md) | Actual channel checks, pilot kit, recovery design/sizing and validation inventory | New evidence, source review or a resolved blocker | ```mermaid flowchart LR - Strategy["Strategy revision 1.2"] --> Goal["One Product Goal"] + Strategy["Strategy revision 1.3"] --> Goal["One Product Goal"] Goal --> Roadmap["Outcome roadmap and milestones"] Roadmap --> Product["Ordered Product Backlog"] Product --> Planning["Sprint Planning"] @@ -122,10 +123,10 @@ Unfinished items return to the Product Backlog for reordering and replanning. Do | Convention | Rule | |---|---| | `PYB-001` … `PYB-032` | Existing strategy planning parents; not GitHub issue numbers | -| `PYB-006.1`, `PYB-006.2`, etc. | Derived child items in this package; acceptance is maintained in file 05 | +| `PYB-006.1`, `PYB-006.2`, etc. | Derived child items in this package; acceptance is maintained in file 05; new residual `PYB-002.1` records the TestFlight metadata discrepancy | | `A-24` | Existing broader persistence story; a bounded child does not complete all of it | | `C1-S1` … `C1-S6` | This cycle's Sprints; distinct from historical App TDD Sprint labels | -| `C1-S1-T01`, etc. | Proposed task rows; not new public contracts | +| `C1-S1-T01`, etc. | Task identities with recorded early C1-S1 outcomes; later task rows remain forecasts, not new public contracts | | `M-01`, etc.; `SG0` … `SG6` | Delivery milestones versus strategy gates; neither replaces CI G0/G1 or C3 firmware gates | | Item/task status | Proposed → Selected at Planning → In progress → Review → Done; Blocked records a reason/owner; later forecasts remain Proposed | | Private versus public records | Contact/consent, device identifiers and raw logs remain private/ignored; publish only reviewed aggregate findings and redacted evidence | @@ -136,7 +137,7 @@ When facts or priority change, update the canonical file above and its dependent | Source | Use and precedence | |---|---| -| [Strategy revision 1.2](../../planning/PyBLE_Implementation_Plan_and_Strategy_v1.0.md) | Scope, targets, six-Sprint capacity, three outcomes, Ready program and conditional horizons | +| [Strategy revision 1.3](../../planning/PyBLE_Implementation_Plan_and_Strategy_v1.0.md) | Scope, targets, six-Sprint capacity, three outcomes, Ready program and conditional horizons | | [Public roadmap](../../ROADMAP.md), [README](../../../README.md) | Current capability and distribution baseline | | [App specification](../../specifications/App/specs.md), [App TDD](../../specifications/App/TDD.md), [ADR-0010](../../decisions/0010-working-loop-in-memory-document.md) | Persistence contract and recorded implementation deviation; consult frozen working-loop scope | | [Firmware roadmap](../../planning/firmware-v0.6.1-v0.7.0-roadmap.md), [PBLE/1](../../specifications/protocol.md) | v0.7 proposals versus frozen wire behavior; old v0.6.1 publication/#24 wording is historical | diff --git a/docs/developments/2026-q4-reliable-workflow/02_Product_Roadmap.md b/docs/developments/2026-q4-reliable-workflow/02_Product_Roadmap.md index 7af8ae80..0953d56f 100644 --- a/docs/developments/2026-q4-reliable-workflow/02_Product_Roadmap.md +++ b/docs/developments/2026-q4-reliable-workflow/02_Product_Roadmap.md @@ -5,9 +5,9 @@ | Control | Value | |---|---| -| Status | Proposed; product direction and forecasts, not approved feature or release commitments | +| Status | C1-S1 repository work recorded; physical/pilot tasks blocked. Future direction remains conditional and forecasts need revision after sizing | | Planning date | 25 September 2026; dates use Asia/Bangkok | -| Source | [Implementation strategy revision 1.2](../../planning/PyBLE_Implementation_Plan_and_Strategy_v1.0.md), particularly §§1, 6–9, 12, 14, and 19 | +| Source | [Implementation strategy revision 1.3](../../planning/PyBLE_Implementation_Plan_and_Strategy_v1.0.md), particularly §§1, 6–9, 12, 14, and 19 | | Inspected baseline | `main` at `23ed764b0ef88dce9720c66fbd1c0655268860cf` | | First cycle | C1: 28 September–20 December 2026; later horizons conditional through September 2028 | | Planning authority | Product Owner orders the Product Backlog; Developers forecast feasible work during Sprint Planning; names and capacity remain unassigned | @@ -33,11 +33,11 @@ continues to communicate direction without promising release dates. ## Completed baseline and remaining uncertainty These records are inputs to planning, not new achievements of this development -cycle. Future work below remains **Proposed** until explicitly selected. +cycle. The [C1-S1 record](c1-s1/00_Execution_Record.md) distinguishes completed design/evidence preparation from blocked installations and observations. Future work remains **Proposed** until explicitly selected. | Baseline item | Recorded state at the planning date | Consequence for this roadmap | |---|---|---| -| Android distribution and public copy | Google Play 0.2.0 open testing; README/site correction completed in PR #33 | Preserve accurate copy; PYB-002 covers only newly found discrepancies | +| Android distribution and public copy | Google Play 0.2.0 open testing; direct live-site checks on 25 September confirm the PR #33 correction | Preserve accurate copy; newly found TestFlight description discrepancy is PYB-002.1 | | App source and installed identity | Source `0.2.0+8`; source version alone does not identify an installed Play/TestFlight binary | PYB-001 records actual installed versions/builds and source mapping or explicit unknowns | | iPad distribution | External TestFlight beta is the recorded channel | Verify the selected installation path and artifact evidence; do not infer production App Store availability | | Existing workflow | PBLE/1 editing, files, run/stop, console, Blocks, tutorials, and reviewed import already exist | Reuse implementation and tests; improve measured failures rather than rebuild the workflow | @@ -78,9 +78,11 @@ for one maintainer. All rows in this table have status **Proposed**. | C1-S5; 23 Nov–6 Dec | Freeze candidate, complete applicable evidence, and assess mature follow-ups | M-04 / SG1; M-06 inputs | Release only when relevant evidence passes; qualified maintenance may also ship earlier | | C1-S6; 7–20 Dec | Verify actual channel/install state and choose one subsequent investment | M-05; M-06 / SG3 | Record pass, iterate, blocked, or inconclusive outcomes; make a dated next-stage decision | +**Sizing update:** recovery now has a 45–72 hour working estimate including supporting tasks. Its 60-hour S2–S4 allocation option would displace original matrix/activation work. The table above is the original sequencing baseline, not a validated selection; replan before using its delivery dates. The full matrix has its own [costed inventory](c1-s1/04_Validation_Inventory_and_Operator_Recipe.md). + The [Sprint Plan](04_Sprint_Plan.md) owns detailed dates and capacity. The first -Sprint Backlog is a candidate for Sprint Planning; later allocations are -forecasts. A milestone review neither replaces a Sprint Review nor supplies +Sprint Backlog now records early C1-S1 execution and its remaining blockers; +later allocations are forecasts requiring replanning. A milestone review neither replaces a Sprint Review nor supplies missing Definition of Done evidence. ```mermaid diff --git a/docs/developments/2026-q4-reliable-workflow/03_Milestones.md b/docs/developments/2026-q4-reliable-workflow/03_Milestones.md index e9e06ea7..45520f02 100644 --- a/docs/developments/2026-q4-reliable-workflow/03_Milestones.md +++ b/docs/developments/2026-q4-reliable-workflow/03_Milestones.md @@ -5,9 +5,9 @@ | Control | Value | |---|---| -| Status | All milestones Proposed; no milestone is completed by this document | +| Status | M-01/SG0 assessed Blocked on 25 September; other milestones remain Proposed and forecast windows need replanning | | Planning date | 25 September 2026; dates use Asia/Bangkok | -| Source | [Implementation strategy revision 1.2](../../planning/PyBLE_Implementation_Plan_and_Strategy_v1.0.md), especially §§4, 8–10, 14, and 19 | +| Source | [Implementation strategy revision 1.3](../../planning/PyBLE_Implementation_Plan_and_Strategy_v1.0.md), especially §§4, 8–10, 14, and 19 | | Inspected baseline | `main` at `23ed764b0ef88dce9720c66fbd1c0655268860cf` | | Related documents | [Framework](01_Overview_and_Scrum_Framework.md), [roadmap](02_Product_Roadmap.md), [Sprint Plan](04_Sprint_Plan.md), [stories](05_Product_Backlog_and_Stories.md), [Sprint Backlogs](06_Sprint_Backlogs.md) | | Meaning | Milestones describe inspectable outcomes and decision evidence; they are not additional Scrum events or promised releases | @@ -44,13 +44,15 @@ no role in this table implies committed staffing or independent review. | ID / status | Outcome and value | Forecast window / stories | Dependencies and evidence | Assessment / accountable contribution | |---|---|---|---|---| -| M-01 — Proposed | Accepted baseline and bounded cycle scope make installation, pilot, and engineering decisions reproducible | C1-S1, 28 Sep–11 Oct; PYB-001/003/004, residual 002, sizing 006/009 | Dated channel/install/source mapping or explicit owned unknowns; one primary cohort/job; safe task/consent rules; initial observations or recruitment blocker; actual capacity; persistence and physical-matrix estimates | SG0: accept a bounded scope or record gaps; Product Owner with release, pilot, and Developers | +| M-01 — Blocked (25 Sep) | Accepted baseline and bounded cycle scope make installation, pilot, and engineering decisions reproducible | C1-S1, 28 Sep–11 Oct; PYB-001/003/004, residual 002, sizing 006/009 | Dated channel/install/source mapping or explicit owned unknowns; one primary cohort/job; safe task/consent rules; initial observations or recruitment blocker; actual capacity; persistence and physical-matrix estimates | SG0: accept a bounded scope or record gaps; Product Owner with release, pilot, and Developers | | M-02 — Proposed | A usable, bounded local-draft recovery increment protects accepted user work after interruption | C1-S2–C1-S3, 12 Oct–8 Nov; selected PYB-006 scope, supporting 009/008, observed 005 only if selected | Accepted App specification/TDD and ADR-0010 change; text/Blocks scope; persistence boundary; relaunch, interrupted-write, and corrupt-state scenarios; no implicit board overwrite/run; relevant regression and physical evidence | Review against the selected story acceptance criteria and Definition of Done; Developers with a named review path | | M-03 — Proposed | Observed first-use and meaningful second-task evidence explains activation and its largest obstacle | C1-S4, 9–22 Nov; PYB-004/011 and justified 005/012 | Safe recorded pilot setup; at least 12 eligible primary-cohort task starts, all outcomes retained; successful unassisted timing; Task C attempts, prior workflow, assistance and reasons | SG2: assess provisional completion/timing targets and severe failures; pilot lead supplies evidence, Product Owner records next investment | | M-04 — Proposed | A frozen maintenance candidate is qualified for its declared release scope | Normally C1-S5, 23 Nov–6 Dec; PYB-008/009/013 and included fixes | Applicable exact-artifact matrix and normative gates pass; provenance/recovery/instructions; no unresolved release-blocking data-loss, unintended/cross-session write, or critical workflow regression within the accepted threat model | SG1: release or submission decision with required sign-off; release owner and QA/review path | | M-05 — Proposed | Users can obtain the selected qualified app build through a verified existing channel | C1-S5–C1-S6, 23 Nov–20 Dec; PYB-014 and residual 002 | M-04; distribution-owner access; separate submission, availability, installed build/provenance, and installation outcome records; current user-facing claims | Verified-channel milestone passes only for the stated evidence; store delays are recorded as blockers; release owner | | M-06 — Proposed | Useful-repeat and support evidence drives one explicit next-stage investment | C1-S6, 7–20 Dec; PYB-011 follow-up, cycle review; Ready inputs only if selected | Mature consented cohort accounting, useful Task C/return outcomes, task opportunity, prompting, missing responses, support burden, and status of candidate/channel evidence; retain blocked outcomes | SG3 assessment plus dated continue/narrow/pause-expansion decision; Product Owner with pilot and Developers | +[C1-S1 evidence](c1-s1/00_Execution_Record.md) prepares the ledger, pilot protocol, recovery contract and cost model, but does not satisfy missing human ownership, confirmed capacity, device installations or participant observations. M-01/SG0 remains blocked. M-02's S2–S3 window is the original baseline; a sized S2–S4 option now requires explicit replanning, with downstream matrix/recruitment dates reviewed together. + M-04 may occur in any Sprint once a maintenance candidate qualifies. M-03 and M-06 do not block it. M-06 can assess learning and choose a narrower next step even if release or recruitment remains blocked; the decision must say so. diff --git a/docs/developments/2026-q4-reliable-workflow/04_Sprint_Plan.md b/docs/developments/2026-q4-reliable-workflow/04_Sprint_Plan.md index 198839dd..0c36398f 100644 --- a/docs/developments/2026-q4-reliable-workflow/04_Sprint_Plan.md +++ b/docs/developments/2026-q4-reliable-workflow/04_Sprint_Plan.md @@ -5,9 +5,9 @@ | Field | Value | |---|---| -| Status | Proposed; goals and selection are confirmed at each Sprint Planning | +| Status | C1-S1 early execution recorded; original S2–S6 forecasts are not ready for selection after the new recovery/matrix estimates | | Cycle | `C1`, 28 September–20 December 2026, Asia/Bangkok | -| Basis | [Strategy revision 1.2, §8](../../planning/PyBLE_Implementation_Plan_and_Strategy_v1.0.md#8-twelve-week-implementation-schedule) | +| Basis | [Strategy revision 1.3, §8](../../planning/PyBLE_Implementation_Plan_and_Strategy_v1.0.md#8-twelve-week-implementation-schedule) | | Product Goal and quality rules | [Working agreement](01_Overview_and_Scrum_Framework.md) | | Acceptance criteria | [Product backlog and stories](05_Product_Backlog_and_Stories.md) | | Task-level proposal | [Sprint backlogs](06_Sprint_Backlogs.md) | @@ -16,7 +16,7 @@ | Planning element | Treatment | |---|---| -| `C1-S1` | Candidate selection for the next Sprint; not a committed Sprint Backlog before Planning | +| `C1-S1` | Early repository execution recorded; remaining device/pilot tasks blocked. Actual staffing and the original formal timebox still require confirmation | | `C1-S2` … `C1-S6` | Forecasts revised using preceding results, capacity and learning | | Sprint Goal | One coherent outcome confirmed by the Scrum Team at Planning | | Scope and task details | Developers select feasible items and adapt their plan with the Product Owner as learning changes scope | @@ -24,6 +24,19 @@ | Estimates | Task hours are initial capacity allowances, not measured velocity, story points, or promises | | Missing people/devices/access | Explicit blockers; do not invent availability or lower the Definition of Done | +## C1-S1 findings and required reforecast + +[Execution evidence](c1-s1/00_Execution_Record.md) records four completed repository tasks and eight blocked installation/pilot tasks. The original calendar is retained; no completed Sprint or SG0 approval is claimed. + +| New sizing input | Planning consequence | +|---|---| +| Recovery engineering 38–63h; recipe, representative physical work and one follow-up allowance bring the original two-week scope to 45–72h | Original S2 allowance is insufficient; contract and all required failure/session protections remain intact | +| [Working allocation option](c1-s1/03_Recovery_Design_and_Sizing.md): S2 26h, S3 22h, S4 12h, totaling 60h | Fits within the three 26h ceilings only by replacing original selections; includes 50h engineering, 2h recipe, 5h physical and 3h rolling follow-up | +| [App matrix](c1-s1/04_Validation_Inventory_and_Operator_Recipe.md): 13.5–26 operator h; fresh firmware qualification 30–59h excluding builds/access/repair | Select the applicable scope; do not treat app-only work as a new firmware release or count representative recovery runs twice | +| Missing human capacity, pilot owner and physical access | Confirm before selecting the revised scope; maintain rolling follow-up only for actual consenting activations | + +The remaining 18h under S2–S4's combined 78h ceiling cannot silently absorb all displaced matrix, activation and repair tasks. Reorder those tasks, review the November recruitment window, and reforecast S5/S6 if required. The tables below preserve the original allowance/calendar for comparison; they are **not** an adopted revised forecast. A tested foundation is not the completed recovery user story. All selected increments still need their applicable Definition of Done. + ## Capacity model The source assumes one primary maintainer at 20 hours/week. Confirm real availability and any contributor capacity at Planning; extra roles do not create extra hours. @@ -53,7 +66,7 @@ The reserve covers events/refinement, support, additional qualification and unce These are whole-product goals, not separate analysis, coding, testing and release departments. Every delivered increment includes its applicable design, implementation, verification and documentation. S3/S5 qualification work does not postpone tests needed to make earlier increments Done. -The full safe recovery slice may exceed the initial S2 allowance. PYB-006.1 must expose that before selection. Replan a smaller independently safe increment or later delivery; never label happy-path-only persistence Done or count the whole A-24 umbrella as complete. +The inspected safe recovery slice exceeds the original S2 allowance. PYB-006.1 now supplies the contract and estimate for replanning before selection. Replan a smaller independently safe increment or later delivery; never label happy-path-only persistence Done or count the whole A-24 umbrella as complete. ## Calendar diff --git a/docs/developments/2026-q4-reliable-workflow/05_Product_Backlog_and_Stories.md b/docs/developments/2026-q4-reliable-workflow/05_Product_Backlog_and_Stories.md index 00f27938..61324dd0 100644 --- a/docs/developments/2026-q4-reliable-workflow/05_Product_Backlog_and_Stories.md +++ b/docs/developments/2026-q4-reliable-workflow/05_Product_Backlog_and_Stories.md @@ -6,10 +6,10 @@ | Control | Value | |---|---| | Product Goal | Make the existing tablet workflow trustworthy enough for useful repeat tasks by the selected primary audience | -| Source | [Implementation strategy revision 1.2](../../planning/PyBLE_Implementation_Plan_and_Strategy_v1.0.md), reviewed 25 September 2026 | +| Source | [Implementation strategy revision 1.3](../../planning/PyBLE_Implementation_Plan_and_Strategy_v1.0.md), reviewed 25 September 2026 | | Cycle | Proposed 28 September–20 December 2026; Asia/Bangkok | | Baseline | `23ed764b0ef88dce9720c66fbd1c0655268860cf`; completed publication work is evidence, not a new commitment | -| Status | Proposed ordered Product Backlog and refinement candidates; no new story is selected, approved, implemented, or Done by this document | +| Status | C1-S1 execution recorded: PYB-001.1 and PYB-006.1 documentation scope Done; pilot/install stories blocked, PYB-009.1 partial; other work remains forecast | | Accountabilities | Product Owner orders the backlog; Developers size and select work in Sprint Planning; named people and capacity remain to be assigned | | Navigation | [Overview and Scrum](01_Overview_and_Scrum_Framework.md) · [Roadmap](02_Product_Roadmap.md) · [Milestones](03_Milestones.md) · [Sprint plan](04_Sprint_Plan.md) · [Sprint Backlogs](06_Sprint_Backlogs.md) | @@ -23,7 +23,7 @@ | Sprint identity | `C1-S1` through `C1-S6` name this cycle; App TDD references to historical S1–S7 remain unchanged | | Backlog order | The first-cycle order below is provisional; dependencies, evidence and the Product Goal guide refinement, rather than treating every P0 as simultaneous work | | Type | User stories express an end-user outcome; engineering, research, governance and release enablers identify the actual work without an artificial persona | -| State and sizing | Every new leaf is `proposed`; named owner/reviewer and estimates are TBD. Forecast sprints are planning candidates. No story points or velocity are asserted | +| State and sizing | Use the dated execution table for current states; future leaves remain proposed and named capacity is unconfirmed. The recovery/matrix estimates now require replanning. No story points or velocity are asserted | | Acceptance and Done | Story acceptance criteria supplement the shared Definition of Done; apply the source contract, repository gates and required physical evidence to the selected change | | Research outcome | A completed, reviewed observation can find that a target failed. That does not pass the corresponding milestone or turn missing participants into completed observations | | Scope change | Split an oversized item into a coherent, safe increment and replan before implementation; preserve carried requirements and record any approved deviation | @@ -32,12 +32,12 @@ | Order | Parent / source priority | Intended outcome | Proposed slices | Forecast / dependency | Current state | |---|---|---|---|---|---| -| 1 | PYB-001 / P0 | Know what users can install and which artifacts they receive | 001.1, 001.2 | C1-S1; existing publication review | Proposed; physical installation and provenance remain unverified | -| — | PYB-002 / P0 accuracy | Keep maintained availability claims correct | Residual discrepancy task only if discovered | PR #33 already corrected Android copy; new discrepancies follow 001 | Original correction complete; no new residual task asserted | -| 2 | PYB-003 / P0 | Conduct a safe, consented pilot with bounded data collection | 003.1 | C1-S1; 001 informs setup | Proposed | -| 3 | PYB-004 / P0 | Observe one reachable audience completing reproducible, useful tasks | 004.1, 004.2 | C1-S1; 001, 003 | Proposed | -| 4 | PYB-006 / P0 | Recover the current text draft after process restart | 006.1, 006.2 | Size in C1-S1; bounded delivery C1-S2–S3; known defect does not wait for recruitment | Proposed; contract and sizing required | -| 5 | PYB-009 / P0 | Make existing validation reproducible by an operator | 009.1; optional 009.2 | Inventory C1-S1, recipe C1-S2; reproduction only with assigned capacity | Proposed | +| 1 | PYB-001 / P0 | Know what users can install and which artifacts they receive | 001.1, 001.2 | C1-S1; existing publication review | 001.1 Done; 001.2 Blocked; physical installation/provenance unverified | +| — | PYB-002 / P0 accuracy | Keep maintained availability claims correct | 002.1: public TestFlight description | PR #33 Android correction complete; residual found during 001 | Correction packet prepared; actual store update/public verification pending | +| 2 | PYB-003 / P0 | Conduct a safe, consented pilot with bounded data collection | 003.1 | C1-S1; 001 informs setup | Protocol prepared; human collection decision blocked | +| 3 | PYB-004 / P0 | Observe one reachable audience completing reproducible, useful tasks | 004.1, 004.2 | C1-S1; 001, 003 | Task kit prepared; cohort/setup and observations blocked | +| 4 | PYB-006 / P0 | Recover the current text draft after process restart | 006.1, 006.2 | Sized in C1-S1; S2–S4 working option requires replanning; known defect does not wait for recruitment | 006.1 Done; 006.2 implementation pending | +| 5 | PYB-009 / P0 | Make existing validation reproducible by an operator | 009.1; optional 009.2 | Inventory C1-S1, scoped recipe C1-S2; reproduction only with assigned capacity | T12 Done; 009.1 remains partial | | 6 | PYB-005 / P0 if observed | Remove a demonstrated first-use blocker | 005.1 | C1-S2 candidate; actual 004 findings | Conditional; no defect invented | | 7 | PYB-008 / P0 for claims | Establish the exact candidate's applicable compatibility evidence | 008.1, 008.2 | Representative checks C1-S2; staged matrix C1-S3–S5; 001, 009.1, artifacts | Proposed; hardware and mandatory workload must be costed | | 8 | PYB-011 / P0 usability | Understand useful first and repeat tasks in the primary cohort | 011.1, 011.2 | Main activation collection C1-S3–S4; rolling follow-up from the first consented activation through C1-S6; 003, 004, recorded tested setup | Proposed; recruitment and follow-up are not assumed | @@ -51,15 +51,30 @@ The completed portion of PYB-002 is [PR #33](https://github.com/PyBLE-dev/PyBLE/pull/33). A fresh mismatch needs its own accepted scope and evidence; do not restart the original correction or count it as this cycle's delivery. +## C1-S1 execution status — 25 September + +| Item | Actual state | Evidence / next action | +|---|---|---| +| PYB-001.1 | Done for the ledger scope | [Ledger](c1-s1/01_Channel_and_Artifact_Ledger.md); unknown fields have responsible owners/actions | +| PYB-001.2 | Blocked | No Android device; iPad app query locked; enrollment/install/build mapping remain unverified | +| PYB-002.1 | Prepared; store correction pending | New TestFlight description discrepancy; no claim of external mutation | +| PYB-003.1 / PYB-004.1 | Blocked; protocol/task cards prepared | [Pilot kit](c1-s1/02_Pilot_Protocol_and_Observation_Kit.md); human owner, cohort/setup and collection decision missing | +| PYB-004.2 / PYB-011.2 | No observations collected | Five baseline starts and all later follow-up remain outstanding | +| PYB-006.1 | Done for design/review/sizing | [Contract and review](c1-s1/03_Recovery_Design_and_Sizing.md); PYB-006.2 implementation remains pending; revised allocation needed | +| PYB-009.1 | Partial | T12 [inventory/cost model](c1-s1/04_Validation_Inventory_and_Operator_Recipe.md) complete; S2 scoped procedure and subsequent operator results still pending | + +The ordered table above retains original priorities and forecast labels. It is not evidence that all proposed dates remain feasible after the recovery estimate; use the [reforecast requirements](04_Sprint_Plan.md#c1-s1-findings-and-required-reforecast) before selecting future work. + ## 3. Detailed first-cycle stories and enablers -All acceptance criteria below describe future verification. They do not report tests, recruitment, approvals or releases already performed. Role names identify needed skills; assignment and sizing remain TBD. +Acceptance criteria below remain the completion authority. The [C1-S1 execution record](c1-s1/00_Execution_Record.md) reports actual outcomes; its evidence does not turn pending installation, recruitment or runtime work into Done. Role names identify needed skills; actual future assignments remain to be confirmed. ### 3.1 Distribution and pilot preparation | ID / type / role | Outcome | Testable acceptance criteria | Dependencies and verification | |---|---|---|---| | PYB-001.1 / Release enabler / Release | Establish a reviewed channel and artifact ledger | Separate publication, installation, provenance and qualification fields; record evidence/date/platform/channel/build; each unknown has an owner and next action; distinguish uploaded AAB/IPA identity from installed or re-signed artifacts | Existing dated publication review; reviewer checks ledger against first-party evidence. A completed ledger does not make an unknown installation pass | +| PYB-002.1 / Publication enabler / Distribution owner | Correct the stale app-level public TestFlight description | Verify the actually offered build supports the claims; apply accurate capability-defined copy through the owner-controlled channel; retain actual metadata update and dated public verification; do not relabel historical build notes or imply untested compatibility | Discovered in 001.1; [prepared correction](c1-s1/05_TestFlight_Metadata_Correction.md). Packet prepared only; store operation needs access and explicit capacity selection | | PYB-001.2 / User story / Release + QA | As a tablet-owning maker, I can follow the existing channel's installation path so I can start using PyBLE | Perform enrollment/install on eligible physical Android and iPad devices for the declared scope; record served version/build, observed restrictions and installation outcome; source mapping is evidenced or explicitly unresolved; instructions reproduce observed steps | 001.1 and channel/device access; dated physical installation records. Missing access or a failed install remains blocked/failed, not a completed successful installation | | PYB-003.1 / Governance enabler / Lead + QA | Approve a bounded pilot that protects participants and their data | Identify trusted setting, harmless loads and wrong-board containment; explain STOP limitations and lack of authenticated ownership; approve consent, assistance/safety rules, contact separation and deletion policy; review a manual support template excluding sensitive content by default | Recorded 001 setup; named pilot decision-maker signs the scoped decision before collection. No background analytics or automatic source/console upload | | PYB-004.1 / Research enabler / Pilot lead | Define one reachable cohort and tasks that reveal product value | Name primary audience, recruitment owner, reference setup and previous-workflow questions; separate Tasks A/B/C; fix eligibility, written guidance, assistance, timeout and exclusions prospectively; define follow-up linkage, prompting and opportunity-to-use questions | 001 and 003.1; reviewed task/observation protocol. Instructor cohort may replace the maker default by a recorded prospective choice | diff --git a/docs/developments/2026-q4-reliable-workflow/06_Sprint_Backlogs.md b/docs/developments/2026-q4-reliable-workflow/06_Sprint_Backlogs.md index 8ac3d40e..fc828c3b 100644 --- a/docs/developments/2026-q4-reliable-workflow/06_Sprint_Backlogs.md +++ b/docs/developments/2026-q4-reliable-workflow/06_Sprint_Backlogs.md @@ -1,11 +1,11 @@ -# Cycle 1 — candidate Sprint Backlog and later forecasts +# Cycle 1 — Sprint Backlog execution and later forecasts | Field | Rule | |---|---| -| Status | C1-S1 is a candidate; C1-S2–C1-S6 are forecasts. Every task below is Proposed, with no named assignee or actual effort recorded | +| Status | C1-S1 execution initiated 25 September: four repository tasks Done, eight device/pilot tasks Blocked. C1-S2–C1-S6 retain original Proposed allowances and require replanning before selection | | Product/Sprint Goals | [Framework](01_Overview_and_Scrum_Framework.md) and [Sprint plan](04_Sprint_Plan.md) | | Acceptance authority | [Product backlog and stories](05_Product_Backlog_and_Stories.md); task completion never overrides a parent story's acceptance criteria | | Selection | Developers confirm scope, ownership, estimates and task plan at each Sprint Planning | @@ -14,6 +14,8 @@ | Evidence | Record artifact identity and actual results; unavailable access/recruitment leaves the affected task Blocked, not Done | | Privacy | Keep private consent/contact/device records outside Git; link only reviewed public aggregates and redacted evidence | +Actual task evidence and blocker owners are maintained in the [C1-S1 execution record](c1-s1/00_Execution_Record.md). The original future task tables below are retained as the baseline; the new 45–72h recovery estimate and matrix cost model invalidate their assumed fit. Use the [reforecast requirements](04_Sprint_Plan.md#c1-s1-findings-and-required-reforecast) before selection. Prepared TestFlight correction copy records residual PYB-002.1; its external application is not an extra committed task. + The initial tasks are small planning units, generally 1–4 hours. If a task or safe story is larger after inspection, split/reforecast before selection. A time allowance does not limit a required test's counts or justify declaring partial qualification complete. The actual Sprint Backlog includes its confirmed Goal, selected items, and the Developers' current plan; update this document as that plan changes. Record optional follow-up consent and the prospective day-7–14 window at each activation. Collect follow-up as windows arrive, starting with the first cohort; do not postpone early cohorts until S5. S1 observation allowances include any follow-up due within S1; S2-T11, S3-T10 and later follow-up rows continue it. Developers must reallocate headroom or other selected work if actual pilot effort exceeds these allowances, preserving required recovery review and tests. Record missed windows as missing/late evidence rather than reconstructing an on-time response. @@ -30,18 +32,18 @@ Record optional follow-up consent and the prospective day-7–14 window at each | Task ID | Parent child item | Proposed task and expected output | Dependency | Contribution role | h | Status | |---|---|---|---|---|---:|---| -| C1-S1-T01 | PYB-001.1 | Assemble the dated channel/install/provenance/qualification ledger from existing records; assign unresolved fields | Current source/publication records | Release | 1 | Proposed | -| C1-S1-T02 | PYB-001.2 | Verify eligible Android enrollment/install and record build/version, restrictions and available source mapping | T01; Play/device access | Release + QA | 2 | Proposed | -| C1-S1-T03 | PYB-001.2 | Verify current TestFlight installation and record its actual build and provenance limitations | T01; TestFlight/device access | Release + QA | 2 | Proposed | -| C1-S1-T04 | PYB-003.1 | Review harmless hardware/pilot boundaries, consent/retention rules, and manual support template | Recorded pilot setup; named pilot owner | Pilot + QA | 2 | Proposed | -| C1-S1-T05 | PYB-004.1 | Confirm primary cohort and Tasks A/B/C, assistance/timeout rules, previous workflow and prospective follow-up | T04; recorded app/setup | Pilot | 2 | Proposed | -| C1-S1-T06 | PYB-004.2 / PYB-011.2 | Observe the first baseline batch; record every eligible start, assistance, consent/window and any due follow-up | T05; consenting participants | Pilot | 2 | Proposed | -| C1-S1-T07 | PYB-004.2 / PYB-011.2 | Observe the next baseline batch under the same task/build rules; record windows and collect due follow-up | T05; consenting participants | Pilot | 2 | Proposed | -| C1-S1-T08 | PYB-004.2 / PYB-011.2 | Complete planned observation/follow-up slots toward five baseline starts; retain failures, missing responses and recruitment gaps | T05; participant access | Pilot | 2 | Proposed | -| C1-S1-T09 | PYB-004.2 | Summarize baseline outcomes and actual observation cost; identify an observed obstacle without inventing one | T06–T08 actual records | Pilot + Product Owner | 1 | Proposed | -| C1-S1-T10 | PYB-006.1 | Draft the bounded Drift recovery contract: write boundary, restore/discard, board association, failure handling and carried Blocks/A-24 scope | ADR-0010 and App contracts; no recruitment dependency | App | 3 | Proposed | -| C1-S1-T11 | PYB-006.1 | Review acceptance scenarios and size the safe increment including required tests; record approval or unresolved design questions | T10; review path | App + reviewer | 1 | Proposed | -| C1-S1-T12 | PYB-009.1 | Inventory existing suites, hardware/operators, applicable gates and matrix cost; draft the next operator recipe | T01 and current tools/specs | QA + firmware | 2 | Proposed | +| C1-S1-T01 | PYB-001.1 | Assemble the dated channel/install/provenance/qualification ledger from existing records; assign unresolved fields | Current source/publication records | Release | 1 | Done | +| C1-S1-T02 | PYB-001.2 | Verify eligible Android enrollment/install and record build/version, restrictions and available source mapping | T01; Play/device access | Release + QA | 2 | Blocked | +| C1-S1-T03 | PYB-001.2 | Verify current TestFlight installation and record its actual build and provenance limitations | T01; TestFlight/device access | Release + QA | 2 | Blocked | +| C1-S1-T04 | PYB-003.1 | Review harmless hardware/pilot boundaries, consent/retention rules, and manual support template | Recorded pilot setup; named pilot owner | Pilot + QA | 2 | Blocked | +| C1-S1-T05 | PYB-004.1 | Confirm primary cohort and Tasks A/B/C, assistance/timeout rules, previous workflow and prospective follow-up | T04; recorded app/setup | Pilot | 2 | Blocked | +| C1-S1-T06 | PYB-004.2 / PYB-011.2 | Observe the first baseline batch; record every eligible start, assistance, consent/window and any due follow-up | T05; consenting participants | Pilot | 2 | Blocked | +| C1-S1-T07 | PYB-004.2 / PYB-011.2 | Observe the next baseline batch under the same task/build rules; record windows and collect due follow-up | T05; consenting participants | Pilot | 2 | Blocked | +| C1-S1-T08 | PYB-004.2 / PYB-011.2 | Complete planned observation/follow-up slots toward five baseline starts; retain failures, missing responses and recruitment gaps | T05; participant access | Pilot | 2 | Blocked | +| C1-S1-T09 | PYB-004.2 | Summarize baseline outcomes and actual observation cost; identify an observed obstacle without inventing one | T06–T08 actual records | Pilot + Product Owner | 1 | Blocked | +| C1-S1-T10 | PYB-006.1 | Draft the bounded Drift recovery contract: write boundary, restore/discard, board association, failure handling and carried Blocks/A-24 scope | ADR-0010 and App contracts; no recruitment dependency | App | 3 | Done | +| C1-S1-T11 | PYB-006.1 | Review acceptance scenarios and size the safe increment including required tests; record approval or unresolved design questions | T10; review path | App + reviewer | 1 | Done | +| C1-S1-T12 | PYB-009.1 | Inventory existing suites, hardware/operators, applicable gates and matrix cost; draft the next operator recipe | T01 and current tools/specs | QA + firmware | 2 | Done | | **C1-S1 total** | | | | | **22** | | Five baseline starts is a target, not the implied result of reserving six hours. If access or session duration prevents it, report the actual sample and replan. A completed findings record does not mark an unperformed installation or observation task Done. Missing store source mapping remains an owned limitation under the applicable gate. diff --git a/docs/developments/2026-q4-reliable-workflow/c1-s1/00_Execution_Record.md b/docs/developments/2026-q4-reliable-workflow/c1-s1/00_Execution_Record.md new file mode 100644 index 00000000..4a0615d7 --- /dev/null +++ b/docs/developments/2026-q4-reliable-workflow/c1-s1/00_Execution_Record.md @@ -0,0 +1,98 @@ + + + +# C1-S1 — execution and evidence record + +| Field | Record | +|---|---| +| Execution date | 25 September 2026, Asia/Bangkok; early work under the user's request to implement C1-S1 | +| Original proposed timebox | 28 September–11 October 2026; retained as a forecast, not a claim that a Sprint ceremony or staffed team occurred | +| Source baseline | Runtime/source `23ed764b0ef88dce9720c66fbd1c0655268860cf`; strategy/Scrum baseline `d039db09779ed45124874721f88b2e0931664743` | +| Scope | Installation evidence, pilot preparation, bounded recovery design/sizing and validation inventory; no S2 persistence implementation | +| Overall state | Repository deliverables prepared; physical installation and participant-dependent tasks remain blocked; C1-S1 and M-01/SG0 are not complete | +| Execution/review | Codex implemented and reviewed repository work across isolated Git worktrees; human pilot ownership, consent and physical observations are not supplied by that review | +| Capacity | Original C1-S1 allowance remains 22 hours; these are planning allowances, not measured human effort or actual velocity | + +## Deliverables and task outcomes + +| Task | Parent | Outcome | Evidence / remaining action | +|---|---|---|---| +| C1-S1-T01 | PYB-001.1 | Done — reviewed ledger and owned unknowns | [Channel/artifact ledger](01_Channel_and_Artifact_Ledger.md); direct HTTPS checks; separate listing/install/provenance/qualification states | +| C1-S1-T02 | PYB-001.2 | Blocked — Android device/account installation evidence missing | ADB saw no connected device; maintainer/release operator must complete eligible enrollment, installation and build capture | +| C1-S1-T03 | PYB-001.2 | Blocked — iPad app query denied while locked | Physical pairing/model metadata obtained; no installed build, fresh TestFlight install or launch attested | +| C1-S1-T04 | PYB-003.1 | Blocked — protocol prepared; human collection decision absent | [Pilot protocol and templates](02_Pilot_Protocol_and_Observation_Kit.md); name the pilot owner and record bounded setup/consent approval before collecting participant data | +| C1-S1-T05 | PYB-004.1 | Blocked — reproducible task cards prepared; cohort/setup unconfirmed | Same kit defines Tasks A/B/C, prospective metrics and follow-up; reachable cohort, owner and exact tested setup remain unconfirmed | +| C1-S1-T06 | PYB-004.2 / PYB-011.2 | Blocked — no eligible participant session | Empty private templates are ready; no consent, start, success or follow-up is invented | +| C1-S1-T07 | PYB-004.2 / PYB-011.2 | Blocked — no eligible participant session | Recruitment/observation owner needed | +| C1-S1-T08 | PYB-004.2 / PYB-011.2 | Blocked — no eligible participant session | Five baseline starts remain outstanding; no substitution by maintainer or automated tests | +| C1-S1-T09 | PYB-004.2 | Blocked — no observation set to analyze | Baseline sample is absent; completion, timing, retention and observed user-friction measures are unavailable, not zero-valued performance results | +| C1-S1-T10 | PYB-006.1 | Done — bounded implementation contract specified | [Normative recovery contract](../../../specifications/App/current-draft-recovery.md), ADR-0048, App specification/TDD and ADR-0010 addendum | +| C1-S1-T11 | PYB-006.1 | Done — source review, scenario matrix and sizing | [Recovery design review](03_Recovery_Design_and_Sizing.md); S2 forecast requires replanning; no implementation or physical acceptance claimed | +| C1-S1-T12 | PYB-009.1 | Done — tool/gate inventory, explicit access gaps and costed recipe | [Validation inventory](04_Validation_Inventory_and_Operator_Recipe.md); host harness checks are separate from physical execution and full recipe reproduction | + +Task completion is narrower than parent completion: PYB-009.1 still carries the S2 recipe completion and later operator updates; PYB-001.2, PYB-003.1 and PYB-004 remain unfinished. Specifying recovery does not implement PYB-006.2 or complete A-24. All hardware and recruitment limitations remain visible. + +## Findings that change planning + +| Finding | Decision / effect | +|---|---| +| Live website is corrected, but the search tool returns older text | Retain the Android correction; do not reopen it from cached snippets. Direct live-response evidence is in the ledger | +| Public TestFlight description still uses an older compatibility baseline | Record residual PYB-002.1 and a [ready-to-review correction packet](05_TestFlight_Metadata_Correction.md); store mutation/public verification remain pending | +| Current text is volatile and recovery is behind a connected-only shell | Specify a local startup choice and truthful durable-write boundary; current app behavior remains unchanged | +| Document value equality and stable connection facades need stronger stale-operation guards | Include revision/session guards and regressions in the recovery slice; no happy-path-only completion | +| Sized recovery work exceeds S2's allowance | Working estimate 45–72 hours including recipe, representative physical checks and follow-up; original S2–S6 selections must be replanned before commitment | +| Full firmware qualification costs are not represented by a few short batches | Use the validation inventory's normative counts and cost model; distinguish an app-only change's affected matrix from a new firmware release | +| No measured pilot data or named owner | Preserve the primary-maker cohort as provisional; SG0 is blocked, usability/retention results remain unavailable | + +## Proposed next allocation — not an extra commitment + +The original 136-hour task allocation, 20-hour planned headroom and 84-hour reserve remain an auditable baseline. They do not prove that newly sized work fits. The [design sizing](03_Recovery_Design_and_Sizing.md) proposes a 60-hour working allocation across S2–S4 as one option within existing ceilings; it displaces planned matrix and observation work and must be selected with actual owners, estimates and access. + +| Next decision | Required input | Consequence | +|---|---|---| +| Confirm S2 scope and capacity | Recovery design's 38–63 engineering hours, applicable tests, dependency review and actual Developer availability | Select coherent implementation work and an honest completion forecast; do not promise recovery Done in S2 from the old allowance | +| Reorder S3/S4 | Revised engineering needs, device/operator availability, pilot owner and observation costs | Move or reduce optional work; explicitly reforecast displaced qualification and recruitment | +| Preserve pilot interpretation | Prospective cohort/task rules and rolling windows | If 20 consenting activations cannot occur by 22 November, retain the original target and report a later window/inconclusive result honestly | +| Admit any maintenance release | All requirements for the declared candidate and compatibility scope pass | Release need not wait for SG2/SG3 or Ready; missing mandatory evidence cannot be waived to meet a date | + +## Review and continuation + +| Review item | Record | +|---|---| +| M-01 / SG0 | Blocked: human pilot owner/cohort/setup and actual capacity still need confirmation; installed-device evidence is incomplete | +| M-02 | Implementation pending; contract and scenario matrix prepared, not a shipped persistence feature | +| M-03 / SG2 and M-06 / SG3 | Not assessed; no participant outcomes or mature follow-up cohort | +| M-04 / M-05 | No new release candidate, submission or verified installation from this execution | +| Ready | No second-operator reproduction or badge awarded | +| Worktree method | Recovery design, pilot preparation and qualification inventory were implemented in separate branches/worktrees from the shared planning baseline, then reviewed and integrated | +| Required next human actions | Supply physical channel access; name the pilot owner and cohort; confirm actual capacity before selecting the revised next Sprint | + +## Integrated verification + +| Check | Actual result / scope | +|---|---| +| Source/design peer review | Recovery contract reviewed against actual controllers; a missing Board Open session guard was corrected in the contract and DR-T11 before integration | +| Focused firmware host harness checks | 110 passed, as recorded in the validation inventory; host fixtures only | +| Publication regression suite | `python3 -m unittest discover -s tests/publication -p 'test_*.py'`: 42 passed in the integrated worktree | +| Markdown links and anchors | 135 tracked/new Markdown files checked, including this execution package; all local targets resolve | +| Mermaid | All 12 diagrams in the Scrum/execution package and recovery contract parsed and rendered to temporary SVGs; rendered artifacts not committed | +| Structure and traceability | Tables/fences/whitespace, 24 child IDs, 60 unique task IDs, original 136h allocation, and four Done/eight Blocked C1-S1 states checked | +| Repository gates | No-leak, SPDX, governance 7/7 and `git diff --check` pass | +| Not executed | Full Flutter/firmware suites, candidate builds, device installations, board/HIL runs, participant sessions, store metadata mutation and external publication | + +No runtime implementation changed in C1-S1. Required future recovery tests are specified, not claimed passed. No app source, firmware binary, store artifact, participant data or raw device identifiers are included in the documentation commits. + +```mermaid +flowchart TD + Request[Authorized C1-S1 work] --> Ledger[Channel ledger and real access checks] + Request --> Pilot[Pilot protocol and empty record templates] + Request --> Design[Recovery contract and sizing] + Request --> Recipe[Validation inventory and operator recipe] + Ledger --> Access[Pending physical installation evidence] + Pilot --> People[Pending human owner and participants] + Design --> Replan[Replan S2 to S6 within actual capacity] + Recipe --> Replan + Access --> Baseline[M-01 and SG0 review] + People --> Baseline + Replan --> Baseline +``` diff --git a/docs/developments/2026-q4-reliable-workflow/c1-s1/01_Channel_and_Artifact_Ledger.md b/docs/developments/2026-q4-reliable-workflow/c1-s1/01_Channel_and_Artifact_Ledger.md new file mode 100644 index 00000000..1efef635 --- /dev/null +++ b/docs/developments/2026-q4-reliable-workflow/c1-s1/01_Channel_and_Artifact_Ledger.md @@ -0,0 +1,96 @@ + + + +# C1-S1 — channel, installation, provenance and qualification ledger + +| Field | Record | +|---|---| +| Observed | 25 September 2026; HTTP responses dated 10:03:21 UTC / 17:03:21 Asia/Bangkok | +| Source baseline | Runtime/source `23ed764b0ef88dce9720c66fbd1c0655268860cf`; planning baseline `d039db09779ed45124874721f88b2e0931664743` | +| Scope | C1-S1-T01/T02/T03; PYB-001.1/001.2; residual TestFlight metadata discrepancy PYB-002 | +| Evidence author | Codex, using direct HTTPS retrieval and local read-only device queries; no independent human installation attestation | +| Release action owner | Project maintainer Viwat Vchirawongkwin; routing responsibility, not a statement of committed availability | +| Physical outcome | Android installation not run; iPad app query blocked by lock state; neither platform's store-installed build is established | +| Related | [Execution record](00_Execution_Record.md), [pilot kit](02_Pilot_Protocol_and_Observation_Kit.md), [validation recipe](04_Validation_Inventory_and_Operator_Recipe.md) | + +## Observed channel matrix + +| Platform / item | Publication observation | Physical installation observation | Artifact provenance | Qualification boundary | +|---|---|---|---|---| +| Android / Google Play | Official English/US listing returned HTTP 200; names PyBLE, SciLabPro and open testing for 0.2.0 | `adb devices -l` returned no devices. No signed-in enrollment, install or launch was performed | Served version code, installed bytes and source mapping remain unverified | Listing availability and the historical build-8 test record do not qualify a currently installed binary | +| iPad / TestFlight | Public invitation returned HTTP 200 and identified the PyBLE beta; the page does not establish the currently served version/build | A paired physical `iPad16,10` was reported. Device details expose iPadOS `26.6.2` / `23G90`; app inventory failed because the device had not been unlocked recently | No installed version/build or store receipt was obtained; the historical build-5 handoff cannot fill these fields | Pairing/device metadata is not installation, launch, BLE or compatibility evidence | +| Live website `/app` | Direct HTTPS returned the corrected Android open-testing and iPad external-beta wording | Not applicable | Page response hash recorded below | Website wording is not a store rollout or physical test | +| Live website `/` | Direct HTTPS returned Android open-testing wording | Not applicable | Page response hash recorded below | Search/indexed extracts may still be stale | +| Firmware v0.6.1 | Existing 11 September publication record attests owner-confirmed publication of five exact profiles | No new board installation or run in this execution | Published source `c8f549eeabe6d2b8c2766eab022517944bb09c8c`; use the release descriptor and exact binary checksums for a physical session | Incomplete automated evidence remains incomplete; this ledger neither requalifies firmware nor awards PyBLE Ready | + +Primary URLs: [Google Play](https://play.google.com/store/apps/details?id=dev.pyble.pyble&hl=en&gl=US), [TestFlight](https://testflight.apple.com/join/yU4e8s6d), [app installation page](https://pyble.dev/app), and [home page](https://pyble.dev/). The direct live website responses supersede the older invited-testing text returned by the search tool during the same inspection. No website source correction or deployment is needed for that stale extract. + +The TestFlight page has a separate current discrepancy: its public description still limits the product to the older ESP-family/agent-0.4.0 baseline. The [metadata correction packet](05_TestFlight_Metadata_Correction.md) supplies replacement app-level copy and an owner verification checklist. Its preparation does not update App Store Connect or prove newer build compatibility. + +## Historical artifact references — not inferred installations + +| Artifact | Recorded identity | Source / original evidence | What remains unknown | +|---|---|---|---| +| Android prepared AAB | `0.2.0 (8)`; SHA-256 `ee2439589e2c2195ef4c861b524f871b0e5168e84fbea60a1cd379319c6eb5d7` | Source `768fafe45beee7731d1a38480cc0463a2f5680cd`; [10 September handoff](../../../testing/google-play/0.2.0-build-8.md) | Whether this bundle is the active open-test build; Google Play-delivered APKs may be split and re-signed, so AAB/APK digests are not interchangeable | +| Android prepared local APK | `0.2.0 (8)`; SHA-256 `3c98983a995c657f10a398d7b0f65a07c2d2af18e07c30e7d5dfc094eefcbdcf` | Same historical source and handoff | A locally signed APK does not prove the store installation path | +| iPad prepared IPA | `0.2.0 (5)`; SHA-256 `e2e44019aafd6b75f1d281a7cf4fb49d3ef7f326a4d604f2900ad249af70f2af` | Source `8f8dd32010fac9b2b636f57f9044fd040565e0dd`; [27 August handoff](../../../testing/testflight/0.2.0-build-5.md) | Processing, beta availability and the currently served build remain unverified; this historical artifact has its original iOS 13 floor | +| Firmware v0.6.1 descriptor | Historical SHA-256 `71f6aca6df07e31a1f54c7f70a48d82c7fe26b1c8ca0626a8ffc57c804fbb1bd` | [11 September publication](../../../testing/firmware-v0.6.1-publication-2026-09-11.md) | No new byte download/board validation is claimed here; bind actual session evidence to the selected release | + +## Open fields and next actions + +| ID | Missing evidence / blocker | Responsible action owner | Next action and review trigger | +|---|---|---|---| +| CH-01 | Physical Android device/account and eligible open-testing installation | Project maintainer / release operator | Connect an eligible device, follow the official listing, record restrictions and complete the checklist below; revisit when available | +| CH-02 | Physical iPad app inventory and current TestFlight installation | Project maintainer / iPad operator | Unlock the paired device, verify the TestFlight invitation and currently offered build, then record actual installation/update and launch; revisit after unlock | +| CH-03 | Installed build-to-source mapping on both platforms | Project maintainer / distribution owner | Match observed installed version/build to retained store build records and immutable source/artifact evidence; explicitly retain any unprovable field | +| CH-04 | TestFlight public description still states an older compatibility baseline | Project maintainer / App Store Connect owner | Review and apply the prepared metadata only with actual build support verified; record the public result and date | +| CH-05 | Current exact-board inventory, operator availability and candidate-bound physical results | Project maintainer / QA operator | Complete the [inventory](04_Validation_Inventory_and_Operator_Recipe.md); select exact artifacts and fund the required matrix before making a new compatibility claim | + +Owners above identify the responsible project function and known maintainer contact. They do not assign an absent volunteer or claim a scheduled hardware session. The user has been asked for device access and a pilot owner; unanswered requests remain unresolved. + +## Repeatable installation checklist + +| Step | Android | iPad | Evidence to retain | +|---|---|---|---| +| 1 — Establish scope | Record device model/Android version and eligible country/account context without account identifiers | Record iPad model/iPadOS and availability of TestFlight | Date, platform, model, OS; private account details excluded | +| 2 — Follow the public channel | Open the official listing; follow its displayed testing/enrollment instructions | Open the public invitation in TestFlight; inspect the offered build and restrictions | Actual steps, enrollment/review restrictions, offered version/build where visible; HTTP 200 alone is insufficient | +| 3 — Install or update safely | Record existing-app/update state; do not uninstall or clear data merely to obtain a clean result | Record existing-app/update state; do not replace it with a locally signed build | Installation/update outcome, errors or blocker; preserve existing user work | +| 4 — Inspect the result | Launch the store-installed app; inspect About and package version/build | Launch the TestFlight-installed app; inspect About and TestFlight build identity | Observed installed identity, launch outcome, installation source and any unresolved field | +| 5 — Resolve provenance | Compare against the selected Play build record; distinguish upload and delivered signing roles | Compare against the selected App Store Connect build record | Immutable source/artifact mapping or explicit unknown; never derive it from source `pubspec.yaml` alone | +| 6 — Review | Review redacted evidence and accurate guidance | Review redacted evidence and accurate guidance | Successful installation satisfies only its scope; compatibility still needs applicable physical tests | + +Read-only inspection commands, after device access is available: + +```sh +adb devices -l +adb shell dumpsys package dev.pyble.pyble +xcrun devicectl device info apps --device '' \ + --include-default-apps --bundle-id dev.pyble.pyble +``` + +Keep full command outputs private because they may contain device identifiers, account-related information or paths. Publish only the selected fields above. A package inventory proves neither fresh enrollment nor a successful launch. No uninstall, clear-data, flashing, source-app installation or store submission is part of these inspection commands. + +## Retained evidence and privacy + +Raw responses/query files are retained in the main workspace's ignored `local/c1-s1/2026-09-25/`, outside Git. The device app query failed with CoreDevice error `10003` / RemotePairing error `1016`; its nested reason was that the device had not been unlocked recently. Device details may be cached, so the OS/model fields are reported as query output rather than proof of an active app session. + +| Raw capture | SHA-256 | Meaning | +|---|---|---| +| `play.html` | `3aa2104a157b5380867ba03db97dba3e5285b2d6699006b9140474fb383f558f` | Public Google Play HTTP body | +| `testflight.html` | `78b9fb6bf3ff04ce12dfdf0e2a24ae694d0fda50cc1b8a468ae5d01c8277fdfb` | Public TestFlight invitation/description body | +| `website-app.html` | `533375076ea081da58700a1f61c1e2dc0db3795085107ec6a5e536cb2ecc6a25` | Corrected live installation page | +| `website-home.html` | `e40dd779caff6c026cd8add49946983516d9aea52f0340eec9d7efd45f2ada01` | Corrected live home page | +| `ipad-pyble-app.json` | `4677ab2fc532ec433fcd3fccde67d43e03b679f6ea23d80d3772a77232aaa474` | Failed read-only app query; no installed-build result | +| `ipad-details.json` | `737e1f0dcf2b618f891683db3a1d9c56adf01c5fc54a81abe06aa0b4d19adc00` | Device metadata query; raw personal identifiers withheld | + +These hashes make the retained capture identifiable; dynamic public pages may return different bytes on a later request. They are not hashes of distributed app binaries. + +```mermaid +flowchart LR + Public[Public listing observed] --> Access[Eligible account and physical device] + Access --> Install[Actual installation and launch] + Install --> Identity[Observed version and build] + Identity --> Mapping[Source mapping or explicit unknown] + Mapping --> Physical[Applicable exact-artifact physical evidence] + Locked[Locked or unavailable device] -. Blocked installation .-> Access +``` diff --git a/docs/developments/2026-q4-reliable-workflow/c1-s1/05_TestFlight_Metadata_Correction.md b/docs/developments/2026-q4-reliable-workflow/c1-s1/05_TestFlight_Metadata_Correction.md new file mode 100644 index 00000000..ee3dbcf7 --- /dev/null +++ b/docs/developments/2026-q4-reliable-workflow/c1-s1/05_TestFlight_Metadata_Correction.md @@ -0,0 +1,41 @@ + + + +# C1-S1 — TestFlight app-level metadata correction + +| Field | Record | +|---|---| +| Discovered | 25 September 2026, during C1-S1-T01 | +| Backlog | PYB-002.1, newly identified residual copy discrepancy; the earlier Android correction remains complete | +| State | Replacement copy prepared; App Store Connect change and public verification pending | +| Action owner | Project maintainer / App Store Connect owner; store access not used in this execution | +| Evidence | [Channel ledger](01_Channel_and_Artifact_Ledger.md), public TestFlight response and retained body hash | + +The live public invitation's description still presents the older ESP-family/agent-0.4.0 scope. A capability-defined app description should explain how to select the correct tested setup without implying that every current board/profile works with an unidentified TestFlight build. The historical [build-5 handoff](../../../testing/testflight/0.2.0-build-5.md) remains unchanged. + +## Prepared Beta App Description + +The following is app-level copy for review against the actual offered build. It is not a build-specific “What to Test” entry and does not announce a new binary, production release or completed compatibility matrix. + +```text +PyBLE (Python over Bluetooth Low Energy) is a free, open-source, tablet-first MicroPython IDE. It connects over BLE to a compatible board running the PBLE/1 PyBLE agent, so you can edit and transfer Python files, run and stop programs, inspect console output, manage board files, and use offline Blocks. + +A Bluetooth-capable board running stock MicroPython is not automatically compatible. Before starting, check https://pyble.dev/flash for exact board and firmware requirements, and follow the compatibility instructions for the TestFlight build you install. Initial firmware installation or recovery may require a computer and USB cable. After provisioning, the normal development workflow uses BLE. + +This is a TestFlight beta. See https://pyble.dev/learn for setup and first-program guidance, https://pyble.dev/support for help, and https://pyble.dev/privacy for the privacy policy. Use harmless test programs and back up important work. Local editor drafts in the current working-loop implementation do not survive an app restart; saving to the board is a separate explicit action. + +PyBLE is MIT-licensed and developed in public at https://github.com/PyBLE-dev/PyBLE. The app has no required account, advertising, analytics, subscriptions or purchases. Optional public GitHub example import requires Internet access; the normal board workflow uses BLE. +``` + +## Owner handoff and completion criteria + +| Action | Required evidence / boundary | +|---|---| +| Identify the offered TestFlight build | Record actual version/build and source mapping or unknowns before changing build-specific compatibility or test instructions | +| Check the app-level description | Confirm the offered build supports the described core features; adjust a claim if its actual artifact differs | +| Apply the metadata through App Store Connect | Record the actual field, locale, saved/submitted state and date; avoid touching unrelated listing fields or version history | +| Keep build-specific notes separate | Use notes tied to the selected artifact; do not paste the old build-5 notes into a different build or assert untested five-profile compatibility | +| Verify the public invitation | Retrieve the public page again and verify the corrected description when Apple exposes it; retain a dated response hash and pending processing state if applicable | +| Close PYB-002.1 | Both the actual metadata update and public verification must be evidenced; preparing this packet alone does not complete the correction | + +This residual task does not block preparation of the persistence contract or otherwise qualified maintenance work. No paid feature, app allowlist, new protocol behavior or PyBLE Ready claim is introduced. diff --git a/docs/planning/PyBLE_Implementation_Plan_and_Strategy_v1.0.md b/docs/planning/PyBLE_Implementation_Plan_and_Strategy_v1.0.md index 871f3c6a..1655284e 100644 --- a/docs/planning/PyBLE_Implementation_Plan_and_Strategy_v1.0.md +++ b/docs/planning/PyBLE_Implementation_Plan_and_Strategy_v1.0.md @@ -11,10 +11,10 @@ | Field | Value | |---|---| -| Document version | 1.2 — product-value and PyBLE Ready revision; original filename retained | +| Document version | 1.3 — C1-S1 execution, evidence and sizing update; original filename retained | | Prepared | 25 September 2026 | -| Last reviewed | 25 September 2026; strategy and PyBLE Ready feedback incorporated after the PR #33 baseline review | -| Status | Proposed execution plan for maintainer review; not approval to implement new protocol behavior | +| Last reviewed | 25 September 2026; C1-S1 worktree deliverables, real access blockers and revised sizing incorporated | +| Status | C1-S1 repository work executed under the user request; device/pilot tasks remain blocked. Future capacity and scope need replanning; no new protocol behavior approved | | Product | PyBLE — Python over Bluetooth Low Energy | | Organization | SciLabPro | | Planning horizon | Immediate 12-week delivery cycle, followed by conditional expansion through September 2028 | @@ -26,7 +26,7 @@ **Scope of this document.** This plan converts the preceding PyBLE strategy discussion into executable workstreams, priorities, acceptance criteria, and decision gates. Existing repository specifications and contributor rules remain authoritative. Proposed features, names, metrics, staffing, and dates below are planning choices—not claims that those features exist or that resources and approvals are secured. -**Evidence boundary.** The baseline review inspected repository source, specifications, test entry points, publication records, and the GitHub state of PR #33 and issue #24 on 25 September. Revision 1.2 incorporates the subsequent strategy and PyBLE Ready feedback. The dated Android review establishes the official listing's open-testing status; it does not identify the installed store binary or prove a signed-in installation. Installation counts, traffic, media engagement, participant outcomes, and new physical-board results have not been measured for this revision. Previously reported publicity and GitHub counts are not proof of product-market fit.[^android-review] +**Evidence boundary.** The baseline review inspected repository source, specifications, test entry points, publication records, and the GitHub state of PR #33 and issue #24 on 25 September. Revision 1.2 incorporates the subsequent strategy and PyBLE Ready feedback. The dated Android review establishes the official listing's open-testing status; it does not identify the installed store binary or prove a signed-in installation. Revision 1.3 adds direct live-channel/website checks and a blocked physical iPad app query in the [C1-S1 ledger](../developments/2026-q4-reliable-workflow/c1-s1/01_Channel_and_Artifact_Ledger.md). No successful store installation, participant outcome or new physical-board result has been measured. Previously reported publicity and GitHub counts are not proof of product-market fit.[^android-review] **Continuation decision.** Carry forward the completed Android publication/copy correction. Concentrate weekly execution on three outcomes: verify what users install, preserve their work through interruptions, and observe useful repeat tasks in one primary audience. Reuse existing lifecycle handling, tutorials, conformance fixtures, and release tooling. A bounded PyBLE Ready rehearsal can reuse one existing profile's evidence work; new ports, broad badge promotion, classroom bundles, and new protocol behavior remain conditional. @@ -35,6 +35,7 @@ | 1.0 | Initial strategy and proposed 12-week program | | 1.1 | Updated baseline after PR #33; separated publication from installed-build evidence; mapped remaining work to current code; bounded the schedule and corrected release/pilot dependencies | | 1.2 | Focused pilot selection and useful second tasks; contextualized retention; defined one version-bound PyBLE Ready badge, installation labels, maintenance rules, and a staged existing-profile/partner pilot | +| 1.3 | Executed C1-S1 repository deliverables in parallel worktrees; recorded device/pilot blockers, stale TestFlight metadata, a bounded recovery contract and larger engineering/matrix estimates; future allocations require replanning | ## Contents @@ -149,13 +150,27 @@ Historical release-roadmap statements about an unpublished v0.6.1 or an open #24 **Output:** extend this baseline into a dated channel/artifact matrix with evidence links, owner, verification date, and separate publication/install/provenance/qualification fields. Mark unresolved fields `unverified`, and physical scenarios `not_run` or `blocked`. -### 2.3 Baseline metrics to collect +### 2.3 C1-S1 execution evidence — 25 September 2026 + +The [execution record](../developments/2026-q4-reliable-workflow/c1-s1/00_Execution_Record.md) separates four completed repository tasks from eight blocked installation/pilot tasks. Early execution does not retrospectively change the proposed 28 September Sprint start or claim a staffed-team ceremony. + +| Workstream | Completed repository output | Remaining requirement | +|---|---|---| +| PYB-001 | Reviewed channel/artifact ledger; direct Play/TestFlight/site HTTP checks; responsible owners for unknowns | Android device unavailable; paired iPad app query blocked while locked; store-installed builds and source mapping unverified | +| Residual PYB-002.1 | Accurate replacement TestFlight app-level description prepared after the public page exposed its older ESP/agent-0.4.0 baseline | Distribution owner must apply it and verify the public result; Android's earlier correction remains complete | +| PYB-003/004 | Operational pilot protocol, safe Tasks A/B/C, consent/retention rules and empty observation/support templates | Human owner, reachable cohort, tested setup and collection decision unconfirmed; no participants or observed outcomes | +| PYB-006.1 | [Recovery contract](../specifications/App/current-draft-recovery.md), ADR-0048, source/peer review, scenario matrix and estimate | Runtime implementation pending; broader A-24/Blocks scope remains carried | +| PYB-009.1 | Existing tool/gate inventory, ten platform/profile rows, cost model and initial operator recipe; 110 focused host harness tests pass | S2 scoped procedure, hardware/operator access, actual physical runs and independent reproduction remain pending | + +The recovery estimate is **38–63 engineering hours**, or **45–72 hours** with the original recipe, representative-platform and follow-up allowances. The [design review](../developments/2026-q4-reliable-workflow/c1-s1/03_Recovery_Design_and_Sizing.md) offers a conditional 60-hour S2–S4 allocation, displacing earlier matrix and activation forecasts. The [validation inventory](../developments/2026-q4-reliable-workflow/c1-s1/04_Validation_Inventory_and_Operator_Recipe.md) estimates 13.5–26 operator hours for the app matrix and 30–59 for fresh full firmware qualification, excluding builds, unavailable access and defect repair. These are working estimates, not actual effort or promises. **SG0 remains blocked.** + +### 2.4 Baseline metrics to collect Record current store channels, download buckets where visible, repository engagement, issue authorship, and existing third-party demonstrations. Establish separate counts for maintainers, project-recruited testers, classroom participants, and independently arriving users. Do not spend the first sprint rebuilding a large analytics dashboard. A small private pilot register plus a public aggregate status report is sufficient. -### 2.4 Implementation map: reuse first, then close the gap +### 2.5 Implementation map: reuse first, then close the gap | Area and inspected source | Already present | Remaining work for this plan | |---|---|---| @@ -166,7 +181,7 @@ Do not spend the first sprint rebuilding a large analytics dashboard. A small pr | [Device information types](../../app/lib/pble/types.dart) | Negotiated chip, agent version, and capabilities | A support export must distinguish observed data from operator-supplied profile/provenance; current HELLO does not prove an artifact hash | | [Host conformance fixtures](../../tests/firmware_tests/host/conformance/README.md), [HIL guide](../../tests/firmware_tests/hil/README.md) | Shared vectors, compiled-native/portable tests, physical benches and release evidence tools | Add a coverage map and operator recipe before creating another harness or schema | -**First engineering candidate:** PYB-006, the carried A-24 persistence gap. Complete its specification and sizing while collecting first-use observations; an already documented loss condition does not need rediscovery by participants. Start with durable recovery of the current text document and explicitly scope Blocks recovery. The existing ADR selects Drift and rejects an ad-hoc scratch-file workaround; any different design needs an explicit superseding decision. This does not approve a full project manager, automatic board writes, or new protocol operations.[^app-contract] +**First engineering candidate:** PYB-006, the carried A-24 persistence gap. Its bounded specification and sizing are now recorded in C1-S1; select implementation against that estimate while collecting first-use observations; an already documented loss condition does not need rediscovery by participants. Start with durable recovery of the current text document and explicitly scope Blocks recovery. The existing ADR selects Drift and rejects an ad-hoc scratch-file workaround; any different design needs an explicit superseding decision. This does not approve a full project manager, automatic board writes, or new protocol operations.[^app-contract] ## 3. Target users and positioning @@ -365,6 +380,9 @@ The cycle intentionally excludes a complete new protocol version, full classroom ### 8.2 Sprint plan +**Reforecast required after C1-S1:** the hour rows below retain the original 136-hour base allocation, not an accepted revised selection. Recovery's 45–72 hour estimate exceeds S2's allowance. A conditional S2/S3/S4 allocation of 26/22/12 hours preserves each 26-hour ceiling but leaves only 18 hours for displaced work across those three Sprints. Reorder matrix, activation and conditional fixes with actual owners/access; reassess S5/S6 and the 22 November recruitment target. Do not borrow the event reserve silently, drop failure cases, or count one physical run twice. The [Sprint plan](../developments/2026-q4-reliable-workflow/04_Sprint_Plan.md#c1-s1-findings-and-required-reforecast) owns the detailed comparison. + + | Sprint | Proposed dates / planned-hour cap | Selected work | Review evidence / exit condition | |---|---|---|---| | S1 | 28 Sep–11 Oct 2026 / 22 h | PYB-001/003/004; residual PYB-002; size PYB-006 and inventory PYB-009 | One primary cohort/task selected; channel unknowns assigned; five baseline observations or recruitment blocker; persistence scope and costed matrix; name a second operator if available | @@ -405,6 +423,8 @@ These horizons overlap where staffing permits. They are not simultaneous commitm ### 9.1 First-cycle backlog +Current execution states and the newly identified residual `PYB-002.1` are maintained in the [derived Product Backlog](../developments/2026-q4-reliable-workflow/05_Product_Backlog_and_Stories.md). Parent acceptance below remains binding; prepared procedures do not complete their physical or human-dependent obligations. + | ID | Priority / owner | Deliverable and acceptance criterion | Dependency | |---|---|---|---| | PYB-001 | P0 / Release | Extend §2.2 into channel/install/provenance/qualification records; capture actual installed version/build and source mapping, or an explicit unknown with owner | Existing publication review | @@ -835,12 +855,12 @@ At cycle end, choose one principal next investment: Reliable Projects, partner p - [x] Identify A-24/ADR-0010 durable drafts as a concrete remaining engineering gap. - [ ] Confirm one reachable primary audience, recruitment owner, previous workflow and meaningful Task C; keep other audiences exploratory. - [ ] Assign actual capacity and accept a bounded first sprint; size persistence and mandatory physical work before promising the full cycle. -- [ ] Complete PYB-001's installed-build/provenance fields for Google Play and TestFlight, or name the blocker and responsible owner. -- [ ] Create or link accepted PYB-001/003/004/006/009 tasks; PYB-002 needs a new issue only for a remaining discrepancy. Preserve existing A-24/ADR identities. +- [x] Record PYB-001's installation/provenance blockers and responsible maintainer/operator actions in the channel ledger; actual installations remain blocked. +- [x] Link PYB-001/003/004/006/009 execution tasks and evidence in the local Scrum package; record the real residual TestFlight discrepancy as PYB-002.1. Preserve A-24/ADR identities; no GitHub issues were fabricated or created. - [ ] Assign one owner and one review path for each initial issue. - [ ] Inventory exact test boards, tablets, cables, and available recovery equipment. - [ ] Freeze Task A/B/C definitions, assistance/timeout rules, prospective follow-up windows and task-opportunity questions, consent procedure, and manual support template; observe initial eligible participants. -- [ ] Review the durable-draft contract and choose its first testable increment; escalate any newly observed release blocker ahead of optional work. +- [x] Specify and peer-review the bounded current-text contract and its acceptance scenarios; size the safe increment. Runtime implementation and physical acceptance remain pending; replan the original S2 forecast. - [ ] If operator/capacity is available, include one existing-profile Ready rehearsal and draft record in PYB-009; show installation status and pending evidence explicitly. ### 20.2 Issue template @@ -909,9 +929,11 @@ Work on one accepted PyBLE issue only. ### 20.4 Decision record for every sprint +[C1-S1 execution and decision record](../developments/2026-q4-reliable-workflow/c1-s1/00_Execution_Record.md) is the first dated instance. Its blockers remain open and it is not a completed Sprint Review. + Record shipped versus proposed work; exact tested artifacts; pass/fail/not-run results; the selected audience and useful-task outcomes; reasons to choose PyBLE; opportunity-to-use and prompting context; maintenance/support burden; and one explicit next-sprint priority. Include Ready rehearsal/record status only when that work is selected. Store identities and participant data separately from public aggregate reports. -**Next action:** confirm one primary audience and useful task, finish the installed-build record, and specify the first A-24 durable-draft increment. Observe useful work and follow-up alongside delivery of the smallest qualified maintenance change. Reuse operator work for a bounded existing-profile Ready rehearsal if capacity is assigned. Let task failures, repeat value, and support effort determine subsequent protocol, partner, or classroom investment. +**Next action:** confirm one primary audience and useful task, finish the installed-build record, and replan/select implementation against the specified bounded A-24 recovery contract and its recorded estimate. Observe useful work and follow-up alongside delivery of the smallest qualified maintenance change. Reuse operator work for a bounded existing-profile Ready rehearsal if capacity is assigned. Let task failures, repeat value, and support effort determine subsequent protocol, partner, or classroom investment. ## 21. Source references @@ -946,4 +968,4 @@ The strategy supplies the proposed direction. The sources below ground the exist --- -**End of document — PyBLE Implementation Plan and Development Strategy, revision 1.2** +**End of document — PyBLE Implementation Plan and Development Strategy, revision 1.3** diff --git a/docs/planning/firmware-v0.6.1-v0.7.0-roadmap.md b/docs/planning/firmware-v0.6.1-v0.7.0-roadmap.md index aef5532f..6659d3ed 100644 --- a/docs/planning/firmware-v0.6.1-v0.7.0-roadmap.md +++ b/docs/planning/firmware-v0.6.1-v0.7.0-roadmap.md @@ -2,11 +2,17 @@ # Firmware v0.6.1 and v0.7.0 roadmap -Status: **v0.6.1 APPROVED for implementation; v0.7.0 remains PROPOSED** +Status: **v0.6.1 published on owner confirmation; v0.7.0 remains PROPOSED** Baseline: **qualified firmware v0.6.0** -Last updated: **2026-09-03** +Last reviewed: **2026-09-25**; the original implementation decision is dated 2026-09-03. + +Current publication is recorded in the [11 September evidence](../testing/firmware-v0.6.1-publication-2026-09-11.md). +Issue #24 was closed as superseded on 13 September; its incomplete checklist +was not marked passed. Publication on owner confirmation does not complete +missing automated qualification. The [C1-S1 validation inventory](../developments/2026-q4-reliable-workflow/c1-s1/04_Validation_Inventory_and_Operator_Recipe.md) +maps applicable gates for future work without waiving them. ## 1. Purpose and status @@ -517,11 +523,12 @@ and focused issues [#24](https://github.com/PyBLE-dev/PyBLE/issues/24), retrospectively on 2026-09-03. This restores explicit ownership, acceptance criteria, and remaining-work tracking, but it does not retroactively satisfy the required ordering and must not be represented as doing so. Issues #25–#28 -record source/host completion; #24 remains open and exclusively owns fresh -candidate-bound five-profile physical qualification and release admission. -Firmware v0.6.1 therefore remains source-selected, unqualified, unpublished, -and unavailable to installers until #24 closes. This deviation approves no -v0.7.0 scope and creates no precedent for a future release. +recorded source/host completion. At that 3 September decision, #24 remained +open and owned fresh candidate-bound five-profile qualification; v0.6.1 was +source-selected and unpublished. The subsequent owner-confirmed publication +and superseded issue closure are recorded above, without converting missing +automated results into passes. This deviation approves no v0.7.0 scope and +creates no precedent for a future release. ## 10. Maintainer review checklist diff --git a/docs/specifications/app.md b/docs/specifications/app.md index 9ab0b683..376c172b 100644 --- a/docs/specifications/app.md +++ b/docs/specifications/app.md @@ -1,6 +1,6 @@ # PyBLE — App Architecture -Status: **DRAFT** · Last updated: 2026-08-15 +Status: **DRAFT** · Last reviewed: 2026-09-25 The PyBLE app is a Flutter, tablet-first IDE for iPad and Android. It connects to a compatible MicroPython board over BLE, speaks PBLE/1, and presents an @@ -11,6 +11,14 @@ firmware targets. > **Detailed app docs:** this page is the overview. The full requirements live in [`App/specs.md`](App/specs.md) and the technical design in [`App/TDD.md`](App/TDD.md) (Technical Design Document), both derived from [PRD §9](prd.md). +**C1-S1 persistence status:** the current editor document remains volatile and +`lib/data/` remains a placeholder. The specified +[bounded current-text recovery contract](App/current-draft-recovery.md) and +[ADR-0048](../decisions/0048-bounded-current-text-draft-recovery.md) define the +next Drift increment, including a local recovery panel before connection. +Implementation and physical acceptance remain pending; this does not complete +full project management, saved boards, settings or Blocks recovery. + ## 1. Layering ``` @@ -42,7 +50,7 @@ Strict rule: **UI widgets never import `lib/ble/`**, and only the `lib/pble/` cl | `lib/connect/` | Scan/connect UI, saved boards. | | `lib/github_import/` | Pull a folder of `.py` from a public GitHub repo → `Connection.putFile`. | | `lib/localization/` | `intl`/ARB strings (`en` first; parity enforced for added languages). | -| `lib/data/` | Local persistence: projects, settings, saved boards (offline-first). | +| `lib/data/` | Planned Drift persistence for projects, settings and saved boards; currently a placeholder. The bounded recovery contract is the first specified slice. | ## 3. The `Connection` API (the seam every widget binds to) @@ -76,7 +84,7 @@ Widgets receive a `Connection` (or narrow callbacks derived from it). Tests inje 1. **Scan** — `flutter_blue_plus` scan filtered to the PyBLE service UUID; show advertised `PyBLE-XXXX` names + RSSI. 2. **Connect** — open GATT, subscribe to TX notify, request MTU 247, read INFO / send HELLO, show `DeviceInfo`, including its display-only board ID and PyBLE agent firmware version. 3. **Use** — editor/console/files bind to the `Connection`. -4. **Reconnect** — on link loss, auto-reattempt; in-flight file transfers resume via PBLE/1 §5. Saved boards reconnect by remembered identifier. +4. **Reconnect — target architecture** — automatic reattempt and saved-board reconnection remain design targets. Current PBLE/1 transfer resumability does not prove automatic app reconnect or continuation; a later explicit PUT may use a firmware-provided resume offset. The [frozen working-loop record](App/TDD.md#116-working-loop-provider-contract-frozen) and current implementation govern what is actually available. The `DeviceInfo.chip` value is a port-defined technical identifier. The app renders unknown future values verbatim and continues from advertised PBLE/1 diff --git a/docs/specifications/architecture.md b/docs/specifications/architecture.md index c901a4fc..6027853d 100644 --- a/docs/specifications/architecture.md +++ b/docs/specifications/architecture.md @@ -150,7 +150,7 @@ This boundary is what makes PyBLE safe to open-source. It is also why the protoc | Firmware architecture | upstream MicroPython + protected PyBLE agent + target adapter | Vendor-neutral contract, no MicroPython fork | | Firmware (v1 reference) | MicroPython ESP32 port + ESP-IDF | Initial `esp32` / `esp32-s3` / `esp32-c3` implementation | | BLE stack (v1 reference) | NimBLE | ESP32-family implementation; future ports may use another conforming BLE peripheral stack | -| Persistence | local (sqlite/Drift or files) | Offline-first; project files & settings | +| Persistence | Planned local SQLite/Drift; current document still volatile | Offline-first target; [ADR-0010](../decisions/0010-working-loop-in-memory-document.md) rejects an ad-hoc scratch-file substitute, and [ADR-0048](../decisions/0048-bounded-current-text-draft-recovery.md) specifies the first bounded recovery slice; implementation pending | All third-party components are MIT/Apache/BSD-compatible; notices ship in `THIRD_PARTY_LICENSES`. From 94faf654e4f18e5e88dc5948de1d595d25e5f8e7 Mon Sep 17 00:00:00 2001 From: Viwat Vchirawongkwin Date: Fri, 25 Sep 2026 17:46:50 +0700 Subject: [PATCH 6/9] [docs] verify C1-S1 Android Play installation and provenance Signed-off-by: Viwat Vchirawongkwin --- .../c1-s1/06_Android_Channel_Verification.md | 127 ++++++++++++++++++ 1 file changed, 127 insertions(+) create mode 100644 docs/developments/2026-q4-reliable-workflow/c1-s1/06_Android_Channel_Verification.md diff --git a/docs/developments/2026-q4-reliable-workflow/c1-s1/06_Android_Channel_Verification.md b/docs/developments/2026-q4-reliable-workflow/c1-s1/06_Android_Channel_Verification.md new file mode 100644 index 00000000..f216e3ba --- /dev/null +++ b/docs/developments/2026-q4-reliable-workflow/c1-s1/06_Android_Channel_Verification.md @@ -0,0 +1,127 @@ + + + +# C1-S1 — physical Android channel verification + +| Field | Observed result | +|---|---| +| Date | 25 September 2026, UTC / Asia/Bangkok | +| Task | C1-S1-T02; Android part of PYB-001.2 | +| Device | Physical Lenovo TB-J616X, Android 12; connected and unlocked | +| Channel | Google Play, existing beta membership; listing explicitly describes open testing | +| Installed application | `dev.pyble.pyble`, version `0.2.0`, version code `8` | +| Result | **Done for the existing-installation verification scope:** official channel, installed identity, launch and About checked; payload-to-historical-artifact mapping established below | +| Evidence author | Codex, through ADB and the actual device UI; no independent participant or second-operator attestation | +| Related records | [Channel ledger](01_Channel_and_Artifact_Ledger.md), [execution record](00_Execution_Record.md), [historical build-8 handoff](../../../testing/google-play/0.2.0-build-8.md) | + +This retry supersedes the earlier “no connected Android device” finding. An +existing, working Play installation was present. There was no Update or Install +action offered, so no fresh enrollment, fresh installation or upgrade event was +performed. The ledger's existing-app/update branch permits this nondestructive +verification; it does not require uninstalling a user's app to manufacture a +fresh-install result. PYB-001.2 still needs the separate iPad result. + +## Actual channel and launch observations + +| Check | Actual evidence | Interpretation | +|---|---|---| +| Official listing | Opened `market://details?id=dev.pyble.pyble` explicitly in `com.android.vending`; the corresponding public listing is [Google Play](https://play.google.com/store/apps/details?id=dev.pyble.pyble) | The actual device's Play Store was used, not third-party indexing or a sideload | +| App identity | Listing displayed PyBLE: MicroPython IDE (Beta), publisher SciLabPro | Correct product listing | +| Testing state | Play showed existing beta-tester membership and said future updates would include beta versions; its update notes stated open testing for PyBLE 0.2.0 | This account/device can access the installed beta; no new opt-in was exercised | +| Available action | Open; no Update or Install action observed | Already installed/current for the offer shown to this account/device; not a global rollout claim | +| Installation source | Android package metadata reported `installerPackageName=com.android.vending`; exact package was installed, enabled, not hidden or suspended | Consistent with the observed Play-managed installation | +| Recorded installation dates | Device package metadata: first installed 22 August 2026; last updated 17 September 2026 | Historical package timestamps, not events performed during this retry | +| Play → app | Tapped Open in the actual listing; PyBLE's disconnected home screen rendered | Successful nondestructive launch from the channel | +| About | Opened About PyBLE; UI displayed `Version 0.2.0 (8)` | UI and package-manager version/build agree | +| Return | Returned from About to the app; did not initiate a BLE scan or board connection | About navigation completed without modifying editor or board content | + +No country, new-account or age eligibility test was performed. There was no +invitation prompt for this already-enrolled account. That observation does not +prove every account/country can enroll. No uninstall, clear-data, force-stop, +local build installation, rating, store submission or account-setting change +occurred. + +## Installed artifact and source provenance + +The device supplied a base APK and an `arm64-v8a` configuration split. Both were +copied read-only into the ignored evidence directory and verified with Android +SDK `apksigner`. Their package version code is `8`; the base reports version +name `0.2.0`. Both signatures verify under the same delivered-app signer. + +| Artifact / field | Actual value | +|---|---| +| Installed base APK | `1,221,421` bytes; SHA-256 `d34417d31d8c8d08fa52458f34657b5b1961cdcacb6b239bf78b8bfafa738e6a` | +| Installed `config.arm64_v8a` APK | `19,714,340` bytes; SHA-256 `f211bc7be13509a4084f4596dda010e0c39e73fb6ad8bdceefc717c6f14b748a` | +| Delivered-app signer certificate | SHA-256 `e3c1334dc7aad1ae20fe043b52c2d5638584a67a66e6a5255a87bf89f56f06d0` | +| Retained historical AAB | Rehashed during this retry: SHA-256 `ee2439589e2c2195ef4c861b524f871b0e5168e84fbea60a1cd379319c6eb5d7`, matching the 10 September handoff | +| Historical source binding | Commit `768fafe45beee7731d1a38480cc0463a2f5680cd`; app tree `27fd1a264a576e68126c38f966db328559660249`, as recorded in that handoff | +| Compiled Dart application | Installed `lib/arm64-v8a/libapp.so` SHA-256 `77108c759dc7f1668f4a1a787663629062dd6bea0db824a0eda145f17982db9a`; byte-identical to the historical AAB entry | +| Android DEX code | Installed `classes.dex` SHA-256 `6baa7d569a6ba4507f4acc52af0a98abd858ae6a3c14dabff8e1c61df73f2f4c`; byte-identical to historical `base/dex/classes.dex` | +| Compared payload set | **38/38 identical:** 35 Flutter asset files, two native libraries (`libapp.so` and `libflutter.so`) and one DEX file; none of these installed payloads lacked a historical AAB counterpart | + +The comparison hashes the uncompressed ZIP-entry bytes. Installed asset/native +paths map to the AAB's `base/` paths; `classes.dex` maps to +`base/dex/classes.dex`. This establishes a concrete payload link to the retained +build-8 artifact and its recorded source, stronger than matching a version +label alone. + +It is not a whole-artifact equality or a reproducible-build result. Play creates +and signs delivery splits, so their digests differ from the upload AAB and local +APK. Android manifests, resource tables and signing records are outside the +38-payload comparison. The delivered base/split manifests report minimum SDK +`29` and the base targets SDK `36`; the historical AAB handoff reports minimum +SDK `24`. This device-specific observation does not redefine the product's +universal OS requirement or explain the manifest transformation. Console upload +history, country targeting and the signer certificate shown in Console were +not inspected. + +## Repeatable read-only procedure + +Use the selected connected device, keep personal device/account identifiers out +of published logs, and retain complete outputs privately. + +```sh +adb -s '' shell dumpsys package dev.pyble.pyble +adb -s '' shell am start \ + -a android.intent.action.VIEW \ + -d 'market://details?id=dev.pyble.pyble' \ + -p com.android.vending +adb -s '' shell uiautomator dump /sdcard/pyble-c1-ui.xml +adb -s '' exec-out cat /sdcard/pyble-c1-ui.xml +adb -s '' exec-out screencap -p +adb -s '' shell pm path dev.pyble.pyble +adb -s '' pull '' '' +apksigner verify --print-certs '' +aapt dump badging '' +``` + +Capture the channel UI before using its Open action; then inspect About and +capture the displayed identity. Resolve each returned APK separately. Compare +only like-for-like uncompressed payload entries against the rehashed historical +AAB. The temporary device UI XML was removed after the private capture; device +coordinates and serials are intentionally omitted from this reusable procedure. + +## Retained evidence + +Raw UI XML/screenshots, package output, APKs, certificate checks and comparison +details remain under the main workspace's ignored +`local/c1-s1/2026-09-25-retry/android/`. They are not committed. Account/device +identifiers are excluded from this report. These hashes identify the actual +private captures, which may contain metadata beyond the selected public fields. + +| Capture | SHA-256 | What it establishes | +|---|---|---| +| `play-listing-first.xml` | `4ef1211ff53b935d28781d5b74fcc18c014cc734e7d6f1b06607c111c4b31934` | Actual listing, beta membership, open-testing notes and Open action | +| `play-listing.png` | `cac6d520c23637e256ed09d7086b717b6fb406c034d5db50aa2c368d6096d9b3` | Retained device screenshot of the listing | +| `app-open.xml` | `993a74964fcef3b2b57b5d50590345918d97660c3f2fd988a91fe9c4832a7ff1` | App rendered after Play's Open action | +| `app-about.xml` | `66142bb0ad9271a347ef5fbf6221872914f54e512b3dbf622561bf2a3d687266` | About identity `0.2.0 (8)` | +| `app-about.png` | `f9a07e3f092c45758a03351c755978c3cc1135f09969c07dbfdc94bea4904ad7` | Retained device screenshot of About | +| `package-dump.txt` | `fbc9d1689ca2dc590f69846e5a7dc15b862ccded5785808cbd25fa4876d57b4e` | Initial installed package/build and installer metadata | +| `package-dump-after.txt` | `2d20c4416aeced749a679d4eeb5342bf039926065aabb549ff3ba53162709639` | Package observation after the UI check | +| `payload-comparison.json` | `d6535850c912c974ba4804f90818a7c9c561682c035614181f12fc7afd533476` | All 38 entry-by-entry comparisons and artifact digest | +| `installed-00-signer.txt`, `installed-01-signer.txt` | `ad8012fcd96316866cfc8ff7a772d3e84933a2ebf15392dca54896704a9ec03f` each | Successful signature verification and identical signer output | + +The result closes Android device access and installed-channel verification for +C1-S1-T02. It does not qualify BLE behavior, firmware/profile compatibility, +draft persistence, first-install or upgrade behavior, or participant usability. +No pilot activation, human observation or PyBLE Ready reproduction is inferred. From 481b3cbda2c574bfd87cf7bc5cbf62ac922750c8 Mon Sep 17 00:00:00 2001 From: Viwat Vchirawongkwin Date: Fri, 25 Sep 2026 17:50:20 +0700 Subject: [PATCH 7/9] [docs] verify current iPad TestFlight installation for C1-S1 Signed-off-by: Viwat Vchirawongkwin --- .../c1-s1/07_iPad_Channel_Verification.md | 118 ++++++++++++++++++ 1 file changed, 118 insertions(+) create mode 100644 docs/developments/2026-q4-reliable-workflow/c1-s1/07_iPad_Channel_Verification.md diff --git a/docs/developments/2026-q4-reliable-workflow/c1-s1/07_iPad_Channel_Verification.md b/docs/developments/2026-q4-reliable-workflow/c1-s1/07_iPad_Channel_Verification.md new file mode 100644 index 00000000..6ca120f6 --- /dev/null +++ b/docs/developments/2026-q4-reliable-workflow/c1-s1/07_iPad_Channel_Verification.md @@ -0,0 +1,118 @@ + + + +# C1-S1 — physical iPad TestFlight verification + +| Field | Record | +|---|---| +| Observed | 25 September 2026, approximately 10:42–10:48 UTC / 17:42–17:48 Asia/Bangkok | +| Task / story | C1-S1-T03; iPad portion of PYB-001.2 | +| Result | **Done for verification of the current TestFlight installation**; fresh enrollment and a new installation/update were not performed | +| Device / OS | Physical `iPad16,10`; iPadOS `26.6.2`, build `23G90`; live device queries and screen captures succeeded | +| Installed app | `dev.pyble.pyble`, version `0.2.0`, build `6` | +| Distribution proof | Installed-app metadata reports `SignerIdentity = TestFlight Beta Distribution`, `beta-reports-active = true`, `get-task-allow = false`; the native TestFlight page offers the same version/build with **Open** | +| Launch | Successful nonterminating activation before and after the TestFlight inspection; captured PyBLE's disconnected screen with **No board connected** | +| Source mapping | Unresolved; no installed binary was matched to an immutable uploaded archive or source revision | +| Evidence author | Codex, direct device queries and inspection; no independent human review or usability participant is implied | +| Related | [Channel ledger](01_Channel_and_Artifact_Ledger.md), [execution record](00_Execution_Record.md), [TestFlight metadata correction](05_TestFlight_Metadata_Correction.md), [Sprint backlog](../06_Sprint_Backlogs.md) | + +This retry supersedes the earlier locked-device result for current iPad access +and installed identity. T03 asks to verify the current TestFlight installation; +the installed beta and its functioning launch satisfy that bounded task without +reinstalling an already working app. The combined PYB-001.2 story still needs its +Android evidence and explicitly retains any unperformed enrollment/install +criteria. Neither this check nor a completed task qualifies BLE, draft recovery, +the firmware matrix, or the five-participant pilot. + +## Observations and acceptance assessment + +| Check | Observed evidence | Assessment / boundary | +|---|---|---| +| Live device access | Exact PyBLE query, device details and native screenshot commands succeeded | Earlier unlock/access blocker cleared | +| Installed identity | CoreDevice and the independent installation-proxy query both report `0.2.0 (6)` | Build is observed on the device; source `pubspec.yaml` was not used to infer it | +| Existing beta access | The public invitation opened on the iPad, then its actual `itms-beta` link opened PyBLE in the native TestFlight app | Existing account can access this beta; no fresh-account eligibility or country-wide availability claim | +| Currently offered build | TestFlight shows `0.2.0`, **Build 6**, **Open**, 62 days until expiration, and 21.6 MB; release date is 27 August 2026 | No Update or Install action was offered on the observed page; the relative expiry is only a dated observation | +| TestFlight origin | Exact installed-app lookup: `TestFlight Beta Distribution`; beta reporting enabled; debugger entitlement disabled | Stronger evidence than an Open button or a matching version alone | +| Foreground launch | Two successful `devicectl` launch results and screenshots of PyBLE's disconnected screen | Launch smoke passed; About was not opened and its text is not claimed as evidence | +| Safe existing state | No uninstall, clear-data, replacement build, test runner, board connection, run, or STOP action | Existing data was not deliberately modified; draft contents and persistence were not assessed | +| Historical/source mapping | Historical build-5 handoff differs from installed build 6; no archive comparison performed | Distribution owner must bind the observed beta to retained build/archive/source evidence | +| Installation floor | Installed-app metadata reports `MinimumOSVersion = 18.0`; TestFlight build notes describe an iOS/iPadOS 15 rebuild | Reconcile the delivered variant, archive and store eligibility before claiming tested support on iPadOS 15–17 | + +CoreDevice reports `builtByDeveloper = true` and `containerAccessible = true` +for this app. Those booleans are **not** used to classify its signing origin: +the scoped installation-proxy response identifies TestFlight Beta Distribution. +Equally, the displayed **Open** action alone would not have established origin. + +The installed `MinimumOSVersion` is a fact about the metadata returned for this +device. It does not establish the universal minimum of all delivered variants, +prove an App Store Connect configuration error, or demonstrate compatibility on +an older OS. The distribution owner owns this follow-up alongside source +mapping. Current-device launch passed on iPadOS 26.6.2 despite this unresolved +cross-version question. The stale public description remains tracked in the +[metadata correction packet](05_TestFlight_Metadata_Correction.md). + +## Reproducible inspection procedure + +| Step | Operation | Result | +|---|---|---| +| 1 | Query the live device and exact `dev.pyble.pyble` bundle, including default apps | One matching app; `0.2.0 (6)` | +| 2 | Activate PyBLE without `--terminate-existing`; capture its screen | Successful launch and disconnected-screen smoke | +| 3 | Query only `com.apple.TestFlight` | Installed TestFlight `4.3.1 (681.1)` | +| 4 | Open `https://testflight.apple.com/join/yU4e8s6d` on the iPad | Public PyBLE beta invitation rendered | +| 5 | Open the invitation's actual `itms-beta://testflight.apple.com/join/yU4e8s6d` link; allow the page to finish loading; capture it | Native TestFlight offered build 6 with Open | +| 6 | Perform read-only `instproxy_lookup` for only `dev.pyble.pyble` through installed libimobiledevice | Installed signer and beta entitlements established; metadata preserved privately | +| 7 | Activate PyBLE again without termination, capture the screen, and repeat exact installed identity query | Successful smoke; installed version/build unchanged | + +Representative commands, with device identifiers and raw output paths replaced: + +```sh +xcrun devicectl device info details --device '' \ + --json-output '/device-details.json' +xcrun devicectl device info apps --device '' \ + --include-default-apps --bundle-id dev.pyble.pyble \ + --json-output '/pyble-apps.json' +xcrun devicectl device process launch --device '' \ + --json-output '/pyble-launch.json' dev.pyble.pyble +xcrun devicectl device capture screenshot --device '' \ + --destination '/pyble-launch.png' +xcrun devicectl device process openURL --device '' \ + 'https://testflight.apple.com/join/yU4e8s6d' +xcrun devicectl device process openURL --device '' \ + 'itms-beta://testflight.apple.com/join/yU4e8s6d' +``` + +Tool versions were Xcode `27.0` (`27A266a`), CoreDevice CLI `642.16`, +libimobiledevice `1.4.0`, and libplist `2.7.0`. The local read-only metadata +probe starts the standard installation-proxy service and calls +`instproxy_lookup` with the sole application ID `dev.pyble.pyble`; it neither +browses unrelated apps nor calls install/uninstall APIs. Its fresh, small C +source is retained with the raw evidence. Only selected nonpersonal fields +are published here. + +The legacy `idevicescreenshot` command failed because its screenshot service +was unavailable; native `devicectl device capture screenshot` then succeeded. +One later launch attempt put device options after the positional app argument +and returned CLI usage error `64`; the corrected command succeeded. These are +inspection-tool failures, not observed PyBLE launch failures. Initial captures +during transitions/loading were not used as final UI evidence. + +## Retained evidence + +Raw logs, plist/JSON responses, helper source and screenshots remain in the main +workspace's ignored `local/c1-s1/2026-09-25-retry/ipad/`. They contain private +device/account context and are excluded from Git. The hashes below identify +captures, not signed app binaries or a source revision. + +| Capture | SHA-256 | Purpose | +|---|---|---| +| `device-details.json` | `1b5311b7ae5d5c7d362477c06c9c7d5973bbffc43204717d975c79a1c9af1d9b` | Live model/OS and available developer services | +| `pyble-apps.json` | `e05fec8dd09a57d1ad3af88180b18cb9b692c273c344a7f86830b731508763a7` | Exact initial installed identity | +| `pyble-launch.json` | `3be33583b4da503617630396123fa191668332946be5e1ad2643ca9050385bd7` | Successful initial activation | +| `pyble-launch.png` | `a3c4501b6a8a097f86a581e48c0098d6899c9d3a0b2f995a85e0b5534c12e7ee` | Initial disconnected-screen smoke | +| `testflight-apps.json` | `3025a8cf7f77741a321c5ff7167e3cce2eb214a5d53f325ff394d972bcec2900` | Exact TestFlight app query | +| `testflight-app-settled.png` | `cc5d640c8e9ffe3f32873dcdb11bf2f8ee9ba83b20c1d0967477c6f3fe11ed53` | Loaded native PyBLE beta page and offered build | +| `pyble-installation-proxy.plist` | `442009f522d4641aad8698d730ca9b72e90cc6fbb12bc9410499c124322199d1` | Exact installed signer, beta entitlements, version and minimum OS metadata | +| `app_lookup.c` | `f0fae980df75eafc22dc595ca3dbecd1d18281461dab17932fd0f9951de9e53c` | Read-only, single-bundle metadata probe source | +| `pyble-final-launch.json` | `30c488910697ab53e74e38a8782b6a9ff7145d4cd5f99e8483e00fb0ad7079bb` | Successful activation after TestFlight inspection | +| `pyble-final-v2.png` | `1dc640507bdd80b3542534b4bca919d554d343c4d970f2206ea994cd5cabab72` | Final disconnected-screen smoke | +| `pyble-apps-final.json` | `aeac713c535d4ccf21cc7cf06b7ee8fbd43afd5c3241e673048e623463288572` | Installed identity unchanged after channel inspection | From 04604c412cd40b6fd9c9a1c0e36597d70813435b Mon Sep 17 00:00:00 2001 From: Viwat Vchirawongkwin Date: Fri, 25 Sep 2026 17:55:22 +0700 Subject: [PATCH 8/9] [docs] update C1-S1 plans from connected-device evidence Signed-off-by: Viwat Vchirawongkwin --- CHANGELOG.md | 12 ++++--- docs/README.md | 3 +- docs/ROADMAP.md | 17 ++++++--- .../02_Product_Roadmap.md | 17 +++++---- .../03_Milestones.md | 6 ++-- .../04_Sprint_Plan.md | 8 ++--- .../05_Product_Backlog_and_Stories.md | 22 ++++++------ ...E_Implementation_Plan_and_Strategy_v1.0.md | 35 ++++++++++--------- 8 files changed, 69 insertions(+), 51 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index a0fd42ef..b1e3b333 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -84,15 +84,19 @@ and submission packet do not claim Play submission, approval, or rollout. regression assertions while retaining the high/critical audit gate. - Added the reviewed Cycle 1 roadmap, milestones, Scrum working agreement, stories and Sprint Backlogs, plus C1-S1 execution evidence and operational - pilot/validation procedures. Physical installation and participant work - remain blocked; no pilot results or new release are claimed. + pilot/validation procedures. Verified existing Play 0.2.0 (8) and TestFlight + 0.2.0 (6) installations and launches on connected tablets; pilot setup and + participant evidence remain pending. No fresh enrollment, reinstall, pilot + results or new release are claimed. - Specified bounded Drift current-text recovery, local restore/discard, failure handling and document/session guards in ADR-0048 and the App contracts. Implementation remains pending; sizing requires revising the original S2 forecast. - Verified live Android open-testing wording and prepared correction of the - older public TestFlight description. Store-installed build identities remain - unverified and the TestFlight metadata change remains pending. + older public TestFlight description. Installed identities are now recorded; + Android code/assets match the retained build-8 AAB, while iPad build-6 source + mapping and a minimum-OS metadata discrepancy need distribution-owner + follow-up. The TestFlight metadata change remains pending. - Prepared Google Play open-testing listing text, reviewer hardware setup, tester instructions, data-use assessment, and reproducible store artwork with authentic screenshot provenance. Store availability remains a separate diff --git a/docs/README.md b/docs/README.md index 061eb8ae..d38c1a1a 100644 --- a/docs/README.md +++ b/docs/README.md @@ -24,7 +24,8 @@ maintainer guidance beside the source they govern. — roadmap, milestones, stories and capacity forecasts - [C1-S1 execution record](developments/2026-q4-reliable-workflow/c1-s1/00_Execution_Record.md) — channel evidence, pilot kit, recovery contract/sizing and validation recipe; - physical installation and participant work remain blocked + existing Play/TestFlight installations verified; pilot setup and participant + evidence remain pending ## Detailed specifications diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index bebd0f95..9c2cab2e 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -32,9 +32,11 @@ v0.7.0 remains non-normative and requires separate maintainer approval. ## Near term - Complete the [C1-S1 remaining evidence](developments/2026-q4-reliable-workflow/c1-s1/00_Execution_Record.md): - physical store installations, confirmed pilot ownership/setup and five real - baseline observations. The channel ledger, pilot kit, recovery design and - validation inventory are prepared; this does not complete the Sprint. + confirmed pilot ownership/setup, actual capacity and five real baseline + observations. Existing Play 0.2.0 (8) and TestFlight 0.2.0 (6) installations + and launches are verified on connected tablets; fresh enrollment/reinstallation + was not exercised. The pilot kit, recovery design and validation inventory + are prepared; this does not complete the Sprint or board qualification. - Implement the [bounded current-text recovery contract](specifications/App/current-draft-recovery.md) after replanning against its 45–72 hour working estimate for engineering, recipe, representative platform checks and follow-up. Current drafts remain @@ -45,8 +47,13 @@ v0.7.0 remains non-normative and requires separate maintainer approval. [Android publication review](testing/website/android-open-testing-2026-09-25.md) records live open-testing availability. The [prepared build-8 handoff](testing/google-play/0.2.0-build-8.md) remains a - source-specific historical record, not validation of subsequent source - changes in the installed store app. + source-specific historical record. The [current Android installation check](developments/2026-q4-reliable-workflow/c1-s1/06_Android_Channel_Verification.md) + matches 38 retained code/asset entries to that AAB; this supports its historical + source mapping, not complete binary equivalence or validation of subsequent + source changes. The [iPad check](developments/2026-q4-reliable-workflow/c1-s1/07_iPad_Channel_Verification.md) + records TestFlight build 6 with source mapping unresolved; distribution-owner + review is needed for conflicting minimum-OS metadata before making a support + claim. - Review the proposed v0.7.0 Reliable Projects scope before implementation. - Expand user-facing setup, recovery, and board-specific wiring guidance - Gather Android open-testing feedback and improve installation and recovery diff --git a/docs/developments/2026-q4-reliable-workflow/02_Product_Roadmap.md b/docs/developments/2026-q4-reliable-workflow/02_Product_Roadmap.md index 0953d56f..f82adef9 100644 --- a/docs/developments/2026-q4-reliable-workflow/02_Product_Roadmap.md +++ b/docs/developments/2026-q4-reliable-workflow/02_Product_Roadmap.md @@ -5,9 +5,9 @@ | Control | Value | |---|---| -| Status | C1-S1 repository work recorded; physical/pilot tasks blocked. Future direction remains conditional and forecasts need revision after sizing | +| Status | C1-S1 has six tasks Done, two Prepared awaiting pilot setup and four Awaiting evidence; existing channel installations verified. Future direction remains conditional and forecasts need revision after sizing | | Planning date | 25 September 2026; dates use Asia/Bangkok | -| Source | [Implementation strategy revision 1.3](../../planning/PyBLE_Implementation_Plan_and_Strategy_v1.0.md), particularly §§1, 6–9, 12, 14, and 19 | +| Source | [Implementation strategy revision 1.4](../../planning/PyBLE_Implementation_Plan_and_Strategy_v1.0.md), particularly §§1, 6–9, 12, 14, and 19 | | Inspected baseline | `main` at `23ed764b0ef88dce9720c66fbd1c0655268860cf` | | First cycle | C1: 28 September–20 December 2026; later horizons conditional through September 2028 | | Planning authority | Product Owner orders the Product Backlog; Developers forecast feasible work during Sprint Planning; names and capacity remain unassigned | @@ -32,14 +32,17 @@ continues to communicate direction without promising release dates. ## Completed baseline and remaining uncertainty -These records are inputs to planning, not new achievements of this development -cycle. The [C1-S1 record](c1-s1/00_Execution_Record.md) distinguishes completed design/evidence preparation from blocked installations and observations. Future work remains **Proposed** until explicitly selected. +These records distinguish the historical baseline from the dated device retry. +The [C1-S1 record](c1-s1/00_Execution_Record.md) records completed design/evidence +preparation and existing channel installations separately from prepared pilot +work and missing observations. Future work remains **Proposed** until explicitly +selected. | Baseline item | Recorded state at the planning date | Consequence for this roadmap | |---|---|---| | Android distribution and public copy | Google Play 0.2.0 open testing; direct live-site checks on 25 September confirm the PR #33 correction | Preserve accurate copy; newly found TestFlight description discrepancy is PYB-002.1 | -| App source and installed identity | Source `0.2.0+8`; source version alone does not identify an installed Play/TestFlight binary | PYB-001 records actual installed versions/builds and source mapping or explicit unknowns | -| iPad distribution | External TestFlight beta is the recorded channel | Verify the selected installation path and artifact evidence; do not infer production App Store availability | +| App source and installed identity | [Lenovo Android](c1-s1/06_Android_Channel_Verification.md): Play `0.2.0 (8)` with beta enrollment, Open and launch verified; 38/38 code/asset entries match the retained AAB | Evidence supports historical source `768fafe`; it is not complete binary equivalence, a Play Console record or validation of later source changes | +| iPad distribution | [iPad](c1-s1/07_iPad_Channel_Verification.md): existing TestFlight `0.2.0 (6)` with offered build, Open, launch and beta signing verified | Source mapping remains unknown; minimum-OS metadata conflict needs owner review. Fresh enrollment/reinstallation and production App Store availability are not claimed | | Existing workflow | PBLE/1 editing, files, run/stop, console, Blocks, tutorials, and reviewed import already exist | Reuse implementation and tests; improve measured failures rather than rebuild the workflow | | Firmware v0.6.1 | Owner-confirmed publication for five exact profiles; incomplete automated evidence remains visible | New qualification and compatibility claims require their own applicable evidence | | Historical issue #24 | Closed as superseded; incomplete checklist was not declared passed | Do not recreate closure as a new dependency or treat historical closure as qualification | @@ -81,7 +84,7 @@ for one maintainer. All rows in this table have status **Proposed**. **Sizing update:** recovery now has a 45–72 hour working estimate including supporting tasks. Its 60-hour S2–S4 allocation option would displace original matrix/activation work. The table above is the original sequencing baseline, not a validated selection; replan before using its delivery dates. The full matrix has its own [costed inventory](c1-s1/04_Validation_Inventory_and_Operator_Recipe.md). The [Sprint Plan](04_Sprint_Plan.md) owns detailed dates and capacity. The first -Sprint Backlog now records early C1-S1 execution and its remaining blockers; +Sprint Backlog now records early C1-S1 execution and pending pilot evidence; later allocations are forecasts requiring replanning. A milestone review neither replaces a Sprint Review nor supplies missing Definition of Done evidence. diff --git a/docs/developments/2026-q4-reliable-workflow/03_Milestones.md b/docs/developments/2026-q4-reliable-workflow/03_Milestones.md index 45520f02..134eb858 100644 --- a/docs/developments/2026-q4-reliable-workflow/03_Milestones.md +++ b/docs/developments/2026-q4-reliable-workflow/03_Milestones.md @@ -5,9 +5,9 @@ | Control | Value | |---|---| -| Status | M-01/SG0 assessed Blocked on 25 September; other milestones remain Proposed and forecast windows need replanning | +| Status | M-01/SG0 remains Blocked on 25 September by pilot ownership/cohort/setup and capacity decisions; existing channel installations verified on retry. Other milestones remain Proposed and forecast windows need replanning | | Planning date | 25 September 2026; dates use Asia/Bangkok | -| Source | [Implementation strategy revision 1.3](../../planning/PyBLE_Implementation_Plan_and_Strategy_v1.0.md), especially §§4, 8–10, 14, and 19 | +| Source | [Implementation strategy revision 1.4](../../planning/PyBLE_Implementation_Plan_and_Strategy_v1.0.md), especially §§4, 8–10, 14, and 19 | | Inspected baseline | `main` at `23ed764b0ef88dce9720c66fbd1c0655268860cf` | | Related documents | [Framework](01_Overview_and_Scrum_Framework.md), [roadmap](02_Product_Roadmap.md), [Sprint Plan](04_Sprint_Plan.md), [stories](05_Product_Backlog_and_Stories.md), [Sprint Backlogs](06_Sprint_Backlogs.md) | | Meaning | Milestones describe inspectable outcomes and decision evidence; they are not additional Scrum events or promised releases | @@ -51,7 +51,7 @@ no role in this table implies committed staffing or independent review. | M-05 — Proposed | Users can obtain the selected qualified app build through a verified existing channel | C1-S5–C1-S6, 23 Nov–20 Dec; PYB-014 and residual 002 | M-04; distribution-owner access; separate submission, availability, installed build/provenance, and installation outcome records; current user-facing claims | Verified-channel milestone passes only for the stated evidence; store delays are recorded as blockers; release owner | | M-06 — Proposed | Useful-repeat and support evidence drives one explicit next-stage investment | C1-S6, 7–20 Dec; PYB-011 follow-up, cycle review; Ready inputs only if selected | Mature consented cohort accounting, useful Task C/return outcomes, task opportunity, prompting, missing responses, support burden, and status of candidate/channel evidence; retain blocked outcomes | SG3 assessment plus dated continue/narrow/pause-expansion decision; Product Owner with pilot and Developers | -[C1-S1 evidence](c1-s1/00_Execution_Record.md) prepares the ledger, pilot protocol, recovery contract and cost model, but does not satisfy missing human ownership, confirmed capacity, device installations or participant observations. M-01/SG0 remains blocked. M-02's S2–S3 window is the original baseline; a sized S2–S4 option now requires explicit replanning, with downstream matrix/recruitment dates reviewed together. +[C1-S1 evidence](c1-s1/00_Execution_Record.md) includes the ledger, pilot protocol, recovery contract, cost model and verified existing Play/TestFlight installations. Six tasks are Done, two are Prepared awaiting pilot setup and four await participant/observation evidence. Human ownership, cohort/setup and actual capacity remain unconfirmed, so M-01/SG0 remains blocked. Missing participants are recorded as a recruitment gap, not completed observations. Current-build verification does not pass M-05 for a future qualified update. M-02's S2–S3 window is the original baseline; a sized S2–S4 option now requires explicit replanning, with downstream matrix/recruitment dates reviewed together. M-04 may occur in any Sprint once a maintenance candidate qualifies. M-03 and M-06 do not block it. M-06 can assess learning and choose a narrower next step diff --git a/docs/developments/2026-q4-reliable-workflow/04_Sprint_Plan.md b/docs/developments/2026-q4-reliable-workflow/04_Sprint_Plan.md index 0c36398f..ef30e9a5 100644 --- a/docs/developments/2026-q4-reliable-workflow/04_Sprint_Plan.md +++ b/docs/developments/2026-q4-reliable-workflow/04_Sprint_Plan.md @@ -7,7 +7,7 @@ |---|---| | Status | C1-S1 early execution recorded; original S2–S6 forecasts are not ready for selection after the new recovery/matrix estimates | | Cycle | `C1`, 28 September–20 December 2026, Asia/Bangkok | -| Basis | [Strategy revision 1.3, §8](../../planning/PyBLE_Implementation_Plan_and_Strategy_v1.0.md#8-twelve-week-implementation-schedule) | +| Basis | [Strategy revision 1.4, §8](../../planning/PyBLE_Implementation_Plan_and_Strategy_v1.0.md#8-twelve-week-implementation-schedule) | | Product Goal and quality rules | [Working agreement](01_Overview_and_Scrum_Framework.md) | | Acceptance criteria | [Product backlog and stories](05_Product_Backlog_and_Stories.md) | | Task-level proposal | [Sprint backlogs](06_Sprint_Backlogs.md) | @@ -16,7 +16,7 @@ | Planning element | Treatment | |---|---| -| `C1-S1` | Early repository execution recorded; remaining device/pilot tasks blocked. Actual staffing and the original formal timebox still require confirmation | +| `C1-S1` | Six tasks Done, including existing channel installations; two Prepared awaiting pilot setup and four Awaiting evidence. Actual staffing and the original formal timebox still require confirmation | | `C1-S2` … `C1-S6` | Forecasts revised using preceding results, capacity and learning | | Sprint Goal | One coherent outcome confirmed by the Scrum Team at Planning | | Scope and task details | Developers select feasible items and adapt their plan with the Product Owner as learning changes scope | @@ -26,14 +26,14 @@ ## C1-S1 findings and required reforecast -[Execution evidence](c1-s1/00_Execution_Record.md) records four completed repository tasks and eight blocked installation/pilot tasks. The original calendar is retained; no completed Sprint or SG0 approval is claimed. +[Execution evidence](c1-s1/00_Execution_Record.md) records six Done tasks after verifying existing Play and TestFlight installations. T04/T05 are Prepared awaiting pilot setup; T06–T08 await participants and T09 awaits observation records. These more specific states preserve their acceptance criteria. The original calendar is retained; no completed Sprint or SG0 approval is claimed. | New sizing input | Planning consequence | |---|---| | Recovery engineering 38–63h; recipe, representative physical work and one follow-up allowance bring the original two-week scope to 45–72h | Original S2 allowance is insufficient; contract and all required failure/session protections remain intact | | [Working allocation option](c1-s1/03_Recovery_Design_and_Sizing.md): S2 26h, S3 22h, S4 12h, totaling 60h | Fits within the three 26h ceilings only by replacing original selections; includes 50h engineering, 2h recipe, 5h physical and 3h rolling follow-up | | [App matrix](c1-s1/04_Validation_Inventory_and_Operator_Recipe.md): 13.5–26 operator h; fresh firmware qualification 30–59h excluding builds/access/repair | Select the applicable scope; do not treat app-only work as a new firmware release or count representative recovery runs twice | -| Missing human capacity, pilot owner and physical access | Confirm before selecting the revised scope; maintain rolling follow-up only for actual consenting activations | +| Connected tablets now verified; human capacity, pilot owner and exact-board setup still unconfirmed | Bind future recovery runs to their actual candidate and board, and confirm owners before selecting revised scope; maintain rolling follow-up only for actual consenting activations | The remaining 18h under S2–S4's combined 78h ceiling cannot silently absorb all displaced matrix, activation and repair tasks. Reorder those tasks, review the November recruitment window, and reforecast S5/S6 if required. The tables below preserve the original allowance/calendar for comparison; they are **not** an adopted revised forecast. A tested foundation is not the completed recovery user story. All selected increments still need their applicable Definition of Done. diff --git a/docs/developments/2026-q4-reliable-workflow/05_Product_Backlog_and_Stories.md b/docs/developments/2026-q4-reliable-workflow/05_Product_Backlog_and_Stories.md index 61324dd0..15a24346 100644 --- a/docs/developments/2026-q4-reliable-workflow/05_Product_Backlog_and_Stories.md +++ b/docs/developments/2026-q4-reliable-workflow/05_Product_Backlog_and_Stories.md @@ -6,10 +6,10 @@ | Control | Value | |---|---| | Product Goal | Make the existing tablet workflow trustworthy enough for useful repeat tasks by the selected primary audience | -| Source | [Implementation strategy revision 1.3](../../planning/PyBLE_Implementation_Plan_and_Strategy_v1.0.md), reviewed 25 September 2026 | +| Source | [Implementation strategy revision 1.4](../../planning/PyBLE_Implementation_Plan_and_Strategy_v1.0.md), reviewed 25 September 2026 | | Cycle | Proposed 28 September–20 December 2026; Asia/Bangkok | | Baseline | `23ed764b0ef88dce9720c66fbd1c0655268860cf`; completed publication work is evidence, not a new commitment | -| Status | C1-S1 execution recorded: PYB-001.1 and PYB-006.1 documentation scope Done; pilot/install stories blocked, PYB-009.1 partial; other work remains forecast | +| Status | C1-S1: PYB-001.1/.2 and PYB-006.1 scoped work Done; pilot preparation awaits setup, observation work awaits evidence, PYB-009.1 partial; other work remains forecast | | Accountabilities | Product Owner orders the backlog; Developers size and select work in Sprint Planning; named people and capacity remain to be assigned | | Navigation | [Overview and Scrum](01_Overview_and_Scrum_Framework.md) · [Roadmap](02_Product_Roadmap.md) · [Milestones](03_Milestones.md) · [Sprint plan](04_Sprint_Plan.md) · [Sprint Backlogs](06_Sprint_Backlogs.md) | @@ -32,10 +32,10 @@ | Order | Parent / source priority | Intended outcome | Proposed slices | Forecast / dependency | Current state | |---|---|---|---|---|---| -| 1 | PYB-001 / P0 | Know what users can install and which artifacts they receive | 001.1, 001.2 | C1-S1; existing publication review | 001.1 Done; 001.2 Blocked; physical installation/provenance unverified | +| 1 | PYB-001 / P0 | Know what users can install and which artifacts they receive | 001.1, 001.2 | C1-S1; existing publication review | 001.1/.2 Done for ledger and existing channel-install verification; provenance limits remain explicit | | — | PYB-002 / P0 accuracy | Keep maintained availability claims correct | 002.1: public TestFlight description | PR #33 Android correction complete; residual found during 001 | Correction packet prepared; actual store update/public verification pending | -| 2 | PYB-003 / P0 | Conduct a safe, consented pilot with bounded data collection | 003.1 | C1-S1; 001 informs setup | Protocol prepared; human collection decision blocked | -| 3 | PYB-004 / P0 | Observe one reachable audience completing reproducible, useful tasks | 004.1, 004.2 | C1-S1; 001, 003 | Task kit prepared; cohort/setup and observations blocked | +| 2 | PYB-003 / P0 | Conduct a safe, consented pilot with bounded data collection | 003.1 | C1-S1; 001 informs setup | Prepared — awaiting pilot setup and named collection decision | +| 3 | PYB-004 / P0 | Observe one reachable audience completing reproducible, useful tasks | 004.1, 004.2 | C1-S1; 001, 003 | 004.1 Prepared — awaiting cohort/setup; 004.2 Awaiting participant evidence | | 4 | PYB-006 / P0 | Recover the current text draft after process restart | 006.1, 006.2 | Sized in C1-S1; S2–S4 working option requires replanning; known defect does not wait for recruitment | 006.1 Done; 006.2 implementation pending | | 5 | PYB-009 / P0 | Make existing validation reproducible by an operator | 009.1; optional 009.2 | Inventory C1-S1, scoped recipe C1-S2; reproduction only with assigned capacity | T12 Done; 009.1 remains partial | | 6 | PYB-005 / P0 if observed | Remove a demonstrated first-use blocker | 005.1 | C1-S2 candidate; actual 004 findings | Conditional; no defect invented | @@ -56,10 +56,10 @@ The completed portion of PYB-002 is [PR #33](https://github.com/PyBLE-dev/PyBLE/ | Item | Actual state | Evidence / next action | |---|---|---| | PYB-001.1 | Done for the ledger scope | [Ledger](c1-s1/01_Channel_and_Artifact_Ledger.md); unknown fields have responsible owners/actions | -| PYB-001.2 | Blocked | No Android device; iPad app query locked; enrollment/install/build mapping remain unverified | -| PYB-002.1 | Prepared; store correction pending | New TestFlight description discrepancy; no claim of external mutation | -| PYB-003.1 / PYB-004.1 | Blocked; protocol/task cards prepared | [Pilot kit](c1-s1/02_Pilot_Protocol_and_Observation_Kit.md); human owner, cohort/setup and collection decision missing | -| PYB-004.2 / PYB-011.2 | No observations collected | Five baseline starts and all later follow-up remain outstanding | +| PYB-001.2 | Done for existing channel installations | [Lenovo Play `0.2.0 (8)`](c1-s1/06_Android_Channel_Verification.md) and [iPad TestFlight `0.2.0 (6)`](c1-s1/07_iPad_Channel_Verification.md): channel/Open/launch and installed identity verified. No fresh enrollment or reinstall; Android code/asset comparison supports historical source mapping, iPad mapping remains unknown | +| PYB-002.1 | Prepared; store correction pending | Public TestFlight description remains discrepant; build-6 minimum-OS metadata also needs distribution-owner review. No claim of external mutation | +| PYB-003.1 / PYB-004.1 | Prepared — awaiting pilot setup | [Pilot kit](c1-s1/02_Pilot_Protocol_and_Observation_Kit.md); technical review completed, but human owner, reachable cohort, tested board setup and collection decision remain missing | +| PYB-004.2 / PYB-011.2 | Awaiting participant/observation evidence | T06–T08 await participant sessions; T09 awaits their records. Five baseline starts and all later follow-up remain outstanding | | PYB-006.1 | Done for design/review/sizing | [Contract and review](c1-s1/03_Recovery_Design_and_Sizing.md); PYB-006.2 implementation remains pending; revised allocation needed | | PYB-009.1 | Partial | T12 [inventory/cost model](c1-s1/04_Validation_Inventory_and_Operator_Recipe.md) complete; S2 scoped procedure and subsequent operator results still pending | @@ -67,7 +67,7 @@ The ordered table above retains original priorities and forecast labels. It is n ## 3. Detailed first-cycle stories and enablers -Acceptance criteria below remain the completion authority. The [C1-S1 execution record](c1-s1/00_Execution_Record.md) reports actual outcomes; its evidence does not turn pending installation, recruitment or runtime work into Done. Role names identify needed skills; actual future assignments remain to be confirmed. +Acceptance criteria below remain the completion authority. The [C1-S1 execution record](c1-s1/00_Execution_Record.md) reports actual outcomes; verified existing installations do not complete recruitment, board qualification or runtime recovery. Prepared and Awaiting evidence are descriptive unfinished states, not waived criteria. Role names identify needed skills; actual future assignments remain to be confirmed. ### 3.1 Distribution and pilot preparation @@ -75,7 +75,7 @@ Acceptance criteria below remain the completion authority. The [C1-S1 execution |---|---|---|---| | PYB-001.1 / Release enabler / Release | Establish a reviewed channel and artifact ledger | Separate publication, installation, provenance and qualification fields; record evidence/date/platform/channel/build; each unknown has an owner and next action; distinguish uploaded AAB/IPA identity from installed or re-signed artifacts | Existing dated publication review; reviewer checks ledger against first-party evidence. A completed ledger does not make an unknown installation pass | | PYB-002.1 / Publication enabler / Distribution owner | Correct the stale app-level public TestFlight description | Verify the actually offered build supports the claims; apply accurate capability-defined copy through the owner-controlled channel; retain actual metadata update and dated public verification; do not relabel historical build notes or imply untested compatibility | Discovered in 001.1; [prepared correction](c1-s1/05_TestFlight_Metadata_Correction.md). Packet prepared only; store operation needs access and explicit capacity selection | -| PYB-001.2 / User story / Release + QA | As a tablet-owning maker, I can follow the existing channel's installation path so I can start using PyBLE | Perform enrollment/install on eligible physical Android and iPad devices for the declared scope; record served version/build, observed restrictions and installation outcome; source mapping is evidenced or explicitly unresolved; instructions reproduce observed steps | 001.1 and channel/device access; dated physical installation records. Missing access or a failed install remains blocked/failed, not a completed successful installation | +| PYB-001.2 / User story / Release + QA | As a tablet-owning maker, I can follow the existing channel's installation path so I can start using PyBLE | Verify an eligible physical Android and iPad channel installation: perform enrollment/install where needed, or verify the existing channel-installed app without erasing user data. Record channel/enrollment state where observable, served and installed version/build, restrictions and successful launch; source mapping is evidenced or explicitly unresolved; instructions reproduce observed steps and distinguish existing-install verification from fresh enrollment/reinstallation | 001.1 and channel/device access; dated physical installation records. Existing-install evidence requires channel provenance and launch, not package inventory alone. Missing access or failed installation/launch remains blocked/failed; no fresh-install or enrollment completion is inferred | | PYB-003.1 / Governance enabler / Lead + QA | Approve a bounded pilot that protects participants and their data | Identify trusted setting, harmless loads and wrong-board containment; explain STOP limitations and lack of authenticated ownership; approve consent, assistance/safety rules, contact separation and deletion policy; review a manual support template excluding sensitive content by default | Recorded 001 setup; named pilot decision-maker signs the scoped decision before collection. No background analytics or automatic source/console upload | | PYB-004.1 / Research enabler / Pilot lead | Define one reachable cohort and tasks that reveal product value | Name primary audience, recruitment owner, reference setup and previous-workflow questions; separate Tasks A/B/C; fix eligibility, written guidance, assistance, timeout and exclusions prospectively; define follow-up linkage, prompting and opportunity-to-use questions | 001 and 003.1; reviewed task/observation protocol. Instructor cohort may replace the maker default by a recorded prospective choice | | PYB-004.2 / Research enabler / Pilot lead | Observe five baseline participants before choosing a first-use change | Record five eligible started Task A outcomes, including failures, abandonment and assistance; retain build/task/OS/profile identity; record useful Task C attempts and reasons to choose PyBLE; identify actionable friction or no observed blocker | 004.1 and recorded tested setup; redacted observations and synthesis. Recruitment shortfall is reported as a blocker, not five completed observations | diff --git a/docs/planning/PyBLE_Implementation_Plan_and_Strategy_v1.0.md b/docs/planning/PyBLE_Implementation_Plan_and_Strategy_v1.0.md index 1655284e..ab6ff9fb 100644 --- a/docs/planning/PyBLE_Implementation_Plan_and_Strategy_v1.0.md +++ b/docs/planning/PyBLE_Implementation_Plan_and_Strategy_v1.0.md @@ -11,10 +11,10 @@ | Field | Value | |---|---| -| Document version | 1.3 — C1-S1 execution, evidence and sizing update; original filename retained | +| Document version | 1.4 — C1-S1 device retry and precise remaining states; original filename retained | | Prepared | 25 September 2026 | -| Last reviewed | 25 September 2026; C1-S1 worktree deliverables, real access blockers and revised sizing incorporated | -| Status | C1-S1 repository work executed under the user request; device/pilot tasks remain blocked. Future capacity and scope need replanning; no new protocol behavior approved | +| Last reviewed | 25 September 2026; connected Lenovo/iPad channel verification and remaining pilot dependencies incorporated | +| Status | C1-S1 has six tasks Done, two Prepared awaiting pilot setup and four Awaiting evidence; Sprint and SG0 remain unfinished. Future capacity and scope need replanning; no new protocol behavior approved | | Product | PyBLE — Python over Bluetooth Low Energy | | Organization | SciLabPro | | Planning horizon | Immediate 12-week delivery cycle, followed by conditional expansion through September 2028 | @@ -26,7 +26,7 @@ **Scope of this document.** This plan converts the preceding PyBLE strategy discussion into executable workstreams, priorities, acceptance criteria, and decision gates. Existing repository specifications and contributor rules remain authoritative. Proposed features, names, metrics, staffing, and dates below are planning choices—not claims that those features exist or that resources and approvals are secured. -**Evidence boundary.** The baseline review inspected repository source, specifications, test entry points, publication records, and the GitHub state of PR #33 and issue #24 on 25 September. Revision 1.2 incorporates the subsequent strategy and PyBLE Ready feedback. The dated Android review establishes the official listing's open-testing status; it does not identify the installed store binary or prove a signed-in installation. Revision 1.3 adds direct live-channel/website checks and a blocked physical iPad app query in the [C1-S1 ledger](../developments/2026-q4-reliable-workflow/c1-s1/01_Channel_and_Artifact_Ledger.md). No successful store installation, participant outcome or new physical-board result has been measured. Previously reported publicity and GitHub counts are not proof of product-market fit.[^android-review] +**Evidence boundary.** The baseline review inspected repository source, specifications, test entry points, publication records, and the GitHub state of PR #33 and issue #24 on 25 September. Revision 1.2 incorporates the subsequent strategy and PyBLE Ready feedback. The dated Android publication review establishes listing status only. Revision 1.3 records direct live-channel/website checks and the original unavailable/locked device attempts. Revision 1.4 adds the connected-device retry in the [C1-S1 ledger](../developments/2026-q4-reliable-workflow/c1-s1/01_Channel_and_Artifact_Ledger.md): existing Play `0.2.0 (8)` and TestFlight `0.2.0 (6)` installations and launches verified. Fresh enrollment/reinstallation was not performed. Android's code/asset comparison supports historical source mapping; iPad source mapping remains unknown. No participant outcome or new physical-board result has been measured. Previously reported publicity and GitHub counts are not proof of product-market fit.[^android-review] **Continuation decision.** Carry forward the completed Android publication/copy correction. Concentrate weekly execution on three outcomes: verify what users install, preserve their work through interruptions, and observe useful repeat tasks in one primary audience. Reuse existing lifecycle handling, tutorials, conformance fixtures, and release tooling. A bounded PyBLE Ready rehearsal can reuse one existing profile's evidence work; new ports, broad badge promotion, classroom bundles, and new protocol behavior remain conditional. @@ -36,6 +36,7 @@ | 1.1 | Updated baseline after PR #33; separated publication from installed-build evidence; mapped remaining work to current code; bounded the schedule and corrected release/pilot dependencies | | 1.2 | Focused pilot selection and useful second tasks; contextualized retention; defined one version-bound PyBLE Ready badge, installation labels, maintenance rules, and a staged existing-profile/partner pilot | | 1.3 | Executed C1-S1 repository deliverables in parallel worktrees; recorded device/pilot blockers, stale TestFlight metadata, a bounded recovery contract and larger engineering/matrix estimates; future allocations require replanning | +| 1.4 | Verified existing Play/TestFlight installations on connected tablets; recorded artifact evidence and remaining provenance/metadata limits; replaced blanket pilot blockers with Prepared/Awaiting evidence states without waiving acceptance criteria | ## Contents @@ -137,9 +138,9 @@ Use the following dated baseline instead of restarting the publication correctio | Item | Status as reviewed on 25 September 2026 | Remaining work | |---|---|---| -| Android listing | Official Google Play listing for `dev.pyble.pyble` identifies 0.2.0 and open testing | Verify eligible-device enrollment/install and record version code, source mapping, and restrictions actually observed | +| Android listing / installation | Official Play listing identifies 0.2.0 open testing; retry verifies an enrolled Lenovo device's existing `0.2.0 (8)` installation and launch | Record existing-install scope; retain code/asset comparison and its provenance limits; no fresh enrollment/reinstall or universal availability claim | | Maintained public copy | PR #33 merged at `23ed764`; README, roadmap, website copy/metadata, setup guidance, and distribution contract now agree | Maintain those checks; search-engine recrawl timing remains outside project control | -| iPad channel | Maintained first-party guidance identifies the external TestFlight beta | Record the currently installable version/build and a fresh eligible-device installation; do not infer it from source | +| iPad channel / installation | Retry verifies the external TestFlight beta's offered/installed `0.2.0 (6)` and launch on iPad | Source mapping remains unresolved; review conflicting minimum-OS metadata. Existing-install verification does not claim a fresh enrollment/reinstall | | Firmware v0.6.1 | Published on owner confirmation; five exact profiles; original artifact/evidence records preserved | New qualification must cite exact tested bytes; pending automated rows remain pending | | Issue #24 | Closed on 13 September 2026 as superseded (`NOT_PLANNED`) | Create a focused successor only for selected new work; do not reopen the obsolete release umbrella or mark its checklist complete | | Product usage | No measured activation or retention baseline in this revision | Collect the bounded, consented evidence defined in §§4 and 12 | @@ -152,18 +153,20 @@ Historical release-roadmap statements about an unpublished v0.6.1 or an open #24 ### 2.3 C1-S1 execution evidence — 25 September 2026 -The [execution record](../developments/2026-q4-reliable-workflow/c1-s1/00_Execution_Record.md) separates four completed repository tasks from eight blocked installation/pilot tasks. Early execution does not retrospectively change the proposed 28 September Sprint start or claim a staffed-team ceremony. +The [execution record](../developments/2026-q4-reliable-workflow/c1-s1/00_Execution_Record.md) now records **six Done tasks**, **two Prepared awaiting pilot setup** and **four Awaiting evidence** after the connected-device retry. T02/T03 verify existing channel installations; T04/T05 need the named owner, cohort and tested board setup, T06–T08 need participant sessions, and T09 needs their observation records. Early execution does not retrospectively change the proposed 28 September Sprint start or claim a staffed-team ceremony. -| Workstream | Completed repository output | Remaining requirement | +| Workstream | Completed output / evidence | Remaining requirement | |---|---|---| -| PYB-001 | Reviewed channel/artifact ledger; direct Play/TestFlight/site HTTP checks; responsible owners for unknowns | Android device unavailable; paired iPad app query blocked while locked; store-installed builds and source mapping unverified | -| Residual PYB-002.1 | Accurate replacement TestFlight app-level description prepared after the public page exposed its older ESP/agent-0.4.0 baseline | Distribution owner must apply it and verify the public result; Android's earlier correction remains complete | +| PYB-001 | Reviewed ledger; [Lenovo Play `0.2.0 (8)`](../developments/2026-q4-reliable-workflow/c1-s1/06_Android_Channel_Verification.md) and [iPad TestFlight `0.2.0 (6)`](../developments/2026-q4-reliable-workflow/c1-s1/07_iPad_Channel_Verification.md) existing installations, channel/Open and launch verified | iPad build-to-source mapping remains unknown; Android code/asset correspondence does not establish complete binary equivalence or store-console provenance. Fresh enrollment/reinstallation was not performed | +| Residual PYB-002.1 | Accurate replacement TestFlight app-level description prepared after the public page exposed its older ESP/agent-0.4.0 baseline | Distribution owner must apply it and verify the public result; also reconcile build-6 installed `MinimumOSVersion` 18 with TestFlight notes stating 15 before asserting support. No store mutation performed; Android's earlier correction remains complete | | PYB-003/004 | Operational pilot protocol, safe Tasks A/B/C, consent/retention rules and empty observation/support templates | Human owner, reachable cohort, tested setup and collection decision unconfirmed; no participants or observed outcomes | | PYB-006.1 | [Recovery contract](../specifications/App/current-draft-recovery.md), ADR-0048, source/peer review, scenario matrix and estimate | Runtime implementation pending; broader A-24/Blocks scope remains carried | | PYB-009.1 | Existing tool/gate inventory, ten platform/profile rows, cost model and initial operator recipe; 110 focused host harness tests pass | S2 scoped procedure, hardware/operator access, actual physical runs and independent reproduction remain pending | The recovery estimate is **38–63 engineering hours**, or **45–72 hours** with the original recipe, representative-platform and follow-up allowances. The [design review](../developments/2026-q4-reliable-workflow/c1-s1/03_Recovery_Design_and_Sizing.md) offers a conditional 60-hour S2–S4 allocation, displacing earlier matrix and activation forecasts. The [validation inventory](../developments/2026-q4-reliable-workflow/c1-s1/04_Validation_Inventory_and_Operator_Recipe.md) estimates 13.5–26 operator hours for the app matrix and 30–59 for fresh full firmware qualification, excluding builds, unavailable access and defect repair. These are working estimates, not actual effort or promises. **SG0 remains blocked.** +The Android check used a Lenovo `TB-J616X` on Android 12; all 38 selected code/asset entries matched the retained build-8 AAB, supporting its historical source `768fafe45beee7731d1a38480cc0463a2f5680cd`. This comparison is narrower than complete installed-binary or Play Console provenance. The iPad was `iPad16,10` on iPadOS `26.6.2`; native TestFlight offered build 6, Open launched it, and the installed signer identity was `TestFlight Beta Distribution`. The historical build-5 handoff does not map build 6 to source. Neither check executes BLE/board qualification or establishes minimum-OS support. + ### 2.4 Baseline metrics to collect Record current store channels, download buckets where visible, repository engagement, issue authorship, and existing third-party demonstrations. Establish separate counts for maintainers, project-recruited testers, classroom participants, and independently arriving users. @@ -316,7 +319,7 @@ Map these ownership areas to the three active outcomes in §1.5. W1–W3 contain Extend the existing publication review into one reviewed channel/artifact record. Distinguish prepared, submitted, processing, testing, production, paused, and unavailable states. Record the source of each state and its last verification date. Document country, account, and device restrictions when known; do not imply universal availability from a single successful store-page fetch. Keep existing website copy/link checks; introduce a generated shared data source only if repeated drift warrants that extra machinery. -Deliverables: channel/build matrix, verified installation instructions, maintained README/store/site consistency, store-artifact provenance, and an update/rollback procedure. Accept the listing-status row from dated first-party publication evidence. Accept the installation row only after installation through that channel on an eligible physical device. Record uploaded AAB/IPA identity separately from store-delivered/re-signed or split binaries; equal version names or unequal upload/install hashes alone do not resolve provenance. +Deliverables: channel/build matrix, verified installation instructions, maintained README/store/site consistency, store-artifact provenance, and an update/rollback procedure. Accept the listing-status row from dated first-party publication evidence. Accept an installation row from an actual channel installation on an eligible physical device, either performed during the check or verified as an existing installation through channel provenance, observed version/build and successful launch. State which path was exercised; do not erase user data merely to repeat installation or infer fresh enrollment from an existing account. Record uploaded AAB/IPA identity separately from store-delivered/re-signed or split binaries; equal version names or unequal upload/install hashes alone do not resolve provenance. ### W2 — First use and mobile resilience @@ -467,7 +470,7 @@ Current execution states and the newly identified residual `PYB-002.1` are maint Split any issue that combines several independently releasable behaviors or cannot fit into one sprint. Do not assign opcode numbers, capabilities, schemas, or release numbers in issue text without linking their approved specification. -Before scheduling each selected item, add its named owner/reviewer, estimate including validation, normative references, evidence location, release lane, and current state (`completed`, `ready`, `in_progress`, `blocked`, or `proposed`). Status belongs to a specific deliverable: PR #33 completion does not complete installed-build verification, and an approved design does not complete its implementation. +Before scheduling each selected item, add its named owner/reviewer, estimate including validation, normative references, evidence location, release lane, and current state (`completed`, `ready`, `in_progress`, `blocked`, or `proposed`). Prepared and Awaiting evidence may explain unfinished task states more precisely; neither means Done or waives acceptance criteria. Status belongs to a specific deliverable: PR #33 completion does not complete installed-build verification, and an approved design does not complete its implementation. ## 10. Quality, compatibility, and release gates @@ -855,7 +858,7 @@ At cycle end, choose one principal next investment: Reliable Projects, partner p - [x] Identify A-24/ADR-0010 durable drafts as a concrete remaining engineering gap. - [ ] Confirm one reachable primary audience, recruitment owner, previous workflow and meaningful Task C; keep other audiences exploratory. - [ ] Assign actual capacity and accept a bounded first sprint; size persistence and mandatory physical work before promising the full cycle. -- [x] Record PYB-001's installation/provenance blockers and responsible maintainer/operator actions in the channel ledger; actual installations remain blocked. +- [x] Verify existing Play/TestFlight installations and launches on the connected tablets; record actual builds, provenance limits and responsible owner follow-up. Fresh enrollment/reinstallation was not exercised. - [x] Link PYB-001/003/004/006/009 execution tasks and evidence in the local Scrum package; record the real residual TestFlight discrepancy as PYB-002.1. Preserve A-24/ADR identities; no GitHub issues were fabricated or created. - [ ] Assign one owner and one review path for each initial issue. - [ ] Inventory exact test boards, tablets, cables, and available recovery equipment. @@ -929,11 +932,11 @@ Work on one accepted PyBLE issue only. ### 20.4 Decision record for every sprint -[C1-S1 execution and decision record](../developments/2026-q4-reliable-workflow/c1-s1/00_Execution_Record.md) is the first dated instance. Its blockers remain open and it is not a completed Sprint Review. +[C1-S1 execution and decision record](../developments/2026-q4-reliable-workflow/c1-s1/00_Execution_Record.md) is the first dated instance. Device installation checks are complete; pilot setup, participant evidence and capacity decisions remain pending. It is not a completed Sprint Review. Record shipped versus proposed work; exact tested artifacts; pass/fail/not-run results; the selected audience and useful-task outcomes; reasons to choose PyBLE; opportunity-to-use and prompting context; maintenance/support burden; and one explicit next-sprint priority. Include Ready rehearsal/record status only when that work is selected. Store identities and participant data separately from public aggregate reports. -**Next action:** confirm one primary audience and useful task, finish the installed-build record, and replan/select implementation against the specified bounded A-24 recovery contract and its recorded estimate. Observe useful work and follow-up alongside delivery of the smallest qualified maintenance change. Reuse operator work for a bounded existing-profile Ready rehearsal if capacity is assigned. Let task failures, repeat value, and support effort determine subsequent protocol, partner, or classroom investment. +**Next action:** confirm one primary audience, pilot owner, tested board setup and useful task; pursue recorded provenance/metadata follow-up; and replan/select implementation against the specified bounded A-24 recovery contract and its estimate. Observe useful work and follow-up alongside delivery of the smallest qualified maintenance change. Reuse operator work for a bounded existing-profile Ready rehearsal if capacity is assigned. Let task failures, repeat value, and support effort determine subsequent protocol, partner, or classroom investment. ## 21. Source references @@ -968,4 +971,4 @@ The strategy supplies the proposed direction. The sources below ground the exist --- -**End of document — PyBLE Implementation Plan and Development Strategy, revision 1.3** +**End of document — PyBLE Implementation Plan and Development Strategy, revision 1.4** From 9a54bba94303a844cddde11c58fdaabeb05c589c Mon Sep 17 00:00:00 2001 From: Viwat Vchirawongkwin Date: Fri, 25 Sep 2026 17:58:05 +0700 Subject: [PATCH 9/9] [docs] reconcile C1-S1 device retry and remaining pilot work Signed-off-by: Viwat Vchirawongkwin --- .../01_Overview_and_Scrum_Framework.md | 16 +++--- .../06_Sprint_Backlogs.md | 25 +++++---- .../c1-s1/00_Execution_Record.md | 55 +++++++++++++------ .../c1-s1/01_Channel_and_Artifact_Ledger.md | 29 +++++----- .../02_Pilot_Protocol_and_Observation_Kit.md | 16 +++--- ...alidation_Inventory_and_Operator_Recipe.md | 30 +++++----- .../05_TestFlight_Metadata_Correction.md | 7 ++- .../c1-s1/06_Android_Channel_Verification.md | 3 +- .../c1-s1/07_iPad_Channel_Verification.md | 7 ++- ...E_Implementation_Plan_and_Strategy_v1.0.md | 2 +- 10 files changed, 111 insertions(+), 79 deletions(-) diff --git a/docs/developments/2026-q4-reliable-workflow/01_Overview_and_Scrum_Framework.md b/docs/developments/2026-q4-reliable-workflow/01_Overview_and_Scrum_Framework.md index 7ee16d95..3266428b 100644 --- a/docs/developments/2026-q4-reliable-workflow/01_Overview_and_Scrum_Framework.md +++ b/docs/developments/2026-q4-reliable-workflow/01_Overview_and_Scrum_Framework.md @@ -9,10 +9,10 @@ |---|---| | Package | PyBLE 2026 Q4 reliable workflow, Cycle 1 (`C1`) | | Prepared | 25 September 2026; Asia/Bangkok | -| Strategy | [Implementation Plan, revision 1.3](../../planning/PyBLE_Implementation_Plan_and_Strategy_v1.0.md) | +| Strategy | [Implementation Plan, revision 1.4](../../planning/PyBLE_Implementation_Plan_and_Strategy_v1.0.md) | | Repository baseline | `23ed764b0ef88dce9720c66fbd1c0655268860cf` | | Proposed cycle | 28 September–20 December 2026; six two-week Sprints | -| Status | C1-S1 execution initiated on 25 September; repository deliverables prepared and physical/pilot work blocked. Later Sprints require replanning against new sizing; no staffed-team ceremony is inferred | +| Status | C1-S1 device retry on 25 September: six tasks Done, two Prepared and four Awaiting evidence; both current channel installations verified, pilot work unfinished. Later Sprints require replanning against new sizing; no staffed-team ceremony is inferred | | Primary audience | Tablet-owning makers, provisionally; confirm one reachable cohort before observation | | Authoritative contracts | [Contributor rules](../../../AGENTS.md), [App specification](../../specifications/App/specs.md), [App TDD](../../specifications/App/TDD.md), [PBLE/1](../../specifications/protocol.md), and applicable firmware/release specifications | @@ -32,7 +32,7 @@ This package derives execution views from the strategy. It does not replace norm ```mermaid flowchart LR - Strategy["Strategy revision 1.3"] --> Goal["One Product Goal"] + Strategy["Strategy revision 1.4"] --> Goal["One Product Goal"] Goal --> Roadmap["Outcome roadmap and milestones"] Roadmap --> Product["Ordered Product Backlog"] Product --> Planning["Sprint Planning"] @@ -58,7 +58,7 @@ flowchart LR | Baseline fact | Consequence | |---|---| | Android open-testing copy correction is complete in PR #33 | Do not replan that correction; identify any new discrepancy separately | -| App source is `0.2.0+8`; Play publicly identifies `0.2.0`; iPad remains external TestFlight beta | Source version does not prove the installed store binary or its source commit | +| App source is `0.2.0+8`; physical retry verifies Play `0.2.0 (8)` and TestFlight `0.2.0 (6)` | Android payloads map to the historical build-8 bundle; iPad source mapping remains unknown. Neither channel check proves BLE or older-OS compatibility | | Firmware v0.6.1 is published on owner confirmation across five exact profiles | Pending automated results stay pending; no automatic PyBLE Ready badge | | Issue #24 is closed/superseded | Do not resurrect its old release umbrella as a dependency | | Editor draft is volatile under [ADR-0010](../../decisions/0010-working-loop-in-memory-document.md) | Close an accepted subset of A-24; do not claim full project persistence or Blocks recovery | @@ -107,7 +107,7 @@ Readiness is a local refinement aid. It does not replace Sprint Planning or add | Claims have evidence | Exact artifacts, pass/fail/not-run states, limitations and pending release work recorded truthfully | | Documentation/discovery scope is complete | Usable reviewed record/guide or agreed findings, source/link checks, and explicit unmet targets; no invented physical results | -This is the proposed package-wide minimum; accepted normative requirements remain binding. Apply it to the selected item rather than treating a source merge as a finished feature. A documentation or discovery item can be Done with a negative finding, while a required physical-installation task cannot be Done if no installation happened. A usable Sprint 1 documentation increment should help an operator or user perform the current workflow; an internal plan alone is not evidence of improved app behavior. +This is the proposed package-wide minimum; accepted normative requirements remain binding. Apply it to the selected item rather than treating a source merge as a finished feature. A documentation or discovery item can be Done with a negative finding, while a required channel-installation verification task needs observed installation identity, origin and launch; verifying an existing installation does not imply a fresh install. A usable Sprint 1 documentation increment should help an operator or user perform the current workflow; an internal plan alone is not evidence of improved app behavior. | State distinction | Meaning | |---|---| @@ -128,7 +128,7 @@ Unfinished items return to the Product Backlog for reordering and replanning. Do | `C1-S1` … `C1-S6` | This cycle's Sprints; distinct from historical App TDD Sprint labels | | `C1-S1-T01`, etc. | Task identities with recorded early C1-S1 outcomes; later task rows remain forecasts, not new public contracts | | `M-01`, etc.; `SG0` … `SG6` | Delivery milestones versus strategy gates; neither replaces CI G0/G1 or C3 firmware gates | -| Item/task status | Proposed → Selected at Planning → In progress → Review → Done; Blocked records a reason/owner; later forecasts remain Proposed | +| Item/task status | Proposed → Selected at Planning → In progress → Review → Done. Prepared means a reviewed partial deliverable; Awaiting evidence identifies an unperformed observation/session. Both remain unfinished. Blocked names a concrete impediment/owner; later forecasts remain Proposed | | Private versus public records | Contact/consent, device identifiers and raw logs remain private/ignored; publish only reviewed aggregate findings and redacted evidence | When facts or priority change, update the canonical file above and its dependent tables together. Preserve old evidence and dated decisions. New opcode/capability values, hardware support, Ready awards, and publication need their normal specification and authorization paths; none is inferred from this package. @@ -137,9 +137,9 @@ When facts or priority change, update the canonical file above and its dependent | Source | Use and precedence | |---|---| -| [Strategy revision 1.3](../../planning/PyBLE_Implementation_Plan_and_Strategy_v1.0.md) | Scope, targets, six-Sprint capacity, three outcomes, Ready program and conditional horizons | +| [Strategy revision 1.4](../../planning/PyBLE_Implementation_Plan_and_Strategy_v1.0.md) | Scope, targets, six-Sprint capacity, three outcomes, Ready program and conditional horizons | | [Public roadmap](../../ROADMAP.md), [README](../../../README.md) | Current capability and distribution baseline | | [App specification](../../specifications/App/specs.md), [App TDD](../../specifications/App/TDD.md), [ADR-0010](../../decisions/0010-working-loop-in-memory-document.md) | Persistence contract and recorded implementation deviation; consult frozen working-loop scope | | [Firmware roadmap](../../planning/firmware-v0.6.1-v0.7.0-roadmap.md), [PBLE/1](../../specifications/protocol.md) | v0.7 proposals versus frozen wire behavior; old v0.6.1 publication/#24 wording is historical | -| [Android publication review](../../testing/website/android-open-testing-2026-09-25.md), [v0.6.1 publication record](../../testing/firmware-v0.6.1-publication-2026-09-11.md) | Dated evidence; neither establishes a newly installed binary or missing automated qualification | +| [Android publication review](../../testing/website/android-open-testing-2026-09-25.md), [v0.6.1 publication record](../../testing/firmware-v0.6.1-publication-2026-09-11.md) | Dated publication evidence, separate from the new [Android](c1-s1/06_Android_Channel_Verification.md) and [iPad](c1-s1/07_iPad_Channel_Verification.md) existing-installation checks; missing automated qualification remains unfinished | | [HIL guide](../../../tests/firmware_tests/hil/README.md), [CI workflow](../../../.github/workflows/ci.yml), [CONTRIBUTING](../../../CONTRIBUTING.md) | Reuse existing tools and gates; actual CI requirements govern merges | diff --git a/docs/developments/2026-q4-reliable-workflow/06_Sprint_Backlogs.md b/docs/developments/2026-q4-reliable-workflow/06_Sprint_Backlogs.md index fc828c3b..359baa1f 100644 --- a/docs/developments/2026-q4-reliable-workflow/06_Sprint_Backlogs.md +++ b/docs/developments/2026-q4-reliable-workflow/06_Sprint_Backlogs.md @@ -5,13 +5,13 @@ | Field | Rule | |---|---| -| Status | C1-S1 execution initiated 25 September: four repository tasks Done, eight device/pilot tasks Blocked. C1-S2–C1-S6 retain original Proposed allowances and require replanning before selection | +| Status | C1-S1 device retry 25 September: six tasks Done, two Prepared and four Awaiting evidence. Both current channel installations verified; participant-dependent work remains unfinished. C1-S2–C1-S6 retain original Proposed allowances and require replanning before selection | | Product/Sprint Goals | [Framework](01_Overview_and_Scrum_Framework.md) and [Sprint plan](04_Sprint_Plan.md) | | Acceptance authority | [Product backlog and stories](05_Product_Backlog_and_Stories.md); task completion never overrides a parent story's acceptance criteria | | Selection | Developers confirm scope, ownership, estimates and task plan at each Sprint Planning | | Hours | Initial task allowances totaling the source plan's 136 hours; not story points or validated effort estimates | | Dependencies | Same-Sprint `Txx` references refer to that Sprint's task. Cross-Sprint dependencies name their full item/task ID | -| Evidence | Record artifact identity and actual results; unavailable access/recruitment leaves the affected task Blocked, not Done | +| Evidence | Record artifact identity and actual results; use Prepared for reviewed partial work, Awaiting evidence for unperformed sessions/observations, and Blocked for a concrete impediment with an owner; unfinished work is never Done | | Privacy | Keep private consent/contact/device records outside Git; link only reviewed public aggregates and redacted evidence | Actual task evidence and blocker owners are maintained in the [C1-S1 execution record](c1-s1/00_Execution_Record.md). The original future task tables below are retained as the baseline; the new 45–72h recovery estimate and matrix cost model invalidate their assumed fit. Use the [reforecast requirements](04_Sprint_Plan.md#c1-s1-findings-and-required-reforecast) before selection. Prepared TestFlight correction copy records residual PYB-002.1; its external application is not an extra committed task. @@ -33,19 +33,21 @@ Record optional follow-up consent and the prospective day-7–14 window at each | Task ID | Parent child item | Proposed task and expected output | Dependency | Contribution role | h | Status | |---|---|---|---|---|---:|---| | C1-S1-T01 | PYB-001.1 | Assemble the dated channel/install/provenance/qualification ledger from existing records; assign unresolved fields | Current source/publication records | Release | 1 | Done | -| C1-S1-T02 | PYB-001.2 | Verify eligible Android enrollment/install and record build/version, restrictions and available source mapping | T01; Play/device access | Release + QA | 2 | Blocked | -| C1-S1-T03 | PYB-001.2 | Verify current TestFlight installation and record its actual build and provenance limitations | T01; TestFlight/device access | Release + QA | 2 | Blocked | -| C1-S1-T04 | PYB-003.1 | Review harmless hardware/pilot boundaries, consent/retention rules, and manual support template | Recorded pilot setup; named pilot owner | Pilot + QA | 2 | Blocked | -| C1-S1-T05 | PYB-004.1 | Confirm primary cohort and Tasks A/B/C, assistance/timeout rules, previous workflow and prospective follow-up | T04; recorded app/setup | Pilot | 2 | Blocked | -| C1-S1-T06 | PYB-004.2 / PYB-011.2 | Observe the first baseline batch; record every eligible start, assistance, consent/window and any due follow-up | T05; consenting participants | Pilot | 2 | Blocked | -| C1-S1-T07 | PYB-004.2 / PYB-011.2 | Observe the next baseline batch under the same task/build rules; record windows and collect due follow-up | T05; consenting participants | Pilot | 2 | Blocked | -| C1-S1-T08 | PYB-004.2 / PYB-011.2 | Complete planned observation/follow-up slots toward five baseline starts; retain failures, missing responses and recruitment gaps | T05; participant access | Pilot | 2 | Blocked | -| C1-S1-T09 | PYB-004.2 | Summarize baseline outcomes and actual observation cost; identify an observed obstacle without inventing one | T06–T08 actual records | Pilot + Product Owner | 1 | Blocked | +| C1-S1-T02 | PYB-001.2 | Verify eligible Android enrollment/current installation and record build/version, restrictions and available source mapping | T01; Play/device access | Release + QA | 2 | Done | +| C1-S1-T03 | PYB-001.2 | Verify current TestFlight installation and record its actual build and provenance limitations | T01; TestFlight/device access | Release + QA | 2 | Done | +| C1-S1-T04 | PYB-003.1 | Review harmless hardware/pilot boundaries, consent/retention rules, and manual support template | Recorded pilot setup; named pilot owner | Pilot + QA | 2 | Prepared — awaiting pilot setup | +| C1-S1-T05 | PYB-004.1 | Confirm primary cohort and Tasks A/B/C, assistance/timeout rules, previous workflow and prospective follow-up | T04; recorded app/setup | Pilot | 2 | Prepared — awaiting pilot setup | +| C1-S1-T06 | PYB-004.2 / PYB-011.2 | Observe the first baseline batch; record every eligible start, assistance, consent/window and any due follow-up | T05; consenting participants | Pilot | 2 | Awaiting participant sessions | +| C1-S1-T07 | PYB-004.2 / PYB-011.2 | Observe the next baseline batch under the same task/build rules; record windows and collect due follow-up | T05; consenting participants | Pilot | 2 | Awaiting participant sessions | +| C1-S1-T08 | PYB-004.2 / PYB-011.2 | Complete planned observation/follow-up slots toward five baseline starts; retain failures, missing responses and recruitment gaps | T05; participant access | Pilot | 2 | Awaiting participant sessions | +| C1-S1-T09 | PYB-004.2 | Summarize baseline outcomes and actual observation cost; identify an observed obstacle without inventing one | T06–T08 actual records | Pilot + Product Owner | 1 | Awaiting observation records | | C1-S1-T10 | PYB-006.1 | Draft the bounded Drift recovery contract: write boundary, restore/discard, board association, failure handling and carried Blocks/A-24 scope | ADR-0010 and App contracts; no recruitment dependency | App | 3 | Done | | C1-S1-T11 | PYB-006.1 | Review acceptance scenarios and size the safe increment including required tests; record approval or unresolved design questions | T10; review path | App + reviewer | 1 | Done | | C1-S1-T12 | PYB-009.1 | Inventory existing suites, hardware/operators, applicable gates and matrix cost; draft the next operator recipe | T01 and current tools/specs | QA + firmware | 2 | Done | | **C1-S1 total** | | | | | **22** | | +T02/T03 verified existing Play `0.2.0 (8)` and TestFlight `0.2.0 (6)` installations, origin and launch using the ledger checklist; no fresh enrollment, reinstall or upgrade was performed. Platform reports retain provenance and minimum-OS limitations. T04/T05 have completed source QA but still need the named pilot owner, cohort and tested reference setup. + Five baseline starts is a target, not the implied result of reserving six hours. If access or session duration prevents it, report the actual sample and replan. A completed findings record does not mark an unperformed installation or observation task Done. Missing store source mapping remains an owned limitation under the applicable gate. ## C1-S2 — deliver a bounded safe recovery increment @@ -208,10 +210,13 @@ flowchart LR S --> W["In progress"] W --> R["Review evidence and acceptance"] R --> D["Done task; assess parent separately"] + R --> A["Prepared or awaiting evidence; unfinished"] + A --> W W --> B["Blocked with reason and owner"] B --> W R --> W B --> U["Unfinished at Sprint end"] + A --> U W --> U U --> PB["Product Backlog: reorder and replan"] PB --> S diff --git a/docs/developments/2026-q4-reliable-workflow/c1-s1/00_Execution_Record.md b/docs/developments/2026-q4-reliable-workflow/c1-s1/00_Execution_Record.md index 4a0615d7..938d2108 100644 --- a/docs/developments/2026-q4-reliable-workflow/c1-s1/00_Execution_Record.md +++ b/docs/developments/2026-q4-reliable-workflow/c1-s1/00_Execution_Record.md @@ -7,10 +7,10 @@ |---|---| | Execution date | 25 September 2026, Asia/Bangkok; early work under the user's request to implement C1-S1 | | Original proposed timebox | 28 September–11 October 2026; retained as a forecast, not a claim that a Sprint ceremony or staffed team occurred | -| Source baseline | Runtime/source `23ed764b0ef88dce9720c66fbd1c0655268860cf`; strategy/Scrum baseline `d039db09779ed45124874721f88b2e0931664743` | +| Source baseline | Runtime/source `23ed764b0ef88dce9720c66fbd1c0655268860cf`; strategy/Scrum baseline `d039db09779ed45124874721f88b2e0931664743`; device retry starts from integrated documentation commit `7077276` | | Scope | Installation evidence, pilot preparation, bounded recovery design/sizing and validation inventory; no S2 persistence implementation | -| Overall state | Repository deliverables prepared; physical installation and participant-dependent tasks remain blocked; C1-S1 and M-01/SG0 are not complete | -| Execution/review | Codex implemented and reviewed repository work across isolated Git worktrees; human pilot ownership, consent and physical observations are not supplied by that review | +| Overall state | Six tasks Done, two Prepared, four Awaiting evidence; both existing channel installations verified. Pilot setup/observations remain unfinished; C1-S1 and M-01/SG0 are not complete | +| Execution/review | Codex implemented and reviewed repository work across isolated Git worktrees; human pilot ownership, consent and participant observations are not supplied by that review | | Capacity | Original C1-S1 allowance remains 22 hours; these are planning allowances, not measured human effort or actual velocity | ## Deliverables and task outcomes @@ -18,25 +18,27 @@ | Task | Parent | Outcome | Evidence / remaining action | |---|---|---|---| | C1-S1-T01 | PYB-001.1 | Done — reviewed ledger and owned unknowns | [Channel/artifact ledger](01_Channel_and_Artifact_Ledger.md); direct HTTPS checks; separate listing/install/provenance/qualification states | -| C1-S1-T02 | PYB-001.2 | Blocked — Android device/account installation evidence missing | ADB saw no connected device; maintainer/release operator must complete eligible enrollment, installation and build capture | -| C1-S1-T03 | PYB-001.2 | Blocked — iPad app query denied while locked | Physical pairing/model metadata obtained; no installed build, fresh TestFlight install or launch attested | -| C1-S1-T04 | PYB-003.1 | Blocked — protocol prepared; human collection decision absent | [Pilot protocol and templates](02_Pilot_Protocol_and_Observation_Kit.md); name the pilot owner and record bounded setup/consent approval before collecting participant data | -| C1-S1-T05 | PYB-004.1 | Blocked — reproducible task cards prepared; cohort/setup unconfirmed | Same kit defines Tasks A/B/C, prospective metrics and follow-up; reachable cohort, owner and exact tested setup remain unconfirmed | -| C1-S1-T06 | PYB-004.2 / PYB-011.2 | Blocked — no eligible participant session | Empty private templates are ready; no consent, start, success or follow-up is invented | -| C1-S1-T07 | PYB-004.2 / PYB-011.2 | Blocked — no eligible participant session | Recruitment/observation owner needed | -| C1-S1-T08 | PYB-004.2 / PYB-011.2 | Blocked — no eligible participant session | Five baseline starts remain outstanding; no substitution by maintainer or automated tests | -| C1-S1-T09 | PYB-004.2 | Blocked — no observation set to analyze | Baseline sample is absent; completion, timing, retention and observed user-friction measures are unavailable, not zero-valued performance results | +| C1-S1-T02 | PYB-001.2 | Done — existing Play installation verified | [Android report](06_Android_Channel_Verification.md): Lenovo TB-J616X / Android 12, `0.2.0 (8)`, Play installer and beta membership, Open/launch/About; 38/38 payloads match retained build-8 AAB | +| C1-S1-T03 | PYB-001.2 | Done — existing TestFlight installation verified | [iPad report](07_iPad_Channel_Verification.md): `iPad16,10` / iPadOS 26.6.2, installed and offered `0.2.0 (6)`, TestFlight signer and successful launch; source mapping remains unknown | +| C1-S1-T04 | PYB-003.1 | Prepared — technical review complete; human collection decision absent | [Pilot protocol and templates](02_Pilot_Protocol_and_Observation_Kit.md); name the pilot owner and record bounded setup/consent approval before collecting participant data | +| C1-S1-T05 | PYB-004.1 | Prepared — task cards technically reviewed; cohort/setup unconfirmed | Same kit defines Tasks A/B/C, prospective metrics and follow-up; reachable cohort, owner and exact tested setup remain unconfirmed | +| C1-S1-T06 | PYB-004.2 / PYB-011.2 | Awaiting participant sessions | Empty private templates are ready; no consent, start, success or follow-up is invented | +| C1-S1-T07 | PYB-004.2 / PYB-011.2 | Awaiting participant sessions | Recruitment/observation owner needed | +| C1-S1-T08 | PYB-004.2 / PYB-011.2 | Awaiting participant sessions | Five baseline starts remain outstanding; no substitution by maintainer or automated tests | +| C1-S1-T09 | PYB-004.2 | Awaiting observation records | Baseline sample is absent; completion, timing, retention and observed user-friction measures are unavailable, not zero-valued performance results | | C1-S1-T10 | PYB-006.1 | Done — bounded implementation contract specified | [Normative recovery contract](../../../specifications/App/current-draft-recovery.md), ADR-0048, App specification/TDD and ADR-0010 addendum | | C1-S1-T11 | PYB-006.1 | Done — source review, scenario matrix and sizing | [Recovery design review](03_Recovery_Design_and_Sizing.md); S2 forecast requires replanning; no implementation or physical acceptance claimed | | C1-S1-T12 | PYB-009.1 | Done — tool/gate inventory, explicit access gaps and costed recipe | [Validation inventory](04_Validation_Inventory_and_Operator_Recipe.md); host harness checks are separate from physical execution and full recipe reproduction | -Task completion is narrower than parent completion: PYB-009.1 still carries the S2 recipe completion and later operator updates; PYB-001.2, PYB-003.1 and PYB-004 remain unfinished. Specifying recovery does not implement PYB-006.2 or complete A-24. All hardware and recruitment limitations remain visible. +Task completion is narrower than parent completion: PYB-009.1 still carries the S2 recipe completion and later operator updates; PYB-001.2 is complete for the verified existing-installation path, while PYB-003.1 and PYB-004 remain unfinished. No fresh enrollment, reinstall or upgrade was performed. Specifying recovery does not implement PYB-006.2 or complete A-24. Current tablet access is resolved; exact-board, operator and recruitment limitations remain visible. Prepared and Awaiting evidence are unfinished states, not additional Done tasks. ## Findings that change planning | Finding | Decision / effect | |---|---| | Live website is corrected, but the search tool returns older text | Retain the Android correction; do not reopen it from cached snippets. Direct live-response evidence is in the ledger | +| Both supplied tablets are accessible and their channel installations launch | T02/T03 complete from direct current-installation evidence; keep the initial failed discovery as dated history | +| Delivered minimum-OS metadata differs from historical artifacts/notes | Android min SDK 29 versus AAB 24; iPad minimum OS 18 versus TestFlight notes 15. Distribution owner reconciles variant/archive/store eligibility before broader OS-support claims | | Public TestFlight description still uses an older compatibility baseline | Record residual PYB-002.1 and a [ready-to-review correction packet](05_TestFlight_Metadata_Correction.md); store mutation/public verification remain pending | | Current text is volatile and recovery is behind a connected-only shell | Specify a local startup choice and truthful durable-write boundary; current app behavior remains unchanged | | Document value equality and stable connection facades need stronger stale-operation guards | Include revision/session guards and regressions in the recovery slice; no happy-path-only completion | @@ -59,15 +61,15 @@ The original 136-hour task allocation, 20-hour planned headroom and 84-hour rese | Review item | Record | |---|---| -| M-01 / SG0 | Blocked: human pilot owner/cohort/setup and actual capacity still need confirmation; installed-device evidence is incomplete | +| M-01 / SG0 | Unfinished: human pilot owner/cohort/setup and actual capacity still need confirmation; current installed-device evidence is complete | | M-02 | Implementation pending; contract and scenario matrix prepared, not a shipped persistence feature | | M-03 / SG2 and M-06 / SG3 | Not assessed; no participant outcomes or mature follow-up cohort | -| M-04 / M-05 | No new release candidate, submission or verified installation from this execution | +| M-04 / M-05 | No new release candidate or submission; current existing installations verified under PYB-001.2, not a future qualified candidate under PYB-014.2 | | Ready | No second-operator reproduction or badge awarded | -| Worktree method | Recovery design, pilot preparation and qualification inventory were implemented in separate branches/worktrees from the shared planning baseline, then reviewed and integrated | -| Required next human actions | Supply physical channel access; name the pilot owner and cohort; confirm actual capacity before selecting the revised next Sprint | +| Worktree method | Recovery design, pilot preparation and qualification inventory used separate worktrees; the retry also isolates Android, iPad, planning updates and integration before review | +| Required next human actions | Name the pilot owner and consenting cohort, confirm exact reference board/setup and perform its smoke check; collect five actual baseline starts and analyze records; confirm actual capacity before selecting the revised next Sprint | -## Integrated verification +## Initial integrated verification — before the device retry | Check | Actual result / scope | |---|---| @@ -80,6 +82,23 @@ The original 136-hour task allocation, 20-hour planned headroom and 84-hour rese | Repository gates | No-leak, SPDX, governance 7/7 and `git diff --check` pass | | Not executed | Full Flutter/firmware suites, candidate builds, device installations, board/HIL runs, participant sessions, store metadata mutation and external publication | +The table above records the initial integration at `7077276`, before the user supplied accessible tablets. Its device limitations and four/eight status count are historical; the current outcomes are in the task table and retry record below. + +## Device retry — 25 September 2026 + +| Check | Actual result / scope | +|---|---| +| Android channel | Existing Play beta installation `0.2.0 (8)` verified; Open launches PyBLE, About agrees, delivered package signatures verified and 38 code/asset payloads match the retained AAB | +| iPad channel | Existing TestFlight installation `0.2.0 (6)` verified by installed signer/beta entitlements and native offer; launch smoke passed before and after channel inspection | +| Initial access failures | Preserved with original capture hashes in the ledger; superseded by live successful device queries | +| Pilot kit source review | Task cards checked against localized UI, first-program tutorial and PBLE/1; Save/Run separation, bounded examples, STOP limitations and consent/follow-up rules retained | +| Current completion | Six Done / two Prepared / four Awaiting evidence; no task currently depends on the resolved tablet-access blockers | +| Independent document review | Separate reviewer checked central status tables, both platform reports, provenance/OS limits and historical access failures; no material findings. Integration review corrected one planning sentence to distinguish the observed TestFlight Open action from the separately executed app launch | +| Documentation validation | All local links/anchors across 137 tracked Markdown files resolve; tables/fences across 17 changed documents pass; 60 unique tasks, 24 detailed child IDs and the original 136h allocation retained | +| Mermaid | All 12 diagrams across the strategy, Scrum/execution package and recovery contract parsed and rendered; temporary SVGs removed | +| Applicable regression/gates | Publication suite 42 passed; governance 7/7, SPDX, no-leak and whitespace checks pass. Runtime/firmware code is unchanged; the earlier 110 host results above were not rerun for this documentation retry | +| Evidence limits | No fresh enrollment/reinstall/upgrade, BLE/board run, participant session, recovery implementation, store metadata update or new release qualification | + No runtime implementation changed in C1-S1. Required future recovery tests are specified, not claimed passed. No app source, firmware binary, store artifact, participant data or raw device identifiers are included in the documentation commits. ```mermaid @@ -88,7 +107,7 @@ flowchart TD Request --> Pilot[Pilot protocol and empty record templates] Request --> Design[Recovery contract and sizing] Request --> Recipe[Validation inventory and operator recipe] - Ledger --> Access[Pending physical installation evidence] + Ledger --> Access[Both current channel installations verified] Pilot --> People[Pending human owner and participants] Design --> Replan[Replan S2 to S6 within actual capacity] Recipe --> Replan diff --git a/docs/developments/2026-q4-reliable-workflow/c1-s1/01_Channel_and_Artifact_Ledger.md b/docs/developments/2026-q4-reliable-workflow/c1-s1/01_Channel_and_Artifact_Ledger.md index 1efef635..505a93f2 100644 --- a/docs/developments/2026-q4-reliable-workflow/c1-s1/01_Channel_and_Artifact_Ledger.md +++ b/docs/developments/2026-q4-reliable-workflow/c1-s1/01_Channel_and_Artifact_Ledger.md @@ -5,20 +5,20 @@ | Field | Record | |---|---| -| Observed | 25 September 2026; HTTP responses dated 10:03:21 UTC / 17:03:21 Asia/Bangkok | +| Observed | 25 September 2026; initial HTTP responses dated 10:03:21 UTC / 17:03:21 Asia/Bangkok; physical retry later the same day, timestamped in the platform reports | | Source baseline | Runtime/source `23ed764b0ef88dce9720c66fbd1c0655268860cf`; planning baseline `d039db09779ed45124874721f88b2e0931664743` | | Scope | C1-S1-T01/T02/T03; PYB-001.1/001.2; residual TestFlight metadata discrepancy PYB-002 | | Evidence author | Codex, using direct HTTPS retrieval and local read-only device queries; no independent human installation attestation | | Release action owner | Project maintainer Viwat Vchirawongkwin; routing responsibility, not a statement of committed availability | -| Physical outcome | Android installation not run; iPad app query blocked by lock state; neither platform's store-installed build is established | +| Physical outcome | Existing Play `0.2.0 (8)` and TestFlight `0.2.0 (6)` installations verified on the Lenovo and iPad; both launch successfully; no fresh enrollment, reinstall or upgrade performed | | Related | [Execution record](00_Execution_Record.md), [pilot kit](02_Pilot_Protocol_and_Observation_Kit.md), [validation recipe](04_Validation_Inventory_and_Operator_Recipe.md) | ## Observed channel matrix | Platform / item | Publication observation | Physical installation observation | Artifact provenance | Qualification boundary | |---|---|---|---|---| -| Android / Google Play | Official English/US listing returned HTTP 200; names PyBLE, SciLabPro and open testing for 0.2.0 | `adb devices -l` returned no devices. No signed-in enrollment, install or launch was performed | Served version code, installed bytes and source mapping remain unverified | Listing availability and the historical build-8 test record do not qualify a currently installed binary | -| iPad / TestFlight | Public invitation returned HTTP 200 and identified the PyBLE beta; the page does not establish the currently served version/build | A paired physical `iPad16,10` was reported. Device details expose iPadOS `26.6.2` / `23G90`; app inventory failed because the device had not been unlocked recently | No installed version/build or store receipt was obtained; the historical build-5 handoff cannot fill these fields | Pairing/device metadata is not installation, launch, BLE or compatibility evidence | +| Android / Google Play | Official public listing identifies open testing; native Play shows existing beta membership and Open | Lenovo TB-J616X / Android 12: installed `0.2.0 (8)`, installer `com.android.vending`; Open launches PyBLE and About agrees | 38/38 installed code/asset payloads match retained build-8 AAB, supporting its source `768fafe45beee7731d1a38480cc0463a2f5680cd`; not whole-artifact or Console-upload attestation | [Android verification](06_Android_Channel_Verification.md) completes T02's existing-installation scope; no fresh enrollment, upgrade, BLE or matrix qualification | +| iPad / TestFlight | Public invitation opens native TestFlight; offered `0.2.0 (6)` with Open | `iPad16,10`, iPadOS `26.6.2` / `23G90`: installed `0.2.0 (6)`, TestFlight Beta Distribution signer and beta entitlements; launch succeeds | Installed source/archive mapping remains an owned unknown; historical build 5 is a different artifact | [iPad verification](07_iPad_Channel_Verification.md) completes T03's existing-installation scope; no fresh enrollment, upgrade, BLE or older-OS compatibility qualification | | Live website `/app` | Direct HTTPS returned the corrected Android open-testing and iPad external-beta wording | Not applicable | Page response hash recorded below | Website wording is not a store rollout or physical test | | Live website `/` | Direct HTTPS returned Android open-testing wording | Not applicable | Page response hash recorded below | Search/indexed extracts may still be stale | | Firmware v0.6.1 | Existing 11 September publication record attests owner-confirmed publication of five exact profiles | No new board installation or run in this execution | Published source `c8f549eeabe6d2b8c2766eab022517944bb09c8c`; use the release descriptor and exact binary checksums for a physical session | Incomplete automated evidence remains incomplete; this ledger neither requalifies firmware nor awards PyBLE Ready | @@ -31,22 +31,23 @@ The TestFlight page has a separate current discrepancy: its public description s | Artifact | Recorded identity | Source / original evidence | What remains unknown | |---|---|---|---| -| Android prepared AAB | `0.2.0 (8)`; SHA-256 `ee2439589e2c2195ef4c861b524f871b0e5168e84fbea60a1cd379319c6eb5d7` | Source `768fafe45beee7731d1a38480cc0463a2f5680cd`; [10 September handoff](../../../testing/google-play/0.2.0-build-8.md) | Whether this bundle is the active open-test build; Google Play-delivered APKs may be split and re-signed, so AAB/APK digests are not interchangeable | +| Android prepared AAB | `0.2.0 (8)`; SHA-256 `ee2439589e2c2195ef4c861b524f871b0e5168e84fbea60a1cd379319c6eb5d7`, rehashed during retry | Source `768fafe45beee7731d1a38480cc0463a2f5680cd`; [10 September handoff](../../../testing/google-play/0.2.0-build-8.md); installed payload comparison in the Android report | Code/assets match on this tablet; complete delivered-artifact equivalence and Console upload binding remain unestablished. AAB/APK digests are not interchangeable | | Android prepared local APK | `0.2.0 (8)`; SHA-256 `3c98983a995c657f10a398d7b0f65a07c2d2af18e07c30e7d5dfc094eefcbdcf` | Same historical source and handoff | A locally signed APK does not prove the store installation path | -| iPad prepared IPA | `0.2.0 (5)`; SHA-256 `e2e44019aafd6b75f1d281a7cf4fb49d3ef7f326a4d604f2900ad249af70f2af` | Source `8f8dd32010fac9b2b636f57f9044fd040565e0dd`; [27 August handoff](../../../testing/testflight/0.2.0-build-5.md) | Processing, beta availability and the currently served build remain unverified; this historical artifact has its original iOS 13 floor | +| iPad prepared IPA | `0.2.0 (5)`; SHA-256 `e2e44019aafd6b75f1d281a7cf4fb49d3ef7f326a4d604f2900ad249af70f2af` | Source `8f8dd32010fac9b2b636f57f9044fd040565e0dd`; [27 August handoff](../../../testing/testflight/0.2.0-build-5.md) | This historical artifact has its original iOS 13 floor and does not map the now-observed TestFlight build 6; build-6 archive/source identity remains unknown | | Firmware v0.6.1 descriptor | Historical SHA-256 `71f6aca6df07e31a1f54c7f70a48d82c7fe26b1c8ca0626a8ffc57c804fbb1bd` | [11 September publication](../../../testing/firmware-v0.6.1-publication-2026-09-11.md) | No new byte download/board validation is claimed here; bind actual session evidence to the selected release | ## Open fields and next actions | ID | Missing evidence / blocker | Responsible action owner | Next action and review trigger | |---|---|---|---| -| CH-01 | Physical Android device/account and eligible open-testing installation | Project maintainer / release operator | Connect an eligible device, follow the official listing, record restrictions and complete the checklist below; revisit when available | -| CH-02 | Physical iPad app inventory and current TestFlight installation | Project maintainer / iPad operator | Unlock the paired device, verify the TestFlight invitation and currently offered build, then record actual installation/update and launch; revisit after unlock | -| CH-03 | Installed build-to-source mapping on both platforms | Project maintainer / distribution owner | Match observed installed version/build to retained store build records and immutable source/artifact evidence; explicitly retain any unprovable field | +| CH-01 | Closed for current Android channel installation | Project maintainer / release operator | Physical Play/Open/installer/build/About evidence retained in the Android report; fresh-account enrollment and install/upgrade behavior were not exercised | +| CH-02 | Closed for current iPad channel installation | Project maintainer / iPad operator | Native TestFlight/build/signing/launch evidence retained in the iPad report; fresh enrollment and install/upgrade behavior were not exercised | +| CH-03 | Android payload mapping established; iPad build-6 source/archive mapping still unknown | Project maintainer / distribution owner | Retain Android comparison limits; bind installed iPad build 6 to immutable archive/upload/source records when available. Explicit unknown does not invalidate PYB-001.2's bounded installation verification | | CH-04 | TestFlight public description still states an older compatibility baseline | Project maintainer / App Store Connect owner | Review and apply the prepared metadata only with actual build support verified; record the public result and date | | CH-05 | Current exact-board inventory, operator availability and candidate-bound physical results | Project maintainer / QA operator | Complete the [inventory](04_Validation_Inventory_and_Operator_Recipe.md); select exact artifacts and fund the required matrix before making a new compatibility claim | +| CH-06 | Delivered minimum-OS metadata differs from historical bundle/build notes | Project maintainer / distribution owner | Android delivered manifests report min SDK 29 versus retained AAB 24; iPad installed metadata reports minimum OS 18 versus TestFlight notes 15. Reconcile variant/archive/store eligibility before extending minimum-OS support claims; launch on the two observed devices passed | -Owners above identify the responsible project function and known maintainer contact. They do not assign an absent volunteer or claim a scheduled hardware session. The user has been asked for device access and a pilot owner; unanswered requests remain unresolved. +Owners above identify the responsible project function and known maintainer contact. They do not assign an absent volunteer or claim a scheduled hardware session. The user supplied both tablets for the retry. Pilot ownership, cohort and exact board setup remain separate pending inputs. ## Repeatable installation checklist @@ -55,7 +56,7 @@ Owners above identify the responsible project function and known maintainer cont | 1 — Establish scope | Record device model/Android version and eligible country/account context without account identifiers | Record iPad model/iPadOS and availability of TestFlight | Date, platform, model, OS; private account details excluded | | 2 — Follow the public channel | Open the official listing; follow its displayed testing/enrollment instructions | Open the public invitation in TestFlight; inspect the offered build and restrictions | Actual steps, enrollment/review restrictions, offered version/build where visible; HTTP 200 alone is insufficient | | 3 — Install or update safely | Record existing-app/update state; do not uninstall or clear data merely to obtain a clean result | Record existing-app/update state; do not replace it with a locally signed build | Installation/update outcome, errors or blocker; preserve existing user work | -| 4 — Inspect the result | Launch the store-installed app; inspect About and package version/build | Launch the TestFlight-installed app; inspect About and TestFlight build identity | Observed installed identity, launch outcome, installation source and any unresolved field | +| 4 — Inspect the result | Launch the store-installed app; inspect About and package version/build | Launch the TestFlight-installed app; inspect installed metadata and TestFlight build identity; record About if inspected | Observed installed identity, launch outcome, installation source and any unresolved field; do not claim a UI view that was not opened | | 5 — Resolve provenance | Compare against the selected Play build record; distinguish upload and delivered signing roles | Compare against the selected App Store Connect build record | Immutable source/artifact mapping or explicit unknown; never derive it from source `pubspec.yaml` alone | | 6 — Review | Review redacted evidence and accurate guidance | Review redacted evidence and accurate guidance | Successful installation satisfies only its scope; compatibility still needs applicable physical tests | @@ -72,7 +73,7 @@ Keep full command outputs private because they may contain device identifiers, a ## Retained evidence and privacy -Raw responses/query files are retained in the main workspace's ignored `local/c1-s1/2026-09-25/`, outside Git. The device app query failed with CoreDevice error `10003` / RemotePairing error `1016`; its nested reason was that the device had not been unlocked recently. Device details may be cached, so the OS/model fields are reported as query output rather than proof of an active app session. +The initial attempt is retained as history in the main workspace's ignored `local/c1-s1/2026-09-25/`, outside Git. Its ADB discovery found no device and iPad app query failed with CoreDevice error `10003` / RemotePairing error `1016` because the device had not been unlocked recently. That attempt supplied no installed-build or active-session evidence. The later successful retry supersedes these access limitations; its private captures and hashes are recorded in the [Android](06_Android_Channel_Verification.md) and [iPad](07_iPad_Channel_Verification.md) reports under ignored `local/c1-s1/2026-09-25-retry/`. | Raw capture | SHA-256 | Meaning | |---|---|---| @@ -88,9 +89,9 @@ These hashes make the retained capture identifiable; dynamic public pages may re ```mermaid flowchart LR Public[Public listing observed] --> Access[Eligible account and physical device] - Access --> Install[Actual installation and launch] + Access --> Install[Verify current channel installation and launch] Install --> Identity[Observed version and build] Identity --> Mapping[Source mapping or explicit unknown] Mapping --> Physical[Applicable exact-artifact physical evidence] - Locked[Locked or unavailable device] -. Blocked installation .-> Access + Locked[Initial access failure retained as history] -. Successful retry .-> Access ``` diff --git a/docs/developments/2026-q4-reliable-workflow/c1-s1/02_Pilot_Protocol_and_Observation_Kit.md b/docs/developments/2026-q4-reliable-workflow/c1-s1/02_Pilot_Protocol_and_Observation_Kit.md index 4c1586ca..bf82aaff 100644 --- a/docs/developments/2026-q4-reliable-workflow/c1-s1/02_Pilot_Protocol_and_Observation_Kit.md +++ b/docs/developments/2026-q4-reliable-workflow/c1-s1/02_Pilot_Protocol_and_Observation_Kit.md @@ -13,13 +13,15 @@ | Inspected source | `d039db09779ed45124874721f88b2e0931664743`; source inspection does not identify the installed app | | Primary cohort | Provisionally adult tablet-owning makers; human owner must confirm a reachable cohort before collection | | Pilot decision-maker / recruitment owner / data custodian | TBD; no assignment, participant contact, consent, or approval inferred | -| Reference app and hardware | Must be bound to a dated installation record and the exact setup table below; no setup has been physically verified for this pilot | -| T04 / PYB-003.1 | Protocol/support template prepared for review; scoped human collection decision pending | -| T05 / PYB-004.1 | Tasks and measurement rules prepared for review; cohort, owner and reference setup confirmation pending | -| T06–T08 / PYB-004.2 | Blocked: collection decision, tested setup and consenting participants absent | -| T09 | Synthesis template prepared; actual baseline analysis blocked without observations | +| Reference app and hardware | Play build 8 and TestFlight build 6 verified in the [channel ledger](01_Channel_and_Artifact_Ledger.md); exact board/reference setup and operator BLE smoke remain unperformed for this pilot | +| T04 / PYB-003.1 | Prepared — technical review complete; scoped human collection decision pending | +| T05 / PYB-004.1 | Prepared — technical review complete; cohort, owner and reference setup confirmation pending | +| T06–T08 / PYB-004.2 | Awaiting participant sessions: collection decision, tested setup and consenting participants still required | +| T09 | Awaiting observation records; synthesis template prepared, actual baseline analysis not yet performed | | Results | Not collected. Success rate, timing, support cost and retention are unavailable; no trial, consent or physical result is claimed | +**Device-retry review, 25 September 2026:** a separate source review checked the task cards against current localized UI, the first-program tutorial and PBLE/1 behavior. Save and Run remain separate explicit actions; the programs are bounded and console-only; STOP limits, assistance, missing data and consent/follow-up separation are consistent. This completes technical QA of the prepared kit, not the named human collection decision or an observed participant session. The [Android](06_Android_Channel_Verification.md) and [iPad](07_iPad_Channel_Verification.md) checks also establish current channel installations and launch. They do not provide a cohort, consent or exact-board smoke result. + This kit is a manual, explicitly consented pilot procedure. It changes neither the app's data handling nor the [public privacy policy source](../../../../tools/web/src/app/privacy/page.tsx) and its [offline counterpart](../../../../app/lib/app/pages/privacy_policy_page.dart). @@ -49,7 +51,7 @@ do not change eligibility, tasks or thresholds retrospectively to improve result flowchart TD Kit["Prepared protocol and empty templates"] --> Decision["Named owner reviews cohort, setup and data rules"] Decision --> Gate{"Collection approved and setup verified?"} - Gate -- No --> Hold["Keep observation tasks blocked"] + Gate -- No --> Hold["Await pilot setup and participant evidence"] Gate -- Yes --> Consent["Voluntary consent and eligibility"] Consent --> A["Task A: retain every eligible start"] A --> C["Optional meaningful Task C and prior workflow"] @@ -281,7 +283,7 @@ Task C demonstrates adaptation only; it is never counted as a later-day return. | After A | Ask Task C purpose/attempt/outcome and reason to choose or leave PyBLE. Offer follow-up separately; record activation/window immediately if consented | | End of session | Stop bounded work if active; disconnect, verify harmless state and clear only owner-approved disposable files. Do not erase private app/board work. Record support and cleanup effort | | T06 / T07 / T08 batches | Schedule within actual capacity toward five baseline starts; reconcile every start, due follow-up, unfilled slot and blocker after each batch | -| T09 analysis | Reconcile records, calculate descriptive outcomes below, report true observation/support cost and observed friction or “no blocker observed.” Without records, leave analysis blocked rather than invent a finding | +| T09 analysis | Reconcile records, calculate descriptive outcomes below, report true observation/support cost and observed friction or “no blocker observed.” Without records, leave analysis Awaiting observation records rather than invent a finding | | Metric | Manual calculation and required context | |---|---| diff --git a/docs/developments/2026-q4-reliable-workflow/c1-s1/04_Validation_Inventory_and_Operator_Recipe.md b/docs/developments/2026-q4-reliable-workflow/c1-s1/04_Validation_Inventory_and_Operator_Recipe.md index 7721d3b0..4dd322a0 100644 --- a/docs/developments/2026-q4-reliable-workflow/c1-s1/04_Validation_Inventory_and_Operator_Recipe.md +++ b/docs/developments/2026-q4-reliable-workflow/c1-s1/04_Validation_Inventory_and_Operator_Recipe.md @@ -9,7 +9,7 @@ | Inspection date / source | 25 September 2026; `d039db09779ed45124874721f88b2e0931664743` before this documentation change | | Worktree | Branch `work/c1-s1-qualification`; isolated from the app/research worktrees | | Result | Existing tools, normative counts, missing access, operator procedure and initial cost range inventoried; 110 focused host tests passed | -| Physical result | No board, app installation, BLE session, flash operation or physical qualification performed for this task | +| Physical result | No board, BLE session, flash operation or physical qualification performed; separate device retry verifies existing channel installations and launch without reinstalling | | Review boundary | Documentary source/command checks are complete; named physical operator, reviewed candidate and actual timed rehearsal remain required before execution | | Related evidence | [Execution record](00_Execution_Record.md), [channel/artifact ledger](01_Channel_and_Artifact_Ledger.md), [pilot procedure](02_Pilot_Protocol_and_Observation_Kit.md), [recovery design](03_Recovery_Design_and_Sizing.md) | @@ -74,13 +74,13 @@ Unless a row names another directory, commands run from the repository root in a ## 3. Physical inventory and ten app rows -Historical release evidence establishes which exact profiles exist, not whether the required bench hardware is presently available. No physical board inventory was performed in this task. The root session's read-only device discovery on 25 September found no ADB device; a paired iPad16,10 reported iPadOS 26.6.2/build 23G90, but app inspection was blocked because the device had not been unlocked recently. Host discovery found no `/dev/cu.usbmodem*`, `/dev/cu.usbserial*`, `/dev/cu.SLAB*` or `/dev/cu.wch*` endpoint; that does not exclude separately powered BLE boards. Pairing is not an app-install or HIL pass. +Historical release evidence establishes which exact profiles exist, not whether the required bench hardware is presently available. No physical board inventory was performed in this task. The initial 25 September discovery found no ADB device and the paired iPad's app query was denied while locked. The later user-supplied device retry supersedes those access gaps: [Lenovo TB-J616X / Android 12](06_Android_Channel_Verification.md) has verified Play `0.2.0 (8)` and [iPad16,10 / iPadOS 26.6.2](07_iPad_Channel_Verification.md) has verified TestFlight `0.2.0 (6)`; both launch. These checks do not select a firmware candidate or execute BLE scenarios. Host discovery found no `/dev/cu.usbmodem*`, `/dev/cu.usbserial*`, `/dev/cu.SLAB*` or `/dev/cu.wch*` endpoint; that does not exclude separately powered BLE boards. Pairing is not an app-install or HIL pass. | Resource | Current execution state | Required owner action before a physical batch | |---|---|---| | Five exact boards, revisions/memory/module markings | Historical profiles recorded; current possession, condition and firmware identity unverified | Physical operator assigned at Planning checks and privately records each exact unit | -| Android tablet / Play access | No device in current ADB discovery; eligible account/enrollment and installed build unverified | Device/channel owner supplies an eligible unlocked tablet and records installation evidence; no enrollment or account access assumed | -| iPad / TestFlight access | Paired device found; locked app query blocked | Device/channel owner unlocks and confirms actual TestFlight install/build; pairing alone is insufficient | +| Android tablet / Play access | Available during retry; existing beta membership, Play installation `0.2.0 (8)` and launch verified | Reconfirm availability for the selected candidate; retain Android payload mapping and delivered minimum-SDK limitations | +| iPad / TestFlight access | Available during retry; TestFlight-origin `0.2.0 (6)` and launch verified | Reconfirm availability for the selected candidate; retain unknown source mapping and delivered minimum-OS discrepancy | | USB data cables, reset adapters, power isolation, known backups | Not inventoried; serial endpoint discovery alone would not prove exact-board identity | Physical operator checks wiring, reliable power/data path and recoverability before operations | | Disposable workspace media / spare boards | Availability and erase authority unconfirmed | Owner supplies an independently verified backup and explicitly disposable target for each required acquisition | | Physical operator / independent reviewer | No named assignment or confirmed availability | Assign actual people/time; an assistant-authored recipe does not supply physical sign-off | @@ -90,16 +90,16 @@ All ten rows below are **not run for C1-S1**. An unchanged historical pass must | Row | Exact provisioning profile | Platform | Required profile distinction | Current blocker | |---|---|---|---|---| -| Q01 | `esp32-4mb` | iPadOS | Classic ESP32, 4 MiB flash; PBLE chip `esp32` | Exact board/candidate/operator unassigned; app query locked | -| Q02 | `esp32-4mb` | Android | Same declared firmware bytes as Q01 | Exact board/candidate/operator and tablet/install evidence unavailable | -| Q03 | `esp32-s3-n16r8` | iPadOS | Lean S3, 16 MiB flash / 8 MiB Octal PSRAM; PBLE chip `esp32-s3` | Exact board/candidate/operator unassigned; app query locked | -| Q04 | `esp32-s3-n16r8` | Android | Same declared firmware bytes as Q03; no bundled TFT-runtime claim | Exact board/candidate/operator and tablet/install evidence unavailable | -| Q05 | `waveshare-esp32-s3-lcd-147b` | iPadOS | Exact B board, 16 MiB / 8 MiB; distinct image despite PBLE chip `esp32-s3` | Exact board/candidate/operator unassigned; app query locked | -| Q06 | `waveshare-esp32-s3-lcd-147b` | Android | Same declared firmware bytes as Q05; exact-board display/splash gates separate | Exact board/candidate/operator and tablet/install evidence unavailable | -| Q07 | `esp32-c3-4mb` | iPadOS | C3 revision v0.3 or newer, 4 MiB flash; C3-G0…C3-G6 required for fresh firmware qualification | Exact board/candidate/operator unassigned; app query locked | -| Q08 | `esp32-c3-4mb` | Android | Same declared firmware bytes as Q07; separate C3-G5 real app run | Exact board/candidate/operator and tablet/install evidence unavailable | -| Q09 | `rpi-pico2-w` | iPadOS | Exact Pico 2 W; bound UF2/raw BIN; RP2 resource facts and GP2 | Exact board/candidate/operator unassigned; app query locked | -| Q10 | `rpi-pico2-w` | Android | Same declared firmware bytes as Q09; separate physical Android workflow | Exact board/candidate/operator and tablet/install evidence unavailable | +| Q01 | `esp32-4mb` | iPadOS | Classic ESP32, 4 MiB flash; PBLE chip `esp32` | Exact board/candidate/operator unassigned; channel installation now verified | +| Q02 | `esp32-4mb` | Android | Same declared firmware bytes as Q01 | Exact board/candidate/operator unassigned; channel installation now verified | +| Q03 | `esp32-s3-n16r8` | iPadOS | Lean S3, 16 MiB flash / 8 MiB Octal PSRAM; PBLE chip `esp32-s3` | Exact board/candidate/operator unassigned; channel installation now verified | +| Q04 | `esp32-s3-n16r8` | Android | Same declared firmware bytes as Q03; no bundled TFT-runtime claim | Exact board/candidate/operator unassigned; channel installation now verified | +| Q05 | `waveshare-esp32-s3-lcd-147b` | iPadOS | Exact B board, 16 MiB / 8 MiB; distinct image despite PBLE chip `esp32-s3` | Exact board/candidate/operator unassigned; channel installation now verified | +| Q06 | `waveshare-esp32-s3-lcd-147b` | Android | Same declared firmware bytes as Q05; exact-board display/splash gates separate | Exact board/candidate/operator unassigned; channel installation now verified | +| Q07 | `esp32-c3-4mb` | iPadOS | C3 revision v0.3 or newer, 4 MiB flash; C3-G0…C3-G6 required for fresh firmware qualification | Exact board/candidate/operator unassigned; channel installation now verified | +| Q08 | `esp32-c3-4mb` | Android | Same declared firmware bytes as Q07; separate C3-G5 real app run | Exact board/candidate/operator unassigned; channel installation now verified | +| Q09 | `rpi-pico2-w` | iPadOS | Exact Pico 2 W; bound UF2/raw BIN; RP2 resource facts and GP2 | Exact board/candidate/operator unassigned; channel installation now verified | +| Q10 | `rpi-pico2-w` | Android | Same declared firmware bytes as Q09; separate physical Android workflow | Exact board/candidate/operator unassigned; channel installation now verified | Every selected row covers the applicable edit/save/run/stdout/STOP/file-readback/disconnect/reconnect workflow plus the increment's affected scenarios. C3-G5 expressly requires both tight-loop and print-flood STOP through the real UI, and GP2 includes both physical platforms. Use [C3 gates](../../../specifications/firmware/ports/esp32-c3-4mb.md), [Pico gates](../../../specifications/firmware/ports/rpi-pico2-w.md), and [Waveshare exact-board requirements](../../../specifications/hardware.md#12-waveshare-esp32-s3-lcd-147b-qualification-contract) without replacing them with this summary. @@ -210,7 +210,7 @@ The full firmware suite, app suite, cross-builds and hardware tests were not run | Remaining action | Owner assignment / next checkpoint | |---|---| | Confirm exact boards, safe fixtures, backups, candidate and physical operator | Product Owner/Developers name the actual operator at Planning; until then Q01–Q10 remain not run | -| Unlock iPad; provide eligible Android tablet and current install evidence | Device/channel owner; reconcile with the channel ledger before any physical app batch | +| Reconfirm tablet availability and candidate identity for the selected physical batch | Device access and current channel installation checks are complete for this retry; device/channel owner rechecks when the candidate or session changes | | Bind executable recovery cases and revise estimate from the accepted contract | App + QA during C1-S2-T01; proposed current-draft behavior has no physical result yet | | Time the first representative pair; allocate remaining rows and reruns | QA/Developers before C1-S3 scope selection | | Independently review and reproduce the recipe if PYB-009.2 is selected | Named second operator with separately allocated time; assistance remains visible and triggers an affected-step rerun | diff --git a/docs/developments/2026-q4-reliable-workflow/c1-s1/05_TestFlight_Metadata_Correction.md b/docs/developments/2026-q4-reliable-workflow/c1-s1/05_TestFlight_Metadata_Correction.md index ee3dbcf7..27b94a94 100644 --- a/docs/developments/2026-q4-reliable-workflow/c1-s1/05_TestFlight_Metadata_Correction.md +++ b/docs/developments/2026-q4-reliable-workflow/c1-s1/05_TestFlight_Metadata_Correction.md @@ -9,10 +9,12 @@ | Backlog | PYB-002.1, newly identified residual copy discrepancy; the earlier Android correction remains complete | | State | Replacement copy prepared; App Store Connect change and public verification pending | | Action owner | Project maintainer / App Store Connect owner; store access not used in this execution | -| Evidence | [Channel ledger](01_Channel_and_Artifact_Ledger.md), public TestFlight response and retained body hash | +| Evidence | [Channel ledger](01_Channel_and_Artifact_Ledger.md), public TestFlight response and retained body hash; [physical iPad verification](07_iPad_Channel_Verification.md) | The live public invitation's description still presents the older ESP-family/agent-0.4.0 scope. A capability-defined app description should explain how to select the correct tested setup without implying that every current board/profile works with an unidentified TestFlight build. The historical [build-5 handoff](../../../testing/testflight/0.2.0-build-5.md) remains unchanged. +The later device retry establishes that the observed native TestFlight offer and installed beta are `0.2.0 (6)`, with a successful launch and TestFlight signing origin. Its source/archive mapping remains unknown. Installed metadata reports `MinimumOSVersion = 18.0` while the build notes describe an iOS/iPadOS 15 rebuild; reconcile that difference with archive and store eligibility before publishing an older-OS support claim. This discovery does not change the public description or the historical build-5 handoff. + ## Prepared Beta App Description The following is app-level copy for review against the actual offered build. It is not a build-specific “What to Test” entry and does not announce a new binary, production release or completed compatibility matrix. @@ -31,7 +33,8 @@ PyBLE is MIT-licensed and developed in public at https://github.com/PyBLE-dev/Py | Action | Required evidence / boundary | |---|---| -| Identify the offered TestFlight build | Record actual version/build and source mapping or unknowns before changing build-specific compatibility or test instructions | +| Identify the offered TestFlight build | Observed build is `0.2.0 (6)` on 25 September; retain unknown archive/source mapping and recheck the offer before changing build-specific compatibility or test instructions | +| Reconcile minimum OS | Check installed variant metadata (18), build notes (15), archive and actual store eligibility; avoid promising support on an untested older OS | | Check the app-level description | Confirm the offered build supports the described core features; adjust a claim if its actual artifact differs | | Apply the metadata through App Store Connect | Record the actual field, locale, saved/submitted state and date; avoid touching unrelated listing fields or version history | | Keep build-specific notes separate | Use notes tied to the selected artifact; do not paste the old build-5 notes into a different build or assert untested five-profile compatibility | diff --git a/docs/developments/2026-q4-reliable-workflow/c1-s1/06_Android_Channel_Verification.md b/docs/developments/2026-q4-reliable-workflow/c1-s1/06_Android_Channel_Verification.md index f216e3ba..c2e52ea1 100644 --- a/docs/developments/2026-q4-reliable-workflow/c1-s1/06_Android_Channel_Verification.md +++ b/docs/developments/2026-q4-reliable-workflow/c1-s1/06_Android_Channel_Verification.md @@ -19,7 +19,8 @@ existing, working Play installation was present. There was no Update or Install action offered, so no fresh enrollment, fresh installation or upgrade event was performed. The ledger's existing-app/update branch permits this nondestructive verification; it does not require uninstalling a user's app to manufacture a -fresh-install result. PYB-001.2 still needs the separate iPad result. +fresh-install result. The separate [iPad result](07_iPad_Channel_Verification.md) completes the other +platform portion of PYB-001.2; both reports retain their evidence limits. ## Actual channel and launch observations diff --git a/docs/developments/2026-q4-reliable-workflow/c1-s1/07_iPad_Channel_Verification.md b/docs/developments/2026-q4-reliable-workflow/c1-s1/07_iPad_Channel_Verification.md index 6ca120f6..f8a53149 100644 --- a/docs/developments/2026-q4-reliable-workflow/c1-s1/07_iPad_Channel_Verification.md +++ b/docs/developments/2026-q4-reliable-workflow/c1-s1/07_iPad_Channel_Verification.md @@ -19,9 +19,10 @@ This retry supersedes the earlier locked-device result for current iPad access and installed identity. T03 asks to verify the current TestFlight installation; the installed beta and its functioning launch satisfy that bounded task without -reinstalling an already working app. The combined PYB-001.2 story still needs its -Android evidence and explicitly retains any unperformed enrollment/install -criteria. Neither this check nor a completed task qualifies BLE, draft recovery, +reinstalling an already working app. The combined PYB-001.2 current-installation verification is complete with the +separate [Android evidence](06_Android_Channel_Verification.md). Fresh enrollment +and install/upgrade behavior remain explicitly unperformed, outside this +existing-installation path. Neither this check nor a completed task qualifies BLE, draft recovery, the firmware matrix, or the five-participant pilot. ## Observations and acceptance assessment diff --git a/docs/planning/PyBLE_Implementation_Plan_and_Strategy_v1.0.md b/docs/planning/PyBLE_Implementation_Plan_and_Strategy_v1.0.md index ab6ff9fb..e1cf66ea 100644 --- a/docs/planning/PyBLE_Implementation_Plan_and_Strategy_v1.0.md +++ b/docs/planning/PyBLE_Implementation_Plan_and_Strategy_v1.0.md @@ -165,7 +165,7 @@ The [execution record](../developments/2026-q4-reliable-workflow/c1-s1/00_Execut The recovery estimate is **38–63 engineering hours**, or **45–72 hours** with the original recipe, representative-platform and follow-up allowances. The [design review](../developments/2026-q4-reliable-workflow/c1-s1/03_Recovery_Design_and_Sizing.md) offers a conditional 60-hour S2–S4 allocation, displacing earlier matrix and activation forecasts. The [validation inventory](../developments/2026-q4-reliable-workflow/c1-s1/04_Validation_Inventory_and_Operator_Recipe.md) estimates 13.5–26 operator hours for the app matrix and 30–59 for fresh full firmware qualification, excluding builds, unavailable access and defect repair. These are working estimates, not actual effort or promises. **SG0 remains blocked.** -The Android check used a Lenovo `TB-J616X` on Android 12; all 38 selected code/asset entries matched the retained build-8 AAB, supporting its historical source `768fafe45beee7731d1a38480cc0463a2f5680cd`. This comparison is narrower than complete installed-binary or Play Console provenance. The iPad was `iPad16,10` on iPadOS `26.6.2`; native TestFlight offered build 6, Open launched it, and the installed signer identity was `TestFlight Beta Distribution`. The historical build-5 handoff does not map build 6 to source. Neither check executes BLE/board qualification or establishes minimum-OS support. +The Android check used a Lenovo `TB-J616X` on Android 12; all 38 selected code/asset entries matched the retained build-8 AAB, supporting its historical source `768fafe45beee7731d1a38480cc0463a2f5680cd`. This comparison is narrower than complete installed-binary or Play Console provenance. The iPad was `iPad16,10` on iPadOS `26.6.2`; native TestFlight offered build 6 with Open, separate app launches succeeded, and the installed signer identity was `TestFlight Beta Distribution`. The historical build-5 handoff does not map build 6 to source. Neither check executes BLE/board qualification or establishes minimum-OS support. ### 2.4 Baseline metrics to collect