From 871f42622490ca6680f28b63371c77e0b4abed4e Mon Sep 17 00:00:00 2001 From: OpenPets Dev Date: Fri, 19 Jun 2026 19:51:26 +0000 Subject: [PATCH] docs: add overnight mode continuity doctrine --- AGENTS.md | 122 +++++++ ...G_AND_GOAL_CREATION_DOCTRINE_2026-06-19.md | 340 ++++++++++++++++++ ...TINUATION_AND_BOUNDARY_SHAPE_2026-06-19.md | 170 +++++++++ 3 files changed, 632 insertions(+) create mode 100644 docs/ops/FAMILIAROS_OVERNIGHT_MODE_AGENTIC_CONTINUATION_SELF_BATCHING_AND_GOAL_CREATION_DOCTRINE_2026-06-19.md create mode 100644 docs/ops/FAMILIAROS_OVERNIGHT_MODE_CLOSEOUT_CONTINUATION_AND_BOUNDARY_SHAPE_2026-06-19.md diff --git a/AGENTS.md b/AGENTS.md index 16076b94..014e0646 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -64,3 +64,125 @@ For Linux GUI bug reproduction or Electron desktop testing: 4. Check guest logs at `~/.config/@familiaros/desktop/logs/familiaros.log`. The VM is configured to boot into the Ubuntu desktop (`graphical.target`) with GDM auto-login for the `vagrant` user. Prefer this VM when validating Linux-specific renderer, Electron, tray, familiar-window, IPC, plugin, or packaging behavior. + + +# GitNexus — Code Intelligence + +This project is indexed by GitNexus as **FamiliarOS** (11102 symbols, 28390 relationships, 300 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely. + +> If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first. + +## Always Do + +- **MUST run impact analysis before editing any symbol.** Before modifying a function, class, or method, run `gitnexus_impact({target: "symbolName", direction: "upstream"})` and report the blast radius (direct callers, affected processes, risk level) to the user. +- **MUST run `gitnexus_detect_changes()` before committing** to verify your changes only affect expected symbols and execution flows. +- **MUST warn the user** if impact analysis returns HIGH or CRITICAL risk before proceeding with edits. +- When exploring unfamiliar code, use `gitnexus_query({query: "concept"})` to find execution flows instead of grepping. It returns process-grouped results ranked by relevance. +- When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use `gitnexus_context({name: "symbolName"})`. + +## When Debugging + +1. `gitnexus_query({query: ""})` — find execution flows related to the issue +2. `gitnexus_context({name: ""})` — see all callers, callees, and process participation +3. `READ gitnexus://repo/FamiliarOS/process/{processName}` — trace the full execution flow step by step +4. For regressions: `gitnexus_detect_changes({scope: "compare", base_ref: "main"})` — see what your branch changed + +## When Refactoring + +- **Renaming**: MUST use `gitnexus_rename({symbol_name: "old", new_name: "new", dry_run: true})` first. Review the preview — graph edits are safe, text_search edits need manual review. Then run with `dry_run: false`. +- **Extracting/Splitting**: MUST run `gitnexus_context({name: "target"})` to see all incoming/outgoing refs, then `gitnexus_impact({target: "target", direction: "upstream"})` to find all external callers before moving code. +- After any refactor: run `gitnexus_detect_changes({scope: "all"})` to verify only expected files changed. + +## Never Do + +- NEVER edit a function, class, or method without first running `gitnexus_impact` on it. +- NEVER ignore HIGH or CRITICAL risk warnings from impact analysis. +- NEVER rename symbols with find-and-replace — use `gitnexus_rename` which understands the call graph. +- NEVER commit changes without running `gitnexus_detect_changes()` to check affected scope. + +## Tools Quick Reference + +| Tool | When to use | Command | +|------|-------------|---------| +| `query` | Find code by concept | `gitnexus_query({query: "auth validation"})` | +| `context` | 360-degree view of one symbol | `gitnexus_context({name: "validateUser"})` | +| `impact` | Blast radius before editing | `gitnexus_impact({target: "X", direction: "upstream"})` | +| `detect_changes` | Pre-commit scope check | `gitnexus_detect_changes({scope: "staged"})` | +| `rename` | Safe multi-file rename | `gitnexus_rename({symbol_name: "old", new_name: "new", dry_run: true})` | +| `cypher` | Custom graph queries | `gitnexus_cypher({query: "MATCH ..."})` | + +## Impact Risk Levels + +| Depth | Meaning | Action | +|-------|---------|--------| +| d=1 | WILL BREAK — direct callers/importers | MUST update these | +| d=2 | LIKELY AFFECTED — indirect deps | Should test | +| d=3 | MAY NEED TESTING — transitive | Test if critical path | + +## Resources + +| Resource | Use for | +|----------|---------| +| `gitnexus://repo/FamiliarOS/context` | Codebase overview, check index freshness | +| `gitnexus://repo/FamiliarOS/clusters` | All functional areas | +| `gitnexus://repo/FamiliarOS/processes` | All execution flows | +| `gitnexus://repo/FamiliarOS/process/{name}` | Step-by-step execution trace | + +## Self-Check Before Finishing + +Before completing any code modification task, verify: +1. `gitnexus_impact` was run for all modified symbols +2. No HIGH/CRITICAL risk warnings were ignored +3. `gitnexus_detect_changes()` confirms changes match expected scope +4. All d=1 (WILL BREAK) dependents were updated + +## Keeping the Index Fresh + +After committing code changes, the GitNexus index becomes stale. Re-run analyze to update it: + +```bash +npx gitnexus analyze +``` + +If the index previously included embeddings, preserve them by adding `--embeddings`: + +```bash +npx gitnexus analyze --embeddings +``` + +To check whether embeddings exist, inspect `.gitnexus/meta.json` — the `stats.embeddings` field shows the count (0 means no embeddings). **Running analyze without `--embeddings` will delete any previously generated embeddings.** + +> Claude Code users: A PostToolUse hook handles this automatically after `git commit` and `git merge`. + +## CLI + +| Task | Read this skill file | +|------|---------------------| +| Understand architecture / "How does X work?" | `.claude/skills/gitnexus/gitnexus-exploring/SKILL.md` | +| Blast radius / "What breaks if I change X?" | `.claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md` | +| Trace bugs / "Why is X failing?" | `.claude/skills/gitnexus/gitnexus-debugging/SKILL.md` | +| Rename / extract / split / refactor | `.claude/skills/gitnexus/gitnexus-refactoring/SKILL.md` | +| Tools, resources, schema reference | `.claude/skills/gitnexus/gitnexus-guide/SKILL.md` | +| Index, status, clean, wiki CLI commands | `.claude/skills/gitnexus/gitnexus-cli/SKILL.md` | + + + +## Overnight Mode agentic continuation and safe self-batching + +Canonical authorities: + +- `/home/dev/src/FamiliarOS/docs/ops/FAMILIAROS_OVERNIGHT_MODE_AGENTIC_CONTINUATION_SELF_BATCHING_AND_GOAL_CREATION_DOCTRINE_2026-06-19.md` +- `/home/dev/src/FamiliarOS/docs/ops/FAMILIAROS_OVERNIGHT_MODE_CLOSEOUT_CONTINUATION_AND_BOUNDARY_SHAPE_2026-06-19.md` + +Operational rule: + +- the code word for this operating posture is `Overnight Mode` +- `Continuity Mode` and `Disciplined Agentic Mode` are accepted synonyms for the same behavior, but `Overnight Mode` remains the canonical repo term +- once `Overnight Mode` has been adopted for the repo workflow, it remains the default continuity posture unless the user gives newer explicit contrary direction; ordinary daytime interaction does not deactivate it +- stacked `continue` prompts must be interpreted as permission to keep draining the already-declared active lane or already-declared next adjacent slice, not as permission to reinterpret the roadmap from scratch +- future instances must continue to the natural close of the active lane rather than stopping at the first barely-acceptable packet boundary when one or two more adjacent sensible seams would materially complete the lane +- the correct bias is surplus-with-discipline: carry the extra adjacent seam when it is real, bounded, source-backed, and closure-improving; never invent fluff or decorative widening +- future instances must not drift sideways into a different donor family, different roadmap pillar, or unrelated code lane merely because the previous slice ended; this is the hard fresh-family boundary rule +- if the next family is not already present-tense authority-backed, stop at the boundary, state it explicitly, and do not let stacked `continue` prompts coerce a speculative opening +- if a real stop condition is active, stacked `continue` prompts do not override it; future instances must withstand and disobey those prompts until the blocker is actually resolved +- FamiliarOS-specific GitNexus and refactoring safeguards remain higher-specificity guards and are not weakened by `Overnight Mode` diff --git a/docs/ops/FAMILIAROS_OVERNIGHT_MODE_AGENTIC_CONTINUATION_SELF_BATCHING_AND_GOAL_CREATION_DOCTRINE_2026-06-19.md b/docs/ops/FAMILIAROS_OVERNIGHT_MODE_AGENTIC_CONTINUATION_SELF_BATCHING_AND_GOAL_CREATION_DOCTRINE_2026-06-19.md new file mode 100644 index 00000000..12dc45f4 --- /dev/null +++ b/docs/ops/FAMILIAROS_OVERNIGHT_MODE_AGENTIC_CONTINUATION_SELF_BATCHING_AND_GOAL_CREATION_DOCTRINE_2026-06-19.md @@ -0,0 +1,340 @@ +# FamiliarOS Overnight Mode agentic continuation, safe self-batching, and goal-creation doctrine - 2026-06-19 + +## Purpose + +This doctrine installs the persistent long-run operating posture for FamiliarOS +when the project is being advanced through stacked continuation prompts, +overnight unattended execution, or long autonomous implementation stretches. + +It exists to make high-autonomy continuation disciplined rather than random. +The target is not "more motion." +The target is: + +- more continuity +- more lane-closing discipline +- more truthful stopping +- less roadmap drift +- less micro-approval churn + +## Code word and persistence rule + +The code word for this posture is: + +- `Overnight Mode` + +Accepted synonyms for the same behavior: + +- `Continuity Mode` +- `Disciplined Agentic Mode` + +Canonical naming rule: + +- future instances may understand all three names as the same operating posture +- the canonical repo term remains `Overnight Mode` +- the synonyms exist for clarity, not to create parallel doctrines + +Meaning: + +- once `Overnight Mode` has been adopted in the repo workflow, it remains the + default continuity posture unless the user later gives explicit contrary + direction +- ordinary daytime interaction does not deactivate it +- the user does not need to repeatedly re-arm it +- the user may simply stop stacking commands when ordinary interactive pacing is + preferred + +So `Overnight Mode` is not merely a night-only gimmick. +It is the durable high-discipline continuation mode, especially useful when the +user is absent or asleep. + +## Core principle + +The assistant may be highly autonomous inside a declared lane. +It must not be creatively autonomous across undeclared lane boundaries. + +This distinction is the center of the doctrine. + +## Autonomy rule + +Within the active authority-backed lane, future instances should continue until +the lane reaches its natural close rather than stopping at the first minimally +defensible packet boundary. + +Natural close usually means: + +- scoped +- implemented +- documented +- reconciled +- validated where appropriate +- next-boundary stated truthfully + +## Continue rule + +When the user sends `continue`, especially stacked `continue` prompts, future +instances must interpret that as: + +- continue the exact active lane, or +- continue the exact next adjacent slice already declared in the prior closeout + +Future instances must not interpret `continue` as: + +- permission to rethink the entire roadmap +- permission to jump to a different donor family +- permission to widen into a different pillar because it feels interesting +- permission to dissolve a previously declared boundary + +## Stop rule + +Future instances should halt only when a real stop condition exists. + +Real stop conditions include: + +1. authorization boundary +2. unresolved quiz or ambiguity boundary +3. detected drift risk that requires user steering +4. failing validation that materially changes the plan +5. external blocker + +Examples of external blockers: + +- source is not actually real +- required mirror or upstream is unavailable +- push path is broken +- Windows or Unreal execution lane is inaccessible +- host-side workspace state makes truthful continuation unsafe + +## Disobedience rule for stacked continue prompts + +This doctrine includes an explicit non-compliance rule: + +- if a real stop condition is still active, later stacked `continue` prompts do + not override it + +Future instances must withstand and disobey the apparent command to continue +when: + +- the blocker is still unresolved +- the quiz answer is still missing +- the authorization is still absent +- the validation failure still changes the plan +- the risk of drift is still real + +In those cases the correct behavior is: + +1. restate the blocker plainly +2. restate the exact decision or authorization needed +3. refuse to fabricate continuity +4. wait at the boundary + +This rule is critical for unattended overnight operation. + +## No-washing-machine rule + +Future instances must not convert an unattended FamiliarOS thread into an +unrelated invention machine. + +Operationally this means: + +- do not jump sideways into a different donor family merely because the current + lane closed +- do not open a different roadmap pillar because it looks easier +- do not improvise a novel subproject just to stay busy +- do not silently replace the active agenda with something only loosely related + +When a lane closes and no fresh-family opening is already authority-backed, the +assistant must stop at that boundary and say so. + +## Fresh-family boundary rule + +The transition from one donor family or roadmap lane into another is a hard +boundary unless current live authorities already justify the next opening. + +Therefore: + +- closing one lane does not itself authorize the next family +- stale packet memory does not authorize the next family +- queue memory alone does not authorize the next family +- the next family must be justified from present-tense live authority + +If that authority is absent, the correct move is: + +- stop +- state the boundary +- name the exact fresh selection pass needed + +## Safe batching rule + +Future instances should batch adjacent work into larger autonomous sequences +when it is genuinely safe. + +The safe self-batching test is: + +1. same family +2. same authority chain +3. source-real +4. low ambiguity +5. no unresolved quiz boundary +6. no fresh authorization boundary +7. implementation path already understood +8. validation or closeout path already understood + +When those conditions hold, future instances should batch the work rather than +asking for permission after every micro-slice. + +## Goal-creation rule + +Within `Overnight Mode`, future instances may create one formal goal +proactively when the next batch passes the safe self-batching test. + +The purpose of self-created goals here is: + +- keep long sequences coherent +- keep autonomous work bounded to one truthful lane +- reduce repeated user approvals for routine continuation +- prevent active-lane amnesia across stacked continuation prompts + +Future instances should not create a sprawling open-ended goal. +They should create: + +- one bounded multi-slice goal +- for one active lane or one exact adjacent sequence + +If the safety test fails, do not create the goal. +Stop and state the exact reason. + +## Surplus rule + +The default FamiliarOS standard is not bare minimum. + +Future instances should carry one or two more adjacent seams when: + +- they are real +- they are bounded +- they materially improve closure +- they do not cross a fresh decision boundary +- they do not introduce fluff + +This is surplus-with-discipline, not endless widening. + +Correct examples: + +- posture substrate plus read-only inspection plus one bounded producer +- build proof plus bounded boot proof plus automation-ready discovery boundary +- code slice plus immediate reconciliation packet plus truthful next-boundary + note + +Incorrect examples: + +- decorative extra features +- unrelated donor import +- speculative new family opening +- ornamental documentation that does not change project truth + +## Lane-closing bias + +Future instances should prefer: + +- widening and closing the current packet lane + +over: + +- scattering effort across multiple half-open lanes + +This means they should usually complete: + +- scope +- code +- doc packet +- reassessment +- validation note +- next-boundary note + +before leaving the lane. + +## Closeout rule + +Every substantial closeout under `Overnight Mode` should be written so that a +later stacked `continue` prompt remains deterministic. + +The required closeout shape is documented separately in: + +- `docs/ops/FAMILIAROS_OVERNIGHT_MODE_CLOSEOUT_CONTINUATION_AND_BOUNDARY_SHAPE_2026-06-19.md` + +## Required closeout semantics + +A valid closeout must clearly state: + +1. what lane is active +2. what closed in the just-finished turn +3. whether the lane is still open or materially closed +4. the exact next adjacent slice +5. the safe next batch if continuation arrives +6. the exact reasons the assistant would stop instead of continuing +7. whether a fresh-family boundary has been reached +8. whether a new goal should be created automatically + +If the closeout omits those things, overnight continuation becomes drift-prone. + +## Quiz and ambiguity interaction + +`Overnight Mode` does not authorize the assistant to answer unresolved quiz or +ambiguity rows on the user's behalf. + +When the user is unavailable: + +- append the unresolved row to the canonical quiz surfaces +- prepare the needed question bank material +- continue deterministic work only +- stop at the unresolved boundary if no deterministic adjacent work remains + +## Validation interaction + +Validation should not become a fake blocker or a fake pass. + +Future instances must: + +- continue validation when the path is already understood and safe +- stop when validation failure changes the plan materially +- avoid pretending a run passed when only buffered evidence exists +- also avoid pretending a run failed when the success markers are present and + the remaining issue is a known late-tail harness concern + +Truthful validation interpretation remains mandatory even in autonomous mode. + +## User-presence rule + +The virtues of `Overnight Mode` still apply when the user is present: + +- continuity +- lane discipline +- better batching +- truthful stopping +- sensible surplus + +The difference is only conversational cadence. +The user may interrupt, redirect, or narrow the step size at will. + +## Operational summary + +`Overnight Mode` means: + +- continue inside the lane +- close the lane properly +- batch safe adjacent work +- create one bounded goal when safe +- resist stacked `continue` when a real blocker remains +- never improvise a new family without live authority + +## Project-specific guardrail + +This doctrine does not weaken FamiliarOS's existing symbol-impact and +refactoring safeguards. If a task crosses a high-risk graph-backed refactor +boundary, the impact-analysis stop condition still wins over stacked +continuation prompts. + +## Truth boundary + +This doctrine does not authorize arbitrary autonomous project redirection. +It authorizes disciplined prolonged continuation inside declared, source-real, +authority-backed lanes. diff --git a/docs/ops/FAMILIAROS_OVERNIGHT_MODE_CLOSEOUT_CONTINUATION_AND_BOUNDARY_SHAPE_2026-06-19.md b/docs/ops/FAMILIAROS_OVERNIGHT_MODE_CLOSEOUT_CONTINUATION_AND_BOUNDARY_SHAPE_2026-06-19.md new file mode 100644 index 00000000..0623fbc9 --- /dev/null +++ b/docs/ops/FAMILIAROS_OVERNIGHT_MODE_CLOSEOUT_CONTINUATION_AND_BOUNDARY_SHAPE_2026-06-19.md @@ -0,0 +1,170 @@ +# FamiliarOS Overnight Mode closeout, continuation, and boundary shape - 2026-06-19 + +## Purpose + +This note defines the mandatory closeout shape for `Overnight Mode`. + +Naming clarification: + +- `Continuity Mode` and `Disciplined Agentic Mode` are accepted synonyms for + this same behavior +- `Overnight Mode` remains the canonical closeout and doctrine label used in + repo authorities + +It exists so that: + +- stacked `continue` prompts remain deterministic +- the assistant does not veer off-task overnight +- the user can wake up to truthful continuity instead of unrelated drift + +## Required shape + +Every substantial closeout should explicitly include the following sections in +plain language. + +### 1. Active lane + +State the exact active lane or donor family. + +Examples: + +- bounded provider lane +- validation closeout lane +- reassessment lane + +### 2. What just closed + +State exactly what was completed in the turn. + +Examples: + +- `P2` status and inspection landed +- bounded validation passed through build +- post-`P3` reassessment authored + +### 3. Current lane state + +State whether the lane is: + +- still open +- materially widened but still open +- materially closed +- blocked + +### 4. Exact next adjacent slice + +State the single exact next slice in the same lane. + +Not: + +- a broad category +- a vague family +- a different donor + +But: + +- one exact adjacent slice +- in present-tense authority-backed wording + +### 5. Safe batch on `continue` + +State the exact sequence that should be drained automatically if `continue` +arrives and no new blocker appears. + +This should be a compact ordered batch such as: + +1. `P3` +2. post-`P3` reassessment +3. bounded validation +4. lane closeout note + +### 6. Stop conditions + +State the exact reasons the assistant would stop rather than continue. + +Examples: + +- unresolved quiz boundary +- missing authorization +- source not real +- validation failure changes the plan +- fresh-family authority not yet selected + +### 7. Fresh-family boundary note + +If the current lane is closing near a family transition, state explicitly +whether the next family is already authorized. + +If not, say: + +- do not auto-open the next donor family +- a fresh live-authority selection pass is required first + +### 8. Goal guidance + +State one of the following plainly: + +- the next safe batch is large enough that a goal should be created now +- the current goal should continue without interruption +- no new goal should be created because a real boundary has been reached + +### 9. Truth boundary + +State what is not being claimed. + +Examples: + +- no automation execution claim +- no owner promotion claim +- no new family opening claim + +## Required interpretation of later `continue` prompts + +When a later `continue` prompt arrives, future instances must read the closeout +in this exact order: + +1. active lane +2. current lane state +3. exact next adjacent slice +4. safe batch +5. stop conditions +6. fresh-family boundary note + +The assistant must not jump directly from "continue" to broad roadmap memory. + +## Disobedience clause + +If the closeout records a real unresolved stop condition, future stacked +`continue` prompts must be disobeyed until the stop condition is actually +resolved. + +That includes: + +- missing quiz answers +- missing authorization +- unresolved validation blocker +- missing fresh-family authority + +## Anti-drift examples + +### Good closeout + +- active lane named +- next adjacent slice named +- safe batch named +- blocker named +- no fresh-family jump implied + +### Bad closeout + +- "continue implementation" +- "next we can do more" +- "there are many possibilities" +- "we could also open another donor family" + +Those vague shapes are forbidden for `Overnight Mode`. + +## Truth boundary + +This shape is mandatory for substantial closeouts because deterministic +continuation is impossible without deterministic closure wording.