@event4u/agent-config 2.8.0 → 2.9.0

package/scripts/agent-config

@@ -62,17 +62,6 @@ Tier 0 — daily-driver (init → sync → validate → work):
                              (Option-A loop; called by the /work command)
   implement-ticket           Drive the work_engine Python engine on a ticket envelope
                              (Option-A loop; called by the /implement-ticket command)
-  first-run                  Guided first-run setup — cost profile, settings, tooling
-  keys:install-anthropic     Install the Anthropic API key for the AI Council
-                             (interactive, /dev/tty only, writes ~/.config/agent-config/anthropic.key 0600)
-  keys:install-openai        Install the OpenAI API key for the AI Council
-                             (interactive, /dev/tty only, writes ~/.config/agent-config/openai.key 0600)
-  council:estimate           Pre-call council cost preview (no API call, no spend)
-                             Usage: council:estimate <question> [--input-mode prompt|roadmap]
-  council:run                Run the council. Requires --confirm to spend.
-                             Usage: council:run <question> --output <path> --confirm
-  council:render             Re-render a saved council responses JSON to markdown
-                             Usage: council:render <responses.json>
   help                       Show this help (default Tier-0; --tier=1|all expands)
   --version, -V              Print package version
 EOF
@@ -110,6 +99,17 @@ Tier 1 — power-user (release shape, audit, migration):
                              Flags: --json | --project=<path>
   migrate                    One-shot migration off legacy composer / npm install paths
                              Flags: --dry-run (detect only)
+  first-run                  Guided first-run setup — cost profile, settings, tooling
+  keys:install-anthropic     Install the Anthropic API key for the AI Council
+                             (interactive, /dev/tty only, writes ~/.config/agent-config/anthropic.key 0600)
+  keys:install-openai        Install the OpenAI API key for the AI Council
+                             (interactive, /dev/tty only, writes ~/.config/agent-config/openai.key 0600)
+  council:estimate           Pre-call council cost preview (no API call, no spend)
+                             Usage: council:estimate <question> [--input-mode prompt|roadmap]
+  council:run                Run the council. Requires --confirm to spend.
+                             Usage: council:run <question> --output <path> --confirm
+  council:render             Re-render a saved council responses JSON to markdown
+                             Usage: council:render <responses.json>
 EOF
   fi
 
@@ -124,6 +124,7 @@ Tier 2 — maintenance / internal (hooks, MCP, memory, telemetry):
                              (one-line MCP server onboarding; idempotent)
   mcp:run                    Run the built-in MCP server over stdio
                              (requires `mcp:setup` first; see docs/mcp-server.md)
+                             (experimental — beta gates: docs/contracts/mcp-beta-criteria.md)
   roadmap:progress           Regenerate agents/roadmaps-progress.md from open roadmaps
   roadmap:progress-check     Fail if agents/roadmaps-progress.md is stale (for CI)
   hooks:install              Install the pre-commit roadmap-progress hook
@@ -161,7 +162,7 @@ EOF
   if [[ "$tier" == "0" ]]; then
     cat <<'EOF'
 
