@event4u/agent-config 1.19.0 → 1.21.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/agent-handoff.md +14 -10
- package/.agent-src/commands/agents.md +1 -1
- package/.agent-src/commands/bug-fix.md +1 -1
- package/.agent-src/commands/bug-investigate.md +2 -2
- package/.agent-src/commands/chat-history/import.md +166 -0
- package/.agent-src/commands/chat-history/learn.md +178 -0
- package/.agent-src/commands/chat-history/show.md +17 -18
- package/.agent-src/commands/chat-history.md +26 -25
- package/.agent-src/commands/compress.md +12 -0
- package/.agent-src/commands/context/create.md +2 -2
- package/.agent-src/commands/context.md +1 -1
- package/.agent-src/commands/copilot-agents.md +1 -1
- package/.agent-src/commands/council/default.md +21 -12
- package/.agent-src/commands/council.md +1 -1
- package/.agent-src/commands/create-pr.md +28 -8
- package/.agent-src/commands/e2e-heal.md +1 -1
- package/.agent-src/commands/e2e-plan.md +1 -1
- package/.agent-src/commands/feature/dev.md +3 -3
- package/.agent-src/commands/feature.md +1 -1
- package/.agent-src/commands/fix/seeder.md +2 -2
- package/.agent-src/commands/fix.md +1 -1
- package/.agent-src/commands/jira-ticket.md +1 -1
- package/.agent-src/commands/judge.md +2 -2
- package/.agent-src/commands/memory.md +1 -1
- package/.agent-src/commands/mode.md +5 -5
- package/.agent-src/commands/module.md +1 -1
- package/.agent-src/commands/onboard.md +4 -4
- package/.agent-src/commands/optimize/augmentignore.md +1 -1
- package/.agent-src/commands/optimize-prompt.md +61 -0
- package/.agent-src/commands/optimize.md +1 -1
- package/.agent-src/commands/override.md +1 -1
- package/.agent-src/commands/review-changes.md +1 -1
- package/.agent-src/commands/review-routing.md +1 -1
- package/.agent-src/commands/roadmap.md +1 -1
- package/.agent-src/commands/set-cost-profile.md +3 -3
- package/.agent-src/commands/sync-agent-settings.md +2 -2
- package/.agent-src/commands/sync-gitignore.md +1 -1
- package/.agent-src/commands/tests/create.md +2 -2
- package/.agent-src/commands/tests.md +1 -1
- package/.agent-src/commands/threat-model.md +4 -4
- package/.agent-src/contexts/authority/commit-mechanics.md +14 -1
- package/.agent-src/contexts/authority/destructive-mechanics.md +14 -1
- package/.agent-src/contexts/authority/scope-mechanics.md +5 -0
- package/.agent-src/contexts/communication/rules-auto/guidelines-mechanics.md +76 -0
- package/.agent-src/contexts/communication/rules-auto/skill-quality-mechanics.md +76 -0
- package/.agent-src/contexts/communication/rules-auto/slash-command-routing-policy-mechanics.md +4 -4
- package/.agent-src/contexts/communication/rules-auto/think-before-action-mechanics.md +98 -0
- package/.agent-src/contexts/communication/rules-auto/token-efficiency-mechanics.md +93 -0
- package/.agent-src/contexts/communication/rules-auto/user-interaction-mechanics.md +125 -9
- package/.agent-src/contexts/execution/autonomy-mechanics.md +44 -0
- package/.agent-src/contexts/model-recommendations.md +2 -2
- package/.agent-src/contexts/override-system.md +1 -1
- package/.agent-src/personas/product-owner.md +2 -2
- package/.agent-src/personas/qa.md +1 -1
- package/.agent-src/rules/agent-authority.md +5 -6
- package/.agent-src/rules/agent-docs.md +11 -53
- package/.agent-src/rules/analysis-skill-routing.md +10 -40
- package/.agent-src/rules/architecture.md +6 -1
- package/.agent-src/rules/artifact-drafting-protocol.md +5 -0
- package/.agent-src/rules/artifact-engagement-recording.md +23 -59
- package/.agent-src/rules/ask-when-uncertain.md +24 -47
- package/.agent-src/rules/augment-portability.md +14 -62
- package/.agent-src/rules/augment-source-of-truth.md +10 -1
- package/.agent-src/rules/autonomous-execution.md +17 -98
- package/.agent-src/rules/capture-learnings.md +9 -80
- package/.agent-src/rules/cli-output-handling.md +12 -42
- package/.agent-src/rules/command-suggestion-policy.md +25 -73
- package/.agent-src/rules/commit-conventions.md +9 -58
- package/.agent-src/rules/commit-policy.md +16 -47
- package/.agent-src/rules/context-hygiene.md +5 -0
- package/.agent-src/rules/direct-answers.md +21 -42
- package/.agent-src/rules/docker-commands.md +11 -45
- package/.agent-src/rules/docs-sync.md +10 -56
- package/.agent-src/rules/downstream-changes.md +5 -0
- package/.agent-src/rules/e2e-testing.md +9 -44
- package/.agent-src/rules/guidelines.md +13 -75
- package/.agent-src/rules/improve-before-implement.md +10 -2
- package/.agent-src/rules/language-and-tone.md +35 -69
- package/.agent-src/rules/laravel-translations.md +11 -40
- package/.agent-src/rules/markdown-safe-codeblocks.md +4 -0
- package/.agent-src/rules/minimal-safe-diff.md +4 -0
- package/.agent-src/rules/missing-tool-handling.md +4 -0
- package/.agent-src/rules/model-recommendation.md +9 -61
- package/.agent-src/rules/no-attribution-footers.md +53 -0
- package/.agent-src/rules/no-cheap-questions.md +11 -27
- package/.agent-src/rules/no-council-references.md +76 -0
- package/.agent-src/rules/no-roadmap-references.md +8 -1
- package/.agent-src/rules/non-destructive-by-default.md +13 -43
- package/.agent-src/rules/onboarding-gate.md +9 -117
- package/.agent-src/rules/package-ci-checks.md +10 -37
- package/.agent-src/rules/php-coding.md +10 -55
- package/.agent-src/rules/preservation-guard.md +9 -0
- package/.agent-src/rules/review-routing-awareness.md +9 -97
- package/.agent-src/rules/reviewer-awareness.md +8 -83
- package/.agent-src/rules/roadmap-progress-sync.md +7 -170
- package/.agent-src/rules/role-mode-adherence.md +6 -2
- package/.agent-src/rules/rule-type-governance.md +8 -66
- package/.agent-src/rules/runtime-safety.md +5 -0
- package/.agent-src/rules/scope-control.md +17 -62
- package/.agent-src/rules/security-sensitive-stop.md +7 -1
- package/.agent-src/rules/size-enforcement.md +6 -1
- package/.agent-src/rules/skill-improvement-trigger.md +9 -49
- package/.agent-src/rules/skill-quality.md +7 -64
- package/.agent-src/rules/slash-command-routing-policy.md +11 -63
- package/.agent-src/rules/think-before-action.md +22 -87
- package/.agent-src/rules/token-efficiency.md +10 -74
- package/.agent-src/rules/token-optimizer-maintenance.md +68 -0
- package/.agent-src/rules/tool-safety.md +4 -0
- package/.agent-src/rules/ui-audit-gate.md +25 -61
- package/.agent-src/rules/upstream-proposal.md +9 -67
- package/.agent-src/rules/user-interaction.md +25 -95
- package/.agent-src/rules/verify-before-complete.md +1 -1
- package/.agent-src/skills/agent-docs-writing/SKILL.md +1 -1
- package/.agent-src/skills/ai-council/SKILL.md +69 -5
- package/.agent-src/skills/analysis-autonomous-mode/SKILL.md +1 -1
- package/.agent-src/skills/analysis-skill-router/SKILL.md +3 -3
- package/.agent-src/skills/artisan-commands/SKILL.md +2 -2
- package/.agent-src/skills/authz-review/SKILL.md +1 -1
- package/.agent-src/skills/aws-infrastructure/SKILL.md +5 -5
- package/.agent-src/skills/blast-radius-analyzer/SKILL.md +8 -8
- package/.agent-src/skills/bug-analyzer/SKILL.md +5 -5
- package/.agent-src/skills/code-refactoring/SKILL.md +4 -4
- package/.agent-src/skills/code-review/SKILL.md +2 -2
- package/.agent-src/skills/command-writing/SKILL.md +11 -0
- package/.agent-src/skills/composer-packages/SKILL.md +2 -2
- package/.agent-src/skills/context-authoring/SKILL.md +11 -0
- package/.agent-src/skills/context-document/SKILL.md +1 -1
- package/.agent-src/skills/copilot-agents-optimization/SKILL.md +23 -0
- package/.agent-src/skills/copilot-config/SKILL.md +1 -1
- package/.agent-src/skills/dcf-modeling/SKILL.md +89 -0
- package/.agent-src/skills/dependency-upgrade/SKILL.md +2 -2
- package/.agent-src/skills/devcontainer/SKILL.md +2 -2
- package/.agent-src/skills/developer-like-execution/SKILL.md +1 -1
- package/.agent-src/skills/docker/SKILL.md +1 -1
- package/.agent-src/skills/dto-creator/SKILL.md +1 -1
- package/.agent-src/skills/estimate-ticket/SKILL.md +2 -2
- package/.agent-src/skills/fe-design/SKILL.md +4 -4
- package/.agent-src/skills/feature-planning/SKILL.md +5 -5
- package/.agent-src/skills/funnel-analysis/SKILL.md +100 -0
- package/.agent-src/skills/laravel/SKILL.md +1 -1
- package/.agent-src/skills/laravel-notifications/SKILL.md +5 -5
- package/.agent-src/skills/laravel-pennant/SKILL.md +1 -1
- package/.agent-src/skills/laravel-pulse/SKILL.md +4 -4
- package/.agent-src/skills/laravel-reverb/SKILL.md +2 -2
- package/.agent-src/skills/laravel-scheduling/SKILL.md +1 -1
- package/.agent-src/skills/md-language-check/SKILL.md +1 -1
- package/.agent-src/skills/migration-creator/SKILL.md +7 -7
- package/.agent-src/skills/multi-tenancy/SKILL.md +8 -8
- package/.agent-src/skills/okr-tree-modeling/SKILL.md +93 -0
- package/.agent-src/skills/performance-analysis/SKILL.md +3 -3
- package/.agent-src/skills/pest-testing/SKILL.md +6 -6
- package/.agent-src/skills/php-service/SKILL.md +2 -2
- package/.agent-src/skills/project-analysis-hypothesis-driven/SKILL.md +3 -3
- package/.agent-src/skills/project-analysis-react/SKILL.md +1 -1
- package/.agent-src/skills/project-analysis-symfony/SKILL.md +1 -1
- package/.agent-src/skills/project-analysis-zend-laminas/SKILL.md +2 -2
- package/.agent-src/skills/project-analyzer/SKILL.md +4 -4
- package/.agent-src/skills/prompt-optimizer/SKILL.md +108 -0
- package/.agent-src/skills/readme-reviewer/SKILL.md +1 -1
- package/.agent-src/skills/rice-prioritization/SKILL.md +100 -0
- package/.agent-src/skills/rule-writing/SKILL.md +33 -0
- package/.agent-src/skills/sentry-integration/SKILL.md +1 -1
- package/.agent-src/skills/skill-writing/SKILL.md +14 -0
- package/.agent-src/skills/subagent-orchestration/SKILL.md +34 -2
- package/.agent-src/skills/terraform/SKILL.md +2 -2
- package/.agent-src/skills/terragrunt/SKILL.md +8 -8
- package/.agent-src/skills/test-performance/SKILL.md +5 -5
- package/.agent-src/skills/threat-modeling/SKILL.md +2 -2
- package/.agent-src/skills/token-optimizer/SKILL.md +110 -0
- package/.agent-src/skills/unit-economics-modeling/SKILL.md +104 -0
- package/.agent-src/skills/universal-project-analysis/SKILL.md +1 -1
- package/.agent-src/skills/using-git-worktrees/SKILL.md +1 -0
- package/.agent-src/templates/AGENTS.md +1 -1
- package/.agent-src/templates/agent-settings.md +25 -41
- package/.agent-src/templates/contexts/tenant-boundaries.md +2 -2
- package/.agent-src/templates/contexts.md +1 -1
- package/.agent-src/templates/copilot-instructions.md +21 -0
- package/.agent-src/templates/copilot-review-instructions.md +76 -0
- package/.agent-src/templates/features.md +1 -1
- package/.agent-src/templates/rule.md +127 -0
- package/.agent-src/templates/scripts/work_engine/hook_bootstrap.py +7 -5
- package/.agent-src/templates/scripts/work_engine/hooks/__init__.py +0 -4
- package/.agent-src/templates/scripts/work_engine/hooks/builtin/__init__.py +0 -4
- package/.agent-src/templates/scripts/work_engine/hooks/builtin/_chat_history_base.py +7 -51
- package/.agent-src/templates/scripts/work_engine/hooks/builtin/chat_history_append.py +1 -2
- package/.agent-src/templates/scripts/work_engine/hooks/builtin/chat_history_halt_append.py +1 -2
- package/.agent-src/templates/scripts/work_engine/hooks/builtin/memory_visibility.py +2 -3
- package/.agent-src/templates/skill.md +30 -1
- package/.claude-plugin/marketplace.json +11 -4
- package/AGENTS.md +71 -3
- package/CHANGELOG.md +180 -3
- package/README.md +24 -23
- package/config/agent-settings.template.yml +63 -23
- package/config/gitignore-block.txt +11 -4
- package/docs/architecture.md +84 -3
- package/docs/catalog.md +23 -11
- package/docs/contracts/adr-chat-history-split.md +10 -1
- package/docs/contracts/agent-memory-contract.md +1 -1
- package/docs/contracts/command-clusters.md +1 -1
- package/docs/contracts/context-paths.md +2 -1
- package/docs/contracts/cross-wing-handoff.md +133 -0
- package/docs/contracts/file-ownership-matrix.json +678 -609
- package/docs/contracts/hook-architecture-v1.md +8 -1
- package/docs/contracts/iron-law-overrides.txt +25 -0
- package/docs/contracts/kernel-membership.md +273 -0
- package/docs/contracts/load-context-schema.md +26 -11
- package/docs/contracts/memory-visibility-v1.md +8 -24
- package/docs/contracts/pilot/agent-authority.md +24 -0
- package/docs/contracts/pilot/direct-answers.md +70 -0
- package/docs/contracts/pilot/language-and-tone.md +63 -0
- package/docs/contracts/rule-classification.md +170 -0
- package/docs/contracts/rule-router.md +153 -0
- package/docs/customization.md +18 -7
- package/docs/decisions/ADR-001-kernel-swap-deferred.md +109 -0
- package/docs/decisions/ADR-002-kernel-bucket-overrides.md +124 -0
- package/docs/decisions/ADR-rule-kernel-and-router.md +122 -0
- package/docs/getting-started.md +19 -27
- package/docs/guidelines/agent-infra/ask-when-uncertain-demos.md +1 -1
- package/docs/guidelines/agent-infra/roadmap-progress-mechanics.md +176 -0
- package/docs/guidelines/agent-infra/rule-type-governance.md +73 -0
- package/docs/guidelines/agent-infra/size-and-scope.md +13 -2
- package/docs/guidelines/agent-infra/skill-quality-checklist.md +119 -0
- package/docs/guidelines/augment-portability-patterns.md +68 -0
- package/docs/guidelines/php/php-coding-patterns.md +62 -0
- package/docs/hook-payload-capture.md +221 -0
- package/docs/migrations/commands-1.15.0.md +17 -12
- package/docs/skills-catalog.md +5 -4
- package/llms.txt +4 -3
- package/package.json +1 -1
- package/scripts/_p43_bodies.py +235 -0
- package/scripts/_p43_compress.py +118 -0
- package/scripts/_p4_migrate.py +199 -0
- package/scripts/_pilot_council_question.py +57 -0
- package/scripts/_pilot_measure.py +53 -0
- package/scripts/agent-config +1 -1
- package/scripts/ai_council/_default_prices.py +4 -4
- package/scripts/ai_council/clients.py +1 -1
- package/scripts/ai_council/modes.py +3 -4
- package/scripts/ai_council/pricing.py +10 -9
- package/scripts/ai_council/session.py +107 -5
- package/scripts/build_linear_digest.py +3 -5
- package/scripts/build_rule_trigger_matrix.py +1 -9
- package/scripts/chat_history.py +952 -596
- package/scripts/check_always_budget.py +39 -6
- package/scripts/check_compressed_paths.py +213 -0
- package/scripts/check_compression.py +15 -0
- package/scripts/check_context_paths.py +1 -0
- package/scripts/check_council_layout.py +105 -0
- package/scripts/check_council_references.py +145 -0
- package/scripts/check_portability.py +2 -0
- package/scripts/check_references.py +14 -2
- package/scripts/check_token_optimizer_freshness.py +131 -0
- package/scripts/compile_router.py +148 -0
- package/scripts/compress.py +219 -11
- package/scripts/council_cli.py +63 -9
- package/scripts/council_prune.py +81 -0
- package/scripts/count_token_optimizer_usage.sh +54 -0
- package/scripts/hook_manifest.yaml +33 -0
- package/scripts/hooks/augment-chat-history.sh +10 -0
- package/scripts/hooks/cowork-dispatcher.sh +98 -0
- package/scripts/hooks/dispatch_hook.py +35 -0
- package/scripts/hooks_status.py +12 -1
- package/scripts/install-hooks.sh +2 -2
- package/scripts/install.sh +81 -2
- package/scripts/iron_law_sha.py +98 -0
- package/scripts/lint_handoffs.py +214 -0
- package/scripts/lint_hook_manifest.py +2 -1
- package/scripts/lint_load_context.py +35 -5
- package/scripts/measure_rule_budget.py +314 -0
- package/scripts/prototype_lint_contradictions.py +150 -0
- package/scripts/redact_hook_capture.py +148 -0
- package/scripts/schemas/rule.schema.json +55 -6
- package/scripts/schemas/skill.schema.json +5 -0
- package/scripts/skill_linter.py +359 -7
- package/scripts/smoke_path_resolution.py +93 -0
- package/scripts/update_prices.py +3 -3
- package/scripts/validate_frontmatter.py +41 -1
- package/.agent-src/commands/chat-history/checkpoint.md +0 -126
- package/.agent-src/commands/chat-history/clear.md +0 -103
- package/.agent-src/commands/chat-history/resume.md +0 -183
- package/.agent-src/contexts/communication/rules-auto/artifact-engagement-recording-mechanics.md +0 -72
- package/.agent-src/contexts/communication/rules-auto/augment-portability-mechanics.md +0 -79
- package/.agent-src/contexts/communication/rules-auto/cli-output-handling-mechanics.md +0 -87
- package/.agent-src/contexts/communication/rules-auto/command-suggestion-policy-mechanics.md +0 -62
- package/.agent-src/contexts/communication/rules-auto/docs-sync-mechanics.md +0 -78
- package/.agent-src/contexts/communication/rules-auto/package-ci-checks-mechanics.md +0 -85
- package/.agent-src/contexts/communication/rules-auto/review-routing-awareness-mechanics.md +0 -65
- package/.agent-src/contexts/communication/rules-auto/roadmap-progress-sync-mechanics.md +0 -78
- package/.agent-src/contexts/communication/rules-auto/ui-audit-gate-mechanics.md +0 -53
- package/.agent-src/rules/chat-history-cadence.md +0 -143
- package/.agent-src/rules/chat-history-ownership.md +0 -124
- package/.agent-src/rules/chat-history-visibility.md +0 -97
- package/.agent-src/templates/scripts/work_engine/hooks/builtin/chat_history_heartbeat.py +0 -50
- package/.agent-src/templates/scripts/work_engine/hooks/builtin/chat_history_turn_check.py +0 -49
- package/scripts/check_phase_coupling.py +0 -148
- /package/{docs → .agent-src/contexts}/contracts/artifact-engagement-flow.md +0 -0
- /package/{docs → .agent-src/contexts}/contracts/command-suggestion-flow.md +0 -0
|
@@ -3,105 +3,17 @@ type: "auto"
|
|
|
3
3
|
tier: "2a"
|
|
4
4
|
description: "When routing reviewers or flagging risk hotspots — consult ownership-map and historical-bug-patterns before suggesting reviewers or claiming a change is safe"
|
|
5
5
|
source: package
|
|
6
|
-
|
|
7
|
-
-
|
|
6
|
+
triggers:
|
|
7
|
+
- keyword: "reviewer"
|
|
8
|
+
- phrase: "risk hotspot"
|
|
9
|
+
- phrase: "ownership map"
|
|
10
|
+
routes_to:
|
|
11
|
+
- "skill:review-routing"
|
|
8
12
|
---
|
|
9
13
|
|
|
10
14
|
# Review Routing Awareness
|
|
11
15
|
|
|
12
|
-
|
|
13
|
-
two project-local data sources — if they exist — to ground the routing in
|
|
14
|
-
the consumer's actual organizational memory:
|
|
16
|
+
**Iron Law.** Consult ownership-map and historical-bug-patterns before suggesting reviewers or claiming a change is safe.
|
|
15
17
|
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
2. **Historical bug patterns** — recurring failure modes or technical debt
|
|
19
|
-
the project has paid for before.
|
|
20
|
-
|
|
21
|
-
Both live in the consumer repository (never in package-shipped files) and
|
|
22
|
-
are optional. Absence is not an error — the agent falls back to
|
|
23
|
-
generic, role-based suggestions from [`reviewer-awareness`](reviewer-awareness.md).
|
|
24
|
-
|
|
25
|
-
## When this rule applies
|
|
26
|
-
|
|
27
|
-
- The agent is classifying PR risk, suggesting reviewers, writing a PR
|
|
28
|
-
description, or producing a review plan.
|
|
29
|
-
- The agent is reviewing its own diff before asking for human review.
|
|
30
|
-
- The change modifies more than a trivial amount of code (≥ 1 file
|
|
31
|
-
outside docs).
|
|
32
|
-
|
|
33
|
-
## Required behavior
|
|
34
|
-
|
|
35
|
-
### 1. Check for project data
|
|
36
|
-
|
|
37
|
-
Look, in order, for:
|
|
38
|
-
|
|
39
|
-
- `.github/ownership-map.yml` (or `agents/ownership-map.yml`)
|
|
40
|
-
- `.github/historical-bug-patterns.yml` (or
|
|
41
|
-
`agents/historical-bug-patterns.yml`)
|
|
42
|
-
|
|
43
|
-
If neither file exists, fall back to the engineering-memory layer.
|
|
44
|
-
Memory-lookup snippet and merge semantics live in
|
|
45
|
-
[`contexts/communication/rules-auto/review-routing-awareness-mechanics.md`](../contexts/communication/rules-auto/review-routing-awareness-mechanics.md)
|
|
46
|
-
§ Memory-lookup fallback. If both memory and project YAMLs are absent,
|
|
47
|
-
skip this rule and rely on
|
|
48
|
-
[`reviewer-awareness`](reviewer-awareness.md) defaults. **Do not
|
|
49
|
-
invent owners or patterns** from context.
|
|
50
|
-
|
|
51
|
-
### 2. Match the diff
|
|
52
|
-
|
|
53
|
-
For every changed file, collect:
|
|
54
|
-
|
|
55
|
-
- **Matching ownership entries** — each yields a role, optional focus
|
|
56
|
-
note, and optional risk hint.
|
|
57
|
-
- **Matching historical patterns** — each yields a named prior failure
|
|
58
|
-
mode and the minimum control or test the project expects.
|
|
59
|
-
|
|
60
|
-
Matching uses glob patterns (see
|
|
61
|
-
[`review-routing-data-format`](../../docs/guidelines/agent-infra/review-routing-data-format.md)
|
|
62
|
-
for the schema).
|
|
63
|
-
|
|
64
|
-
### 3. Surface findings
|
|
65
|
-
|
|
66
|
-
When producing a review plan, include owner-mapped roles (preferred
|
|
67
|
-
over generic), historical-pattern warnings (with required control),
|
|
68
|
-
and a staleness note if the ownership map's `updated` field is older
|
|
69
|
-
than 6 months. Worked examples for each in
|
|
70
|
-
[`contexts/communication/rules-auto/review-routing-awareness-mechanics.md`](../contexts/communication/rules-auto/review-routing-awareness-mechanics.md)
|
|
71
|
-
§ Surface findings.
|
|
72
|
-
|
|
73
|
-
### 4. Do NOT overreach
|
|
74
|
-
|
|
75
|
-
The "do NOT overreach" guardrails (no path renames as side effects, no
|
|
76
|
-
"safe because no match", no pattern names in diffs/commits) live in
|
|
77
|
-
[`contexts/communication/rules-auto/review-routing-awareness-mechanics.md`](../contexts/communication/rules-auto/review-routing-awareness-mechanics.md)
|
|
78
|
-
§ Do NOT overreach.
|
|
79
|
-
|
|
80
|
-
## Interaction with other rules
|
|
81
|
-
|
|
82
|
-
- Feeds [`reviewer-awareness`](reviewer-awareness.md) — this rule
|
|
83
|
-
**resolves** owners; reviewer-awareness **formats** them.
|
|
84
|
-
- Extends [`verify-before-complete`](verify-before-complete.md) — if a
|
|
85
|
-
historical pattern demands a regression test, the verification gate
|
|
86
|
-
requires that test before completion is claimed.
|
|
87
|
-
- Does not override [`minimal-safe-diff`](minimal-safe-diff.md) — a
|
|
88
|
-
matched pattern is a reason to **add a test**, never a reason to
|
|
89
|
-
expand scope into unrelated refactors.
|
|
90
|
-
|
|
91
|
-
## Anti-patterns
|
|
92
|
-
|
|
93
|
-
The four anti-pattern rejections (invented owners, invented patterns,
|
|
94
|
-
downgrading high-severity hits, treating stale maps as absent) live in
|
|
95
|
-
[`contexts/communication/rules-auto/review-routing-awareness-mechanics.md`](../contexts/communication/rules-auto/review-routing-awareness-mechanics.md)
|
|
96
|
-
§ Anti-patterns.
|
|
97
|
-
|
|
98
|
-
## See also
|
|
99
|
-
|
|
100
|
-
- [`reviewer-awareness`](reviewer-awareness.md) — formatting reviewer
|
|
101
|
-
suggestions.
|
|
102
|
-
- [`review-routing-data-format`](../../docs/guidelines/agent-infra/review-routing-data-format.md)
|
|
103
|
-
— YAML schemas for ownership-map and historical-bug-patterns.
|
|
104
|
-
- [`review-routing`](../skills/review-routing/SKILL.md) — the skill
|
|
105
|
-
that produces the merged routing report.
|
|
106
|
-
- [`judge-test-coverage`](../skills/judge-test-coverage/SKILL.md) —
|
|
107
|
-
consumes the "required test" output from historical patterns.
|
|
18
|
+
Body migrated to `skill:review-routing` (per P4 of `road-to-kernel-and-router.md`).
|
|
19
|
+
Trigger-set above activates this routing under the `balanced` and `full` profiles.
|
|
@@ -3,91 +3,16 @@ type: "auto"
|
|
|
3
3
|
tier: "2a"
|
|
4
4
|
description: "When suggesting reviewers for a change — anchor the choice in paths and risk, never prestige or seniority; require primary + secondary role for medium/high risk"
|
|
5
5
|
source: package
|
|
6
|
+
triggers:
|
|
7
|
+
- keyword: "reviewer"
|
|
8
|
+
- phrase: "suggest reviewers"
|
|
9
|
+
routes_to:
|
|
10
|
+
- "skill:review-routing"
|
|
6
11
|
---
|
|
7
12
|
|
|
8
13
|
# Reviewer Awareness
|
|
9
14
|
|
|
10
|
-
|
|
11
|
-
(not individuals) based on what the diff actually touches — not who is
|
|
12
|
-
loudest, most senior, or who "usually reviews this kind of thing".
|
|
15
|
+
**Iron Law.** Anchor reviewer choice in paths and risk, never seniority; medium / high risk requires primary + secondary role.
|
|
13
16
|
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
- The agent is asked to suggest reviewers, draft a PR description, or
|
|
17
|
-
consolidate a review plan.
|
|
18
|
-
- The change is classified medium or high risk by
|
|
19
|
-
[`review-routing`](../skills/review-routing/SKILL.md), the
|
|
20
|
-
`pr_risk_review.py` script, or explicit user judgment.
|
|
21
|
-
- For **low-risk** changes, reviewer suggestions are optional and may be
|
|
22
|
-
omitted.
|
|
23
|
-
|
|
24
|
-
## Required behavior
|
|
25
|
-
|
|
26
|
-
1. **Anchor every suggestion in the diff.** Name the path or change that
|
|
27
|
-
triggered the role — "backend because `app/Services/PaymentGateway.php`
|
|
28
|
-
changed", not "backend because it's a code change".
|
|
29
|
-
2. **Two roles minimum for medium/high risk** — one **primary** (the
|
|
30
|
-
domain most at risk) and one **secondary** (cross-cutting sanity:
|
|
31
|
-
security, infra, domain owner).
|
|
32
|
-
3. **Explain the focus area** for each reviewer — what they should look
|
|
33
|
-
at, not just that they should look. "security: confirm the new
|
|
34
|
-
authorization boundary actually denies cross-tenant reads".
|
|
35
|
-
4. **Prefer ownership-mapped owners** when an ownership map exists
|
|
36
|
-
(see [`review-routing-awareness`](review-routing-awareness.md)). Fall
|
|
37
|
-
back to generic roles only when no mapping matches.
|
|
38
|
-
5. **Never name individual reviewers** in package-shipped artifacts.
|
|
39
|
-
The consumer repo's CODEOWNERS or ownership map does the mapping
|
|
40
|
-
role → person.
|
|
41
|
-
|
|
42
|
-
## Reviewer roles
|
|
43
|
-
|
|
44
|
-
The reference set — extend per project, but keep these as the common
|
|
45
|
-
vocabulary:
|
|
46
|
-
|
|
47
|
-
| Role | Typical focus |
|
|
48
|
-
|---|---|
|
|
49
|
-
| `backend` | business logic, validation, side effects, data integrity |
|
|
50
|
-
| `frontend` | UX, accessibility, client-side state, rendering |
|
|
51
|
-
| `security` | authz, secrets, trust boundaries, data exposure |
|
|
52
|
-
| `infra` / `ops` | rollout, migration safety, observability, retries |
|
|
53
|
-
| `database` | schema changes, indexes, query plans, rollback realism |
|
|
54
|
-
| `domain owner` | business invariants, policy intent, edge-case correctness |
|
|
55
|
-
| `qa` | test coverage, regression scenarios, flake risk |
|
|
56
|
-
|
|
57
|
-
## Anti-patterns — reject them
|
|
58
|
-
|
|
59
|
-
- "Reviewers: @alice, @bob" inside a shared package artifact — individuals
|
|
60
|
-
live in the consumer's CODEOWNERS, not in package output.
|
|
61
|
-
- "Any senior engineer" — prestige is not a review strategy.
|
|
62
|
-
- "Whoever reviewed this last time" — selection by habit, not by
|
|
63
|
-
current risk.
|
|
64
|
-
- One role for a 🔴 high-risk change — single-reviewer risk, especially
|
|
65
|
-
when the change crosses an authorization or tenancy boundary.
|
|
66
|
-
- Suggesting reviewers without naming what they should look at — a
|
|
67
|
-
rubber-stamp invitation.
|
|
68
|
-
|
|
69
|
-
## Format
|
|
70
|
-
|
|
71
|
-
When the agent proposes reviewers, use this block:
|
|
72
|
-
|
|
73
|
-
```
|
|
74
|
-
Suggested reviewers (role-based):
|
|
75
|
-
• primary: <role> — focus: <one line, anchored in diff>
|
|
76
|
-
• secondary: <role> — focus: <one line, anchored in diff>
|
|
77
|
-
(optional) additional: <role> — focus: …
|
|
78
|
-
```
|
|
79
|
-
|
|
80
|
-
## Rationale
|
|
81
|
-
|
|
82
|
-
The right reviewer reduces blind spots more than the loudest reviewer.
|
|
83
|
-
Blind-spot reduction comes from role diversity (different angles on the
|
|
84
|
-
same diff), not from seniority.
|
|
85
|
-
|
|
86
|
-
## See also
|
|
87
|
-
|
|
88
|
-
- [`review-routing-awareness`](review-routing-awareness.md) — how
|
|
89
|
-
ownership maps and historical patterns feed reviewer selection.
|
|
90
|
-
- [`review-routing`](../skills/review-routing/SKILL.md) — the skill that
|
|
91
|
-
produces the reviewer block.
|
|
92
|
-
- [`requesting-code-review`](../skills/requesting-code-review/SKILL.md) —
|
|
93
|
-
PR preparation and self-review before asking for reviewers.
|
|
17
|
+
Body migrated to `skill:review-routing` (per P4 of `road-to-kernel-and-router.md`).
|
|
18
|
+
Trigger-set above activates this routing under the `balanced` and `full` profiles.
|
|
@@ -2,179 +2,16 @@
|
|
|
2
2
|
type: "auto"
|
|
3
3
|
tier: "1"
|
|
4
4
|
description: "Any touch to agents/roadmaps/ — create/rename/delete/move, edit checkboxes ([x]/[~]/[-]), add/rename/remove phases — must regenerate dashboard and archive if 0 open items, same response"
|
|
5
|
-
alwaysApply: false
|
|
6
5
|
source: package
|
|
7
|
-
|
|
8
|
-
-
|
|
6
|
+
triggers:
|
|
7
|
+
- path_prefix: "agents/roadmaps/"
|
|
8
|
+
routes_to:
|
|
9
|
+
- "guideline:agent-infra/roadmap-progress-mechanics"
|
|
9
10
|
---
|
|
10
11
|
|
|
11
|
-
<!-- cloud_safe: degrade -->
|
|
12
|
-
<!-- Authoring discipline applies in cloud; local script + regen are no-ops there. -->
|
|
13
|
-
|
|
14
12
|
# Roadmap Progress Sync
|
|
15
13
|
|
|
16
|
-
|
|
17
|
-
> on Augment + Claude Code (`PostToolUse`). Hook is primary; the prose
|
|
18
|
-
> below is the specification the hook implements and the fallback when
|
|
19
|
-
> the platform has no hook surface.
|
|
20
|
-
|
|
21
|
-
## Iron Law — dashboard sync
|
|
22
|
-
|
|
23
|
-
```
|
|
24
|
-
ANY ROADMAP TOUCH → REGENERATE THE DASHBOARD, SAME RESPONSE.
|
|
25
|
-
NO EXCEPTIONS. NO "I'LL DO IT AT THE END". NO BATCHING ACROSS TURNS.
|
|
26
|
-
A ROADMAP NOT IN THE DASHBOARD IS A RULE VIOLATION, NOT AN OVERSIGHT.
|
|
27
|
-
```
|
|
28
|
-
|
|
29
|
-
**Roadmap touch =** create the file, rename it, delete it, move it
|
|
30
|
-
between `roadmaps/` ↔ `archive/` ↔ `skipped/`, add/rename/remove a
|
|
31
|
-
phase, **OR** flip any checkbox (`[ ]` ↔ `[x]` ↔ `[~]` ↔ `[-]`).
|
|
32
|
-
|
|
33
|
-
`agents/roadmaps-progress.md` is the read-only dashboard. Every
|
|
34
|
-
unsynced edit makes it lie to the next reader. Created a roadmap
|
|
35
|
-
without regenerating? The dashboard claims it does not exist. Marked
|
|
36
|
-
8 steps `[x]` and forgot the regen? The dashboard says 0 done.
|
|
37
|
-
|
|
38
|
-
## Iron Law — every active roadmap is trackable
|
|
39
|
-
|
|
40
|
-
```
|
|
41
|
-
EVERY ACTIVE ROADMAP MUST CONTAIN AT LEAST ONE TRACKABLE CHECKBOX
|
|
42
|
-
(`- [ ]`) PER NON-INTRO PHASE. ROADMAPS WITHOUT EXECUTABLE STEPS
|
|
43
|
-
EITHER GET A CHECKLIST OR THE `status: draft` FLAG.
|
|
44
|
-
CI-ENFORCED: `scripts/check_roadmap_trackable.py` (CANNOT BE DEFERRED).
|
|
45
|
-
```
|
|
46
|
-
|
|
47
|
-
**Active roadmap =** any file in `agents/roadmaps/` (root, not
|
|
48
|
-
`archive/` or `skipped/`) without `status: draft` frontmatter.
|
|
49
|
-
|
|
50
|
-
**Trackable checkbox =** an actionable `- [ ]` line under a `## Phase N`
|
|
51
|
-
or `### Phase N` heading (numeric `Phase 1`, roman `Phase II`, or
|
|
52
|
-
letter-track `Phase A1` — matched by the dashboard's `PHASE_RE`).
|
|
53
|
-
Tables of decisions, ICE matrices, ADR captures, and "block
|
|
54
|
-
sequencing" tables are valid **rationale**, but they do not satisfy
|
|
55
|
-
this rule on their own — they must be paired with at least one
|
|
56
|
-
`## Phase N` section whose checkboxes execute the decision.
|
|
57
|
-
Headings such as `## Phase steps`, `### Sequencing — Phase 1 …`,
|
|
58
|
-
`### P0 #1 — …`, or `## Block A` do **not** count — only the
|
|
59
|
-
canonical `Phase <id>` form parsed by the dashboard.
|
|
60
|
-
|
|
61
|
-
**CI backstop.** `scripts/check_roadmap_trackable.py` (package-shipped,
|
|
62
|
-
wire into the consumer's pre-commit / pre-push / Actions gate) fails
|
|
63
|
-
when an active roadmap has zero canonical `Phase` headings or when
|
|
64
|
-
any parsed phase has zero checkboxes. Last line of defence — real-time
|
|
65
|
-
authoring still flips checkboxes and regenerates the dashboard the
|
|
66
|
-
same response.
|
|
67
|
-
|
|
68
|
-
## Status — binary `ready` (default) vs `draft`
|
|
69
|
-
|
|
70
|
-
```yaml
|
|
71
|
-
---
|
|
72
|
-
status: draft # hidden from the dashboard until flipped
|
|
73
|
-
---
|
|
74
|
-
```
|
|
75
|
-
|
|
76
|
-
Two values, no synonyms. Anything else — no frontmatter at all,
|
|
77
|
-
`status: ready`, an unknown value — counts as **ready** and lands
|
|
78
|
-
in the dashboard.
|
|
79
|
-
|
|
80
|
-
- **Ready** is the implicit default. New roadmaps are created
|
|
81
|
-
ready unless the user explicitly says draft. Ready roadmaps are
|
|
82
|
-
listed in the dashboard, count towards open/done totals, and
|
|
83
|
-
trip the "completed but not archived" warning when they close.
|
|
84
|
-
- **Draft** hides the file from the dashboard entirely (not
|
|
85
|
-
counted, not listed). Use it while the roadmap is still being
|
|
86
|
-
authored, while waiting for upstream decisions, or as a
|
|
87
|
-
capture-only synthesis that has not yet been promoted to
|
|
88
|
-
executable phases. Flip to ready (or remove the field) the
|
|
89
|
-
moment the roadmap is ready to track.
|
|
90
|
-
|
|
91
|
-
**Completion = archival, same response.** When the edit takes a
|
|
92
|
-
roadmap to `count_open == 0` (every item is `[x]`, `[~]`, or `[-]`),
|
|
93
|
-
`git mv` it into `agents/roadmaps/archive/` (or `skipped/` if no `[x]`
|
|
94
|
-
at all) **before** regenerating the dashboard. A 100%-complete
|
|
95
|
-
roadmap left under `agents/roadmaps/` is a rule violation, not an
|
|
96
|
-
optional cleanup. See `roadmap-management` skill for the archive vs
|
|
97
|
-
skipped decision table.
|
|
98
|
-
|
|
99
|
-
## Agent-authored roadmaps — placement is mandatory
|
|
100
|
-
|
|
101
|
-
```
|
|
102
|
-
A FILE THE AGENT DROPS INTO agents/roadmaps/ MUST EITHER
|
|
103
|
-
(a) PASS check_roadmap_trackable.py AND LAND IN THE DASHBOARD, OR
|
|
104
|
-
(b) NOT BE IN agents/roadmaps/ AT ALL.
|
|
105
|
-
NO "DECISION MATRIX" / "DESIGN NOTE" SHORTCUT.
|
|
106
|
-
```
|
|
107
|
-
|
|
108
|
-
When the agent autonomously creates a roadmap, it owns the placement
|
|
109
|
-
in the **same response**:
|
|
110
|
-
|
|
111
|
-
- **Phase plan** (checkboxes, multi-turn execution) → `agents/roadmaps/<name>.md`, `status: ready` (default), regen dashboard.
|
|
112
|
-
- **Decision matrix / ADR / pattern / lookup** (no `Phase N`, durable rationale) → `agents/contexts/<name>.md`.
|
|
113
|
-
- **Completed work snapshot** → `agents/roadmaps/archive/<name>.md`.
|
|
114
|
-
|
|
115
|
-
A non-trackable file in `agents/roadmaps/` is a rule violation — the
|
|
116
|
-
trackable CI fails it, the dashboard hides it. The agent that
|
|
117
|
-
created it moves it the same response. If the autonomous run also
|
|
118
|
-
**finishes** the roadmap within the session (every box `[x]`/`[~]`/`[-]`),
|
|
119
|
-
the completion-archival rule above fires too — same response.
|
|
120
|
-
|
|
121
|
-
## Autonomous execution — checkbox cadence
|
|
122
|
-
|
|
123
|
-
When executing a roadmap autonomously (multi-turn, no per-step user
|
|
124
|
-
prompt), the user loses progress visibility unless checkboxes flip
|
|
125
|
-
**as work lands**, not in a batch at the end. Iron Law:
|
|
126
|
-
|
|
127
|
-
```
|
|
128
|
-
EVERY DONE STEP FLIPS [ ] → [x] IN NEXT REPLY THAT ACKNOWLEDGES IT.
|
|
129
|
-
NO "I UPDATE ROADMAP AT END OF PHASE."
|
|
130
|
-
NO "FOUR STEPS DONE, ONE COMMIT, ONE REGEN."
|
|
131
|
-
```
|
|
132
|
-
|
|
133
|
-
Step counts as completed when:
|
|
134
|
-
|
|
135
|
-
- Code / docs change for that step has been **written and saved** AND
|
|
136
|
-
- Verification cited in the step (project CI command, targeted test, lint) has
|
|
137
|
-
**passed in this response or an earlier one** — fresh output, not memory.
|
|
138
|
-
|
|
139
|
-
Then in the **same reply**: flip the checkbox, regenerate the
|
|
140
|
-
dashboard, commit if commit policy allows.
|
|
141
|
-
|
|
142
|
-
**Forbidden:** four turns of step work, dashboard flat, single regen at the end.
|
|
143
|
-
**Required:** each turn — implement step, flip `[x]`, regen, commit (if policy allows).
|
|
144
|
-
A reply that lands a verified step without flipping its checkbox is a rule violation.
|
|
145
|
-
|
|
146
|
-
**In-progress marker:** when a step takes more than one reply,
|
|
147
|
-
mark it `[~]` the moment work starts on it and regenerate. The
|
|
148
|
-
user sees one row move from `[ ]` to `[~]` to `[x]` instead of
|
|
149
|
-
silent rows. `[~]` is treated as open for `count_open` but moves
|
|
150
|
-
the phase percentage forward in the dashboard.
|
|
151
|
-
|
|
152
|
-
## Mechanics — triggers, regen command, self-check, failures
|
|
153
|
-
|
|
154
|
-
The triggers table, the regen command (`./agent-config roadmap:progress`),
|
|
155
|
-
the mandatory pre-send self-check, the failure-mode catalog, and the
|
|
156
|
-
`Do NOT` list live in
|
|
157
|
-
[`contexts/communication/rules-auto/roadmap-progress-sync-mechanics.md`](../contexts/communication/rules-auto/roadmap-progress-sync-mechanics.md).
|
|
158
|
-
Pull it whenever a trigger fires — the rule above is the obligation
|
|
159
|
-
surface; the mechanics file is the lookup material.
|
|
160
|
-
|
|
161
|
-
## Copilot fallback
|
|
162
|
-
|
|
163
|
-
GitHub Copilot has no `PostToolUse` hook surface, so
|
|
164
|
-
`scripts/roadmap_progress_hook.py` cannot detect roadmap-file writes
|
|
165
|
-
structurally. The dashboard at `agents/roadmaps-progress.md` will
|
|
166
|
-
not regenerate on its own.
|
|
167
|
-
|
|
168
|
-
The cooperative path: every time a roadmap touch fires (per the
|
|
169
|
-
trigger list in the mechanics context above), the agent regenerates
|
|
170
|
-
the dashboard in the same response — which is the same Iron Law the
|
|
171
|
-
hook enforces, just executed manually:
|
|
172
|
-
|
|
173
|
-
```bash
|
|
174
|
-
./agent-config roadmap:progress
|
|
175
|
-
```
|
|
14
|
+
**Iron Law.** Any touch to `agents/roadmaps/` regenerates the dashboard in the same response; archive the roadmap when 0 open items remain.
|
|
176
15
|
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
it is a rule violation, not a hook gap — the Iron Law on dashboard
|
|
180
|
-
sync survives the missing hook surface.
|
|
16
|
+
Body migrated to `guideline:agent-infra/roadmap-progress-mechanics` (per P4 of `road-to-kernel-and-router.md`).
|
|
17
|
+
Trigger-set above activates this routing under the `balanced` and `full` profiles.
|
|
@@ -4,13 +4,17 @@ tier: "2a"
|
|
|
4
4
|
description: "When roles.active_role is set in .agent-settings.yml — closing outputs must match the mode's contract and emit the structured mode marker"
|
|
5
5
|
alwaysApply: false
|
|
6
6
|
source: package
|
|
7
|
+
triggers:
|
|
8
|
+
- keyword: "active_role"
|
|
9
|
+
- keyword: "role-mode"
|
|
10
|
+
- intent: "mode marker"
|
|
7
11
|
---
|
|
8
12
|
|
|
9
13
|
# Role Mode Adherence
|
|
10
14
|
|
|
11
15
|
Auto-activates when `.agent-settings.yml` sets `roles.active_role` to
|
|
12
16
|
one of the six modes defined in
|
|
13
|
-
[`role-contracts`](
|
|
17
|
+
[`role-contracts`](../docs/guidelines/agent-infra/role-contracts.md):
|
|
14
18
|
`developer`, `reviewer`, `tester`, `po`, `incident`, `planner`.
|
|
15
19
|
|
|
16
20
|
Read `roles.active_role` from `.agent-settings.yml` at session start. Empty / missing → rule is inert; do NOT guess a mode.
|
|
@@ -47,7 +51,7 @@ Infer the mode (Phase-3 router does that). Touch `.agent-settings.yml`
|
|
|
47
51
|
|
|
48
52
|
## See also
|
|
49
53
|
|
|
50
|
-
- [`role-contracts`](
|
|
54
|
+
- [`role-contracts`](../docs/guidelines/agent-infra/role-contracts.md)
|
|
51
55
|
- [`/mode`](../commands/mode.md)
|
|
52
56
|
- [`ask-when-uncertain`](ask-when-uncertain.md)
|
|
53
57
|
- [`scope-control`](scope-control.md)
|
|
@@ -2,74 +2,16 @@
|
|
|
2
2
|
type: "auto"
|
|
3
3
|
tier: "2a"
|
|
4
4
|
description: "Creating or editing rules, or auditing rule types — decides when a rule should be always vs auto"
|
|
5
|
-
alwaysApply: false
|
|
6
5
|
source: package
|
|
6
|
+
triggers:
|
|
7
|
+
- path_prefix: ".agent-src.uncompressed/rules/"
|
|
8
|
+
routes_to:
|
|
9
|
+
- "guideline:agent-infra/rule-type-governance"
|
|
7
10
|
---
|
|
8
11
|
|
|
9
|
-
#
|
|
12
|
+
# Rule Type Governance
|
|
10
13
|
|
|
11
|
-
|
|
14
|
+
**Iron Law.** Choose `always` vs `auto` per the governance table; over-broad `always` rules degrade the kernel budget.
|
|
12
15
|
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
- Universal agent behavior (language, tone, interaction style)
|
|
16
|
-
- Safety constraints (scope control, verification before completion)
|
|
17
|
-
- Token/efficiency constraints
|
|
18
|
-
- First-message checks that cannot wait for auto-trigger
|
|
19
|
-
|
|
20
|
-
## `auto` = loaded on demand by description match
|
|
21
|
-
|
|
22
|
-
Use for everything else:
|
|
23
|
-
|
|
24
|
-
- Language-specific rules (PHP, JS, SQL)
|
|
25
|
-
- Tool-specific rules (Docker, Git, quality tools)
|
|
26
|
-
- Workflow-specific rules (commands, skill creation, E2E testing)
|
|
27
|
-
- Domain-specific rules (translations, architecture)
|
|
28
|
-
|
|
29
|
-
## Decision test
|
|
30
|
-
|
|
31
|
-
> "Does this rule need to be active when the user asks a simple question, reviews a PR, or discusses architecture?"
|
|
32
|
-
|
|
33
|
-
- Yes → `always`
|
|
34
|
-
- No → `auto` with a clear trigger description
|
|
35
|
-
|
|
36
|
-
## Auto description quality
|
|
37
|
-
|
|
38
|
-
The `description` field IS the trigger. It must describe **when** the rule applies, not **what** it contains.
|
|
39
|
-
|
|
40
|
-
- ❌ `"PHP coding standards"` — too vague, won't match reliably
|
|
41
|
-
- ✅ `"Writing or reviewing PHP code — strict types, naming, Eloquent conventions"`
|
|
42
|
-
|
|
43
|
-
## Hard constraint
|
|
44
|
-
|
|
45
|
-
- Default to `auto`. Justify `always`.
|
|
46
|
-
- If >50% of conversations don't need a rule → it must be `auto`.
|
|
47
|
-
- `optimize-agents` command checks this and suggests changes.
|
|
48
|
-
|
|
49
|
-
## Hardening tier — required on new or edited rules
|
|
50
|
-
|
|
51
|
-
Every new rule, and every edited rule whose body changes the trigger
|
|
52
|
-
or the obligation, MUST classify itself against the hardening tiers
|
|
53
|
-
documented in [`rule-trigger-matrix.md`](../../agents/contexts/rule-trigger-matrix.md):
|
|
54
|
-
|
|
55
|
-
| Tier | Meaning |
|
|
56
|
-
|---|---|
|
|
57
|
-
| `1` | Mechanically enforceable — hook acts, rule body stays minimal. |
|
|
58
|
-
| `2a` | Marker nudge — hook injects signal, agent acts on it. |
|
|
59
|
-
| `2b` | Structured injection / tool-call gate — hook reads/writes state, may deny. |
|
|
60
|
-
| `3` | Soft, judgment-bound — no platform surface; self-check rule. |
|
|
61
|
-
| `safety-floor` | Iron-Law subset, never modified. |
|
|
62
|
-
| `mechanical-already` | Precedent — script enforces, rule body documents. |
|
|
63
|
-
|
|
64
|
-
Classification surface: the optional `tier:` frontmatter field
|
|
65
|
-
(declared in `scripts/schemas/rule.schema.json`). Recommended for new
|
|
66
|
-
rules; bulk-retrofit of existing rules is tracked separately.
|
|
67
|
-
|
|
68
|
-
Tier 3 dispositions are recorded centrally in
|
|
69
|
-
[`agents/contexts/tier-3-dispositions.md`](../../agents/contexts/tier-3-dispositions.md)
|
|
70
|
-
with a 6-month re-audit clock. New Tier 3 rules append to that list
|
|
71
|
-
on landing.
|
|
72
|
-
|
|
73
|
-
The `optimize-agents` command checks the tier alongside `type`/`source`
|
|
74
|
-
and suggests escalations when a rule's trigger matches a hardening
|
|
75
|
-
opportunity that has shipped since the rule was authored.
|
|
16
|
+
Body migrated to `guideline:agent-infra/rule-type-governance` (per P4 of `road-to-kernel-and-router.md`).
|
|
17
|
+
Trigger-set above activates this routing under the `balanced` and `full` profiles.
|
|
@@ -3,6 +3,11 @@ type: auto
|
|
|
3
3
|
tier: "2b"
|
|
4
4
|
source: package
|
|
5
5
|
description: "When a skill declares execution metadata — enforce safety constraints for assisted and automated execution types"
|
|
6
|
+
triggers:
|
|
7
|
+
- keyword: "execution"
|
|
8
|
+
- keyword: "automated"
|
|
9
|
+
- keyword: "assisted"
|
|
10
|
+
- keyword: "handler"
|
|
6
11
|
---
|
|
7
12
|
|
|
8
13
|
# Runtime Safety
|
|
@@ -5,7 +5,7 @@ description: "Scope control — no unsolicited architectural changes, refactors,
|
|
|
5
5
|
alwaysApply: true
|
|
6
6
|
source: package
|
|
7
7
|
load_context:
|
|
8
|
-
-
|
|
8
|
+
- ../contexts/authority/scope-mechanics.md
|
|
9
9
|
---
|
|
10
10
|
|
|
11
11
|
# Scope Control
|
|
@@ -14,73 +14,35 @@ load_context:
|
|
|
14
14
|
- Do NOT replace existing patterns with alternatives.
|
|
15
15
|
- Do NOT refactor existing code solely to comply with current rules.
|
|
16
16
|
- Do NOT suggest new libraries unless explicitly requested.
|
|
17
|
-
-
|
|
18
|
-
- New
|
|
19
|
-
- Stay within
|
|
20
|
-
- When unsure about
|
|
17
|
+
- Modify existing code only when directly related to the current change, required for bug fixes / security, or explicitly requested.
|
|
18
|
+
- New / modified code MUST follow all coding rules.
|
|
19
|
+
- Stay within established project structure and conventions.
|
|
20
|
+
- When unsure about scope, ask the user.
|
|
21
21
|
|
|
22
22
|
## Git operations — permission-gated
|
|
23
23
|
|
|
24
|
-
The user decides the git shape
|
|
25
|
-
|
|
26
|
-
> **Commit specifics:** see the canonical [`commit-policy`](commit-policy.md)
|
|
27
|
-
> rule — narrower than the general "no git ops without permission"
|
|
28
|
-
> below (covers the never-ask-about-committing default and the
|
|
29
|
-
> roadmap-authorized exception).
|
|
24
|
+
The user decides the git shape. Never improvise. Commit specifics: canonical [`commit-policy`](commit-policy.md).
|
|
30
25
|
|
|
31
26
|
- NEVER commit, push, merge, rebase, or force-push without explicit user permission.
|
|
32
|
-
- NEVER create a
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
- NEVER
|
|
36
|
-
|
|
37
|
-
- NEVER push a tag or create a release without explicit user permission.
|
|
38
|
-
- NEVER include version numbers, target releases, deprecation dates,
|
|
39
|
-
release-tied milestones, or git tags inside roadmaps, plans, tickets,
|
|
40
|
-
or any other planning artifact. Roadmaps plan **work**; releases and
|
|
41
|
-
tags are a separate decision the user makes outside the roadmap.
|
|
42
|
-
Never surface "which release should this ship in?" as an option in
|
|
43
|
-
numbered choices, ADRs, or roadmap text. If the user wants a release
|
|
44
|
-
pinned to a milestone, they will say so explicitly.
|
|
45
|
-
- If a task seems to need a separate branch or PR, STOP and **brief
|
|
46
|
-
the user before asking** — see
|
|
47
|
-
[`scope-mechanics`](../contexts/authority/scope-mechanics.md)
|
|
48
|
-
§ Brief-before-asking for the required Why / What / How sequence.
|
|
27
|
+
- NEVER create / switch / delete a branch without explicit permission — includes spike, scratch, throwaway, worktree branches.
|
|
28
|
+
- NEVER create, close, reopen, or change the target of a pull request without permission.
|
|
29
|
+
- NEVER push a tag or create a release without permission.
|
|
30
|
+
- NEVER include version numbers, target releases, deprecation dates, release-tied milestones, or git tags in roadmaps, plans, tickets, or any planning artifact. Roadmaps plan **work**; releases / tags are a separate decision outside the roadmap. Never surface "which release should this ship in?" as a numbered choice. User pins by saying so explicitly.
|
|
31
|
+
- Task seems to need a separate branch / PR → STOP and **brief before asking** ([`scope-mechanics § Brief-before-asking`](../contexts/authority/scope-mechanics.md)).
|
|
49
32
|
|
|
50
|
-
"Explicit permission"
|
|
51
|
-
standing instruction they have not revoked**. Earlier permission for a
|
|
52
|
-
different operation does not carry over.
|
|
33
|
+
"Explicit permission" = user said so **this turn or in a standing instruction not yet revoked**. Earlier permission for a different operation does not carry over.
|
|
53
34
|
|
|
54
35
|
## Production, infrastructure, bulk-destructive — Hard Floor
|
|
55
36
|
|
|
56
|
-
A subset
|
|
57
|
-
auto-permitted by a standing autonomy directive. Canonical rule:
|
|
58
|
-
[`non-destructive-by-default`](non-destructive-by-default.md). The
|
|
59
|
-
trigger list (production-branch merges, deploys / releases, prod
|
|
60
|
-
data / infra, bulk-destructive ops) and the
|
|
61
|
-
"authorization is this turn, not earlier" clarification live in
|
|
62
|
-
[`scope-mechanics`](../contexts/authority/scope-mechanics.md)
|
|
63
|
-
§ Production, infrastructure, bulk-destructive.
|
|
37
|
+
A subset is **never** autonomous and never auto-permitted by a standing autonomy directive. Canonical: [`non-destructive-by-default`](non-destructive-by-default.md). Trigger list (prod-branch merges, deploys / releases, prod data / infra, bulk-destructive ops) and the "authorization is this turn, not earlier" clarification: [`scope-mechanics § Production, infrastructure, bulk-destructive`](../contexts/authority/scope-mechanics.md).
|
|
64
38
|
|
|
65
39
|
## Decline = silence — no re-asking on the same task
|
|
66
40
|
|
|
67
|
-
After the user **declines** a proposal (branch switch, PR creation,
|
|
68
|
-
tag/release entry, separate worktree, version pinning in a roadmap),
|
|
69
|
-
do **not** raise the same proposal again on the same task. The decline
|
|
70
|
-
stands until the user reopens the topic themselves.
|
|
71
|
-
|
|
72
|
-
Timing and "is this worth asking?" guidance lives in
|
|
73
|
-
[`scope-mechanics`](../contexts/authority/scope-mechanics.md)
|
|
74
|
-
§ Decline = silence — context.
|
|
41
|
+
After the user **declines** a proposal (branch switch, PR creation, tag/release entry, separate worktree, version pinning), do **not** raise it again on the same task. Decline stands until the user reopens the topic. Timing / "is this worth asking?": [`scope-mechanics § Decline = silence`](../contexts/authority/scope-mechanics.md).
|
|
75
42
|
|
|
76
43
|
## Fenced step — user-set review gates
|
|
77
44
|
|
|
78
|
-
|
|
79
|
-
yet"*, *"plan only"*, *"just write the roadmap, I'll review"*,
|
|
80
|
-
*"review first"*, *"erst Roadmap, ich schau drüber"*, *"nichts
|
|
81
|
-
implementieren"*, *"nur planen"*, *"erstmal nur X, dann ich"* — the
|
|
82
|
-
agent's reply is **the deliverable plus a handoff**, never the
|
|
83
|
-
deliverable plus *"shall we start?"*.
|
|
45
|
+
User explicitly fences off the next step — *"don't implement yet"*, *"plan only"*, *"just write the roadmap, I'll review"*, *"review first"*, *"erst Roadmap, ich schau drüber"*, *"nichts implementieren"*, *"nur planen"*, *"erstmal nur X, dann ich"* — reply is **the deliverable plus a handoff**, never deliverable plus *"shall we start?"*.
|
|
84
46
|
|
|
85
47
|
```
|
|
86
48
|
USER FENCED OFF EXECUTION → DELIVER + HAND BACK.
|
|
@@ -89,13 +51,6 @@ NO "READY TO IMPLEMENT?" RE-ASK.
|
|
|
89
51
|
NO "STARTEN WIR MIT PHASE 1?" PIVOT.
|
|
90
52
|
```
|
|
91
53
|
|
|
92
|
-
|
|
93
|
-
like `Decline = silence` above. Permitted follow-up questions on the
|
|
94
|
-
same turn cover **the deliverable** (adjust scope, fix wording, add a
|
|
95
|
-
section), never **its execution**.
|
|
54
|
+
Fence stands until the user reopens, exactly like `Decline = silence`. Permitted follow-up questions cover **the deliverable** (adjust scope, fix wording, add a section), never **its execution**.
|
|
96
55
|
|
|
97
|
-
|
|
98
|
-
delivery, hand-off-to-execution drift, inferring acceptance from a
|
|
99
|
-
thumbs-up) and the explicit bypass phrases that lift the fence, see
|
|
100
|
-
[`scope-mechanics`](../contexts/authority/scope-mechanics.md)
|
|
101
|
-
§ Fenced step.
|
|
56
|
+
Failure-mode catalog (Option 1 = "start now", re-asking after delivery, hand-off-to-execution drift, inferring acceptance from a thumbs-up) and explicit bypass phrases: [`scope-mechanics § Fenced step`](../contexts/authority/scope-mechanics.md).
|
|
@@ -4,6 +4,12 @@ tier: "2a"
|
|
|
4
4
|
alwaysApply: false
|
|
5
5
|
description: "Security-sensitive paths — auth, billing, tenant boundaries, secrets, file uploads, external integrations, webhooks, public endpoints — stop and run threat analysis BEFORE editing"
|
|
6
6
|
source: package
|
|
7
|
+
triggers:
|
|
8
|
+
- keyword: "auth"
|
|
9
|
+
- keyword: "billing"
|
|
10
|
+
- keyword: "tenant"
|
|
11
|
+
- keyword: "secret"
|
|
12
|
+
- keyword: "webhook"
|
|
7
13
|
---
|
|
8
14
|
|
|
9
15
|
# Security-Sensitive Stop Rule
|
|
@@ -43,7 +49,7 @@ STOP writing code. Run the matching analysis skill first:
|
|
|
43
49
|
| Wide refactor of security-sensitive code | `blast-radius-analyzer` |
|
|
44
50
|
|
|
45
51
|
**Before running the analysis, consult memory for prior incidents** on
|
|
46
|
-
this surface. Via [`memory-access`](
|
|
52
|
+
this surface. Via [`memory-access`](../docs/guidelines/agent-infra/memory-access.md):
|
|
47
53
|
|
|
48
54
|
```python
|
|
49
55
|
from scripts.memory_lookup import retrieve
|