gardenia 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (42) hide show
  1. gardenia-0.1.0/.readthedocs.yaml +13 -0
  2. gardenia-0.1.0/AGENTS.md +63 -0
  3. gardenia-0.1.0/CHANGELOG.md +33 -0
  4. gardenia-0.1.0/LICENSE +21 -0
  5. gardenia-0.1.0/MANIFEST.in +6 -0
  6. gardenia-0.1.0/PKG-INFO +111 -0
  7. gardenia-0.1.0/README.md +82 -0
  8. gardenia-0.1.0/docs/architecture.md +85 -0
  9. gardenia-0.1.0/docs/assets/README.md +48 -0
  10. gardenia-0.1.0/docs/assets/gardenia.svg +23 -0
  11. gardenia-0.1.0/docs/changelog.md +2 -0
  12. gardenia-0.1.0/docs/conf.py +10 -0
  13. gardenia-0.1.0/docs/contributing.md +46 -0
  14. gardenia-0.1.0/docs/host-vs-repo.md +80 -0
  15. gardenia-0.1.0/docs/index.md +70 -0
  16. gardenia-0.1.0/docs/quickstart.md +118 -0
  17. gardenia-0.1.0/docs/reference.md +223 -0
  18. gardenia-0.1.0/docs/releasing.md +26 -0
  19. gardenia-0.1.0/docs/requirements.txt +3 -0
  20. gardenia-0.1.0/docs/session_handoff_format.md +16 -0
  21. gardenia-0.1.0/gardenia.toml +9 -0
  22. gardenia-0.1.0/pyproject.toml +46 -0
  23. gardenia-0.1.0/scripts/check +7 -0
  24. gardenia-0.1.0/scripts/verify-wheel.py +99 -0
  25. gardenia-0.1.0/setup.cfg +4 -0
  26. gardenia-0.1.0/src/gardenia/__init__.py +7 -0
  27. gardenia-0.1.0/src/gardenia/__main__.py +10 -0
  28. gardenia-0.1.0/src/gardenia/cli.py +482 -0
  29. gardenia-0.1.0/src/gardenia/host.py +1324 -0
  30. gardenia-0.1.0/src/gardenia/models.py +211 -0
  31. gardenia-0.1.0/src/gardenia/repo.py +1113 -0
  32. gardenia-0.1.0/src/gardenia.egg-info/PKG-INFO +111 -0
  33. gardenia-0.1.0/src/gardenia.egg-info/SOURCES.txt +40 -0
  34. gardenia-0.1.0/src/gardenia.egg-info/dependency_links.txt +1 -0
  35. gardenia-0.1.0/src/gardenia.egg-info/entry_points.txt +2 -0
  36. gardenia-0.1.0/src/gardenia.egg-info/requires.txt +9 -0
  37. gardenia-0.1.0/src/gardenia.egg-info/top_level.txt +1 -0
  38. gardenia-0.1.0/tests/conftest.py +273 -0
  39. gardenia-0.1.0/tests/test_host_check.py +166 -0
  40. gardenia-0.1.0/tests/test_host_setup.py +181 -0
  41. gardenia-0.1.0/tests/test_repo.py +230 -0
  42. gardenia-0.1.0/tests/test_unified_check.py +100 -0
