{"id":49539560,"url":"https://github.com/liuyingxuvka/flowguard","last_synced_at":"2026-06-07T02:01:32.625Z","repository":{"id":354438739,"uuid":"1223625440","full_name":"liuyingxuvka/FlowGuard","owner":"liuyingxuvka","description":"Executable finite-state models for designing and checking AI-agent workflows, UI flows, and development processes","archived":false,"fork":false,"pushed_at":"2026-05-27T07:46:47.000Z","size":7997,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-27T09:23:34.229Z","etag":null,"topics":["ai-agents","architecture-simulator","codex","deduplication","idempotency","model-checking","open-source","python","testing","workflow","workflow-simulation"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/liuyingxuvka.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-28T13:55:41.000Z","updated_at":"2026-05-27T07:46:53.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/liuyingxuvka/FlowGuard","commit_stats":null,"previous_names":["liuyingxuvka/flowguard","liuyingxuvka/flow-guard"],"tags_count":46,"template":false,"template_full_name":null,"purl":"pkg:github/liuyingxuvka/FlowGuard","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/liuyingxuvka%2FFlowGuard","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/liuyingxuvka%2FFlowGuard/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/liuyingxuvka%2FFlowGuard/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/liuyingxuvka%2FFlowGuard/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/liuyingxuvka","download_url":"https://codeload.github.com/liuyingxuvka/FlowGuard/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/liuyingxuvka%2FFlowGuard/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33834011,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-02T02:00:07.132Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","architecture-simulator","codex","deduplication","idempotency","model-checking","open-source","python","testing","workflow","workflow-simulation"],"created_at":"2026-05-02T14:02:07.246Z","updated_at":"2026-06-02T20:00:34.095Z","avatar_url":"https://github.com/liuyingxuvka.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# FlowGuard\n\n\u003c!-- README HERO START --\u003e\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./assets/readme-hero/hero.png\" alt=\"FlowGuard concept hero image\" width=\"100%\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./assets/readme-hero/flowguard-icon.png\" alt=\"FlowGuard icon\" width=\"120\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eA model-first guardrail for AI coding agents before small edits become large-project maintenance debt.\u003c/strong\u003e\n\u003c/p\u003e\n\u003c!-- README HERO END --\u003e\n\n| Public release | Schema | Runtime | License |\n| --- | --- | --- | --- |\n| `v0.40.7` | `1.0` | Python standard library only | MIT |\n\nEnglish lead content comes first; a Chinese mirror follows below.\n\n## Why FlowGuard Exists\n\nAI coding agents are useful because they can move quickly through small edits. The failure mode appears when the project stops being small: the agent can keep adding code while the real workflow state is already wrong.\n\nCommon symptoms look familiar:\n\n- a retry path runs twice and creates duplicate side effects;\n- branches multiply until nobody knows which path still owns the state;\n- tests pass, but they no longer prove the claim being made;\n- a child fix is fresh, while the parent plan still trusts stale evidence;\n- a UI has visible buttons, but the launch-to-terminal journey has no valid recovery path;\n- a release, README, or \"done\" claim survives after later code, docs, tests, or peer writes invalidated it.\n\nFlowGuard is built for that problem. It makes the risky transition explicit before the agent acts, runs a small executable state model, and turns hidden failure paths into counterexamples that can change the next engineering step.\n\nIt does not promise that software has no bugs. It helps prevent a specific maintenance disaster: AI agents continuing from an invalid state and piling more code, tests, or public claims on top of it.\n\n## What FlowGuard Does\n\nFlowGuard is a lightweight Python toolkit and AI-agent skill layer for model-first workflow checks. Any agent can use the method; Codex-compatible skills are provided as ready-to-install guidance, not as the boundary of the project.\n\nThe practical loop is:\n\n```text\nrisky AI action -\u003e explicit state model -\u003e executable checks\n-\u003e counterexample trace -\u003e revise plan, code, tests, UI, or claim\n```\n\nInstead of asking an agent to \"be careful\", FlowGuard asks the agent to name the state, inputs, outputs, side effects, ownership boundaries, and evidence gates that decide whether the next action is safe.\n\n## The Core Model\n\nEach function block is represented as:\n\n```text\nInput x State -\u003e Set(Output x State)\n```\n\nThat small shape is enough to expose many large-project problems:\n\n- repeated inputs that should be idempotent;\n- dead branches that return no legal output;\n- multiple possible outputs that need explicit ownership;\n- stale evidence after later artifact changes;\n- remembered maintenance obligations that reopen when the same surface changes;\n- parent/child model drift;\n- invalid final claims after skipped or scoped validation.\n\nFlowGuard explores finite traces inside the declared model and checks invariants, scenarios, progress properties, conformance expectations, evidence freshness, and closure boundaries. When a check fails, the important output is the counterexample path: the concrete state sequence that shows why the current plan should not continue unchanged.\n\n## Start Small\n\nMost useful FlowGuard work can start thin:\n\n```text\nchoose one risky boundary\n-\u003e name Input, State, Output, side effects, and owners\n-\u003e write one invariant or scenario\n-\u003e run the check\n-\u003e inspect the counterexample\n-\u003e fix the model, plan, code, tests, UI, or claim\n```\n\nOnly escalate when the risk boundary demands it: UI topology, code structure, test hierarchy, model/test alignment, parent/child model mesh, staged release evidence, architecture reduction, existing-model ownership, or model-miss repair.\n\n## What You Can Design And Verify\n\n| Work type | What FlowGuard helps design | What it checks |\n| --- | --- | --- |\n| Development process | staged route, legal next actions, validation gates, stale-evidence reset, peer-write invalidation, done and release readiness | skipped gates, stale validation, progress-only evidence, invalid completion claims |\n| UI flow | persistent regions, contextual panels, visible controls, overlays, recovery paths, display ownership, duplicate-control rules | launch-to-terminal journeys, unavailable controls, missing recovery, duplicate actions, warning/error escalation |\n| Code structure | module split, facade boundary, state owner, side-effect owner, config owner, validation owner | ownership leaks, dependency cycles, facade drift, config drift, missing parity evidence |\n| Architecture reduction | observable contract, duplicate implementation candidates, safe target action | whether handlers, adapters, branches, modules, or validation layers can shrink without changing observable behavior |\n| Test strategy | routine and release test layers, parent/child suites, timeout boundaries, stale and hidden evidence rules | skipped tests, release-only evidence, broad/slow direct checks, stale passes, wrong-provenance evidence |\n| Model mesh and bug repair | parent/child boundaries, reattachment gates, sibling-impact review, same-class bad cases | child evidence freshness, parent consumption, analogous defect risks, same-class test evidence |\n| Release and public claims | evidence ledger, claim-chain boundary, publish readiness | whether the public claim is supported by current model, code, test, mesh, freshness, and risk evidence |\n\nThis is the core product: FlowGuard turns a vague workflow, UI journey, refactor, test strategy, or release process into a small state machine with explicit failure traces. The counterexample is not just a bug report; it is design feedback that says which state, gate, owner, or evidence rule must change before work continues.\n\n## What FlowGuard Is Not\n\nFlowGuard is not an LLM wrapper, a prompt trick, a probability engine, a Monte Carlo simulator, or a replacement for ordinary tests.\n\nIt is a structural preflight layer. Tests still verify production code. Code review still matters. UI polish and browser/device behavior still need real UI review. FlowGuard sits earlier: it asks whether the agent's intended transition is coherent before the transition becomes code, tests, UI, or a public confidence claim.\n\n## When To Use It\n\nUse FlowGuard when order, state, ownership, side effects, UI availability, role handoff, or evidence freshness can change whether the plan is actually safe.\n\nGood fits:\n\n- AI-agent coding work with multiple stages or handoffs;\n- retries, deduplication, cache refresh, ingestion, or repeated job processing;\n- refactors where public entrypoints must remain compatible;\n- UI flows where visible controls do not guarantee legal recovery paths;\n- tests or release checks where old evidence can be mistaken for current proof;\n- parent/child models where one green result should not automatically make the parent green.\n\nBad fits:\n\n- one-line typo fixes;\n- formatting-only edits;\n- tasks where no state, side effect, ordering, or evidence boundary matters;\n- claims that need statistical truth rather than structural workflow checks.\n\n## Quick Start\n\n```powershell\ngit clone https://github.com/liuyingxuvka/FlowGuard.git\ncd FlowGuard\npython -m pip install -e .\npython -m flowguard schema-version\npython -m flowguard self-review\n```\n\nAdopt FlowGuard into another project so future agents can find the repository, version record, and project rules:\n\n```powershell\npython -m flowguard project-adopt --root \u003ctarget-project\u003e\npython -m flowguard project-audit --root \u003ctarget-project\u003e\npython -m flowguard project-upgrade --root \u003ctarget-project\u003e\n```\n\nUseful template entry points:\n\n```powershell\npython -m flowguard project-template\npython -m flowguard project-adoption-template\npython -m flowguard plan-detailing-template\npython -m flowguard model-test-alignment-template\npython -m flowguard existing-model-preflight-template\npython -m flowguard model-similarity-template\npython -m flowguard risk-evidence-ledger-template\npython -m flowguard maintenance-scan-template\npython -m flowguard closure-contract-template\npython -m flowguard code-structure-recommendation-template\npython -m flowguard ui-flow-structure-template\npython -m flowguard development-process-flow-template\npython -m flowguard workflow-step-contracts-template\npython -m flowguard test-mesh-template\npython -m flowguard structure-mesh-template\npython -m flowguard topology-hazard-template\n```\n\nRun focused examples:\n\n```powershell\npython examples/flowguard_product_boundary/run_review.py\npython examples/hierarchical_model_mesh/run_review.py\npython examples/risk_evidence_ledger/run_checks.py\npython examples/job_matching/run_checks.py\n```\n\n## Minimal Python Sketch\n\n```python\nfrom dataclasses import dataclass, replace\n\nfrom flowguard import Explorer, FunctionResult, Invariant, Workflow\n\n\n@dataclass(frozen=True)\nclass State:\n    processed: tuple[str, ...] = ()\n    side_effects: int = 0\n\n\n@dataclass(frozen=True)\nclass Input:\n    job_id: str\n    retry: bool = False\n\n\nclass ProcessJob:\n    name = \"process_job\"\n    accepted_input_type = Input\n    reads = (\"processed\", \"side_effects\")\n    writes = (\"processed\", \"side_effects\")\n    input_description = \"job request\"\n    output_description = \"job status\"\n    idempotency = \"same job id creates at most one side effect\"\n\n    def apply(self, input_obj: Input, state: State):\n        if input_obj.job_id in state.processed:\n            return [\n                FunctionResult(\n                    output=\"already_processed\",\n                    new_state=state,\n                    label=\"deduplicated_retry\",\n                )\n            ]\n        return [\n            FunctionResult(\n                output=\"processed\",\n                new_state=replace(\n                    state,\n                    processed=state.processed + (input_obj.job_id,),\n                    side_effects=state.side_effects + 1,\n                ),\n                label=\"first_processing\",\n            )\n        ]\n\n\nworkflow = Workflow((ProcessJob(),), name=\"retry_deduplication\")\n\nreport = Explorer(\n    workflow=workflow,\n    initial_states=(State(),),\n    external_inputs=(Input(\"A\"),),\n    invariants=(\n        Invariant(\n            name=\"side_effect_once\",\n            description=\"The same job may not create duplicate side effects.\",\n            predicate=lambda state, trace: state.side_effects \u003c= len(set(state.processed)),\n        ),\n    ),\n    max_sequence_length=2,\n    progress_steps=0,\n).explore()\nprint(report.format_text())\n```\n\n## Skill Routes\n\nFlowGuard has one kernel and several peer satellite skills. Use the smallest route that owns the actual risk:\n\n| Skill route | Use it when |\n| --- | --- |\n| `model-first-function-flow` | ordinary behavior/state modeling, unclear route selection, or cross-route coordination |\n| `flowguard-plan-detailing-compiler` | a rough idea or short plan needs explicit scope, state, side effects, evidence, receipts, rework, and claim boundaries |\n| `flowguard-existing-model-preflight` | existing modeled-system work should first identify model ownership, reuse/extend decisions, and duplicate-boundary risk |\n| `flowguard-development-process-flow` | staged development, archive, publish, release, or done confidence depends on current validation evidence |\n| `flowguard-ui-flow-structure` | UI controls, visible buttons, launch-to-terminal journeys, overlays, recovery paths, and information ownership need modeling |\n| `flowguard-code-structure-recommendation` | a function-flow model should derive module, facade, state-owner, side-effect, config, and validation boundaries |\n| `flowguard-structure-mesh` | a script, package, command, public API, or refactor split needs facade compatibility and parity evidence |\n| `flowguard-test-mesh` | validation is layered, slow, stale, skipped, release-only, or split across child suites |\n| `flowguard-model-test-alignment` | model obligations, code contracts, code-boundary observations, and test evidence need direct comparison |\n| `flowguard-model-mesh` | parent/child model evidence, sibling impact, or oversized model surfaces need mesh governance |\n| `flowguard-model-topology-hazard-review` | a locally green model may still imply repeatable future-use hazards before broad confidence |\n| `flowguard-architecture-reduction` | model-equivalent handlers, adapters, modules, branches, or validation layers may be safely contracted |\n| `flowguard-model-miss-review` | runtime, tests, replay, logs, or manual validation failed after a FlowGuard model passed |\n\n## Relationship To The Guard Family\n\n| Project | Focus |\n| --- | --- |\n| FlowGuard | stateful behavior, process flow, evidence freshness, parent/child model confidence |\n| LogicGuard | claims, evidence, warrants, assumptions, rebuttals, scope, and overclaiming in written reasoning |\n| PhysicsGuard | low-fidelity residual checks and model-building blueprints for physical simulation debugging |\n| FlowPilot | long-running project orchestration and route control for AI-agent software work |\n\n## Documentation Map\n\n| File | Purpose |\n| --- | --- |\n| `docs/concept.md` | short conceptual introduction |\n| `docs/modeling_protocol.md` | core model-first protocol |\n| `docs/api_surface.md` | public Python API overview |\n| `docs/invariant_examples.md` | examples of useful invariants |\n| `docs/development_process_flow.md` | staged development, validation freshness, archive, publish, and release gates |\n| `docs/ui_flow_structure.md` | UI interaction and structure modeling |\n| `docs/code_structure_recommendation.md` | model-derived code structure recommendations |\n| `docs/structure_mesh.md` | refactor and module split governance |\n| `docs/test_evidence_mesh.md` | layered validation and evidence freshness |\n| `docs/model_test_alignment.md` | model obligation and test evidence alignment |\n| `docs/model_mesh_protocol.md` | parent/child model mesh governance |\n| `docs/model_topology_hazard_review.md` | topology-grounded future-use hazard review |\n| `docs/model_similarity_consolidation.md` | model-to-model relation review and consolidation handoffs |\n| `docs/flowguard_closure_contract.md` | closure contract for complete FlowGuard use |\n| `docs/risk_evidence_ledger.md` | risk-to-model-to-code-to-evidence confidence boundary |\n| `docs/runtime_gateway_adoption.md` | runtime gateway adoption levels and critical-state writer inventory |\n\n## Repository Layout\n\n```text\nflowguard/     Core library, review helpers, templates, mesh routes, CLI\nexamples/      Small executable models and public self-reviews\ndocs/          Protocols, API notes, examples, and adoption guidance\ntests/         Focused regression tests for the public helpers\nassets/        README hero image and generation notes\n```\n\n## Public Boundary\n\nThis repository is designed to be useful as a public starter and reference implementation. It includes the library, examples, protocol docs, public templates, and AI-agent skill material, including Codex-compatible skills.\n\nIt does not include private project logs, personal predictive knowledge, credentials, customer data, or claims that every real system is covered by the model. A FlowGuard pass means the declared model obligations passed. It does not mean the whole project is correct.\n\n## License\n\nMIT. See `LICENSE`.\n\n---\n\n## 中文说明\n\nFlowGuard 是给 AI 编程 agent 用的 model-first guardrail：在小改动逐渐变成大项目维护债之前，先把危险的状态转移建模并检查。\n\n## 为什么需要 FlowGuard\n\nAI 编程 agent 在小代码、小软件、小改动里很好用。真正危险的地方通常出现在项目变大以后：agent 还能继续写代码，但实际 workflow 的状态、证据、ownership 或发布结论已经错了。\n\n常见症状包括：\n\n- retry 路径跑了两次，产生重复 side effect；\n- 分支越来越多，没人知道哪条路径还拥有真实 state；\n- 测试通过了，但已经不再证明当前声明；\n- 子模型刚修好，父级计划却还在信任旧证据；\n- UI 有可见按钮，但从启动到终态的 journey 没有合法恢复路径；\n- release、README 或 done 声明在后续代码、文档、测试或 peer 写入后仍然留着。\n\nFlowGuard 就是为这个问题设计的。它在 agent 动手之前，把危险转移写成明确的小型状态模型，运行可执行检查，并把隐藏失败路径变成能改变下一步工程动作的 counterexample。\n\n它不承诺软件没有 bug。它防的是一种更具体的维护灾难：AI agent 带着无效状态继续推进，把更多代码、测试或公开声明堆在错误计划上。\n\n## FlowGuard 做什么\n\nFlowGuard 是轻量 Python 工具包，也是通用 AI-agent skill layer。任何 agent 都可以用这套方法；Codex-compatible skills 只是现成接入方式，不是项目边界。\n\n实际循环是：\n\n```text\n危险 AI 行动 -\u003e 显式状态模型 -\u003e 可执行检查\n-\u003e counterexample trace -\u003e 修改计划、代码、测试、UI 或声明\n```\n\n它不是让 agent “小心一点”，而是要求 agent 说清楚 state、input、output、side effect、ownership boundary 和 evidence gate，因为这些才决定下一步是否安全。\n\n## 核心模型\n\n每个 function block 表示为：\n\n```text\nInput x State -\u003e Set(Output x State)\n```\n\n这个小结构足以暴露很多大项目问题：\n\n- 重复 input 是否应该幂等；\n- 死分支是否没有合法 output；\n- 多个可能 output 是否有明确 ownership；\n- 后续 artifact 变化后证据是否过期；\n- 记住的维护义务是否会在同一风险面被再次改动时自动重开；\n- 父子模型证据是否漂移；\n- final claim 是否在跳过验证或 scoped 验证后仍被接受。\n\nFlowGuard 在声明的有限模型里探索 trace，并检查 invariant、scenario、progress、conformance、evidence freshness 和 closure boundary。失败时，最重要的输出是 counterexample path：一条具体状态序列，说明当前计划为什么不能原样继续。\n\n## 从小开始\n\n大多数 FlowGuard 使用可以很薄：\n\n```text\n选择一个风险边界\n-\u003e 命名 Input、State、Output、side effect 和 owner\n-\u003e 写一个 invariant 或 scenario\n-\u003e 运行检查\n-\u003e 看 counterexample\n-\u003e 修模型、计划、代码、测试、UI 或声明\n```\n\n只有风险边界真的需要时，才升级到高级路线：UI 拓扑、代码结构、测试层级、model/test alignment、parent/child model mesh、分阶段发布证据、architecture reduction、existing-model ownership 或 model-miss repair。\n\n## 它能设计并验证什么\n\n| 工作类型 | FlowGuard 帮你设计什么 | 它检查什么 |\n| --- | --- | --- |\n| 开发流程 | staged route、合法 next action、validation gate、stale-evidence reset、peer-write invalidation、done/release readiness | skipped gate、旧验证、progress-only evidence、无效完成声明 |\n| UI flow | 持久区域、上下文 panel、可见控件、overlay、恢复路径、display ownership、重复控件规则 | launch-to-terminal journey、不可用控件、缺失恢复、重复动作、warning/error escalation |\n| 代码结构 | module split、facade boundary、state owner、side-effect owner、config owner、validation owner | ownership leak、dependency cycle、facade drift、config drift、缺失 parity evidence |\n| 架构缩减 | observable contract、重复实现 candidate、安全 target action | handler、adapter、branch、module 或 validation layer 能否在不改变可观察行为的前提下收缩 |\n| 测试策略 | routine/release test layer、父子 suite、timeout 边界、旧证据和隐藏证据规则 | skipped test、release-only evidence、过宽/过慢直接检查、旧 pass、来源不对的 evidence |\n| Model mesh 和 bug 修复 | 父子边界、reattachment gate、sibling-impact review、same-class bad case | child evidence freshness、parent consumption、analogous defect risk、same-class test evidence |\n| 发布和公开声明 | evidence ledger、claim-chain boundary、publish readiness | 公开声明是否被当前 model、code、test、mesh、freshness 和 risk evidence 支撑 |\n\n这才是 FlowGuard 的核心产品：把模糊的 workflow、UI journey、refactor、test strategy 或 release process 变成小型状态机，并给出明确失败路径。counterexample 不是单纯 bug report，而是设计反馈：它告诉你哪个 state、gate、owner 或 evidence rule 必须先改，工作才能继续。\n\n## FlowGuard 不是什么\n\nFlowGuard 不是 LLM wrapper，不是 prompt trick，不是概率引擎，不是 Monte Carlo simulator，也不是普通测试的替代品。\n\n它是结构化预检层。测试仍然要验证真实代码，code review 仍然重要，UI polish 和浏览器/设备行为仍然需要真实 UI review。FlowGuard 更早一步：在转移变成代码、测试、UI 或公开信心声明之前，先检查这个转移是否自洽。\n\n## 什么时候用\n\n当顺序、状态、ownership、side effect、UI availability、role handoff 或 evidence freshness 会改变计划是否安全时，用 FlowGuard。\n\n适合：\n\n- 有多个阶段或 handoff 的 AI-agent coding work；\n- retry、deduplication、cache refresh、ingestion 或重复 job processing；\n- 公开入口必须兼容的 refactor；\n- 可见控件不等于合法恢复路径的 UI flow；\n- 旧 evidence 可能被误当作当前 proof 的测试或发布检查；\n- 一个 child green 不应该自动让 parent green 的父子模型。\n\n不适合：\n\n- 一行 typo；\n- 纯格式修改；\n- 没有 state、side effect、顺序或 evidence boundary 的任务；\n- 需要统计事实而不是结构化 workflow 检查的声明。\n\n## 快速开始\n\n```powershell\ngit clone https://github.com/liuyingxuvka/FlowGuard.git\ncd FlowGuard\npython -m pip install -e .\npython -m flowguard schema-version\npython -m flowguard self-review\n```\n\n把 FlowGuard 接入另一个项目，让后续 agent 能看到仓库地址、版本记录和项目规则：\n\n```powershell\npython -m flowguard project-adopt --root \u003ctarget-project\u003e\npython -m flowguard project-audit --root \u003ctarget-project\u003e\npython -m flowguard project-upgrade --root \u003ctarget-project\u003e\n```\n\n常用模板入口：\n\n```powershell\npython -m flowguard project-template\npython -m flowguard project-adoption-template\npython -m flowguard plan-detailing-template\npython -m flowguard model-test-alignment-template\npython -m flowguard existing-model-preflight-template\npython -m flowguard model-similarity-template\npython -m flowguard risk-evidence-ledger-template\npython -m flowguard maintenance-scan-template\npython -m flowguard closure-contract-template\npython -m flowguard code-structure-recommendation-template\npython -m flowguard ui-flow-structure-template\npython -m flowguard development-process-flow-template\npython -m flowguard workflow-step-contracts-template\npython -m flowguard test-mesh-template\npython -m flowguard structure-mesh-template\npython -m flowguard topology-hazard-template\n```\n\n运行示例：\n\n```powershell\npython examples/flowguard_product_boundary/run_review.py\npython examples/hierarchical_model_mesh/run_review.py\npython examples/risk_evidence_ledger/run_checks.py\npython examples/job_matching/run_checks.py\n```\n\n## Skill 架构\n\nFlowGuard 有一个 kernel 和多个同级 satellite skill。选择真正拥有当前风险的最小路线：\n\n| Skill route | 适用场景 |\n| --- | --- |\n| `model-first-function-flow` | 普通行为/状态建模、路线不清楚或跨路线协调 |\n| `flowguard-plan-detailing-compiler` | 粗想法或短计划需要明确 scope、state、side effect、evidence、receipt、rework 和 claim boundary |\n| `flowguard-existing-model-preflight` | 已有模型系统里的工作要先找到 model owner、复用/扩展判断和重复 boundary 风险 |\n| `flowguard-development-process-flow` | staged development、archive、publish、release 或 done confidence 取决于当前验证证据 |\n| `flowguard-ui-flow-structure` | UI control、可见按钮、launch-to-terminal journey、overlay、恢复路径和信息 ownership 需要建模 |\n| `flowguard-code-structure-recommendation` | function-flow 模型要推导 module、facade、state-owner、side-effect、config 和 validation boundary |\n| `flowguard-structure-mesh` | 脚本、包、命令、公开 API 或 refactor 拆分需要 facade compatibility 和 parity evidence |\n| `flowguard-test-mesh` | 验证分层、很慢、过期、被 skip、只在 release 跑，或分布在 child suite |\n| `flowguard-model-test-alignment` | 需要直接对照 model obligation、code contract、code-boundary observation 和 test evidence |\n| `flowguard-model-mesh` | parent/child model evidence、sibling impact 或过大 model surface 需要 mesh governance |\n| `flowguard-model-topology-hazard-review` | 本地 green 模型在广泛信心前仍可能暗示可复发的未来使用风险 |\n| `flowguard-architecture-reduction` | 模型等价的 handler、adapter、module、branch 或 validation layer 可能可以安全收缩 |\n| `flowguard-model-miss-review` | runtime、test、replay、log 或人工验证在 FlowGuard 模型通过后仍然失败 |\n\n## Guard Family 关系\n\n| 项目 | 关注点 |\n| --- | --- |\n| FlowGuard | stateful behavior、process flow、evidence freshness、parent/child model confidence |\n| LogicGuard | 写作推理里的 claim、evidence、warrant、assumption、rebuttal、scope 和 overclaiming |\n| PhysicsGuard | 物理仿真调试中的低保真 residual check 和模型构建蓝图 |\n| FlowPilot | 长周期 AI-agent 软件工作的项目编排和路线控制 |\n\n## 文档入口\n\n| 文件 | 作用 |\n| --- | --- |\n| `docs/concept.md` | 简短概念介绍 |\n| `docs/modeling_protocol.md` | 核心 model-first 协议 |\n| `docs/api_surface.md` | 公开 Python API 概览 |\n| `docs/invariant_examples.md` | 常用 invariant 示例 |\n| `docs/development_process_flow.md` | staged development、validation freshness、archive、publish 和 release gate |\n| `docs/ui_flow_structure.md` | UI interaction 和结构建模 |\n| `docs/code_structure_recommendation.md` | 模型推导代码结构建议 |\n| `docs/structure_mesh.md` | refactor 和 module split 治理 |\n| `docs/test_evidence_mesh.md` | 分层验证和证据新鲜度 |\n| `docs/model_test_alignment.md` | 模型义务和测试证据对齐 |\n| `docs/model_mesh_protocol.md` | parent/child model mesh 治理 |\n| `docs/model_topology_hazard_review.md` | 从模型拓扑推断未来使用风险的审查 |\n| `docs/model_similarity_consolidation.md` | model-to-model 关系审查和 consolidation handoff |\n| `docs/flowguard_closure_contract.md` | 完整 FlowGuard 使用的 closure contract |\n| `docs/risk_evidence_ledger.md` | risk-to-model-to-code-to-evidence 信心边界 |\n| `docs/runtime_gateway_adoption.md` | runtime gateway adoption level 和 critical-state writer inventory |\n\n## 仓库结构\n\n```text\nflowguard/     核心库、review helpers、templates、mesh routes、CLI\nexamples/      小型可执行模型和公开 self-review\ndocs/          协议、API 说明、示例和 adoption guidance\ntests/         针对公开 helper 的回归测试\nassets/        README hero image 和生成说明\n```\n\n## 公开边界\n\n这个仓库适合作为公开 starter 和 reference implementation。它包含库代码、示例、协议文档、公开模板和通用 AI-agent skill material，其中也包括 Codex-compatible skills。\n\n它不包含私有项目日志、个人 predictive knowledge、credential、客户数据，也不声称模型覆盖了所有真实系统。FlowGuard 通过只表示声明的模型义务通过，不表示整个项目已经正确。\n\n## 许可证\n\nMIT. See `LICENSE`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fliuyingxuvka%2Fflowguard","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fliuyingxuvka%2Fflowguard","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fliuyingxuvka%2Fflowguard/lists"}