docs: describe halt->learn (teach) as shipped, not maturing - #13
Merged
Conversation
The self-serve halt->learn loop shipped as `openadapt flow teach` (openadapt-flow PR #101). Update the docs to describe it as a real, shipped capability rather than a maturing library-only feature. - index.md "The shape of it": keep the halt->learn Mermaid edge; rewrite the prose so a halt is resolved by demonstrating the fix once and `openadapt flow teach` compiling it back through the identity/effect/ policy gates. Drop the "a self-serve version is maturing" hedge. - concepts/halt-learn-loop.md: replace the stale "not a one-command flow" note with a documented `teach` verb (inputs: halted run dir + a fix recording or correction spec; governed induction + regression gate + held-out canary; refusal path exits nonzero with no bundle written; $0/model-free with the reference inducer). Flags verified against the real CLI. - reference/cli.md: add `teach` to the verbs-at-a-glance table and a full section with flags and exit codes (0 promoted / 1 refused / 2 bad input). - guides/run-reports.md: note a halt is not terminal and point to teach. mkdocs build --strict passes. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CKrVJJy5jWVCkXAqgUqtqZ
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
The self-serve halt->learn loop shipped as
openadapt flow teach(openadapt-flow PR #101,8e17641, onorigin/main). The docs still described it as a maturing, library-only capability, and https://docs.openadapt.ai/#the-shape-of-it undersold a halt as "cannot verify -> halt with a report" when the real purpose is to collect a new demonstration and compile the fix back in so it never halts there again.What changed
docs/index.md"The shape of it": kept the halt->learn Mermaid edge (Halt --demonstrate the fix--> learn --governed & gated--> bundle); rewrote the prose so a halt is resolved by demonstrating the fix once andopenadapt flow teachcompiling it back through the identity/effect/policy gates. Dropped the "a one-command, self-serve version is maturing" hedge.docs/concepts/halt-learn-loop.md: replaced the stale "a governed library capability, not a one-command flow" note with a documentedteachverb — inputs (halted run dir + a fix recording or.jsoncorrection spec), the governed induction + regression gate + held-out canary, the refusal path (underdetermined/unsafe fixes are refused, nonzero exit, no bundle written), and that it is$0/model-free with the reference inducer.docs/reference/cli.md: addedteachto the verbs-at-a-glance table and a full## teachsection with flags and exit codes.docs/guides/run-reports.md: reconciled "read the halt" so a halt reads as not terminal, pointing toteach.Accuracy
All flags/exit codes verified against the shipped CLI on
openadapt-floworigin/main(openadapt_flow/__main__.py_cmd_teach/teachadd_parser, andopenadapt_flow/learning/teach.py):openadapt flow teach <run_dir> --fix <recording|spec.json> --bundle <base> --out <updated> [--skill-id ID] [--library DIR]0promoted (updated bundle written),1governed refusal (nothing written),2unusable inputs (no halt / no bundle / malformed fix).No em-dashes (house style).
mkdocs build --strictpasses (exit 0).Supersedes the held branch
The prior held branch
docs/shape-halt-learnexisted only as uncommitted working-tree changes (never committed or pushed, no PR). Its useful parts (the Mermaid halt->learn edge) are incorporated here and its stale "maturing" hedge is removed, so it is fully superseded and its local branch can be deleted.🤖 Generated with Claude Code
https://claude.ai/code/session_01CKrVJJy5jWVCkXAqgUqtqZ