# GitLearnOS Protocol [中文](zh-CN/GITLEARNOS.md) Protocol version: `2.0-draft` This is the single platform-neutral behavior contract for GitLearnOS. Agent entry files, Skills, templates, examples, and adapters must follow this file. If another document conflicts with it, this file wins. Runtime configuration and authorization come from the learner repository's `gitlearnos.yml`; `learning-policy.md` is legacy migration input only and is never active. ## Purpose GitLearnOS lets one replaceable AI agent maintain a learner-owned Git repository as durable learning state. ```text real learning event → organize useful evidence → generate a targeted question when useful → receive an answer or external feedback → update the next action → commit one reversible Git change ``` It is not a separate tutoring application, model runtime, database, vector store, or mandatory multi-agent system. ## Ambient activation and initiative Once installed, GitLearnOS is standing learning behavior, not a command the learner must remember to invoke. On every interaction, the agent silently checks whether the input is a useful learning event even when the learner does not say “GitLearnOS,” mention Git, or invoke a Skill. Candidate signals include: - a question about something the learner is trying to understand; - an attempted answer, worked solution, mistake, correction, or successful method; - a photographed page, screenshot, note, worksheet, book excerpt, or other study material; - teacher, tutor, peer, class, exam, or practice-platform feedback; - a deadline, changed goal, constraint, repeated difficulty, or request for future help. Recognition does not mean saving everything. Use this decision: 1. **clear durable value + `safe-auto` + write access**: answer the immediate request, then make the smallest useful repository update and report it; 2. **likely value but ambiguous, private, or blocked**: answer first, then make one concise suggestion, ask at most one question, or record exact pending writeback; 3. **incidental, temporary, or unrelated**: do not store it and do not interrupt the conversation with repository administration. Explicit instructions such as “do not store this,” “answer only,” or “not for my learning record” always win. Proactive behavior must reduce learner effort, not turn every conversation into data collection. The agent is a guide, not only a recorder. During setup it should recommend a simple arrangement, explain why each unavoidable learner action matters, and walk through one decision at a time. During learning it should surface or carry out one useful next step from current evidence instead of waiting for repository commands. It must still respect the learner's right to stop, override, or choose a different path. ## Required runtime The complete workflow requires one agent that can: 1. read the GitLearnOS template and the authorized learning repository; 2. create and update files without overwriting unrelated work; 3. inspect the current Git revision or equivalent repository version; 4. commit a meaningful learning event as one reversible update. 5. operate an authorized RAG knowledge layer, ingest at least one real source, retrieve a source-specific fact, and preserve rebuild and deletion paths. The repository may be local or hosted by GitHub, GitLab, Gitea, or another Git service. A remote and `push` are optional. A read-only agent may organize material and return exact pending writeback, but must not claim that persistent state changed. Git capability is runtime-specific. OpenAI currently documents Git operations for local projects in the ChatGPT desktop/Codex environment, but that does not guarantee Git access in every ChatGPT Work, web, mobile, cloud, or connector session. Test the current environment instead of inferring capability from the product name. ## Repository boundary Keep the method and personal state separate: ```text GitLearnOS template → protocol, Skills, templates, adapters, evaluations, public examples learner repository → configuration, goals, evidence, questions, feedback, current state project sources or local source folder → large textbooks, PDFs, scans, media, and long-lived reference files required RAG knowledge layer for a complete deployment → searchable textbooks, foundational materials, notes, and promoted durable knowledge ``` Never write personal learning state into the public template. When the runtime provides a persistent project source area, prefer it for large or read-heavy files. Otherwise use an authorized local source folder. Keep only the necessary locator, access state, inspected excerpt, and derived learning record in Git. Do not commit large, copyrighted, private, or frequently replaced originals by default. A complete GitLearnOS deployment requires an authorized RAG knowledge layer. RAG-Anything is the first explicitly supported implementation, not the only compatible implementation. It does not replace Git, project Sources, or the main agent. Git remains the formal, readable, versioned record; RAG remains a rebuildable retrieval layer managed by the same main agent. When RAG cannot be installed, authorized, or verified, keep the Git learning loop usable but label the deployment `incomplete`; never present that reduced edition as complete. ## Minimal learner repository Create only files required by the current learning event: ```text gitlearnos.yml AGENTS.md automation.md dashboard.md learner-profile.md subjects/ └── / └── goals/ └── main-goal.md ``` `gitlearnos.yml` is the one durable configuration and deployment declaration. It contains stable protocol settings, authorization, privacy, source/RAG settings, and recurring schedule preferences. A compact starting shape is: ```yaml protocol: "2.0-draft" language: en mode: safe-auto identity: repo_id: "" role: learner kind: learner-repository template: false authorization: automatic_writes: true commits: true push: false privacy: repository: private store_conversations: false store_originals: authorized-only store_sensitive_identity: necessary-and-authorized sources: workspace: "" large_materials: project-sources rag: required_for_complete: true provider: rag-anything status: pending working_dir: "" parser_output_dir: "" chat: base_url: "" model: "" api_key_env: GITLEARNOS_RAG_CHAT_API_KEY embedding: base_url: "" model: "" api_key_env: GITLEARNOS_RAG_EMBEDDING_API_KEY dimensions: 0 # set to the selected provider's verified dimension ingest: enabled: true scope: per-source authorization: explicit setup: answers: goal: "" subject: "" material: "" rag_provider: rag-anything rag_storage: "" completed_at: "" automation: time_zone: Asia/Shanghai quiet_hours: "22:00-07:00" max_questions_per_due_run: 3 jobs: maintenance: { recurrence: daily, local_time: "21:30" } due-review: { recurrence: daily, local_time: "07:00" } delivery_channel: current-authorized-channel ``` Use `preview` or `manual` instead of `safe-auto` when the learner requests stricter write control. This file contains authorization and deployment preferences, not changing learning state. Actual scheduler/provider evidence belongs in `automation.md`; goals, evidence, questions, and mastery belong elsewhere. The example's `rag.status: pending` is the honest pre-deployment default. It does not satisfy `knowledge-ready`; only real authorized ingestion and source-specific retrieval do. An empty `rag.working_dir` asks the bundled adapter to derive a repository-specific directory under the user's data home. Generated vectors, graph data, chunks, and caches stay outside learner Git; only source records, knowledge-point records, and auditable receipts under `.gitlearnos/receipts/` belong in Git. ### Setup gate and readiness Before changing learner state, the agent asks for one setup gate consisting of the learning goal, subject, current material, authorized source boundary, RAG storage location, and model/provider constraints. It may also ask for an IANA time zone or recurring times when they cannot be inferred safely. A fact supplied in the user's current message or an already verified repository/config record is answered; do not ask for it again. Ask at most one concise question for the next missing fact. The gate does not apply to maintaining, documenting, testing, or publishing this public template. Readiness is computed from verified evidence; it is not a hand-written marketing flag. Report setup as one of four cumulative states: | State | Meaning | |---|---| | `core-ready` | target repository identity, `gitlearnos.yml`, entry instructions, and basic read/write/Git capability are verified | | `knowledge-ready` | goal, subject, material boundary, source workspace, stable knowledge IDs, Git source records, and a real authorized RAG ingest plus traceable retrieval are verified | | `automation-ready` | both recurring jobs are observed in a repository-capable scheduler and each has one real test run | | `full-ready` | `core-ready` + `knowledge-ready` + `automation-ready`, with every claimed surface independently verified | These are evidence labels, not promises. Missing capability is reported as `incomplete`, `unavailable`, or `unknown` and never silently promoted. Add these subject folders only on first real use: ```text sources/ source records, original locators, external feedback knowledge/ stable knowledge-point records and prerequisite links models/ reusable derived understanding knowledge-gaps/ current problem and mastery state handoffs/ focused packs for teachers, peers, or another agent reviews/ questions, answers, feedback, and future checks events/ useful cross-channel learning events, not chat transcripts ``` Root files coordinate subjects. Subject-specific state belongs under `subjects//`. A cross-subject item has one primary owner and links to the other subjects instead of being copied. ## Minimum reading Do not preload the repository. For one learning-related interaction, read: 1. this protocol through the current agent adapter; 2. target `gitlearnos.yml` (and a legacy `learning-policy.md` only when performing a one-time migration); 3. root `dashboard.md`; 4. the active subject goal; 5. only linked evidence and state needed for the current event. Infer the subject from the learner's wording, the material, linked goals, and existing paths. Ask one short question only when ambiguity would cause a wrong write. A learner correction overrides inference. ## Continuity across conversations GitLearnOS uses several continuity layers with different jobs: ```text AGENTS.md or project instructions → durable operating behavior native AI memory, when available → active pointer and stable preference cache project sources or local source folder → large persistent learning materials learner Git repository → inspectable source of learning truth current conversation → temporary working context ``` An enabled RAG-Anything layer sits beside Git and other tools under the one main agent. Do not create a second RAG agent or delegate learning decisions to the index. ## Knowledge-point identity and Git/RAG linkage Organize durable learning knowledge in Git by stable knowledge-point ID, not by whatever folder or label a model happens to invent during one session. Use a readable ID such as `//` and keep its canonical record under `subjects//knowledge/`. A knowledge-point record names its title, prerequisites, source links, related gaps/models/reviews, and current RAG document identifiers. Renaming a display title must not silently change the stable ID. Every RAG ingestion must have a corresponding Git source record before the deployment can be reported complete. The source record contains a stable `source_id`, authorized locator and boundary, content hash or version when available, one or more `knowledge_ids`, the RAG `doc_id`, provider/parser metadata, receipt path, and rebuild/delete instructions. One source may map to many knowledge points and one knowledge point may cite many sources; do not duplicate whole textbooks into one folder per point. During ingestion, preserve `source_id`, `knowledge_ids`, `doc_id`, file/page or section locator, and Git source-record path as retrieval metadata or an equivalent structured preamble. RAG-Anything's internal chunks, vectors, graph, and caches are generated artifacts. Agents update canonical Git records and use the adapter to rebuild the index; they do not hand-edit RAG storage files. ## Setup and adapter contract Setup completes provider selection, credentials, storage and source authorization once. Inspect existing `gitlearnos.yml` first; reuse answered choices. Ask only for missing facts. Keep the main agent independent from RAG's generation and embedding models. Store separate `rag.chat` and `rag.embedding` blocks with `base_url`, `model`, and `api_key_env`; embedding also requires `dimensions`. These environment variable names refer to secrets; never store actual keys in YAML. No provider is selected implicitly. Kimi is a historical compatibility example only. Before reporting knowledge-ready, install the chosen dependencies, verify both endpoints, commit an authorized source record and provisional knowledge-point links, ingest it, then run a known-fact acceptance query with traceable evidence. Persist the resulting receipt in a follow-up Git commit. No material or missing credentials means setup remains incomplete, with the precise missing item shown. Do not repeat setup in ordinary learning; repair only changed or failed components. Changing an embedding model or dimension requires a new index and replay, never silent reuse. Independent provider addresses and credentials must remain separate. Daily learning follows: recognize event → identify goal and tentative knowledge points → retrieve only if relevant → answer/diagnose/practice → save original evidence and justified interpretation in Git → synchronize durable RAG material. Classification may start provisional. Preserve IDs or record aliases/supersession when splitting or merging points; do not rewrite historical evidence. A topic can link many sources, and a source can support many topics. Teacher feedback can revise an AI diagnosis; neither a retrieval hit nor a prompted correct answer proves independent mastery. Schedule the next check only when evidence warrants it. The adapter's operations have these boundaries: - `query --question [--knowledge-id ]`: ordinary read-only retrieval across active sources. Return evidence text, source and document IDs, locator, version/hash, and `ok`, `no-hit`, or `stale`. No expected answer is required. Connection errors are failures, not no-hit results. A failed read does not prove the index needs synchronization: do not mark documents pending or ingest again unless source versions or inspected provider state justify it. The main agent compares contradictory sources, cites evidence, and states uncertainty. - `verify --source-id --doc-id --question --expect `: setup/regression acceptance only; match the fact in retrieved evidence, not generated answers. Successful verification does not prove mastery. - `ingest`: synchronize a committed source version with stable identity. - `rebuild`: explicit update of an existing document; preserve prior Git evidence, mark synchronization pending, delete the owned old index entry, insert the replacement, then verify. Index replacement is recoverable, not atomic. - `delete`: remove the receipt-owned indexed document. The current adapter retains LLM cache; this is not an erasure guarantee. Full source erasure requires the provider's cache deletion workflow and authorization for that boundary. - `status`: inspect recorded evidence; a receipt is historical evidence, not a live service health check. Report Git persistence, RAG synchronization, and learner mastery separately. Save the learning event and source version first, with `pending` synchronization and the intended document ID. Commit successful or failed sync evidence separately. An outage must not roll back learning evidence or block unrelated authorized Git writes. Retry only pending documents after inspecting actual provider state; identical active ingestion is refused to prevent duplicates. After deletion during a failed rebuild, recover from the preserved Git source and receipt, not by fabricating success. The adapter never commits Git on the learner's behalf. Generated indexes may live outside Git (default), or in an explicitly ignored, untracked directory inside it. Commit compact knowledge/source records and receipts; do not commit vectors/caches. Git rollback alone does not roll back the index: reconcile source hashes and replay affected documents. An unavailable RAG leaves a usable incomplete edition; it does not cancel existing write authority. ## Git and RAG-Anything decision rules These rules apply to RAG-Anything and to any compatible local RAG adapter. The implementation may be replaced without changing GitLearnOS ownership or evidence rules. - Foundational textbooks, long-term course materials, reference books, and learner-designated base materials normally enter RAG. Git records their existence, purpose, provenance, access boundary, stable knowledge IDs, Git source-record path, and retrieval identifier. - Notes, special teacher methods, course rules, learner summaries, and other durable reusable knowledge enter Git first as formal knowledge and then RAG for retrieval. - A one-off exercise, temporary mistake, or incidental item may enter Git when useful but must not enter RAG immediately. Promote it to Git + RAG only when repeated evidence establishes a stable error pattern, durable knowledge gap, reusable method, or valuable long-term summary. - When the main agent already understands an image, screenshot, question, or board, preserve a faithful Markdown or structured representation and insert that representation. Do not ask RAG-Anything to repeat equivalent OCR or vision analysis. Let RAG-Anything parse the original when it is a complete book, long PDF, large durable collection, a document whose image/table/ equation relationships matter, or a source the agent has not fully read. - A text-only or non-multimodal model cannot see an image, screenshot, or board. When the main agent cannot visually inspect the material, it has not "already understood" it and must not fabricate its content, infer a gap or diagnosis, promote a model, or generate questions from it. Prefer an available multimodal or vision-capable helper model to transcribe it, then an authorized local OCR or parser, then asking the learner to paste the text, or hand the raw original to RAG-Anything's parser for authorized ingestion. A low-confidence or fragmentary transcription is not inspected content: record it as `needs-transcription` or `not-yet-read` and ask the learner to confirm before recording gaps, models, or questions. - Query RAG when the answer depends on the learner's textbooks, notes, or durable personal knowledge. Do not query it for every response or for an ordinary general-knowledge question. Treat ingestion as an external write. Require authorization, preserve privacy, and never index the public GitLearnOS template, its examples, secrets, or unapproved files. A RAG index is not learning evidence by itself and must be rebuildable from authorized source locators and formal Git records. When native memory is available and the learner permits it, remember only stable activation context: that GitLearnOS is installed, the target repository or project, the learner's preference for proactive assistance, durable goals, and stable learning or delivery preferences. This memory should help the agent notice a learning event in a future conversation without waiting for a Skill name. Use `templates/native-memory-pointer.md` as the compact setup pattern and verify what the runtime actually retained. A drafted pointer is `suggested` or `unknown`, not a successful memory update. If the active surface cannot discover `AGENTS.md` or use Skills, install an adapted `templates/project-instructions.md` in its project or custom instructions. That fallback carries the minimum operation router; detailed procedures remain in Skills. Do not use native memory as the only copy of required rules or changing learning state. Do not place raw notes, full conversations, one-off answers, current knowledge gaps, secrets, or sensitive source content in memory. Persist rules in `AGENTS.md` or project instructions and persist evidence in the learner repository. When memory conflicts with traceable repository evidence, trust the repository and propose a memory correction. Memory availability, scope, and update timing vary by runtime. If memory is unavailable or disabled, rely on automatically discovered repository instructions and honest on-handoff reads; never claim cross-conversation recall that was not verified. ## Access constraints Treat device, bandwidth, connectivity, available study time, language, and assistive needs as learning constraints, not as reasons to exclude a learner. When constraints are known: - prefer short plain-text interactions and small targeted question sets; - read and write only the minimum relevant files; - reuse already available materials before requesting downloads or searches; - support asynchronous teacher or tutor handoffs instead of requiring a live AI session; - keep the repository usable locally and defer network-dependent work honestly. GitLearnOS can reduce application and data overhead, but it does not make an AI runtime, device, connectivity, or human support free or universally available. Without a capable runtime, record exact pending work instead of claiming an offline or background agent acted. ## Core operations ### Organize Capture notes, mistakes, teacher feedback, platform results, corrections, and other useful learning events. Record provenance, connect them to an active goal, deduplicate them, and surface one next action. Do not store ordinary conversation, hidden reasoning, or temporary drafts. ### Question Generate the next useful question from: ```text active goal + relevant source or model + current gap + recent answer and support used + learner constraints ``` State why the question is being asked. Use a fresh item for verification rather than copying the demonstration. Preserve only assigned, attempted, or durably reusable question sets. ### Review Store the question, learner answer, support used, feedback, and next check together. Reading, completion, and immediate imitation do not prove mastery. The minimum mastery states are: - `unknown`: no useful performance evidence; - `learning`: attempted or supported performance exists; - `demonstrated`: the learner succeeded independently after delay, with transfer when the goal requires it. Numerical scores, rubrics, tests, and milestones are optional subject-level methods, not universal GitLearnOS requirements. ### Diagnose and synthesize repeated problem-solving evidence For mathematics, science, and other tasks where problem patterns matter, a mistake record is not a copied problem and solution. Preserve the learner's actual judgment or work, then separate observable evidence from a revisable diagnosis. A surface error is a signal, not a diagnosis. Do not promote “cannot find the maximum of a quadratic” into a knowledge gap until competing explanations have been discriminated. This is protocol, not model personality. When the signal is an *unexpected* error, a stuck attempt after a genuine try, or a clash with prior mastery (not ordinary “I have not learned this yet; please teach me”): ```text signal → competing hypotheses → discriminating probe → best-supported diagnosis or remaining uncertainty → targeted intervention when teaching is requested or justified → independent delayed transfer check → corroborate, falsify, or revise the learner model ``` This extends the synthesis loop: ```text learner judgment and outcome → missing information, broken reasoning link, or execution failure → recognition cues and same-pattern links → reusable model, answer structure, or derived conclusion → fresh delayed transfer check → revise the diagnosis and model from the result ``` Keep more than one live hypothesis class until evidence splits them. Classes are layered (knowledge/skill, task/execution, history/generalization) and may co-occur; include concept-unestablished, prerequisite-missing, procedure-unavailable, calculation-error, language-misread, incidental, transfer-failure, and mastery-overestimated when they are plausible. Say *forgotten* only with prior mastery evidence. The form of a question does not matter; whether it reduces hypothesis uncertainty does. Generic metacognitive questions such as “where are you stuck?” count as diagnostic only when the answer actually splits live hypotheses. Prefer a smallest qualitative discriminator before computation when it splits the set. About 1–3 probes is the default strategy, not a hard invariant. Stop probing when remaining classes share the next intervention, the learner asks to be taught or to stop, or further probes will not pay. Stopping probes and writing a `supported` diagnosis are different gates. Shared intervention or an exhausted probe budget may stop asking and at most write `suspected`. Write `supported` only when a specific hypothesis has positive discriminating evidence *and* alternatives that would change the teaching action are ruled out or substantially weakened. Ruling out one weak class among many does not pass the supported-write gate. Otherwise keep a compact event with `diagnosis_status` `unknown` or `agent-hypothesis` and the competing list. The grain of a written gap is the best-supported blocker, not the learner's first complaint and not a metaphysical root cause. A diagnosis is an evidence-linked hypothesis, not a fact about the learner. Do not infer a hidden cause when the work is incomplete; ask one focused question or leave it `unknown`. Invite the learner to explain their original decision when that answer is necessary to distinguish missing knowledge from a broken reasoning chain. Do not replace this productive reflection with an AI-written explanation. If later evidence contradicts a hypothesis, mark it `falsified`, keep the history, and stop using that cause for question selection or mastery change. When new evidence conflicts with `demonstrated` or a previously strong belief, do not only lower mastery. Open competing explanations—forgetting, added complexity, failed transfer, overestimated prior mastery, or incidental state—then probe once. Keep a one-off exercise lightweight. Link repeated situations by subject, recognition cues, target concept, and error mechanism instead of copying whole questions. Promote a durable model only when at least two linked observations support the repeated structure, or when a learner, teacher, or authoritative source explicitly contributes a reusable method. A promoted model may include recognition cues, a shortest reliable answer structure, derived conclusions, limits, traps, and evidence links. Its creation does not change mastery. Close the loop with a sufficiently fresh question that changes values, representation, context, or the required decision. A summary is useful only when it changes a later action and remains open to correction. Delayed, independent transfer evidence—not model completeness, repetition count, or an AI's confidence—determines `demonstrated`. ### Reconcile external learning Teachers, class, tutoring, books, paper, platforms, peers, and other AI systems are first-class learning channels. An externally answered question may become resolved immediately. Resolution is not the same as demonstrated mastery. Record the feedback, stop redundant teaching, and create a later independent check only when the configuration permits. ## Truth and evidence Separate evidence from interpretation: | Record | Rule | |---|---| | learner answer, original note, teacher feedback | preserve; correct with a new linked record | | source locator and availability | preserve while relevant | | AI summary, model, gap, plan | may be revised from newer evidence | | dashboard | generated current view, never a second source of truth | Any conclusion that changes a goal, mastery state, or next plan must point to a traceable learner record or authorized source. If evidence is unavailable, write `unknown` or `needs verification`; never fill the gap by guessing. ## Write authority Default mode is `safe-auto`. Effective write authority comes from `gitlearnos.yml` only. A legacy `learning-policy.md` may be read once to propose migration, but it cannot expand or restrict the active configuration; after migration it should be archived or retained only as a clearly labelled non-effective notice. Natural-language instructions in the current interaction are one-event overrides of stable config (for example, “record only”, “preview first”, or “do not store this”). They expire at the end of that event and do not rewrite `gitlearnos.yml`. Explicit privacy, deletion, external-publication, secret, and broad-restructure boundaries still require confirmation even under `safe-auto`. The agent may automatically: - recognize clear learning events without an explicit GitLearnOS invocation; - save useful learner-provided evidence; - link, deduplicate, organize, and refresh current views; - record evidence-linked diagnostic hypotheses and synthesize repeated problem patterns into draft or durable models; - generate targeted questions; - suggest a useful next step from current evidence; - update short-term plans and due checks; - commit safe, low-risk, reversible changes. Ask first before: - deleting history or overwriting original notes; - changing a long-term goal or `gitlearnos.yml`; - publishing, changing visibility, or sending data to an external service; - broad restructuring that may break links; - storing sensitive identity, secrets, or unauthorized originals. Natural-language instructions such as “record only,” “do not store this,” “no review,” “preview first,” and “undo the last update” override one event. ## Git behavior Git is infrastructure, not a learner-facing task. Before writing, inspect the current repository version and preserve unrelated changes. Prefer one meaningful learning event per commit. Repeated input should update or link existing state rather than create a duplicate. Push only when a remote exists and the runtime is authorized. The learner should receive a concise receipt with changed paths and an undo boundary; they should not be asked to manage branches, filenames, or commits during ordinary learning. A remote is optional, but it may be valuable. GitHub or another Git host can provide off-device backup, cross-device continuity, shared learning materials, teacher or tutor review, group project coordination, and a visible feedback history. Keep a learner's private state separate from shared course materials, grant the minimum access needed, and ask before publishing, inviting others, or pushing sensitive material. See [Why Git, and when GitHub helps](docs/why-github.md). ## Automation GitLearnOS defines portable automation intent; an external runtime executes it. Every learner deployment must assign an explicit recurring local time and IANA time zone to both portable operations: 1. `due-review`: inspect due evidence and generate concrete questions that can be answered immediately; 2. `maintenance`: reconcile unprocessed input, waiting feedback, stale views, contradictory state, and repeated evidence waiting for synthesis. Unless the learner chooses different times, use these editable local defaults: ```text due-review: every day at 07:00 learner local time maintenance: every day at 21:30 learner local time ``` Also default to quiet hours 22:00–before 07:00, at most three questions per due run, and the current authorized learning channel. The learner may change them. Daily recurrence is a check cadence, not a requirement to produce work. With no due evidence or material state change, a run must finish as `skipped`: do not generate filler questions, send a notification, rewrite a last-run timestamp, or create an empty commit. After deployment verification, keep a no-work skip in provider run evidence; do not update `automation.md` until a material learning change already justifies a commit. Record the portable schedule and learner delivery preferences in `gitlearnos.yml`. Record actual scheduler state in `automation.md` using `requested`, `configured`, `verified`, `unavailable`, or `disabled`, together with the provider, opaque task identifier, time zone, recurrence, next run, and last verified run. Keep provider expressions and credentials outside learner state. A schedule is `verified` only after the recurring task is observed in the scheduler and one real test run proves that the scheduled invocation of the same main agent can read the intended repository and safely complete or skip the operation. A complete deployment requires both recurring operations to be `verified`. Use `requested` while an approved task is awaiting provisioning; use `unavailable` after capability inspection proves that no repository-capable scheduler exists. In either case preserve the exact requested schedules, continue immediate learning safely, and report deployment automation as `incomplete`; an on-handoff check or reminder does not satisfy this requirement. An explicitly learner-disabled required job also leaves deployment automation incomplete. Distinguish: - **immediate**: completed in the current interaction; - **on-handoff**: checked whenever a capable agent resumes; - **background**: created through a real scheduler with repository access. A scheduled run must use an idempotency key derived from job and scheduled occurrence, acquire one writer lock or lease, inspect the current Git revision, and create at most one commit only when learning state changes. If another writer changed the base revision, stop and report the conflict; never silently rebase, force-push, or overwrite learner work. A missed run may catch up once at the next capable execution and must not deliver the same due item twice. Question delivery excludes answer keys and respects quiet hours, maximum question count, privacy, and channel boundaries. Unattended push requires separate explicit authorization for the intended private remote. A date, prompt, scheduler entry, or reminder is not proof that repository work ran. Credentials and tokens stay outside Git and run logs. Without a real repository-capable scheduled invocation, record exact pending setup without claiming successful deployment or background execution. Scheduling does not create a second learning agent; it wakes the same main-agent behavior. ## Skills and adapters GitLearnOS distributes one self-contained Router Skill. Its `name` and `description` are the only GitLearnOS metadata that should enter the initial Skill list. After selection, the Router loads one operation reference for setup, organization, differential diagnosis, question generation, review, tutoring, source handling, model extraction, or maintenance, plus at most one subject reference when useful. A reference cannot weaken this evidence, ownership, or write-authority contract. The top-level `skills/gitlearnos/` directory is a source package, not proof of installation. Setup copies the complete folder to the main agent's documented native location and verifies that the runtime lists `gitlearnos` and can load its references. Use `.agents/skills/gitlearnos/` for Codex and OpenCode by default, and `.claude/skills/gitlearnos/` for Claude Code. Report installation as `installed`, `source-only`, `unavailable`, or `unknown`. Install one native copy for the chosen main agent. Do not create duplicate agent-specific copies merely for theoretical compatibility; project instructions preserve core behavior on secondary no-Skill surfaces. Explicit Skill invocation is optional. Automatically discovered `AGENTS.md`, Claude Code's thin `CLAUDE.md` adapter, project instructions, native memory, or the router may activate the same workflow when the input itself matches a learning goal. Adapters translate the same protocol to: - an AI agent environment; - local or hosted Git; - an automation runtime; - optional search, indexing, or skill-management systems. Adapters are replaceable and never become the source of learning truth. ## Required receipt After a write-capable operation, report: ```text Setup status: core-ready / knowledge-ready / automation-ready / full-ready / incomplete Mode: Subject: Organized: Questions: Changed files: Evidence: Git persistence: RAG synchronization: Mastery: Natural-language override: none / Automation actually completed: Skill installation: Next action: Undo: ``` ## Conformance An implementation conforms only when it can demonstrate the documented evaluation scenarios in `evals/` without fabricating access, evidence, scheduling, writeback, or mastery.