@event4u/agent-config 5.6.0 → 5.7.0
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.
- package/.agent-src/commands/cost-report.md +12 -7
- package/.agent-src/commands/prediction-pool.md +215 -0
- package/.agent-src/commands/set-cost-profile.md +8 -8
- package/.agent-src/commands/sync-agent-settings.md +2 -2
- package/.agent-src/presets/README.md +1 -1
- package/.agent-src/profiles/README.md +1 -1
- package/.agent-src/rules/non-destructive-by-default.md +2 -1
- package/.agent-src/skills/prediction-pool-optimizer/SKILL.md +196 -0
- package/.agent-src/skills/prediction-pool-optimizer/evals/triggers.json +18 -0
- package/.agent-src/skills/prediction-pool-optimizer/reference/ev-fixtures.md +80 -0
- package/.agent-src/templates/agent-settings.md +7 -7
- package/.agent-src/templates/agents/agent-project-settings.example.yml +2 -2
- package/.agent-src/templates/scripts/work_engine/_lib/agent_settings.py +2 -1
- package/.agent-src/templates/scripts/work_engine/hook_bootstrap.py +1 -1
- package/.agent-src/templates/scripts/work_engine/hooks/builtin/memory_visibility.py +9 -7
- package/.agent-src/templates/scripts/work_engine/hooks/settings.py +9 -10
- package/.agent-src/templates/scripts/work_engine/scoring/memory_visibility.py +17 -4
- package/.claude-plugin/marketplace.json +3 -1
- package/CHANGELOG.md +57 -0
- package/README.md +2 -2
- package/config/agent-settings.template.yml +11 -2
- package/config/discovery/packs.yml +11 -0
- package/config/discovery/workspaces.yml +1 -1
- package/config/profiles/balanced.ini +1 -1
- package/config/profiles/full.ini +1 -1
- package/config/profiles/minimal.ini +1 -1
- package/dist/discovery/deprecation-report.md +1 -1
- package/dist/discovery/discovery-manifest.json +80 -14
- package/dist/discovery/discovery-manifest.json.sha256 +1 -1
- package/dist/discovery/discovery-manifest.summary.md +3 -2
- package/dist/discovery/orphan-report.md +1 -1
- package/dist/discovery/packs.json +34 -3
- package/dist/discovery/trust-report.md +2 -2
- package/dist/discovery/workspaces.json +13 -4
- package/dist/mcp/registry-manifest.json +3 -3
- package/dist/server/io/substituteTemplate.js +3 -3
- package/dist/server/io/substituteTemplate.js.map +1 -1
- package/dist/server/routes/settings.js +2 -2
- package/dist/server/routes/settings.js.map +1 -1
- package/dist/server/schemas/settings.js +4 -2
- package/dist/server/schemas/settings.js.map +1 -1
- package/dist/ui/assets/{index-DVsyUMZe.js → index-5lFqAKL0.js} +2 -2
- package/dist/ui/assets/index-5lFqAKL0.js.map +1 -0
- package/dist/ui/index.html +1 -1
- package/docs/architecture/current-onboard-baseline.md +3 -3
- package/docs/architecture.md +2 -2
- package/docs/catalog.md +7 -5
- package/docs/contracts/adr-level-6-productization.md +1 -1
- package/docs/contracts/config-presets.md +2 -2
- package/docs/contracts/cost-profile-defaults.md +5 -5
- package/docs/contracts/discovery-manifest.schema.json +1 -1
- package/docs/contracts/explain-trace.schema.json +3 -3
- package/docs/contracts/memory-visibility-v1.md +15 -7
- package/docs/contracts/profile-system.md +2 -2
- package/docs/contracts/settings-api.md +3 -3
- package/docs/contracts/value-report-schema.md +14 -1
- package/docs/customization.md +21 -5
- package/docs/decisions/ADR-010-profile-pack-preset-boundary.md +11 -11
- package/docs/decisions/ADR-013-discovery-frontmatter-contract.md +16 -2
- package/docs/decisions/ADR-034-per-skill-model-recommendation-transport.md +1 -1
- package/docs/decisions/ADR-036-global-install-browser-wizard-handoff.md +106 -0
- package/docs/decisions/ADR-037-cost-profile-untangle.md +117 -0
- package/docs/decisions/ADR-rule-kernel-and-router.md +1 -1
- package/docs/decisions/INDEX.md +2 -0
- package/docs/getting-started.md +2 -2
- package/docs/guidelines/agent-infra/layered-settings.md +2 -2
- package/docs/installation.md +3 -3
- package/docs/setup/mcp-client-config.md +1 -1
- package/docs/value.md +9 -7
- package/docs/wizard.md +1 -1
- package/package.json +1 -1
- package/scripts/__pycache__/validate_frontmatter.cpython-312.pyc +0 -0
- package/scripts/_cli/cmd_explain.py +1 -1
- package/scripts/_cli/explain_last/inputs.py +11 -8
- package/scripts/_cli/explain_last/sections/inputs.py +1 -1
- package/scripts/_lib/__pycache__/__init__.cpython-312.pyc +0 -0
- package/scripts/_lib/__pycache__/agent_src.cpython-312.pyc +0 -0
- package/scripts/_lib/agent_settings.py +2 -1
- package/scripts/_lib/value_ladder.py +99 -2
- package/scripts/_lib/value_report.py +30 -16
- package/scripts/ai_council/modes.py +1 -1
- package/scripts/audit_initial_context.py +16 -0
- package/scripts/check_skill_requires.py +143 -0
- package/scripts/condense.py +13 -2
- package/scripts/first-run.sh +11 -11
- package/scripts/install +14 -1
- package/scripts/install.py +127 -428
- package/scripts/install_anthropic_key.sh +1 -1
- package/scripts/install_openai_key.sh +1 -1
- package/scripts/lint_discovery_vocabulary.py +5 -5
- package/scripts/lint_value_dashboard.py +1 -1
- package/scripts/pack_mcp_content.py +1 -1
- package/scripts/prediction-pool/adapters/_schema.md +42 -0
- package/scripts/prediction-pool/adapters/kicktipp.yml +23 -0
- package/scripts/prediction-pool/poisson_sim.py +167 -0
- package/scripts/render_value_md.py +1 -0
- package/scripts/schemas/agent-settings.schema.json +77 -0
- package/scripts/schemas/skill.schema.json +7 -0
- package/scripts/smoke_quickstart.py +4 -4
- package/scripts/sync_agent_settings.py +4 -2
- package/scripts/validate_agent_settings.py +120 -0
- package/templates/minimal/.agent-settings.yml +1 -1
- package/dist/ui/assets/index-DVsyUMZe.js.map +0 -1
package/dist/ui/index.html
CHANGED
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
|
6
6
|
<meta name="robots" content="noindex" />
|
|
7
7
|
<title>agent-config</title>
|
|
8
|
-
<script type="module" crossorigin src="/assets/index-
|
|
8
|
+
<script type="module" crossorigin src="/assets/index-5lFqAKL0.js"></script>
|
|
9
9
|
<link rel="stylesheet" crossorigin href="/assets/index-BbWWuFrF.css">
|
|
10
10
|
</head>
|
|
11
11
|
<body>
|
|
@@ -27,7 +27,7 @@ inert — no settings file, no flow.
|
|
|
27
27
|
| 4 | `personal.ide` (+ auto-detect via `ps aux`) and `personal.open_edited_files` | IDE id, auto-open flag | unset |
|
|
28
28
|
| 5 | `personal.pr_comment_bot_icon` | bool | always (no detection possible) |
|
|
29
29
|
| 6 | `personal.rtk_installed` (via `which rtk`) | bool + install action | rtk not found |
|
|
30
|
-
| 7 | `
|
|
30
|
+
| 7 | `rule_loading_tier` and `pipelines.skill_improvement` | profile id, learning bool | always (one summary screen) |
|
|
31
31
|
| 8 | Mark `onboarding.onboarded: true` | — | always |
|
|
32
32
|
| 9 | Write user-global `~/.event4u/agent-config/agent-settings.yml` | six whitelisted keys | step 2 captured "yes" |
|
|
33
33
|
| 10 | Summary block | — | always |
|
|
@@ -65,7 +65,7 @@ personal:
|
|
|
65
65
|
open_edited_files: true|false # step 4
|
|
66
66
|
pr_comment_bot_icon: true|false # step 5
|
|
67
67
|
rtk_installed: true|false # step 6
|
|
68
|
-
|
|
68
|
+
rule_loading_tier: "balanced" # step 7 (default unchanged)
|
|
69
69
|
pipelines:
|
|
70
70
|
skill_improvement: true # step 7 (default unchanged)
|
|
71
71
|
onboarding:
|
|
@@ -74,7 +74,7 @@ onboarding:
|
|
|
74
74
|
|
|
75
75
|
User-global file (step 9, opt-in): the six whitelisted keys in
|
|
76
76
|
[`scripts/_lib/agent_settings.py`](../../scripts/_lib/agent_settings.py)
|
|
77
|
-
— `name`, `ide`, `
|
|
77
|
+
— `name`, `ide`, `rule_loading_tier`, `personal.bot_icon`,
|
|
78
78
|
`personal.autonomy`, `telegraph.speak_scope`.
|
|
79
79
|
|
|
80
80
|
## Iron Laws today
|
package/docs/architecture.md
CHANGED
|
@@ -146,9 +146,9 @@ note, package-internal path-swap, description budget, and the
|
|
|
146
146
|
|
|
147
147
|
| Layer | Count | Purpose |
|
|
148
148
|
|---|---|---|
|
|
149
|
-
| **Skills** |
|
|
149
|
+
| **Skills** | 223 | On-demand expertise — stack analysis (Laravel · Symfony · Zend / Laminas · Next.js · React · Node), testing, Docker, API design, security, observability, … |
|
|
150
150
|
| **Rules** | 79 | Always-active constraints — coding standards, scope control, verification, language-and-tone, agent-authority |
|
|
151
|
-
| **Commands** |
|
|
151
|
+
| **Commands** | 146 | Slash-command workflows — `/commit`, `/create-pr`, `/fix ci`, `/optimize skills`, `/feature plan`, `/work`, `/implement-ticket`, `/condense`, … |
|
|
152
152
|
| **Guidelines** | 73 | Reference material cited by skills — PHP patterns, Eloquent, Playwright, agent-infra, … |
|
|
153
153
|
| **Templates** | 7 | Scaffolds for features, roadmaps, contexts, skills, overrides |
|
|
154
154
|
| **Contexts** | 5 | Shared knowledge about the system itself |
|
package/docs/catalog.md
CHANGED
|
@@ -1,13 +1,13 @@
|
|
|
1
1
|
# agent-config — Public Catalog
|
|
2
2
|
|
|
3
|
-
Consumer-facing catalog of all **
|
|
3
|
+
Consumer-facing catalog of all **520 public artefacts** shipped by
|
|
4
4
|
this package. Internal package-maintenance rules and deprecation shims
|
|
5
5
|
are excluded.
|
|
6
6
|
|
|
7
7
|
> **Regenerate:** `python3 scripts/generate_index.py`
|
|
8
8
|
> Auto-generated — do not edit manually.
|
|
9
9
|
|
|
10
|
-
## Skills (
|
|
10
|
+
## Skills (223)
|
|
11
11
|
|
|
12
12
|
| kind | name | extra | description |
|
|
13
13
|
|---|---|---|---|
|
|
@@ -157,6 +157,7 @@ are excluded.
|
|
|
157
157
|
| skill | [`playwright-testing`](../.agent-src/skills/playwright-testing/SKILL.md) | | Use when writing Playwright E2E tests — browser automation, visual regression testing, Page Objects, fixtures, and reliable test patterns. |
|
|
158
158
|
| skill | [`po-discovery`](../.agent-src/skills/po-discovery/SKILL.md) | | Use when shaping a fuzzy product ask into a refined backlog item — problem framing, user-story rewrite, AC tightening — even if the user just says 'help me write this ticket'. |
|
|
159
159
|
| skill | [`positioning-strategy`](../.agent-src/skills/positioning-strategy/SKILL.md) | | Use when locking the market frame — category, segment, alternative, point-of-view — before messaging, launch, or pricing rides on it. Triggers on 'who are we for', 'opposable audit'. |
|
|
160
|
+
| skill | [`prediction-pool-optimizer`](../.agent-src/skills/prediction-pool-optimizer/SKILL.md) | | Optimize prediction-pool tips (kicktipp etc.): pool rules + market odds → the expected-points-maximizing tip per match. Triggers 'optimize my pool tips', 'best kicktipp picks', 'predict'. |
|
|
160
161
|
| skill | [`privacy-review`](../.agent-src/skills/privacy-review/SKILL.md) | | Use when reviewing data flows, support macros, refund templates for GDPR/CCPA/HIPAA fit — regime, consent, PII redaction (email, order-id), breach triage. Triggers 'is this GDPR-safe', 'PII redact'. |
|
|
161
162
|
| skill | [`project-analysis-core`](../.agent-src/skills/project-analysis-core/SKILL.md) | | Raw discovery primitives — project discovery, version resolution, docs loading, architecture mapping, execution flow. Called by `universal-project-analysis`. Single-pass scan → `project-analyzer`. |
|
|
162
163
|
| skill | [`project-analysis-hypothesis-driven`](../.agent-src/skills/project-analysis-hypothesis-driven/SKILL.md) | | Use when a bug has multiple plausible causes across layers — competing hypotheses, validation loops, evidence-based conclusions — even when the user just says 'why is this happening?'. |
|
|
@@ -285,7 +286,7 @@ are excluded.
|
|
|
285
286
|
| rule | [`no-decorative-emojis-in-git-surfaces`](../.agent-src/rules/no-decorative-emojis-in-git-surfaces.md) | auto | Generating PR/issue/commit titles or PR/issue comments — forbids decorative emojis; allowed in PR/issue descriptions + commit bodies only when matched by an in-artifact legend |
|
|
286
287
|
| rule | [`no-pr-progress-comments`](../.agent-src/rules/no-pr-progress-comments.md) | auto | Posting comments on an open PR — refuses unsolicited progress / status / CI-fix narration unless personal.pr_progress_comments is true |
|
|
287
288
|
| rule | [`no-roadmap-references`](../.agent-src/rules/no-roadmap-references.md) | auto | Linking transient files (agents/roadmaps/, agents/runtime/council/*/) from a stable artifact — both layers expire; promote findings |
|
|
288
|
-
| rule | [`non-destructive-by-default`](../.agent-src/rules/non-destructive-by-default.md) | always |
|
|
289
|
+
| rule | [`non-destructive-by-default`](../.agent-src/rules/non-destructive-by-default.md) | always | Hard Floor: agent asks before prod-trunk commits/merges, deploys, pushes, prod data/infra, bulk deletions/infra commits; verify branch before each commit; no autonomy or roadmap bypass |
|
|
289
290
|
| rule | [`onboarding-gate`](../.agent-src/rules/onboarding-gate.md) | auto | First turn — if onboarding.onboarded is false in .agent-settings.yml, instruct dev to run `agent-config setup` before any request |
|
|
290
291
|
| rule | [`package-ci-checks`](../.agent-src/rules/package-ci-checks.md) | manual | Before pushing to remote or creating a PR in the agent-config package — run all CI checks locally first |
|
|
291
292
|
| rule | [`persona-governance`](../.agent-src/rules/persona-governance.md) | auto | Creating/editing/proposing personas — enforce per-domain cap (≤ 2 specialists), ≥ 1 skill citation, deprecation path |
|
|
@@ -317,7 +318,7 @@ are excluded.
|
|
|
317
318
|
| rule | [`user-interrupt-priority`](../.agent-src/rules/user-interrupt-priority.md) | always | User interrupts override the current task — STOP, complete new task in full, then ASK before resuming; never silently return to prior work |
|
|
318
319
|
| rule | [`verify-before-complete`](../.agent-src/rules/verify-before-complete.md) | always | Verify before completion — run tests and quality tools before claiming done |
|
|
319
320
|
|
|
320
|
-
## Commands (
|
|
321
|
+
## Commands (146)
|
|
321
322
|
|
|
322
323
|
| kind | name | cluster | description |
|
|
323
324
|
|---|---|---|---|
|
|
@@ -428,6 +429,7 @@ are excluded.
|
|
|
428
429
|
| command | [`post-as`](../.agent-src/commands/post-as.md) | cluster: post-as | Consumer-facing write entry points — :me drafts in the maintainer's own voice from .agent-user.md (no disclosure); :ghostwriter is a thin alias for /ghostwriter:write (mandatory disclosure footer). |
|
|
429
430
|
| command | [`post-as:ghostwriter`](../.agent-src/commands/post-as/ghostwriter.md) | cluster: post-as | Thin alias for /ghostwriter:write — drafts a copyable markdown post in a captured public-figure voice with the mandatory non-removable disclosure footer. |
|
|
430
431
|
| command | [`post-as:me`](../.agent-src/commands/post-as/me.md) | cluster: post-as | Draft a copyable markdown post in the maintainer's own voice (style source = .agent-user.md.voice_sample). No disclosure footer — the user is the author. |
|
|
432
|
+
| command | [`prediction-pool`](../.agent-src/commands/prediction-pool.md) | | Fill a prediction pool (kicktipp, football/basketball WM): optimize expected points under the rules, enter tips via Playwright. Triggers 'Tippspiel', 'kicktipp', 'predict the pool'. |
|
|
431
433
|
| command | [`prepare-for-review`](../.agent-src/commands/prepare-for-review.md) | | Prepare a PR branch for local review — updates main and merges the full branch chain so the branch is up to date |
|
|
432
434
|
| command | [`project-analyze`](../.agent-src/commands/project-analyze.md) | | Full project analysis — detect stack, inventory modules, audit docs, create missing contexts |
|
|
433
435
|
| command | [`project-health`](../.agent-src/commands/project-health.md) | | Quick project health check — show status of docs, modules, contexts, and roadmaps without creating anything |
|
|
@@ -445,7 +447,7 @@ are excluded.
|
|
|
445
447
|
| command | [`roadmap:process-phase`](../.agent-src/commands/roadmap/process-phase.md) | cluster: roadmap | Autonomously process every open step in the next or current phase of a roadmap, then stop. Default execution scope of the /roadmap cluster. |
|
|
446
448
|
| command | [`roadmap:process-step`](../.agent-src/commands/roadmap/process-step.md) | cluster: roadmap | Autonomously process the single next open step of a roadmap and stop. Smallest execution scope of the /roadmap cluster — one step in, one step out. |
|
|
447
449
|
| command | [`rule-compliance-audit`](../.agent-src/commands/rule-compliance-audit.md) | | Audit rule trigger quality, simulate activation, detect overlaps, and find never-activating rules |
|
|
448
|
-
| command | [`set-cost-profile`](../.agent-src/commands/set-cost-profile.md) | | Change the
|
|
450
|
+
| command | [`set-cost-profile`](../.agent-src/commands/set-cost-profile.md) | | Change the rule_loading_tier in .agent-settings.yml — shows each profile's meaning and applies the selection |
|
|
449
451
|
| command | [`skill`](../.agent-src/commands/skill.md) | cluster: skill | Single-skill orchestrator — routes to preview. Non-destructive "what will this skill do?" before you run it. |
|
|
450
452
|
| command | [`skill:preview`](../.agent-src/commands/skill/preview.md) | cluster: skill | Non-destructive preview of a skill — its declared steps, execution type, allowed tools, and file/command targets — before you run it. Read-only, no execution. |
|
|
451
453
|
| command | [`skills`](../.agent-src/commands/skills.md) | cluster: skills | Skill discovery orchestrator — routes to discover. Local, explained skill recommendations over the catalog + role shortlists + optional local analytics. |
|
|
@@ -38,7 +38,7 @@ stability: stable
|
|
|
38
38
|
- README "Quickstart" block — install → `/onboard` → `/work "first
|
|
39
39
|
real task"`, contributor detail moved below the `## For contributors`
|
|
40
40
|
fold.
|
|
41
|
-
- Default `
|
|
41
|
+
- Default `rule_loading_tier` flipped from `minimal` to `balanced`;
|
|
42
42
|
rationale in [`cost-profile-defaults.md`](cost-profile-defaults.md).
|
|
43
43
|
- `/onboard` step 11 prints the Quickstart command list inline.
|
|
44
44
|
- CI gate: `task smoke-quickstart` runs the installer into a tmpdir
|
|
@@ -10,7 +10,7 @@ keep-beta-until: 2026-08-14
|
|
|
10
10
|
> Schema and semantics for the **Config Preset** axis introduced in
|
|
11
11
|
> step-15 Phase 1 item 4. Records the **Cost Enforcement** model
|
|
12
12
|
> (Council v3 action #3 prerequisite) so the preset loader can ship.
|
|
13
|
-
> Boundary against `profile.id`, `pack.id`, and `
|
|
13
|
+
> Boundary against `profile.id`, `pack.id`, and `rule_loading_tier`:
|
|
14
14
|
> [`ADR-010`](../decisions/ADR-010-profile-pack-preset-boundary.md).
|
|
15
15
|
|
|
16
16
|
## Decision
|
|
@@ -136,7 +136,7 @@ no other axis may write preset-owned knobs.
|
|
|
136
136
|
|
|
137
137
|
## Non-goals
|
|
138
138
|
|
|
139
|
-
- This contract does **not** define profiles, packs, or `
|
|
139
|
+
- This contract does **not** define profiles, packs, or `rule_loading_tier`.
|
|
140
140
|
See the corresponding contracts.
|
|
141
141
|
- It does **not** ship a UI. CLI-first (`agent-config cost`,
|
|
142
142
|
`agent-config preset set <id>`).
|
|
@@ -7,9 +7,9 @@ keep-beta-until: 2026-08-13
|
|
|
7
7
|
|
|
8
8
|
> **Status:** beta · **Owner:** package maintainer · **Last reviewed:** 2026-05-14
|
|
9
9
|
>
|
|
10
|
-
> Normative contract for the **default `
|
|
10
|
+
> Normative contract for the **default `rule_loading_tier`** new installs receive.
|
|
11
11
|
> Profile semantics themselves are documented in
|
|
12
|
-
> [`docs/customization.md` §
|
|
12
|
+
> [`docs/customization.md` § rule_loading_tier](../customization.md) and
|
|
13
13
|
> [`docs/contracts/rule-router.md`](rule-router.md); this file owns only the
|
|
14
14
|
> **default-selection decision** and the rationale behind it.
|
|
15
15
|
|
|
@@ -20,7 +20,7 @@ DEFAULT_PROFILE = "balanced"
|
|
|
20
20
|
```
|
|
21
21
|
|
|
22
22
|
`scripts/install.py` and `npx @event4u/agent-config init` write
|
|
23
|
-
`
|
|
23
|
+
`rule_loading_tier: balanced` into `.agent-settings.yml` for fresh installs
|
|
24
24
|
unless the user passes `--profile=minimal` or `--profile=full`.
|
|
25
25
|
|
|
26
26
|
## Profile table
|
|
@@ -64,7 +64,7 @@ at `balanced`:
|
|
|
64
64
|
Token-budget pressure → flip in `.agent-settings.yml`:
|
|
65
65
|
|
|
66
66
|
```yaml
|
|
67
|
-
|
|
67
|
+
rule_loading_tier: minimal
|
|
68
68
|
```
|
|
69
69
|
|
|
70
70
|
…or pass `--profile=minimal` to `npx @event4u/agent-config init`.
|
|
@@ -77,7 +77,7 @@ CI must keep three surfaces in sync:
|
|
|
77
77
|
|
|
78
78
|
- `scripts/install.py` — `DEFAULT_PROFILE` constant.
|
|
79
79
|
- `config/agent-settings.template.yml` — comment block on the
|
|
80
|
-
`
|
|
80
|
+
`rule_loading_tier:` key.
|
|
81
81
|
- `docs/customization.md` — cost-profile table default column.
|
|
82
82
|
|
|
83
83
|
Reviewer guidance: a PR that changes any one of these must touch the
|
|
@@ -64,7 +64,7 @@
|
|
|
64
64
|
"product-basic", "product-discovery",
|
|
65
65
|
"finance-basic", "finance-advanced",
|
|
66
66
|
"gtm-sales", "gtm-marketing",
|
|
67
|
-
"ops-people", "founder-strategy", "small-business", "construction", "ai-video", "meta"
|
|
67
|
+
"ops-people", "founder-strategy", "small-business", "construction", "ai-video", "fun", "meta"
|
|
68
68
|
]
|
|
69
69
|
},
|
|
70
70
|
"lifecycle": {
|
|
@@ -42,13 +42,13 @@
|
|
|
42
42
|
},
|
|
43
43
|
"inputs": {
|
|
44
44
|
"type": ["object", "null"],
|
|
45
|
-
"description": "Profile / preset /
|
|
46
|
-
"required": ["profile", "preset", "
|
|
45
|
+
"description": "Profile / preset / rule_loading_tier resolution chain. Null when the loader could not resolve any of them (broken settings).",
|
|
46
|
+
"required": ["profile", "preset", "rule_loading_tier", "source_per_knob"],
|
|
47
47
|
"additionalProperties": false,
|
|
48
48
|
"properties": {
|
|
49
49
|
"profile": {"type": ["string", "null"]},
|
|
50
50
|
"preset": {"type": ["string", "null"]},
|
|
51
|
-
"
|
|
51
|
+
"rule_loading_tier": {"type": ["string", "null"]},
|
|
52
52
|
"source_per_knob": {
|
|
53
53
|
"type": "object",
|
|
54
54
|
"description": "Map<knob, source>; source ∈ pack | profile | preset | user | env | runtime | default.",
|
|
@@ -88,14 +88,22 @@ counts and ids for downstream metrics.
|
|
|
88
88
|
|
|
89
89
|
## Cadence interaction
|
|
90
90
|
|
|
91
|
-
|
|
|
91
|
+
| `memory.cadence` | Visibility line |
|
|
92
92
|
|---|---|
|
|
93
|
-
| `
|
|
94
|
-
| `
|
|
95
|
-
| `
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
93
|
+
| `auto` | suppress unless `asks ≥ 3` |
|
|
94
|
+
| `always` | always when `asks ≥ 1` |
|
|
95
|
+
| `never` | suppress entirely |
|
|
96
|
+
|
|
97
|
+
Cadence lookup respects `.agent-settings.yml`'s `memory.cadence` key.
|
|
98
|
+
Default is `always`. The legacy `memory.visibility: off` master switch
|
|
99
|
+
(above) still wins over any `memory.cadence` value.
|
|
100
|
+
|
|
101
|
+
> **History.** Before the 2026-06-01 `cost_profile` untangle this
|
|
102
|
+
> cadence was keyed off `cost_profile` with the values
|
|
103
|
+
> `lean | standard | verbose` — a collision with the rule-loading
|
|
104
|
+
> `cost_profile` (`minimal | balanced | full`) that made the `lean`
|
|
105
|
+
> branch unreachable on every real install. The cadence now owns its
|
|
106
|
+
> own `memory.cadence` key.
|
|
99
107
|
|
|
100
108
|
## End-of-run "Memory changed decisions" block
|
|
101
109
|
|
|
@@ -11,7 +11,7 @@ keep-beta-until: 2026-08-14
|
|
|
11
11
|
> Phase 1 item 1. Profile answers *who is the user?* — audience
|
|
12
12
|
> taxonomy that selects the default skill/command surface, README
|
|
13
13
|
> entry-paragraph, and persona pre-selection. Boundary against
|
|
14
|
-
> `preset.id`, `pack.id`, and `
|
|
14
|
+
> `preset.id`, `pack.id`, and `rule_loading_tier`:
|
|
15
15
|
> [`ADR-010`](../decisions/ADR-010-profile-pack-preset-boundary.md).
|
|
16
16
|
|
|
17
17
|
## Decision
|
|
@@ -128,7 +128,7 @@ Only changes to the **seed set** require an ADR.
|
|
|
128
128
|
- This contract does **not** define preset knobs. See
|
|
129
129
|
[`config-presets.md`](config-presets.md).
|
|
130
130
|
- It does **not** define packs. See `workflow-packs.md` (Phase 2 item 7).
|
|
131
|
-
- It does **not** override `
|
|
131
|
+
- It does **not** override `rule_loading_tier`. The rule-tier loader keeps
|
|
132
132
|
its independent axis per
|
|
133
133
|
[`cost-profile-defaults.md`](cost-profile-defaults.md).
|
|
134
134
|
- It does **not** ship a UI. Profile selection happens in `/onboard`
|
|
@@ -58,7 +58,7 @@ defaults (config/agent-settings.template.yml)
|
|
|
58
58
|
< project (<projectRoot>/settings/.agent-settings.yml, optional)
|
|
59
59
|
```
|
|
60
60
|
|
|
61
|
-
Defaults come from the package template with `
|
|
61
|
+
Defaults come from the package template with `__RULE_LOADING_TIER__` /
|
|
62
62
|
`__USER_TYPE__` placeholders substituted for their permissive defaults
|
|
63
63
|
(`balanced` / `""`). Global and project layers are read with the typed
|
|
64
64
|
subdir preferred over the legacy flat path. The route mirrors
|
|
@@ -69,7 +69,7 @@ Response (200):
|
|
|
69
69
|
|
|
70
70
|
```json
|
|
71
71
|
{
|
|
72
|
-
"values": { "
|
|
72
|
+
"values": { "rule_loading_tier": "balanced", "...": "..." },
|
|
73
73
|
"lastModified": 1747749791842,
|
|
74
74
|
"path": "settings/.agent-settings.yml",
|
|
75
75
|
"legacyHints": { "user_name": "Matze" }
|
|
@@ -106,7 +106,7 @@ changes** modal. Request:
|
|
|
106
106
|
}
|
|
107
107
|
```
|
|
108
108
|
|
|
109
|
-
Response (200): `{ "changes": [{ "path": "
|
|
109
|
+
Response (200): `{ "changes": [{ "path": "rule_loading_tier", "from": "minimal", "to": "balanced" }, ...] }`.
|
|
110
110
|
|
|
111
111
|
Errors: **409** on mtime drift; **422** on validation failure (`fields`
|
|
112
112
|
populated).
|
|
@@ -49,9 +49,13 @@ cost_ladder:
|
|
|
49
49
|
token_delta: <signed int> # per-request input token delta
|
|
50
50
|
eur_delta: <float> # priced at reference_scale
|
|
51
51
|
cumulative_pct: <signed float> # % of baseline.input_tokens_per_request
|
|
52
|
-
confidence: measured | estimated | vendor-claim | pending
|
|
52
|
+
confidence: measured | estimated | vendor-claim | pending | available
|
|
53
53
|
source_report: <relative path> # raw report this was derived from
|
|
54
54
|
footnote: "<optional caveat>" # e.g. "Thin-Root files excluded"
|
|
55
|
+
- id: thin
|
|
56
|
+
... # the thin-projection lever; ships behind
|
|
57
|
+
... # the lean_projection.mode kill-switch
|
|
58
|
+
... # (default eager-all) → confidence: available
|
|
55
59
|
- id: condense
|
|
56
60
|
...
|
|
57
61
|
- id: rtk
|
|
@@ -127,6 +131,15 @@ the cumulative (its raw value is the renderer's best guess from the
|
|
|
127
131
|
raw report; it MUST NOT influence the headline until it flips to
|
|
128
132
|
`measured`).
|
|
129
133
|
|
|
134
|
+
A rung with `confidence: available` is **measured** but ships behind a
|
|
135
|
+
default-off kill-switch (e.g. the `thin` rung gated on
|
|
136
|
+
`lean_projection.mode`, default `eager-all`). Its measured `token_delta`
|
|
137
|
+
is displayed, but — like `pending` — it contributes `0` to the default
|
|
138
|
+
cumulative / NETTO: the headline reflects what actually ships by default,
|
|
139
|
+
not the best achievable after an opt-in flip. The footnote states the
|
|
140
|
+
would-be total and the validation state. Only `measured`, `estimated`,
|
|
141
|
+
and `vendor-claim` rungs count toward the cumulative.
|
|
142
|
+
|
|
130
143
|
## Markdown shape (informational human dump)
|
|
131
144
|
|
|
132
145
|
The `.md` sibling of every `value-v1.json` is informational — a
|
package/docs/customization.md
CHANGED
|
@@ -63,7 +63,7 @@ mergeable from the user-global file; every other key is silently ignored:
|
|
|
63
63
|
```
|
|
64
64
|
name
|
|
65
65
|
ide
|
|
66
|
-
|
|
66
|
+
rule_loading_tier
|
|
67
67
|
personal.bot_icon
|
|
68
68
|
personal.autonomy
|
|
69
69
|
telegraph.speak_scope
|
|
@@ -95,7 +95,7 @@ user-global layer. Non-root in-project layers (intermediate +
|
|
|
95
95
|
``<CWD>``) carry arbitrary keys — they live inside the project
|
|
96
96
|
boundary, are tracked in git, and reviewed in PRs like any other
|
|
97
97
|
config. Use a subdirectory `.agent-settings.yml` to scope a single
|
|
98
|
-
field (e.g. a `
|
|
98
|
+
field (e.g. a `rule_loading_tier` override for `services/heavy-ml/`) without
|
|
99
99
|
duplicating the root file.
|
|
100
100
|
|
|
101
101
|
The user-global file is created **only on explicit opt-in via the
|
|
@@ -169,7 +169,7 @@ is recovered on the next server boot.
|
|
|
169
169
|
| Setting | Default | Description |
|
|
170
170
|
|---|---|---|
|
|
171
171
|
| `agent_config_version` | *(empty)* | Exact semver pin of the agent-config release (see above). Empty = unpinned. |
|
|
172
|
-
| `
|
|
172
|
+
| `rule_loading_tier` | `balanced` | Token budget (`minimal`, `balanced`, `full`, `custom`) — rationale: [`docs/contracts/cost-profile-defaults.md`](contracts/cost-profile-defaults.md) |
|
|
173
173
|
| `personal.user_name` | *(empty)* | User's first name for personalized responses |
|
|
174
174
|
| `personal.minimal_output` | `true` | Suppress intermediate output |
|
|
175
175
|
| `personal.play_by_play` | `false` | Share intermediate findings during analysis |
|
|
@@ -202,7 +202,23 @@ if the key file's permissions drift.
|
|
|
202
202
|
|
|
203
203
|
### Cost profiles
|
|
204
204
|
|
|
205
|
-
|
|
205
|
+
> **Four "cost" concepts — don't confuse them.** Several settings sound like
|
|
206
|
+
> they steer spend; only one is the rule-loading footprint:
|
|
207
|
+
>
|
|
208
|
+
> | Concept | What it controls | What it's a lever for |
|
|
209
|
+
> |---|---|---|
|
|
210
|
+
> | `rule_loading_tier` *(this setting)* | How many behavioural rule tiers load each session | Token footprint of the rule layer (small, ~once per session) |
|
|
211
|
+
> | `memory.cadence` | Whether the `🧠 Memory: …` visibility line renders (`auto`/`always`/`never`) | Output noise — **not** spend |
|
|
212
|
+
> | `model.auto_switch` + a skill's `model_tier` | Which Claude model runs a skill (lite/medium/high → haiku/sonnet/opus) | The **dominant** per-turn spend lever (~10× delta) |
|
|
213
|
+
> | `/cost:report` + `cost.budgets` | Tracking actual token/USD spend + optional ceilings | Budget enforcement |
|
|
214
|
+
>
|
|
215
|
+
> Before the 2026-06-01 untangle, `rule_loading_tier` was named `cost_profile`
|
|
216
|
+
> **and** the same key also carried the `memory.cadence` values — one key, two
|
|
217
|
+
> colliding meanings. The rename split them so each lever owns its name. When
|
|
218
|
+
> a budget is tight, reach for the **model** lever first — lowering the rule
|
|
219
|
+
> tier saves little and drops guardrails.
|
|
220
|
+
|
|
221
|
+
`rule_loading_tier` is the master switch for rule-tier loading. The kernel
|
|
206
222
|
(always-loaded Iron-Law floor, ≤ 26k chars across 9 rules) ships in every
|
|
207
223
|
profile. Tier-1 and tier-2 rules are gated by profile and resolved at
|
|
208
224
|
session start from `dist/router.json` (compiled by `scripts/compile_router.py`).
|
|
@@ -497,7 +513,7 @@ Sample Markdown output:
|
|
|
497
513
|
- [x] api-rate-limit-is-100rpm — accepted in step `refine`
|
|
498
514
|
```
|
|
499
515
|
|
|
500
|
-
Disable for `
|
|
516
|
+
Disable for `rule_loading_tier: minimal` CI runs by setting `explain.enable_last: false`
|
|
501
517
|
in `.agent-settings.yml`; the command then exits 0 with a one-line
|
|
502
518
|
notice instead of producing a trace. Exit codes: `0` rendered or
|
|
503
519
|
disabled · `1` no recent run found · `2` invocation error.
|
|
@@ -34,7 +34,7 @@ Step-15 introduces three new configuration concepts:
|
|
|
34
34
|
|
|
35
35
|
A pre-existing fourth concept is in play:
|
|
36
36
|
|
|
37
|
-
- **`
|
|
37
|
+
- **`rule_loading_tier`** — current setting in `.agent-settings.yml`, values
|
|
38
38
|
`minimal` / `balanced` / `full` / `custom`. Owns **rule-tier loading**
|
|
39
39
|
(kernel · kernel + tier-1 · kernel + tier-1 + tier-2). Contract:
|
|
40
40
|
[`docs/contracts/cost-profile-defaults.md`](../contracts/cost-profile-defaults.md).
|
|
@@ -42,7 +42,7 @@ A pre-existing fourth concept is in play:
|
|
|
42
42
|
Without a written boundary, three failure modes are predictable:
|
|
43
43
|
|
|
44
44
|
1. The preset loader re-implements rule-tier gating (overlap with
|
|
45
|
-
`
|
|
45
|
+
`rule_loading_tier`).
|
|
46
46
|
2. Packs ship duplicate `profile` + `preset` defaults that drift from
|
|
47
47
|
the canonical source.
|
|
48
48
|
3. Three teams add knobs to three places, and a user picking
|
|
@@ -58,22 +58,22 @@ Four orthogonal axes, four owners, one resolution chain.
|
|
|
58
58
|
| **Profile** | *Who is the user?* (audience taxonomy) | Default skill/command surface; README entry-paragraph; persona pre-selection | `profile.id` |
|
|
59
59
|
| **Preset** | *How cautious is this run?* (risk + cost + autonomy budget) | The 12+ governance knobs (per-call $ ceiling, confidence band, block-on-risk, autonomy default, council escalation, …) | `preset.id` |
|
|
60
60
|
| **Pack** | *What bundle of skills + commands?* (workflow recipe) | A frozen `(profile, preset, allow_skills, allow_commands)` 4-tuple; nothing more | `pack.id` |
|
|
61
|
-
| **Cost Profile** | *How many rules load?* (token budget) | Rule-tier loading at session start (kernel · +tier-1 · +tier-2) | `
|
|
61
|
+
| **Cost Profile** | *How many rules load?* (token budget) | Rule-tier loading at session start (kernel · +tier-1 · +tier-2) | `rule_loading_tier` |
|
|
62
62
|
|
|
63
63
|
### Resolution chain (read order, last writer wins)
|
|
64
64
|
|
|
65
65
|
```
|
|
66
|
-
pack → profile → preset →
|
|
66
|
+
pack → profile → preset → rule_loading_tier → user/env/runtime overrides
|
|
67
67
|
```
|
|
68
68
|
|
|
69
69
|
- A **pack** declares defaults for `profile`, `preset`, and the
|
|
70
|
-
skill / command allowlists. It cannot set `
|
|
70
|
+
skill / command allowlists. It cannot set `rule_loading_tier` (that
|
|
71
71
|
axis belongs to the rule-tier loader and is governed separately).
|
|
72
72
|
- A **profile** declares defaults for `preset`, audience-specific
|
|
73
73
|
README pointer, persona pre-selection. It cannot set any preset
|
|
74
74
|
knob directly — only `preset.id`.
|
|
75
75
|
- A **preset** owns the 12+ knobs. No other axis writes them.
|
|
76
|
-
- A **
|
|
76
|
+
- A **rule_loading_tier** owns rule-tier loading. No other axis writes it.
|
|
77
77
|
- The user's `.agent-settings.yml`, environment variables, and
|
|
78
78
|
runtime CLI flags override every axis above them.
|
|
79
79
|
|
|
@@ -86,7 +86,7 @@ DUPLICATION ACROSS AXES IS A CONTRACT VIOLATION.
|
|
|
86
86
|
|
|
87
87
|
- A pack **may not** override a preset knob; it overrides `preset.id`.
|
|
88
88
|
- A profile **may not** override a preset knob; it overrides `preset.id`.
|
|
89
|
-
- A preset **may not** override `
|
|
89
|
+
- A preset **may not** override `rule_loading_tier`; the user does that.
|
|
90
90
|
- The CI `task lint-config-schema` (added in Phase 1) hard-fails on a
|
|
91
91
|
pack/profile YAML that names any preset-owned knob.
|
|
92
92
|
|
|
@@ -101,15 +101,15 @@ DUPLICATION ACROSS AXES IS A CONTRACT VIOLATION.
|
|
|
101
101
|
has a single home.
|
|
102
102
|
- Phase 2 item 7 (Workflow Packs) is a 4-tuple, not a re-implementation
|
|
103
103
|
of profile + preset. Pack YAML stays under 30 lines.
|
|
104
|
-
- `
|
|
104
|
+
- `rule_loading_tier` keeps its single-axis charter; this ADR explicitly
|
|
105
105
|
refuses to fold it into the preset layer.
|
|
106
106
|
|
|
107
107
|
### Negative
|
|
108
108
|
|
|
109
109
|
- One more concept on the install screen (`profile` + `preset` + `pack`
|
|
110
|
-
+ `
|
|
110
|
+
+ `rule_loading_tier` = four axes). Mitigated by: the wizard (Phase 1 item
|
|
111
111
|
2) only asks for **profile** + **stack** + **risk appetite** and
|
|
112
|
-
derives the rest. Packs are opt-in; `
|
|
112
|
+
derives the rest. Packs are opt-in; `rule_loading_tier` keeps its
|
|
113
113
|
`balanced` default.
|
|
114
114
|
- A skill-allowlist conflict between a pack and a runtime CLI flag is
|
|
115
115
|
resolved by "runtime wins". Users on a pack who shadow-disable a
|
|
@@ -127,6 +127,6 @@ DUPLICATION ACROSS AXES IS A CONTRACT VIOLATION.
|
|
|
127
127
|
|
|
128
128
|
## See also
|
|
129
129
|
|
|
130
|
-
- [`docs/contracts/cost-profile-defaults.md`](../contracts/cost-profile-defaults.md) — the existing `
|
|
130
|
+
- [`docs/contracts/cost-profile-defaults.md`](../contracts/cost-profile-defaults.md) — the existing `rule_loading_tier` contract this ADR explicitly does **not** touch.
|
|
131
131
|
- [`agents/roadmaps/step-15-product-refinement.md`](../../agents/roadmaps/step-15-product-refinement.md) — Phase 1 items 1, 4 and Phase 2 item 7.
|
|
132
132
|
- [`agents/runtime/council/responses/2026-05-16-step-15-product-refinement-v3.json`](../../agents/runtime/council/responses/2026-05-16-step-15-product-refinement-v3.json) — Council v3 action #2 (origin). <!-- council-ref-allowed: ADR decision-trace to originating council response -->
|
|
@@ -34,7 +34,7 @@ truth. The scan emits a single `dist/discovery/discovery-manifest.json`
|
|
|
34
34
|
shipped inside the npm tarball; every downstream surface reads from that
|
|
35
35
|
file and from nothing else. This ADR locks the **frontmatter shape**, the
|
|
36
36
|
**closed vocabularies**, and the **non-overlap rule** that keeps the new
|
|
37
|
-
keys from colliding with the existing `
|
|
37
|
+
keys from colliding with the existing `rule_loading_tier` / `profile.id` axes
|
|
38
38
|
(ADR-010).
|
|
39
39
|
|
|
40
40
|
### Why a closed vocabulary
|
|
@@ -121,6 +121,7 @@ Amendments to the workspace list require an ADR-013 amendment.
|
|
|
121
121
|
| `small-business` | SMB-shaped owner workflows. |
|
|
122
122
|
| `construction` | Trade-business workflows. |
|
|
123
123
|
| `ai-video` | AI video pipeline (per ADR-011, the only heavyweight domain). |
|
|
124
|
+
| `fun` | Non-essential social/fun workflows (prediction-pool tips, etc.). Optional under the `small-business` workspace; `experimental` trust. |
|
|
124
125
|
| `meta` | Artefacts that maintain *this* package (`agent-config` itself). |
|
|
125
126
|
|
|
126
127
|
Amendments to the pack list require an ADR-013 amendment and the
|
|
@@ -128,7 +129,7 @@ matching `config/discovery/packs.yml` row in the same PR.
|
|
|
128
129
|
|
|
129
130
|
### Non-overlap rule (ADR-010 alignment)
|
|
130
131
|
|
|
131
|
-
- `
|
|
132
|
+
- `rule_loading_tier` values (`minimal`, `balanced`, `full`, `custom`) are
|
|
132
133
|
**not** pack ids. The scanner hard-fails on overlap.
|
|
133
134
|
- `profile.id` values (`founder`, `developer`, `content_creator`,
|
|
134
135
|
`agency`, `finance`, `ops`) are **not** pack ids. The scanner
|
|
@@ -246,6 +247,19 @@ allowed by [`discovery-manifest.schema.json`](../contracts/discovery-manifest.sc
|
|
|
246
247
|
Additive, no vocabulary rename. (Same change cleaned the `finance` label from
|
|
247
248
|
"Finance / CFO" to "Finance".)
|
|
248
249
|
|
|
250
|
+
### 2026-06-01 — New `fun` pack
|
|
251
|
+
|
|
252
|
+
Added pack id `fun` to the closed vocabulary (Non-essential social/fun
|
|
253
|
+
workflows — prediction-pool tip optimization, etc.). Mirrored in
|
|
254
|
+
[`config/discovery/packs.yml`](../../config/discovery/packs.yml) and the
|
|
255
|
+
`ADR_PACKS` frozenset in
|
|
256
|
+
[`scripts/lint_discovery_vocabulary.py`](../../scripts/lint_discovery_vocabulary.py).
|
|
257
|
+
Optional under the `small-business` workspace (alongside `ai-video`);
|
|
258
|
+
`trust_level_default: experimental`, `install.default: false`. First
|
|
259
|
+
artefacts: the `/prediction-pool` command + `prediction-pool-optimizer` skill in
|
|
260
|
+
`packages/pack-fun/`. Additive, no rename; non-overlap with cost-profile
|
|
261
|
+
and `profile.id` reservations holds.
|
|
262
|
+
|
|
249
263
|
## Cross-references
|
|
250
264
|
|
|
251
265
|
- [ADR-007 — Agent Discovery Scopes](ADR-007-agent-discovery-scopes.md):
|
|
@@ -23,7 +23,7 @@ review_date: 2026-08-30
|
|
|
23
23
|
|
|
24
24
|
## Context
|
|
25
25
|
|
|
26
|
-
`model-recommendation` (tier-2a, `core`) is a dead shell — it routes to `command:set-cost-profile`, which flips `
|
|
26
|
+
`model-recommendation` (tier-2a, `core`) is a dead shell — it routes to `command:set-cost-profile`, which flips `rule_loading_tier` but never selects a model. The task→model intelligence already exists in `contexts/model-recommendations.md` but has no mechanism to act. Claude Code now honours a native skill `model:` frontmatter key — verified against the official skills docs (`code.claude.com/docs/en/skills.md`): the override applies for the rest of the current turn, reverts to the session model on the next prompt, and accepts the `/model` values plus `inherit`. That makes per-skill model selection structural on Claude; Augment has no per-turn override, so a rule surfaces a one-question suggestion there.
|
|
27
27
|
|
|
28
28
|
The projection constraint: source `SKILL.md` is shared across tools via `.agent-src/`. `.claude/skills/<name>` is a whole-**directory symlink** to `.agent-src/skills/<name>`; `.claude/skills/<slug>/SKILL.md` for commands is a **symlink** inside a real dir. Augment skills symlink the same target. A Claude-only native `model:` therefore cannot live in the shared symlink target without also appearing in Augment.
|
|
29
29
|
|
|
@@ -0,0 +1,106 @@
|
|
|
1
|
+
---
|
|
2
|
+
adr: 036
|
|
3
|
+
status: accepted
|
|
4
|
+
date: 2026-06-01
|
|
5
|
+
decision: global-install-browser-wizard-handoff
|
|
6
|
+
supersedes: —
|
|
7
|
+
superseded_by: —
|
|
8
|
+
phase: v5.x · install-UX consistency
|
|
9
|
+
type: forward-looking
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
# ADR-036 — Global install hands off to the browser wizard (zero terminal prompts)
|
|
13
|
+
|
|
14
|
+
## Status
|
|
15
|
+
|
|
16
|
+
**Accepted** · 2026-06-01. Implements the install-UX half of
|
|
17
|
+
[`road-to-self-update-and-global-hook-resolution`](../../agents/roadmaps/road-to-self-update-and-global-hook-resolution.md)
|
|
18
|
+
(Phase 6). Builds on [`ADR-020`](ADR-020-global-only-consumer-scope.md)
|
|
19
|
+
(global-only consumer scope) and reuses the wizard contract from
|
|
20
|
+
[`gui-wizard`](../contracts/gui-wizard.md).
|
|
21
|
+
|
|
22
|
+
## Context
|
|
23
|
+
|
|
24
|
+
`npx @event4u/agent-config init` is the canonical first-time install
|
|
25
|
+
(README Quickstart) and `agent-config upgrade` is the self-update path
|
|
26
|
+
(ADR-020 update-lag fix). Both reach the global install through
|
|
27
|
+
`scripts/install --global` → `install.py` `install_global()`. Field use
|
|
28
|
+
surfaced four defects that made the global path drop into terminal
|
|
29
|
+
interaction instead of the browser wizard the project path already used:
|
|
30
|
+
|
|
31
|
+
1. **Terminal tool-picker.** `scripts/install`'s `prompt_tools()` fired
|
|
32
|
+
on every interactive run, pre-empting the wizard and — via
|
|
33
|
+
`TOOLS_EXPLICIT` — suppressing it (`_wizard_should_launch` treats an
|
|
34
|
+
explicit `--tools=` as "headless").
|
|
35
|
+
2. **No wizard on `--global`.** `install_global()` returned before the
|
|
36
|
+
`_wizard_should_launch` / `_wizard_spawn` block; only the project
|
|
37
|
+
path launched the GUI.
|
|
38
|
+
3. **Browser never opened.** `_wizard_await_ready` **printed** the
|
|
39
|
+
`WIZARD_READY` URL but never opened it (the child is spawned with
|
|
40
|
+
`--no-open` so the Python parent owns the open — it only printed).
|
|
41
|
+
4. **Wrong identity + ADR-020 leak.** Spawning the wizard with
|
|
42
|
+
`--project-root <detect_root>` forced project write-root, so the
|
|
43
|
+
wizard read neither nor wrote the **global**
|
|
44
|
+
`~/.event4u/agent-config/settings/.agent-user.yml` (the saved
|
|
45
|
+
identity → name/language pre-fill defaulted to the OS account, e.g.
|
|
46
|
+
`mathiasberg`, instead of the saved `Matze`/`de`), and global content
|
|
47
|
+
would land in the project tree — an ADR-020 violation.
|
|
48
|
+
|
|
49
|
+
## Decision
|
|
50
|
+
|
|
51
|
+
On the interactive global-install path (`agent-config init` / `global` /
|
|
52
|
+
`upgrade` / `refresh --global`), the install is **zero-terminal-interaction
|
|
53
|
+
and hands off to the browser wizard**:
|
|
54
|
+
|
|
55
|
+
- `scripts/install` skips `prompt_tools()` when the wizard will launch
|
|
56
|
+
(TTY · not `CI` · not `AGENT_CONFIG_NO_UI`) — the wizard is the single
|
|
57
|
+
tool-selection surface.
|
|
58
|
+
- `install.py` launches the wizard after `install_global()` (parity with
|
|
59
|
+
the project path), gated by the single source of truth
|
|
60
|
+
`_wizard_should_launch`.
|
|
61
|
+
- The wizard is spawned **without** `--project-root` so `resolveWriteRoot`
|
|
62
|
+
picks the **global** write root — the saved `.agent-user.yml` drives the
|
|
63
|
+
identity pre-fill, and no global content is written into the project
|
|
64
|
+
tree (reinforces ADR-020).
|
|
65
|
+
- `_wizard_await_ready` opens the browser (`webbrowser.open`) after
|
|
66
|
+
printing the URL; the printed URL remains the headless fallback.
|
|
67
|
+
- On the wizard-handoff path the run is non-interactive: foreign-file
|
|
68
|
+
conflicts auto-resolve to overwrite and the legacy migration runs
|
|
69
|
+
without the `[Y/n]` gate — no `--force`, no prompts. The wizard is the
|
|
70
|
+
settings + package surface that recreates fresh config.
|
|
71
|
+
|
|
72
|
+
The terminal picker, conflict prompt, and migrate prompt remain the
|
|
73
|
+
behaviour on **headless** paths (no TTY · `CI` · `--no-ui` ·
|
|
74
|
+
explicit `--tools=`), where no wizard launches.
|
|
75
|
+
|
|
76
|
+
## Consequences
|
|
77
|
+
|
|
78
|
+
**Positive.**
|
|
79
|
+
- "Run the command, it installs, then the wizard opens for packages +
|
|
80
|
+
settings" — the contract holds for `init` and `upgrade` alike.
|
|
81
|
+
- A returning user's name/language pre-fill from the saved identity, not
|
|
82
|
+
the OS account.
|
|
83
|
+
- Global content never leaks into the project tree on the wizard path.
|
|
84
|
+
|
|
85
|
+
**Negative / trade-offs.**
|
|
86
|
+
- Auto-overwrite + auto-migrate on the wizard path remove the per-file
|
|
87
|
+
confirmation. Scoped to the wizard-handoff path on paths agent-config
|
|
88
|
+
owns (ADR-020 global root); headless paths keep the prompts.
|
|
89
|
+
- The browser-open + zero-prompt flow cannot be asserted in headless CI;
|
|
90
|
+
the welcome-step identity pre-fill (`Matze`/`de` from the global
|
|
91
|
+
write root) is covered by a Playwright drive.
|
|
92
|
+
|
|
93
|
+
## Alternatives considered
|
|
94
|
+
|
|
95
|
+
- **`npx` fallback inside the PostToolUse hook.** Rejected by the
|
|
96
|
+
2026-05-30 council (per-tool-call network + version drift) and again
|
|
97
|
+
2026-06-01; orthogonal to install UX. Hooks resolve the global binary.
|
|
98
|
+
- **Keep the terminal prompts, document `--force`.** Rejected — the
|
|
99
|
+
maintainer's explicit contract is zero terminal interaction with a
|
|
100
|
+
browser handoff.
|
|
101
|
+
|
|
102
|
+
## References
|
|
103
|
+
|
|
104
|
+
- [`ADR-020`](ADR-020-global-only-consumer-scope.md) — global-only consumer scope.
|
|
105
|
+
- [`gui-wizard`](../contracts/gui-wizard.md) — wizard apply contract.
|
|
106
|
+
- [`road-to-self-update-and-global-hook-resolution`](../../agents/roadmaps/road-to-self-update-and-global-hook-resolution.md) — companion roadmap.
|