docs: record confirmed product scope and planning workflow (#3)

.planning/README.md

@@ -0,0 +1,90 @@
+# Planning memory
+
+This directory preserves the reasoning behind Medora decisions and discoveries across conversations. GitHub Issues track work; these records preserve the context and evidence. PR descriptions and chat history are pointers, not substitutes for the records.
+
+## Layout and naming
+
+```text
+.planning/
+  README.md
+  templates/
+    session.md
+    decision.md
+    follow-up.md
+  decisions/
+    <DATETIME-ISSUE-ID>/
+      session.md
+      D000-<slug>.md
+      D001-<slug>.md
+  follow-ups/
+    <DATETIME-title>/
+      follow-up.md
+      <optional supporting evidence>
+```
+
+- `DATETIME` is the creation time in UTC, formatted `YYYYMMDDTHHMMSSZ`. Metadata timestamps use ISO 8601 UTC (`YYYY-MM-DDTHH:MM:SSZ`). Record time is not an inferred time of the original conversation.
+- `ISSUE-ID` is the actual GitHub issue number, without `#`; store the repository and full issue URL in metadata. Reuse the same folder when continuing a session. A separately scoped session gets a new timestamped folder even if it shares an issue.
+- Use lowercase hyphenated title slugs. Preserve directory names and decision IDs after creation; change the display title in metadata. If a creation-time collision occurs, use the next actual creation timestamp, never overwrite another record.
+- If GitHub is unavailable, save under `<DATETIME-pending>` with a null issue and an explicit blocker. Once an issue exists, rename to the required issue-number form and repair references. Do not invent an issue ID or lose answers while waiting for GitHub.
+- Decision IDs are sequential within a session (`D001`, `D002`, etc.); a full reference includes the session folder. `D000` may capture explicit user constraints supplied before the interview. One decision file covers one question; clarification exchanges stay with that decision.
+- Cross-record metadata paths are relative to the repository root. Markdown links are relative to their containing file. Use real paths/URLs, `null`, or empty lists; do not invent evidence.
+- Templates define required fields and sections. Mark unknown values `null`/`unknown`, and explain genuinely inapplicable sections. Extend records when necessary without silently changing field meanings; increment `schema_version` for incompatible schema changes.
+
+## Grilling workflow
+
+1. Read the product vision, the session index if resuming, relevant predecessor decisions, and related follow-ups. Create or reuse the tracking issue and session folder. Record the topic, constraints, participants, origin, and scope before the first round.
+2. Build a decision tree. Ask only questions whose prerequisites are settled; record prerequisite links and the unresolved branches in `session.md`. Recommendations and alternatives belong beside the exact question, not in the confirmed-decision field.
+3. Save each answer before asking the next round. Quote the user's words separately from the assistant's interpretation. Record a message/turn description if no conversation URL or message ID is available. For partial answers, retain unresolved subquestions; never substitute the recommendation for an omitted answer.
+4. An explicit, unambiguous user choice can confirm that decision. When the user explicitly delegates a choice, record the delegation source, the assistant-selected outcome, and its rationale without attributing the details to the user. If the interpretation introduces commitments the user did not state, use `needs-clarification` and ask. Silence, a timeout, and an assistant recommendation never confirm a decision.
+5. Maintain the session's decision table, dependency tree, current question frontier, deferred branches, and linked follow-ups. A deliberately deferred question must name its reason, blocking prerequisite or revisit trigger, and follow-up when it represents future work.
+6. Preserve history when an answer changes. Append the new exchange, record what changed and why, and identify downstream decisions needing reconsideration. A replacement decision links `supersedes`; the older record links `superseded_by`. Keep old replies intact rather than rewriting them to fit the latest outcome.
+7. Before ending a round, persist records and report anything not yet saved. Follow the repository's branch/PR workflow for publication. Keep an ongoing interview's PR in draft and its issue open; saving records does not imply the session is complete.
+8. When all in-scope branches are resolved or explicitly deferred, present the shared understanding and request explicit session confirmation. Store that confirmation before implementing the resulting design. Logging rules already requested by the user may be written during the interview.
+
+Session statuses: `active`, `awaiting-confirmation`, `confirmed`, `paused`, `superseded`. Decision statuses: `unanswered`, `needs-clarification`, `confirmed`, `deferred`, `superseded`. A reopened decision returns to `needs-clarification` with its earlier answer retained in history.
+
+## Follow-up workflow
+
+- Capture an unrelated idea, bug, risk, question, or deferred task as soon as it is recognized. Record why it arose, when it was observed, where it was encountered, the current task, relevant evidence, analysis, affected product capabilities or code components, and why it is outside the current scope.
+- Search existing follow-ups before creating another. Add new evidence to an existing record for the same concern. Distinct duplicates link to the canonical record; do not discard their provenance.
+- Separate observed facts, user reports, hypotheses, and unknowns. Include reproduction steps for bugs when available; use explicit `not applicable` for other kinds. Do not invent a diagnosis or priority.
+- `kind` is one of `feat`, `bug`, `docs`, `research`, `question`, `security`, `perf`, `refactor`, `test`, `ci`, `build`, `chore`. Record severity separately from delivery priority; an unassessed item has null values.
+- Status progresses from `captured` to `triaged`, `scheduled`, `in-progress`, then `resolved`; `dismissed` and `duplicate` are alternative outcomes. Record an owner, next action, dependencies, and revisit trigger as they become known. Capture alone neither expands the current task nor authorizes implementation.
+- Before related work, read matching open records and check whether their assumptions still hold. When promoting one to a GitHub issue, link both directions and keep the original context here. Resolve only with outcome/verification evidence; dismissal needs a reason, and duplication needs a canonical link.
+- Keep each follow-up folder's `follow-up.md` as its canonical record. Update the index below when creating, scheduling, superseding, or resolving records.
+
+## Confidentiality and sources
+
+Use synthetic patient examples and avoid private practice details or credentials in this public repository. Preserve user replies verbatim when safe; if redaction is necessary, mark the redaction and reason explicitly and never claim the stored text is an unaltered transcript. Link restricted evidence instead of copying sensitive content. Record only relevant conversation excerpts.
+
+Confirmed planning decisions inform product documents and implementation issues; those should link back to the originating records. A future architecture ADR records the architectural decision and links to relevant planning history. Do not silently replace an existing product constraint or ADR with a new interpretation.
+
+## Feature register
+
+[Product feature register](feature-register.md) preserves the full capability vision and separates confirmed first-increment scope from unsequenced work.
+
+## Schemas
+
+- [Session schema](templates/session.md): purpose, scope, issue, origin, decision tree, round index, unresolved branches, follow-ups, and final confirmation.
+- [Decision schema](templates/decision.md): context, predecessors, exact question, recommendations, raw replies, interpretation, outcome, consequences, evidence, and history.
+- [Follow-up schema](templates/follow-up.md): why/when/where, analysis, affected components, kind, impact, next action, dependencies, and closure evidence.
+
+## Sessions
+
+| Session | Scope | Status |
+| --- | --- | --- |
+| [20261015T085738Z-3](decisions/20261015T085738Z-3/session.md) | Product functionality and initial scope; no technical stack | confirmed |
+
+## Follow-ups
+
+| Follow-up | Kind | Status | Revisit trigger |
+| --- | --- | --- | --- |
+| [Select i18n/localization libraries](follow-ups/20261015T102802Z-select-internationalization-and-localization-libraries/follow-up.md) | build | captured | Technical stack planning after language requirements |
+| [AI-generated additional UI translations](follow-ups/20261015T110819Z-ai-generated-additional-ui-translations/follow-up.md) | feat | captured | Expansion beyond the initial four languages |
+| [Choose beta operating countries](follow-ups/20261015T121349Z-choose-beta-operating-countries/follow-up.md) | question | captured | Before beta eligibility/local operating rules |
+| [Validate WhatsApp linked-line onboarding](follow-ups/20261015T142428Z-validate-whatsapp-linked-line-onboarding/follow-up.md) | research | captured | Technical integration planning before promising connection modes |
+| [Define detailed booking and rescheduling policies](follow-ups/20261015T155426Z-define-detailed-booking-policies/follow-up.md) | question | captured | Before implementing the affected scheduling policies or activating them for a practice |
+| [Define identity, permissions and sharing access rules](follow-ups/20261015T155426Z-define-identity-permissions-and-sharing/follow-up.md) | question | captured | Before enabling affected record access, membership administration, sharing or booking changes |
+| [Define handoff, group and notification workflows](follow-ups/20261015T155426Z-define-handoff-and-notification-workflows/follow-up.md) | question | captured | Before implementing or enabling the corresponding handoff, group or delivery-failure flows |
+| [Define profile, intake and correction details](follow-ups/20261015T155426Z-define-profile-fields-and-intake-details/follow-up.md) | question | captured | Before implementing affected profile/intake behavior or collecting real patient intake |
+| [Define beta validation and public-release criteria](follow-ups/20261015T155426Z-define-beta-validation-and-release-gates/follow-up.md) | question | captured | Before inviting real beta practices or claiming readiness for broader advertising |

.planning/decisions/20261015T085738Z-3/D000-planning-memory-and-scope.md

@@ -0,0 +1,77 @@
+---
+{
+  "schema_version": 1,
+  "id": "20261015T085738Z-3/D000",
+  "session": ".planning/decisions/20261015T085738Z-3/session.md",
+  "title": "User-directed session scope and durable planning records",
+  "status": "confirmed",
+  "round": 0,
+  "created_at": "2026-10-15T08:57:38Z",
+  "updated_at": "2026-10-15T08:57:38Z",
+  "asked_at": null,
+  "answered_at": null,
+  "confirmed_at": null,
+  "decision_owner": "user",
+  "recorded_by": "assistant",
+  "issue_url": "https://github.com/codeonym-org/medora/issues/3",
+  "predecessors": [],
+  "related_decisions": [],
+  "supersedes": [],
+  "superseded_by": [],
+  "affected_components": [
+    "Agent instructions",
+    "Planning memory",
+    "Product discovery"
+  ],
+  "follow_ups": [],
+  "sources": [
+    "User message invoking grill-me in the current conversation"
+  ]
+}
+---
+
+# Context — why ask this?
+
+The user initiated product discovery and explicitly requested durable reasoning records to prevent decisions and unrelated discoveries from being lost in chat or PRs. This is a direct instruction, not a question asked by the assistant.
+
+## Predecessor decisions
+
+None. The existing product vision supplies the product context.
+
+## Question
+
+Not applicable: the user supplied the instruction before the first interview round.
+
+## Recommendation and alternatives
+
+The assistant proposes versioned Markdown templates, one session index and one file per decision, plus separate follow-up records. Field names, UTC formatting, statuses, and file organization are implementation choices for the requested schema; they are editable and were not separately dictated by the user.
+
+## User reply — original words
+
+Source: current conversation, user message invoking `$grill-me`; no message timestamp or URL was provided.
+
+> $grill-me lets do some digging about the project functionalities, ideas etc ... (no technical stack for now) also, id like you for each grilling session we create from now on, store the decisions under .planning/decisions/<DATETIME-ISSUE-ID>/ each decision shall cover the context (why it was asked?) the predecessor decisions, the question, the user reply, the intepretation, extra notes .... save this into your instructions! same apply for follow-ups, occutionally, we will some follow ups that are unrelated to current task at hand, instead of adding it only to PR or somewhere where its hard to remember, we log it into .planning/follow-ups/<DATETIME-title> it shall has good context like: why, when, where, analysis, affected components, kind: feat / bug / ... etc .... (draft a complete schema)
+
+## Interpretation
+
+Record future Medora grilling sessions in the requested session folders, including exact exchanges and dependency context. Record unrelated follow-ups independently with enough context to act later. Persist the rules in repository agent instructions. Explore product functionality now; defer technical stack selection.
+
+## Decision and rationale
+
+The logging requirement and current scope are confirmed by the direct user instruction. The user wants discoverable context beyond PR descriptions. The schema is a concrete draft implementing that request; individual product questions remain unanswered. Null answer/confirmation timestamps indicate that the original message time was not available; created_at records when this evidence was saved.
+
+## Consequences and affected components
+
+AGENTS.md points future sessions to the planning lifecycle and templates. Every interview round must preserve replies before continuing. Incidental ideas remain discoverable without silently expanding the active task.
+
+## Assumptions, evidence, and open questions
+
+Persistence is repository-scoped. Global agent settings are not modified. The final product design has not been confirmed.
+
+## Extra notes and follow-ups
+
+No unrelated follow-up has been identified yet. No application work is authorized by merely recording an idea.
+
+## History
+
+- 2026-10-15T08:57:38Z — Assistant recorded the explicit user instruction and distinguished it from proposed schema details.