-(Hidden: 9 Tier-1 + 26 Tier-2 commands. Run `./agent-config --help --tier=1`
+(Hidden: 15 Tier-1 + 26 Tier-2 commands. Run `./agent-config --help --tier=1`
 or `--tier=all` to see them. Tier criteria: docs/contracts/command-surface-tiers.md.)
 EOF
   fi
@@ -173,14 +174,8 @@ Examples (Tier 0):
   ./agent-config sync --dry-run
   ./agent-config sync
   ./agent-config validate
-  ./agent-config first-run
   ./agent-config work --state-file .work-state.json --prompt-file prompt.txt
   ./agent-config implement-ticket --state-file .work-state.json
-  ./agent-config keys:install-anthropic
-  ./agent-config keys:install-openai
-  ./agent-config council:estimate prompt.txt
-  ./agent-config council:run prompt.txt --output agents/council-sessions/out.json --confirm
-  ./agent-config council:render agents/council-sessions/out.json
 EOF
 
   if [[ "$tier" == "1" || "$tier" == "all" ]]; then
@@ -203,6 +198,12 @@ Examples (Tier 1):
   ./agent-config versions --json
   ./agent-config init --offline --tools=claude-code,cursor --yes
   ./agent-config update --offline --to=2.2.0
+  ./agent-config first-run
+  ./agent-config keys:install-anthropic
+  ./agent-config keys:install-openai
+  ./agent-config council:estimate prompt.txt
+  ./agent-config council:run prompt.txt --output agents/council-sessions/out.json --confirm
+  ./agent-config council:render agents/council-sessions/out.json
 EOF
   fi
 

package/scripts/install.py

@@ -105,6 +105,11 @@ def warn(msg: str) -> None:
 
 def fail(msg: str) -> "None":
     print(f"  ❌  {msg}", file=sys.stderr)
+    print(
+        "      Diagnose: `./agent-config doctor` "
+        "(or `--check <id>` for a single category)",
+        file=sys.stderr,
+    )
     sys.exit(1)
 
 

package/scripts/lint_context_spine_usage.py

@@ -34,6 +34,7 @@ SKILL_GLOBS = (
 VALID_SLOTS = (
     "product", "team", "repo",
     "channel-stage", "funnel-stage", "customer-segment",
+    "fiscal-period", "org-stage", "regulatory-regime",
 )
 
 CONTEXT_SPINE_PAT = re.compile(

package/scripts/mcp_server/__init__.py

@@ -11,6 +11,7 @@ boundary in `agents/roadmaps/road-to-mcp-server.md`. No `tools`
 primitive, no engine spawn, no shell execution.
 
 Stability: experimental. Contract: `docs/contracts/mcp-phase-1-scope.md`.
+Promotion to beta gated on `docs/contracts/mcp-beta-criteria.md`.
 """
 from __future__ import annotations
 

package/scripts/mcp_server/server.py

@@ -125,9 +125,10 @@ def build_server(
         name=SERVER_NAME,
         version=__version__,
         instructions=(
-            "agent-config MCP server (Phase 3, experimental). Exposes "
-            "all skills + commands as instructional prompts, plus "
-            "rules + guidelines + contexts as read-only resources."
+            "agent-config MCP server (Phase 3, experimental; beta gates "
+            "in docs/contracts/mcp-beta-criteria.md). Exposes all skills "
+            "+ commands as instructional prompts, plus rules + guidelines "
+            "+ contexts as read-only resources."
         ),
     )
 

package/scripts/schemas/skill.schema.json

@@ -72,9 +72,9 @@
       "uniqueItems": true,
       "items": {
         "type": "string",
-        "enum": ["product", "team", "repo", "channel-stage", "funnel-stage", "customer-segment"]
+        "enum": ["product", "team", "repo", "channel-stage", "funnel-stage", "customer-segment", "fiscal-period", "org-stage", "regulatory-regime"]
       },
-      "description": "Senior-skill opt-in for the context spine. Declares which slots under agents/context-spine/ the skill expects to read. Cross-wing slots (product, team, repo) are locked at 3 by council Q1 (KEEP-3); wing-scoped slots (channel-stage, funnel-stage, customer-segment — Wing-3 GTM) follow the per-wing ADR track in docs/contracts/context-spine.md § 5. Wing-3 slots authorized by docs/contracts/adr-gtm-context-spine.md."
+      "description": "Senior-skill opt-in for the context spine. Declares which slots under agents/context-spine/ the skill expects to read. Cross-wing slots (product, team, repo) are locked at 3 by council Q1 (KEEP-3); wing-scoped slots follow the per-wing ADR track in docs/contracts/context-spine.md § 5. Wing-3 (channel-stage, funnel-stage, customer-segment) authorized by docs/contracts/adr-gtm-context-spine.md; Wing-4 (fiscal-period, org-stage, regulatory-regime) authorized by docs/contracts/adr-wing4-context-spine.md."
     },
     "execution": {
       "type": "object",

package/scripts/skill_linter.py

@@ -211,6 +211,48 @@ WING3_CHANNEL_TACTIC_PATTERN = re.compile(
     re.IGNORECASE,
 )
 
+# --- Wing-4 Money/Strategy/Ops cognition-boundary patterns (council Q7 / J2) ---
+# Triggered only when a skill's context_spine declares a Wing-4 slot.
+# See docs/contracts/adr-wing4-context-spine.md and
+# agents/roadmaps/road-to-money-strategy-ops.md § J2.
+WING4_SPINE_SLOTS = {"fiscal-period", "org-stage", "regulatory-regime"}
+
+# agent-operability: external finance / HR / legal SaaS URLs
+WING4_SAAS_URL_PATTERN = re.compile(
+    r"https?://[\w.-]*\.(quickbooks|intuit|netsuite|xero|sage|"
+    r"carta|pulley|gusto|bamboohr|lattice|15five|justworks|"
+    r"docusign|ironclad|onetrust|rippling|workday|deel|"
+    r"namely|adp|paychex|trinet|hibob|cultureamp)\.(com|io|co)\b",
+    re.IGNORECASE,
+)
+
+# vendor-independence: finance / HR / legal brand / SDK slugs
+WING4_VENDOR_BLACKLIST = re.compile(
+    r"\b(quickbooks|netsuite|xero|sage intacct|"
+    r"carta|pulley|gusto|bamboohr|lattice|15five|justworks|"
+    r"docusign|ironclad|onetrust|rippling|workday|deel|"
+    r"namely|adp|paychex|trinet|hibob|culture amp)\b",
+    re.IGNORECASE,
+)
+
+# stage-agnosticism: prescriptive stage-specific thresholds that lock cognition
+# Catches hardcoded runway / ARR / burn / team-size prescriptions tied to a
+# specific funding stage. Framework-style framing ("read the org-stage slot",
+# "applies across seed and public") passes; hard prescriptions ("18 months of
+# runway", "Series A teams must hire") fire.
+WING4_STAGE_AGNOSTIC_PATTERN = re.compile(
+    r"(?:"
+    r"\b\d+\s+months?\s+of\s+runway\b"
+    r"|\brunway\s+of\s+at\s+least\s+\d+\s+months?\b"
+    r"|\bminimum\s+runway\s+of\s+\d+\b"
+    r"|\b(?:seed|series\s+[a-d]|growth|pre-?ipo|post-?ipo)[-\s]stage\s+"
+    r"(?:companies|startups|teams|founders|orgs)\s+(?:must|should|always|never)\b"
+    r"|\bteam\s+of\s+\d+\s+(?:or\s+more|or\s+fewer)\b"
+    r"|\b(?:arr|mrr|burn\s+rate)\s+(?:of|over|under|above|below)\s+\$\d+"
+    r")",
+    re.IGNORECASE,
+)
+
 
 @dataclass
 class Issue:
@@ -619,9 +661,9 @@ def lint_skill(path: Path, text: str) -> LintResult:
     skill_name = path.parent.name if path.name == "SKILL.md" else path.stem
     if skill_name and "-" not in skill_name and len(skill_name) >= 3:
         # Single word without qualifier — likely too generic
-        ALLOWED_BARE_NOUNS = {"database", "devcontainer", "docker", "eloquent", "flux", "grafana",
-                              "laravel", "livewire", "mcp", "openapi", "performance", "security",
-                              "terraform", "terragrunt", "traefik", "websocket"}
+        ALLOWED_BARE_NOUNS = {"database", "devcontainer", "docker", "eloquent", "flux", "forecasting",
+                              "grafana", "laravel", "livewire", "mcp", "openapi", "performance",
+                              "security", "terraform", "terragrunt", "traefik", "websocket"}
         if skill_name.lower() not in ALLOWED_BARE_NOUNS:
             issues.append(Issue("warning", "bare_noun_name",
                                 f"Bare-noun skill name `{skill_name}` — consider adding a qualifier (e.g., `{skill_name}-management`)"))
@@ -660,6 +702,10 @@ def lint_skill(path: Path, text: str) -> LintResult:
         if spine_slots and any(s in WING3_SPINE_SLOTS for s in spine_slots):
             issues.extend(lint_wing3_boundaries(text))
 
+        # --- Wing-4 Money/Strategy/Ops cognition-boundary check (council Q7 / J2) ---
+        if spine_slots and any(s in WING4_SPINE_SLOTS for s in spine_slots):
+            issues.extend(lint_wing4_boundaries(text))
+
     procedure_block = find_procedure_block(text)
     if procedure_block is not None:
         if not procedure_block:
@@ -1140,6 +1186,64 @@ def lint_wing3_boundaries(text: str) -> List[Issue]:
     return issues
 
 
+def lint_wing4_boundaries(text: str) -> List[Issue]:
+    """Four Wing-4 Money/Strategy/Ops cognition-boundary checks.
+
+    Triggered when a skill's ``context_spine`` declares at least one
+    Wing-4 slot (fiscal-period, org-stage, regulatory-regime). Enforces
+    council Q7 / J2 verdict that Money/Strategy/Ops cognition stays:
+
+    - **agent-operability** — no external finance/HR/legal SaaS URLs.
+    - **vendor-independence** — no QuickBooks/Carta/Gusto-class brand slugs.
+    - **transferability** — no stack-locked tooling instructions.
+    - **stage-agnosticism** — no prescriptive stage-specific thresholds.
+
+    Carve-outs are identical to Wing-3: fenced code, inline backticks,
+    the ``## Do NOT`` block, and ``**WHEN NOT to use this**`` lists.
+    Regulatory regime names (GDPR / HIPAA / SOC2 / PCI / CCPA) are
+    cognition-relevant constraints, not vendors — they pass.
+    """
+    issues: List[Issue] = []
+    body = _strip_wing3_carve_outs(text)
+
+    match = WING4_SAAS_URL_PATTERN.search(body)
+    if match:
+        issues.append(Issue(
+            "warning", "wing4_agent_operability",
+            f"Wing-4 skill cites external SaaS URL `{match.group(0)}` outside "
+            f"carve-outs — cognition skills must operate without SaaS auth "
+            f"(council Q7 boundary)",
+        ))
+
+    match = WING4_VENDOR_BLACKLIST.search(body)
+    if match:
+        issues.append(Issue(
+            "warning", "wing4_vendor_independence",
+            f"Wing-4 skill names vendor `{match.group(0)}` outside carve-outs "
+            f"— keep cognition vendor-agnostic (council Q7 boundary)",
+        ))
+
+    match = WING3_STACK_LOCKED_PATTERN.search(body)
+    if match:
+        issues.append(Issue(
+            "warning", "wing4_transferability",
+            f"Wing-4 skill includes stack-locked instruction `{match.group(0)}` "
+            f"outside carve-outs — cognition should transfer across stacks "
+            f"(council Q7 boundary)",
+        ))
+
+    match = WING4_STAGE_AGNOSTIC_PATTERN.search(body)
+    if match:
+        issues.append(Issue(
+            "warning", "wing4_stage_agnosticism",
+            f"Wing-4 skill prescribes stage-locked threshold "
+            f"`{match.group(0)}` outside carve-outs — cognition must "
+            f"transfer across seed and public (council Q7 boundary)",
+        ))
+
+    return issues
+
+
 def lint_execution_metadata(execution: dict) -> List[Issue]:
     """Validate the execution block of a skill."""
     issues: List[Issue] = []