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.
- gardenia-0.1.0/.readthedocs.yaml +13 -0
- gardenia-0.1.0/AGENTS.md +63 -0
- gardenia-0.1.0/CHANGELOG.md +33 -0
- gardenia-0.1.0/LICENSE +21 -0
- gardenia-0.1.0/MANIFEST.in +6 -0
- gardenia-0.1.0/PKG-INFO +111 -0
- gardenia-0.1.0/README.md +82 -0
- gardenia-0.1.0/docs/architecture.md +85 -0
- gardenia-0.1.0/docs/assets/README.md +48 -0
- gardenia-0.1.0/docs/assets/gardenia.svg +23 -0
- gardenia-0.1.0/docs/changelog.md +2 -0
- gardenia-0.1.0/docs/conf.py +10 -0
- gardenia-0.1.0/docs/contributing.md +46 -0
- gardenia-0.1.0/docs/host-vs-repo.md +80 -0
- gardenia-0.1.0/docs/index.md +70 -0
- gardenia-0.1.0/docs/quickstart.md +118 -0
- gardenia-0.1.0/docs/reference.md +223 -0
- gardenia-0.1.0/docs/releasing.md +26 -0
- gardenia-0.1.0/docs/requirements.txt +3 -0
- gardenia-0.1.0/docs/session_handoff_format.md +16 -0
- gardenia-0.1.0/gardenia.toml +9 -0
- gardenia-0.1.0/pyproject.toml +46 -0
- gardenia-0.1.0/scripts/check +7 -0
- gardenia-0.1.0/scripts/verify-wheel.py +99 -0
- gardenia-0.1.0/setup.cfg +4 -0
- gardenia-0.1.0/src/gardenia/__init__.py +7 -0
- gardenia-0.1.0/src/gardenia/__main__.py +10 -0
- gardenia-0.1.0/src/gardenia/cli.py +482 -0
- gardenia-0.1.0/src/gardenia/host.py +1324 -0
- gardenia-0.1.0/src/gardenia/models.py +211 -0
- gardenia-0.1.0/src/gardenia/repo.py +1113 -0
- gardenia-0.1.0/src/gardenia.egg-info/PKG-INFO +111 -0
- gardenia-0.1.0/src/gardenia.egg-info/SOURCES.txt +40 -0
- gardenia-0.1.0/src/gardenia.egg-info/dependency_links.txt +1 -0
- gardenia-0.1.0/src/gardenia.egg-info/entry_points.txt +2 -0
- gardenia-0.1.0/src/gardenia.egg-info/requires.txt +9 -0
- gardenia-0.1.0/src/gardenia.egg-info/top_level.txt +1 -0
- gardenia-0.1.0/tests/conftest.py +273 -0
- gardenia-0.1.0/tests/test_host_check.py +166 -0
- gardenia-0.1.0/tests/test_host_setup.py +181 -0
- gardenia-0.1.0/tests/test_repo.py +230 -0
- gardenia-0.1.0/tests/test_unified_check.py +100 -0
gardenia-0.1.0/AGENTS.md
ADDED
|
@@ -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.
|
gardenia-0.1.0/PKG-INFO
ADDED
|
@@ -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).
|
gardenia-0.1.0/README.md
ADDED
|
@@ -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,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`).
|