@@ -0,0 +1,13 @@
1
+ version: 2
2
+ build:
3
+ os: ubuntu-24.04
4
+ tools:
5
+ python: "3.12"
6
+ sphinx:
7
+ configuration: docs/conf.py
8
+ fail_on_warning: true
9
+ python:
10
+ install:
11
+ - requirements: docs/requirements.txt
12
+ - method: pip
13
+ path: .
@@ -0,0 +1,63 @@
1
+ # gardenia contributor instructions
2
+
3
+ Keep this file limited to repository-wide guardrails. Follow the canonical contracts and
4
+ procedures listed in [docs/index.md](docs/index.md), the
5
+ [contributor workflow](docs/contributing.md), the
6
+ [CLI and schema reference](docs/reference.md), and the
7
+ [release guide](docs/releasing.md). End changed work with the four-part
8
+ [session handoff](docs/session_handoff_format.md).
9
+
10
+ <!-- gardenia:begin -->
11
+ - Use the installed `agrein` skills: `ticket-delivery` before changing code, docs,
12
+ config, infrastructure, or live state; `epic-queue` when decomposing multi-ticket
13
+ work or coordinating subagent workers; `bug-investigation` before fixing defects or
14
+ failing checks; and `owner-escalation` for unsettled product/policy rulings, live
15
+ operation approvals, and decision handoffs.
16
+ - Coordinate ticket work by delegating each authorized ticket to a worker selected with
17
+ the installed `agroute` and `howhard` skills; an assigned leaf worker implements its
18
+ ticket directly without recursively delegating it (report a capability gap first if
19
+ `agroute` or worker delegation is unavailable on the host):
20
+ 1. Inspect or refresh live agent quota state with `agr usage`.
21
+ 2. Emit eligible provider-qualified candidates for this host with
22
+ `agr candidates --host <codex|claude|agy> --output /tmp/TASK-candidates.json --json`.
23
+ If `price_request` is non-null, look up official first-party provider pricing (or
24
+ classify internal harness models as `"alias"` or `"unlisted"`), run
25
+ `agr prices resolve --file /tmp/TASK-prices.json --json`, and re-emit candidates once.
26
+ 3. Select a route with `howhard` (`context`/`retrieve`/`decide` with an independent
27
+ stateless baseline forecast, or `pick`), then resolve the execution plan with
28
+ `agr plan --host <codex|claude|agy> --decision /tmp/TASK-decision.json --json`.
29
+ 4. Honor `needs_review`. Execute native plans (`target_agent == host_agent`) with the
30
+ host's native subagent tool and cross-agent plans (`target_agent != host_agent`) with
31
+ the returned non-interactive CLI command.
32
+ 5. Record the actual outcome and measured usage in `howhard` following the plan's
33
+ `feedback` block (`matched_receipt` or `raw_native`), then update `howhard` memory.
34
+ - Track every code, test, documentation, or packaging change with a descriptive issue
35
+ (`#N — one sentence describing the work`). Do not file an issue solely for
36
+ machine-local installation, deployment, configuration, service lifecycle, or other
37
+ operator state unless it also requires a repository change or the user requests one.
38
+ - Develop and validate only in an issue-specific Git worktree branched from
39
+ `origin/main`. Preserve unrelated work and keep the primary checkout read-only during
40
+ development.
41
+ - Verify behavior at public boundaries. Start bug fixes with a failing behavioral test;
42
+ accompany runtime changes with focused tests, affected canonical documentation, and a
43
+ `CHANGELOG.md` entry when the change is user-facing.
44
+ - A documentation-only change needs no tests or AGCoord gate. It qualifies only when
45
+ every changed path is `README.md`, `CHANGELOG.md`, `AGENTS.md`, Markdown below
46
+ `docs/`, or a `.png` or `.svg` image below `docs/assets/` whose provenance is
47
+ recorded in `docs/assets/README.md`. Verify the exact pull-request file list and
48
+ diff, then merge it through the forge; the issue, worktree, branch, pull-request,
49
+ and no-direct-target-push rules still apply.
50
+ - On Linux hosts with `agcoord` (`agc`), route checks and pull-request landing through
51
+ the local coordinator with integer byte memory claims:
52
+ - Check: `agc run --no-overflow --resource cpu=4 --resource memory=4294967296 -- bash scripts/check`
53
+ - Land: `agc land <pr> --no-overflow --resource cpu=4 --resource memory=4294967296 -- bash scripts/check`
54
+ Never submit coordinated work recursively inside an admitted job, and never bypass or
55
+ separate the gate verdict from publication. On hosts without `agc`, run
56
+ `bash scripts/check` directly and merge through the forge after checks pass.
57
+ - Tests must own and stop every process, repository, and temporary directory they
58
+ create, and must never inspect or mutate real host state (`~/.codex`, `~/.claude`,
59
+ `~/.gemini`, `~/.config`, or `~/.local`).
60
+ - Never upload a distribution to PyPI or modify live host/production state unless the
61
+ owner explicitly authorizes that exact operation. Permission to implement, test,
62
+ commit, push, merge, tag, or create a GitHub release does not authorize a PyPI upload.
63
+ <!-- gardenia:end -->
@@ -0,0 +1,33 @@
1
+ # Changelog
2
+
3
+ All notable changes to `gardenia` are documented in this file.
4
+
5
+ ## 0.1.0 — 2026-11-22
6
+
7
+ - Initial `gardenia` `0.1.0` zero-dependency CLI (`Python 3.11+`, console script `gardenia`)
8
+ implementing strict **per-host** vs. **per-repository** separation:
9
+ - `gardenia host check` — read-only inspection of `howhard`, `agr`, Linux `agc` CLI
10
+ versions and broker enforcement mode (`cgroup-v2` vs. `admission-only`), detected
11
+ coding-agent clients (`codex`, `claude`, `agy`), user-scoped plugin versions and
12
+ CLI-vs-plugin drift (inspecting Codex via `~/.codex/config.toml` and cached
13
+ `plugin.json` without invoking interactive `codex plugin list`), and
14
+ `~/.config/agroute/config.toml` reserve settings.
15
+ - `gardenia host setup` — idempotent installation/upgrade of host CLIs (`uv tool` /
16
+ `pipx`), enforced-broker-safe `agc host` setup (`--broker auto|user|enforced|skip`),
17
+ native plugin installation/refresh across Codex, Claude Code, and Antigravity,
18
+ optional non-destructive `~/.config/agroute/config.toml` reserve defaults, and
19
+ `--dry-run` planning.
20
+ - `gardenia repo check`, `gardenia repo init`, and `gardenia repo render` — explicit
21
+ separation of tracked repository settings (`AGENTS.md` managed block,
22
+ `CLAUDE.md -> AGENTS.md` symlink, `gardenia.toml` / `[tool.gardenia]`, optional
23
+ `howhard.toml` and `agroute.toml`) from local per-clone `.git/` state
24
+ (`.git/howhard` non-destructive pre-4.0 loose JSON warning and `.git/agroute`
25
+ pending price inspection via `agr prices pending --json`), with linked-worktree
26
+ protection and surrounding-prose preservation.
27
+ - `gardenia check` — unified host + repository diagnostic returning the
28
+ `gardenia-check-v1` JSON schema with explicit `scope: "host" | "repo"` findings.
29
+ - Added geometric monochrome `docs/assets/gardenia.svg` mark with provenance in
30
+ `docs/assets/README.md`.
31
+ - Added Read the Docs Sphinx + MyST + Furo documentation (`docs/quickstart.md`,
32
+ `docs/host-vs-repo.md`, `docs/architecture.md`, `docs/reference.md`,
33
+ `docs/contributing.md`, `docs/releasing.md`, `docs/changelog.md`).
gardenia-0.1.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 gardenia contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,6 @@
1
+ include AGENTS.md CHANGELOG.md gardenia.toml
2
+ include .readthedocs.yaml
3
+ recursive-include docs *.md *.py *.txt *.svg
4
+ recursive-exclude docs/_build *
5
+ recursive-include scripts *
6
+ recursive-include tests *.py
@@ -0,0 +1,111 @@
1
+ Metadata-Version: 2.4
2
+ Name: gardenia
3
+ Version: 0.1.0
4
+ Summary: Bootstrap, initialize, and verify the coding-agent stack with explicit host vs. repository separation.
5
+ License-Expression: MIT
6
+ Project-URL: Repository, https://github.com/xu-hao/gardenia
7
+ Project-URL: Issues, https://github.com/xu-hao/gardenia/issues
8
+ Project-URL: Changelog, https://github.com/xu-hao/gardenia/blob/main/CHANGELOG.md
9
+ Project-URL: Documentation, https://gardenia.readthedocs.io/en/latest/
10
+ Classifier: Development Status :: 3 - Alpha
11
+ Classifier: Environment :: Console
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: Programming Language :: Python :: 3
14
+ Classifier: Programming Language :: Python :: 3.11
15
+ Classifier: Programming Language :: Python :: 3.12
16
+ Classifier: Programming Language :: Python :: 3.13
17
+ Classifier: Topic :: Software Development :: Build Tools
18
+ Requires-Python: >=3.11
19
+ Description-Content-Type: text/markdown
20
+ License-File: LICENSE
21
+ Provides-Extra: test
22
+ Requires-Dist: pytest>=8; extra == "test"
23
+ Requires-Dist: build; extra == "test"
24
+ Provides-Extra: docs
25
+ Requires-Dist: sphinx>=8; extra == "docs"
26
+ Requires-Dist: myst-parser>=4; extra == "docs"
27
+ Requires-Dist: furo; extra == "docs"
28
+ Dynamic: license-file
29
+
30
+ # gardenia
31
+
32
+ <img src="docs/assets/gardenia.svg" alt="gardenia rosette mark" width="160" height="160">
33
+
34
+ *Where the grain (`agrein`), gourd (`agcoord`), root (`agroute`), and `howhard` grow together.*
35
+
36
+ [Read the documentation](https://gardenia.readthedocs.io/en/latest/).
37
+
38
+ `gardenia` is the zero-dependency bootstrapper, repository initializer, verifier, and
39
+ canonical full-stack guide for the four-tool coding-agent ecosystem:
40
+
41
+ | Layer | Role | Scope |
42
+ | --- | --- | --- |
43
+ | [**agrein**](https://github.com/xu-hao/agrein) (*“a grain”*) | Contributor & epic/subagent skills (`ticket-delivery`, `epic-queue`, `bug-investigation`, `owner-escalation`) | Host plugin + repo policy trigger |
44
+ | [**agcoord**](https://github.com/xu-hao/agcoord) (`agc`, *“a gourd”*) | Linux local resource/cgroup-v2 broker and atomic `agc land` merge gate | Host CLI + broker + plugin; repo check/land command |
45
+ | [**howhard**](https://github.com/xu-hao/howhard) | Bayesian model/effort selector, outcome accounting, and writable semantic memory (`>= 4.0.0`) | Host CLI + plugin; per-clone `.git/howhard` store |
46
+ | [**agroute**](https://github.com/xu-hao/agroute) (`agr`, *“a root”*) | Cross-agent (`codex`, `claude`, `agy`) live quota filtering and execution-plan resolution (`>= 0.6.0`) | Host CLI + plugin + `~/.config/agroute/config.toml`; per-clone `.git/agroute` store |
47
+
48
+ `gardenia` enforces an explicit boundary between **per-host** workstation setup and
49
+ **per-repository** policy and local `.git/` state across every CLI subcommand, JSON
50
+ schema, and documentation page:
51
+
52
+ - **`gardenia host ...`** inspects or configures only workstation / OS-user state
53
+ (`PATH` CLIs, Linux `agc` broker, user-scoped plugins across Codex/Claude Code/Antigravity,
54
+ and `~/.config/agroute/config.toml`). It never inspects or mutates a Git repository.
55
+ - **`gardenia repo ...`** inspects, renders, or updates only a target Git repository,
56
+ distinguishing **tracked repository settings** (`AGENTS.md` managed block,
57
+ `CLAUDE.md -> AGENTS.md` symlink, `gardenia.toml` / `[tool.gardenia]`, optional
58
+ `howhard.toml` and `agroute.toml`) from **local per-clone `.git/` state**
59
+ (`.git/howhard` and `.git/agroute`). It never mutates user-home host installations.
60
+ - **`gardenia check`** combines `host check` and (when inside a Git checkout or given
61
+ `--repo`) `repo check`, tagging every finding with `"scope": "host"` or
62
+ `"scope": "repo"` and a concrete remediation command.
63
+
64
+ ## Quickstart
65
+
66
+ Install `gardenia` (Python 3.11+, zero third-party runtime dependencies):
67
+
68
+ ```sh
69
+ uv tool install gardenia
70
+ gardenia --version
71
+ ```
72
+
73
+ ### Step 1 — Once per workstation (`gardenia host`)
74
+
75
+ Preview and apply host CLIs, safe Linux broker setup (preserving any existing
76
+ `cgroup-v2` enforced broker), user-scoped plugins across detected clients, and optional
77
+ quota reserves:
78
+
79
+ ```sh
80
+ gardenia host setup --dry-run
81
+ gardenia host setup --reserve-pct 5 --host-reserve-credit 20 --min-remaining-credit 5
82
+ gardenia host check
83
+ ```
84
+
85
+ ### Step 2 — Once per repository (`gardenia repo`)
86
+
87
+ Inside your repository's primary checkout, insert the delimited
88
+ `<!-- gardenia:begin --> ... <!-- gardenia:end -->` guardrail block into `AGENTS.md`
89
+ (preserving every surrounding project-specific line), link `CLAUDE.md -> AGENTS.md`,
90
+ and persist your profile to `gardenia.toml`:
91
+
92
+ ```sh
93
+ gardenia repo init --gate "bash scripts/check" --cpu 4 --memory-gb 4 --save-config
94
+ gardenia repo check
95
+ ```
96
+
97
+ ### Unified diagnostic
98
+
99
+ ```sh
100
+ gardenia check --json
101
+ ```
102
+
103
+ ## Documentation
104
+
105
+ - [Quickstart](docs/quickstart.md) — step-by-step workstation setup and repository onboarding.
106
+ - [Host vs. repository boundary](docs/host-vs-repo.md) — complete side-by-side matrix of host state, tracked repo policy, and local `.git/` state.
107
+ - [Full-stack architecture](docs/architecture.md) — end-to-end Coordinator vs. Leaf Worker runtime lifecycle.
108
+ - [CLI and schema reference](docs/reference.md) — subcommands, flags, exit codes, `gardenia.toml`, and `gardenia-check-v1` JSON schema.
109
+ - [Contributor workflow](docs/contributing.md) and [Packaging and release](docs/releasing.md).
110
+
111
+ Licensed under the [MIT License](LICENSE).
@@ -0,0 +1,82 @@
1
+ # gardenia
2
+
3
+ <img src="docs/assets/gardenia.svg" alt="gardenia rosette mark" width="160" height="160">
4
+
5
+ *Where the grain (`agrein`), gourd (`agcoord`), root (`agroute`), and `howhard` grow together.*
6
+
7
+ [Read the documentation](https://gardenia.readthedocs.io/en/latest/).
8
+
9
+ `gardenia` is the zero-dependency bootstrapper, repository initializer, verifier, and
10
+ canonical full-stack guide for the four-tool coding-agent ecosystem:
11
+
12
+ | Layer | Role | Scope |
13
+ | --- | --- | --- |
14
+ | [**agrein**](https://github.com/xu-hao/agrein) (*“a grain”*) | Contributor & epic/subagent skills (`ticket-delivery`, `epic-queue`, `bug-investigation`, `owner-escalation`) | Host plugin + repo policy trigger |
15
+ | [**agcoord**](https://github.com/xu-hao/agcoord) (`agc`, *“a gourd”*) | Linux local resource/cgroup-v2 broker and atomic `agc land` merge gate | Host CLI + broker + plugin; repo check/land command |
16
+ | [**howhard**](https://github.com/xu-hao/howhard) | Bayesian model/effort selector, outcome accounting, and writable semantic memory (`>= 4.0.0`) | Host CLI + plugin; per-clone `.git/howhard` store |
17
+ | [**agroute**](https://github.com/xu-hao/agroute) (`agr`, *“a root”*) | Cross-agent (`codex`, `claude`, `agy`) live quota filtering and execution-plan resolution (`>= 0.6.0`) | Host CLI + plugin + `~/.config/agroute/config.toml`; per-clone `.git/agroute` store |
18
+
19
+ `gardenia` enforces an explicit boundary between **per-host** workstation setup and
20
+ **per-repository** policy and local `.git/` state across every CLI subcommand, JSON
21
+ schema, and documentation page:
22
+
23
+ - **`gardenia host ...`** inspects or configures only workstation / OS-user state
24
+ (`PATH` CLIs, Linux `agc` broker, user-scoped plugins across Codex/Claude Code/Antigravity,
25
+ and `~/.config/agroute/config.toml`). It never inspects or mutates a Git repository.
26
+ - **`gardenia repo ...`** inspects, renders, or updates only a target Git repository,
27
+ distinguishing **tracked repository settings** (`AGENTS.md` managed block,
28
+ `CLAUDE.md -> AGENTS.md` symlink, `gardenia.toml` / `[tool.gardenia]`, optional
29
+ `howhard.toml` and `agroute.toml`) from **local per-clone `.git/` state**
30
+ (`.git/howhard` and `.git/agroute`). It never mutates user-home host installations.
31
+ - **`gardenia check`** combines `host check` and (when inside a Git checkout or given
32
+ `--repo`) `repo check`, tagging every finding with `"scope": "host"` or
33
+ `"scope": "repo"` and a concrete remediation command.
34
+
35
+ ## Quickstart
36
+
37
+ Install `gardenia` (Python 3.11+, zero third-party runtime dependencies):
38
+
39
+ ```sh
40
+ uv tool install gardenia
41
+ gardenia --version
42
+ ```
43
+
44
+ ### Step 1 — Once per workstation (`gardenia host`)
45
+
46
+ Preview and apply host CLIs, safe Linux broker setup (preserving any existing
47
+ `cgroup-v2` enforced broker), user-scoped plugins across detected clients, and optional
48
+ quota reserves:
49
+
50
+ ```sh
51
+ gardenia host setup --dry-run
52
+ gardenia host setup --reserve-pct 5 --host-reserve-credit 20 --min-remaining-credit 5
53
+ gardenia host check
54
+ ```
55
+
56
+ ### Step 2 — Once per repository (`gardenia repo`)
57
+
58
+ Inside your repository's primary checkout, insert the delimited
59
+ `<!-- gardenia:begin --> ... <!-- gardenia:end -->` guardrail block into `AGENTS.md`
60
+ (preserving every surrounding project-specific line), link `CLAUDE.md -> AGENTS.md`,
61
+ and persist your profile to `gardenia.toml`:
62
+
63
+ ```sh
64
+ gardenia repo init --gate "bash scripts/check" --cpu 4 --memory-gb 4 --save-config
65
+ gardenia repo check
66
+ ```
67
+
68
+ ### Unified diagnostic
69
+
70
+ ```sh
71
+ gardenia check --json
72
+ ```
73
+
74
+ ## Documentation
75
+
76
+ - [Quickstart](docs/quickstart.md) — step-by-step workstation setup and repository onboarding.
77
+ - [Host vs. repository boundary](docs/host-vs-repo.md) — complete side-by-side matrix of host state, tracked repo policy, and local `.git/` state.
78
+ - [Full-stack architecture](docs/architecture.md) — end-to-end Coordinator vs. Leaf Worker runtime lifecycle.
79
+ - [CLI and schema reference](docs/reference.md) — subcommands, flags, exit codes, `gardenia.toml`, and `gardenia-check-v1` JSON schema.
80
+ - [Contributor workflow](docs/contributing.md) and [Packaging and release](docs/releasing.md).
81
+
82
+ Licensed under the [MIT License](LICENSE).
@@ -0,0 +1,85 @@
1
+ # Full-stack architecture
2
+
3
+ `gardenia` ties four focused tools into one coherent workflow without collapsing their
4
+ responsibilities into a monolith. Each layer owns one clear boundary:
5
+
6
+ - **`agrein`** defines *how* work is scoped, isolated, escalated, and verified (pure
7
+ Markdown Agent Skills, zero runtime).
8
+ - **`agroute` (`agr`)** answers *which agent and models are eligible right now* given live
9
+ subscription quotas, credit reserves, and first-party rate cards, and resolves a chosen
10
+ route into either a native subagent directive or a cross-agent CLI command.
11
+ - **`howhard`** answers *which eligible `(agent, model, effort)` cell maximizes expected
12
+ quality per unit cost*, records actual outcomes and token usage, attributes escaped
13
+ defects, and maintains writable semantic memory.
14
+ - **`agcoord` (`agc`)** owns *machine resource admission, kernel cgroup-v2 limits, and
15
+ atomic gate-plus-merge publication* on a shared Linux workstation.
16
+
17
+ ## Coordinator vs. Leaf Worker lifecycle
18
+
19
+ The stack separates **coordinating** an epic or ticket queue from **executing** a single
20
+ authorized leaf ticket so delegation never loops recursively and every worker operates in
21
+ complete Git and resource isolation.
22
+
23
+ ```text
24
+ +-----------------------------------------------------------------------------+
25
+ | COORDINATOR (interactive session in primary checkout or epic control plane) |
26
+ | |
27
+ | 1. Triage & escalate unsettled product/policy questions |
28
+ | -> agrein: epic-queue + owner-escalation |
29
+ | |
30
+ | 2. Filter eligible routes within live subscription quotas & credit reserves|
31
+ | -> agr usage |
32
+ | -> agr candidates --host <codex|claude|agy> --output /tmp/TASK-c.json |
33
+ | (if price_request != null: look up official prices -> agr prices |
34
+ | resolve --file /tmp/TASK-p.json -> re-emit candidates once) |
35
+ | |
36
+ | 3. Choose optimal (agent, model, effort) from history & semantic memory |
37
+ | -> howhard context / retrieve / decide (with independent baseline) |
38
+ | -> agr plan --host <host> --decision /tmp/TASK-d.json --json |
39
+ | |
40
+ | 4. Dispatch leaf worker (native subagent tool OR cross-agent CLI plan) |
41
+ +--------------------------------------+--------------------------------------+
42
+ |
43
+ v
44
+ +-----------------------------------------------------------------------------+
45
+ | LEAF WORKER (assigned one ticket; NEVER delegates recursively) |
46
+ | |
47
+ | 1. Follow agrein: ticket-delivery (+ bug-investigation for defects) |
48
+ | 2. Create isolated worktree & venv under /var/tmp/<repo>-<N>-* |
49
+ | (primary checkout stays read-only) |
50
+ | 3. Implement change + focused hermetic tests + docs + CHANGELOG.md |
51
+ | 4. Run coordinated validation with integer byte memory claims: |
52
+ | -> agc run --no-overflow --resource cpu=4 --resource memory=4294967296 |
53
+ | -- bash scripts/check |
54
+ | 5. Open PR ("Closes #N") and gate + merge atomically: |
55
+ | -> agc land <pr> --no-overflow --resource cpu=4 |
56
+ | --resource memory=4294967296 -- bash scripts/check |
57
+ | 6. Verify origin/main, CI, empty git cherry, clean /var/tmp artifacts |
58
+ | 7. Return four-part session handoff to coordinator |
59
+ +--------------------------------------+--------------------------------------+
60
+ |
61
+ v
62
+ +-----------------------------------------------------------------------------+
63
+ | COORDINATOR POST-RUN ACCOUNTING |
64
+ | |
65
+ | 1. Record outcome & measured usage following plan.feedback block: |
66
+ | -> howhard observe <decision_id> <clean|loud|silent> ... |
67
+ | -> howhard usage attach ... (matched_receipt or raw_native) |
68
+ | 2. Distill durable lessons into repository semantic memory: |
69
+ | -> howhard memory add / update / remove |
70
+ +-----------------------------------------------------------------------------+
71
+ ```
72
+
73
+ ## Where `gardenia` sits
74
+
75
+ `gardenia` does not sit in the hot path of routing, execution, or merge gating. It is the
76
+ **setup, policy synchronization, and health-check layer** around the four tools:
77
+
78
+ - Before work begins on a workstation, `gardenia host setup` and `gardenia host check`
79
+ verify that the Python CLIs, Linux `agc` broker, user-scoped plugins across Codex,
80
+ Claude Code, and Antigravity, and host quota reserves are installed and version-aligned.
81
+ - Before work begins in a repository, `gardenia repo init` renders the exact managed
82
+ guardrail block into `AGENTS.md` (with integer byte memory claims for `agc`, the
83
+ configured routing layer, and the docs-only exemption) and keeps `CLAUDE.md` linked.
84
+ - At any point, `gardenia check` diagnoses drift across both layers without mutating
85
+ either one.
@@ -0,0 +1,48 @@
1
+ # Project image provenance
2
+
3
+ ## Gardenia rosette mark
4
+
5
+ [gardenia.svg](gardenia.svg) is gardenia's project mark, published in the repository
6
+ README and documentation homepage. It depicts a symmetrical eight-petal pinwheel
7
+ gardenia rosette centered inside a subtle open-cornered square garden border. The
8
+ source specifies exactly two colors: solid black (`#000000`) for all strokes and solid
9
+ white (`#ffffff`) for the background. It contains no shading, gradients, texture,
10
+ text, fonts, embedded raster images, or external dependencies.
11
+
12
+ The SVG was authored directly for [Issue #1](https://github.com/xu-hao/gardenia/issues/1)
13
+ on 2026-11-22 in the same geometric monochrome style as `howhard` (`spiral.svg`) and
14
+ `agroute` (`route.svg`). No third-party artwork was used.
15
+
16
+ ### Mathematical construction
17
+
18
+ - Canvas and viewBox: `512 × 512`, centered at `(256, 256)`.
19
+ - Uniform line weight: `stroke-width="17"`, `stroke-linecap="round"`,
20
+ `stroke-linejoin="round"`.
21
+ - Open-cornered garden border: four equal straight wall segments along `x = 52`,
22
+ `x = 460`, `y = 52`, and `y = 460`, each spanning from `108` to `404` (leaving
23
+ symmetric `56`-unit open corner gaps).
24
+ - Central ring: circle centered at `(256, 256)` with radius `r0 = 34`.
25
+ - Eight-petal pinwheel rosette (`C8` rotational symmetry, `θ_k = k·π/4 − π/2` for
26
+ `k = 0..7`):
27
+ - Outward cubic Bézier for petal `k` from `(r0 = 34, θ_k)` through polar control
28
+ points `(78, θ_k − 10°)` and `(136, θ_k + 4°)` to outer petal crest
29
+ `(152, θ_k + 24°)`.
30
+ - Return cubic Bézier from the crest through polar control points `(160, θ_k + 42°)`
31
+ and `(124, θ_k + 52°)` to the exact analytic join point `C_{k+1}(0.48)` on the
32
+ neighboring petal's outward curve.
33
+ - Resulting rosette bounding box is `[109.37, 402.63] × [109.37, 402.63]`, leaving
34
+ `57.37` units of uniform clearance to every border edge.
35
+
36
+ Browsers may antialias edges; the vector source itself defines only `#000000` and
37
+ `#ffffff`.
38
+
39
+ ### Checksum
40
+
41
+ The SHA-256 digest of `docs/assets/gardenia.svg` is:
42
+
43
+ `67d91d31b967746dc3bc402df54575e9fc3954f695179a4066a222c5b4819be4`
44
+
45
+ ### Tracking
46
+
47
+ [Issue #1](https://github.com/xu-hao/gardenia/issues/1) tracks authoring `gardenia.svg`
48
+ for the `0.1.0` CLI and documentation release.
@@ -0,0 +1,23 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" width="512" height="512" viewBox="0 0 512 512"
2
+ role="img" aria-labelledby="gardenia-title gardenia-description">
3
+ <title id="gardenia-title">gardenia rosette mark</title>
4
+ <desc id="gardenia-description">A symmetrical eight-petal pinwheel gardenia rosette inside an open-cornered square garden border, in solid black on white.</desc>
5
+ <rect width="512" height="512" fill="#ffffff"/>
6
+ <!-- Open-cornered square garden border (edges at 52 and 460, open corner gaps of 56 units). -->
7
+ <path fill="none" stroke="#000000" stroke-width="17" stroke-linecap="round"
8
+ d="M 108 52 H 404
9
+ M 460 108 V 404
10
+ M 404 460 H 108
11
+ M 52 404 V 108"/>
12
+ <!-- Eight-petal pinwheel gardenia rosette with exact C8 rotational symmetry. -->
13
+ <circle cx="256" cy="256" r="34" fill="none" stroke="#000000" stroke-width="17"/>
14
+ <path fill="none" stroke="#000000" stroke-width="17" stroke-linecap="round" stroke-linejoin="round"
15
+ d="M 256.000 222.000 C 242.455 179.185 265.487 120.331 317.824 117.141 C 363.061 137.097 353.713 179.658 329.386 189.647
16
+ M 280.042 231.958 C 300.739 192.106 358.641 166.776 397.904 201.528 C 415.781 247.626 379.076 271.112 354.810 260.973
17
+ M 290.000 256.000 C 332.815 242.455 391.669 265.487 394.859 317.824 C 374.903 363.061 332.342 353.713 322.353 329.386
18
+ M 280.042 280.042 C 319.894 300.739 345.224 358.641 310.472 397.904 C 264.374 415.781 240.888 379.076 251.027 354.810
19
+ M 256.000 290.000 C 269.545 332.815 246.513 391.669 194.176 394.859 C 148.939 374.903 158.287 332.342 182.614 322.353
20
+ M 231.958 280.042 C 211.261 319.894 153.359 345.224 114.096 310.472 C 96.219 264.374 132.924 240.888 157.190 251.027
21
+ M 222.000 256.000 C 179.185 269.545 120.331 246.513 117.141 194.176 C 137.097 148.939 179.658 158.287 189.647 182.614
22
+ M 231.958 231.958 C 192.106 211.261 166.776 153.359 201.528 114.096 C 247.626 96.219 271.112 132.924 260.973 157.190"/>
23
+ </svg>
@@ -0,0 +1,2 @@
1
+ ```{include} ../CHANGELOG.md
2
+ ```
@@ -0,0 +1,10 @@
1
+ from importlib.metadata import version as distribution_version
2
+
3
+ project = "gardenia"
4
+ release = distribution_version("gardenia")
5
+ version = release
6
+ extensions = ["myst_parser"]
7
+ source_suffix = {".md": "markdown"}
8
+ master_doc = "index"
9
+ html_theme = "furo"
10
+ exclude_patterns = ["_build"]
@@ -0,0 +1,46 @@
1
+ # Contributor workflow
2
+
3
+ Track every code, test, documentation, or packaging change with a descriptive GitHub
4
+ issue (`#N — one sentence describing the work`). Develop and validate only in an
5
+ issue-specific Git worktree branched from `origin/main`, keeping the primary checkout
6
+ read-only during development.
7
+
8
+ ```sh
9
+ git fetch origin
10
+ git worktree add -b issue-N-description /var/tmp/agrein-gardenia-N-wt origin/main
11
+ cd /var/tmp/agrein-gardenia-N-wt
12
+ uv venv --python 3.12 /var/tmp/agrein-gardenia-N-venv
13
+ uv pip install --python /var/tmp/agrein-gardenia-N-venv/bin/python -e '.[test,docs]'
14
+ ```
15
+
16
+ Run the full validation gate through `agcoord` on Linux (using integer bytes for memory
17
+ claims):
18
+
19
+ ```sh
20
+ agc run --no-overflow --resource cpu=4 --resource memory=4294967296 -- bash scripts/check
21
+ ```
22
+
23
+ `scripts/check` runs:
24
+
25
+ 1. `python -m pytest -q` (hermetic behavioral tests using temporary `HOME`, `PATH`, fake
26
+ CLI shims, and temporary Git repositories — never touching real `~/.codex`,
27
+ `~/.claude`, `~/.gemini`, `~/.config`, or `~/.local`).
28
+ 2. `python -m build` (sdist and wheel).
29
+ 3. `python scripts/verify-wheel.py` (inspecting metadata, entry point, clean wheel
30
+ contents, and executing `gardenia --version` and `gardenia repo render` from an
31
+ isolated temporary virtual environment).
32
+ 4. `python -m sphinx -W --keep-going -b html docs docs/_build/html` (strict warning-free
33
+ Read the Docs build).
34
+
35
+ Update affected canonical documents, `gardenia.toml` / `AGENTS.md` (via
36
+ `gardenia repo init --allow-worktree` inside a ticket worktree if policy changes), and
37
+ `CHANGELOG.md` for user-facing changes.
38
+
39
+ Gate and publish pull requests atomically through one `agc land` command:
40
+
41
+ ```sh
42
+ agc land <pr> --no-overflow --resource cpu=4 --resource memory=4294967296 -- bash scripts/check
43
+ ```
44
+
45
+ Documentation-only changes follow the narrower exemption in `AGENTS.md`. End changed
46
+ work with the four-part [session handoff](session_handoff_format.md).
@@ -0,0 +1,80 @@
1
+ # Host vs. repository boundary
2
+
3
+ Mixing workstation setup with repository configuration is the single most common source
4
+ of drift, broken CI, and accidentally committed machine paths in multi-agent setups.
5
+ `gardenia` enforces a strict three-zone model across its CLI, JSON schemas, and internal
6
+ modules:
7
+
8
+ 1. **Per-Host (Workstation / OS User)** — managed exclusively by `gardenia host ...`.
9
+ 2. **Per-Repository Tracked Policy (Committed in Git)** — managed by `gardenia repo init`
10
+ / `gardenia repo render` and verified by `gardenia repo check`.
11
+ 3. **Per-Repository Local Clone State (Untracked under `.git/`)** — inspected read-only
12
+ by `gardenia repo check`, shared across linked Git worktrees through
13
+ `git rev-parse --git-common-dir`, and never committed to Git.
14
+
15
+ ## Side-by-side boundary matrix
16
+
17
+ | Artifact or Setting | Zone | Location | Managed / Checked By | Shared Across |
18
+ | --- | --- | --- | --- | --- |
19
+ | `howhard`, `agr`, `agc`, `gardenia` binaries | **Per-Host** | `~/.local/bin` (via `uv tool` / `pipx`) | `gardenia host setup` / `host check` | All repos on workstation |
20
+ | `agcoord` host broker & cgroup-v2 bindings | **Per-Host** | `~/.local/state/agcoord`, `~/.local/libexec/agcoord`, or `/usr/libexec/agcoord` | `gardenia host setup --broker ...` / `host check` | All repos & worktrees for OS user |
21
+ | User-scoped Codex plugins & cache | **Per-Host** | `~/.codex/config.toml`, `~/.codex/plugins/cache/<pkg>/<pkg>/*/plugin.json` | `gardenia host setup --clients codex` / `host check` | All Codex sessions |
22
+ | User-scoped Claude Code plugins | **Per-Host** | `~/.claude/plugins/` (`--scope user`) | `gardenia host setup --clients claude` / `host check` | All Claude Code sessions |
23
+ | User-scoped Antigravity plugins | **Per-Host** | `~/.gemini/config/plugins/` | `gardenia host setup --clients agy` / `host check` | All Antigravity sessions |
24
+ | Subscription plans, quota cutoffs & credit reserves | **Per-Host** | `${XDG_CONFIG_HOME:-~/.config}/agroute/config.toml` | `gardenia host setup --reserve-*` / `host check` | All repos for OS user |
25
+ | Contributor guardrails (managed block + project rules) | **Per-Repo Tracked** | `<repo>/AGENTS.md` | `gardenia repo init` / `repo render` / `repo check` | All contributors via Git |
26
+ | Claude Code root instruction symlink | **Per-Repo Tracked** | `<repo>/CLAUDE.md -> AGENTS.md` | `gardenia repo init` / `repo check` | All contributors via Git |
27
+ | Gardenia repository profile | **Per-Repo Tracked** | `<repo>/gardenia.toml` (or `[tool.gardenia]` in `pyproject.toml`) | `gardenia repo init --save-config` / `repo check` | All contributors via Git |
28
+ | Optional project `howhard` policy/inventories | **Per-Repo Tracked** | `<repo>/howhard.toml` | Validated by `gardenia repo check` | All contributors via Git |
29
+ | Optional project `agroute` overrides | **Per-Repo Tracked** | `<repo>/agroute.toml` | Validated by `gardenia repo check` | All contributors via Git |
30
+ | `howhard` learned store, payloads, & semantic memory | **Per-Repo Local `.git/`** | `<git-common-dir>/howhard/` (`store.json`, `payloads.sqlite3`, `memory.sqlite3`) | Inspected read-only by `gardenia repo check` | Primary checkout + all linked worktrees of one clone |
31
+ | `agroute` route history, usage, & resolved prices | **Per-Repo Local `.git/`** | `<git-common-dir>/agroute/` (`routes.sqlite3`, `prices.json`, `usage.json`) | Inspected read-only by `gardenia repo check` (`agr prices pending --json`) | Primary checkout + all linked worktrees of one clone |
32
+
33
+ ## Why these boundaries are enforced in code
34
+
35
+ ### 1. Protecting enforced `cgroup-v2` brokers
36
+
37
+ On Ubuntu 24.04-class hosts with a privileged `cgroup-v2` AGCoord broker, blindly running
38
+ `agc host install --user` would replace or conflict with kernel-enforced resource limits.
39
+ `gardenia host check` inspects `agc --json list` (`resource_bindings`) read-only, and
40
+ `gardenia host setup`:
41
+
42
+ - Preserves any active `cgroup-v2` enforced broker untouched under `--broker auto`.
43
+ - Refuses `--broker user` with exit code `2` when an enforced broker is detected (unless
44
+ `--force-broker` is explicitly supplied).
45
+ - Uses `agc host upgrade --download` (or `agc host install --download`) only when the
46
+ operator explicitly asks for `--broker enforced`.
47
+
48
+ ### 2. Non-interactive Codex inspection
49
+
50
+ Invoking `codex plugin list` without a TTY opens an interactive TUI and blocks automation.
51
+ `gardenia host check` never invokes `codex plugin list`. Instead, it parses
52
+ `~/.codex/config.toml` (`[marketplaces.<pkg>]` and `[plugins."<pkg>@<pkg>"]`) and reads
53
+ cached plugin manifests at `~/.codex/plugins/cache/<pkg>/<pkg>/*/plugin.json` (selecting
54
+ the highest semantic version when multiple cached versions exist, falling back to
55
+ `~/.codex/.tmp/marketplaces/<pkg>/plugin.json`).
56
+
57
+ ### 3. Linked worktrees vs. primary checkouts
58
+
59
+ Under the `agrein` workflow, ticket work happens in temporary linked Git worktrees
60
+ (for example `/var/tmp/<repo>-<N>-wt`) while the primary checkout stays clean.
61
+
62
+ - `gardenia repo init` refuses linked worktrees by default (exit code `2`) so routine
63
+ onboarding runs in the primary checkout rather than an ephemeral ticket branch; pass
64
+ `--allow-worktree` when intentionally updating `AGENTS.md` inside an issue worktree.
65
+ - `gardenia repo check` resolves both `--git-dir` and `--git-common-dir` so it accurately
66
+ locates shared `.git/howhard` and `.git/agroute` stores from any linked worktree.
67
+
68
+ ### 4. Non-destructive `howhard` legacy payload checks
69
+
70
+ If a repository's `<git-common-dir>/howhard/` still contains pre-4.0 loose
71
+ `requests/*.json` or `decisions/*.json` files, `gardenia repo check` emits a
72
+ `scope="repo"` warning pointing to `howhard`'s `migrate-payloads.py` script without ever
73
+ deleting or rewriting those files.
74
+
75
+ ### 5. Scope-tagged diagnostics
76
+
77
+ When you run `gardenia check --json`, every finding explicitly declares
78
+ `"scope": "host"` or `"scope": "repo"`. Automation and humans can tell immediately
79
+ whether a failure needs a workstation fix (`gardenia host setup`) or a tracked
80
+ repository update (`gardenia repo init`).