Merge branch 'ChesterRa:main' into main

Author: howold-lab

docs/release/v0.4.6_release_notes.md

@@ -1,47 +1,77 @@
 # CCCC v0.4.6 Release Notes
 
-`v0.4.6` is a smaller quality release focused on operator discipline and agent behavior rather than new product surface area.
+`v0.4.6` builds on `v0.4.5` with a broader set of improvements than a pure prompt/preset polish release.
 
-It strengthens the built-in role presets with higher-signal planning, review, debugging, and implementation rules, while keeping the core prompt stack compact and predictable.
+Compared with `v0.4.5`, this version extends IM bridge coverage, tightens Web-side context and cache behavior, introduces the first built-in role preset workflow, and hardens startup/shutdown behavior further across Windows and the supervised Web runtime.
 
 ## Highlights
 
-## 1) Built-in role presets are more rigorous
+## 1) WeCom IM bridge support is now real and documented
 
-This release upgrades the first-wave built-in role presets with stronger execution discipline harvested from high-quality external prompt patterns.
+The biggest functional addition in `v0.4.6` is WeCom bridge support.
+
+Key changes:
+
+- a dedicated WeCom adapter was added instead of trying to force everything through the older bridge path
+- Web-side IM bridge settings were extended so WeCom can be configured from the same operator surface as other bridge providers
+- authentication and readiness behavior for the bridge were repaired and covered by targeted tests
+- the docs now include a dedicated WeCom guide and screenshots for the operator flow
+
+This matters because `v0.4.5` still treated IM bridge support as narrower and more uneven in practice. `v0.4.6` makes WeCom a real supported path instead of a partial edge lane.
+
+## 2) Web context and cache behavior are tighter and less wasteful
+
+`v0.4.6` also improves how the Web surface reads and refreshes shared control-plane state.
 
 Key improvements:
 
-- planners now push harder on existing-code leverage, minimum viable scope, and complete-vs-shortcut tradeoffs
-- implementers are pushed more explicitly to finish the real blast radius in one pass, including nearby tests, docs, and obvious edge-case handling
-- reviewers are stricter about reading the full diff first and checking whether docs, diagrams, or adjacent tests went stale
-- debuggers are more firmly rooted in regression checks, hypothesis confirmation, and regression-test follow-through
-- explorers are better at separating true canonical anchor files from nearby noise
+- actor and context route caching is more deliberate and more thoroughly tested
+- cache invalidation after writes is less fragile, which reduces stale readback after actor/context updates
+- related API/client/store coverage was expanded significantly so the Web state layer is less likely to drift silently
+- surrounding settings and control surfaces were cleaned up so context-related interactions behave more predictably
+
+This is not a flashy feature, but it is a meaningful quality improvement over `v0.4.5` because it reduces a class of “the write succeeded but the UI still feels stale or noisy” problems.
+
+## 3) Built-in role presets and prompt discipline landed
+
+This release introduces the first built-in role preset workflow in the Web actor surfaces and strengthens the default collaboration guidance around those roles.
+
+Highlights:
+
+- built-in role presets were added for the first-wave roster, including planner, implementer, reviewer, debugger, explorer, and related roles
+- preset application now gives actors a faster way to start from a strong role note instead of writing everything from scratch
+- the prompt/help surface was tightened so startup guidance stays lean while richer discipline lives in the longer-lived help/preset layers
+- planning, implementation, review, and debugging guidance are now sharper about things like existing-code leverage, full-diff-first review, regression thinking, and one-pass blast-radius cleanup
 
-## 2) The startup prompt stays lean, but a bit smarter
+Relative to `v0.4.5`, this is the biggest day-to-day agent-behavior improvement in the release.
 
-`v0.4.6` keeps the startup preamble compact while sharpening one important default:
+## 4) Windows and runtime lifecycle handling were hardened again
 
-- actors are nudged to reuse working paths first instead of inventing parallel ones
+`v0.4.5` already improved startup and shutdown behavior. `v0.4.6` continues that line with another pass of runtime hardening.
 
-This is intentionally a small change. The goal is to improve default judgment without making the startup prompt bloated again.
+Important changes:
 
-## 3) Built-in help now has a safer growth budget
+- Windows shutdown cleanup was tightened further so lingering process/lifecycle edge cases are handled more reliably
+- daemon/Web supervised runtime ownership and cleanup paths were hardened with additional lifecycle coverage
+- Web readiness checks now tolerate more real failure modes, including `OSError` and `HTTPException`, instead of surfacing brittle behavior
+- process-path handling and related platform-sensitive helpers received more validation, especially around mocked Windows path resolution and runtime probing
 
-The built-in help surface remains compact, but the enforced ceiling is relaxed from `1300` to `1500` words.
+This makes `v0.4.6` a stronger operational release than `v0.4.5`, especially if you are running CCCC on Windows or frequently exercising stop/start/restart flows.
 
-Why this matters:
+## 5) Quality bar and verification
 
-- it preserves a hard anti-bloat boundary
-- it leaves room for a few more genuinely universal rules in future iterations
-- it avoids treating the previous `1300` test limit as a product law when it was really just a local compactness guardrail
+Beyond the visible changes above, `v0.4.6` also includes:
 
-## 4) Release readiness stayed clean
+- additional tests around Web cache behavior and stores
+- stronger coverage for IM bridge startup/config flows
+- targeted prompt-default and role-preset tests so the new guidance surfaces are less likely to regress silently
+- follow-up lint/typecheck cleanup after the role preset work landed
 
-This version is intentionally small in scope, and the main goal was to land the quality improvements without reopening broader workflow or UI churn.
+In short, `v0.4.6` is not just “the preset release.” It is the release that combines:
 
-Validation included:
+1. WeCom bridge support
+2. better Web context/cache behavior
+3. the first built-in role preset workflow
+4. another round of Windows/runtime hardening
 
-- Python test suite passing cleanly
-- targeted prompt-default tests passing after the compactness-budget change
-- Web lint and type-check remaining clean alongside the role-preset text updates
+relative to the `v0.4.5` baseline.

src/cccc/daemon/ops/capability_ops/_handlers.py

@@ -8,7 +8,7 @@
 from typing import Any, Dict, List, Optional, Tuple
 
 from ....contracts.v1 import DaemonResponse
-from ....kernel.capabilities import BUILTIN_CAPABILITY_PACKS
+from ....kernel.capabilities import BUILTIN_CAPABILITY_PACKS, BUILTIN_CAPSULE_SKILLS
 from ....util.time import parse_utc_iso, utc_now_iso
 
 from ._common import (
@@ -268,11 +268,58 @@ def _build_curated_records_from_policy(policy: Dict[str, Any]) -> Dict[str, Dict
     return out
 
 
+def _build_builtin_skill_records() -> Dict[str, Dict[str, Any]]:
+    now_iso = utc_now_iso()
+    out: Dict[str, Dict[str, Any]] = {}
+    for cap_id, raw in BUILTIN_CAPSULE_SKILLS.items():
+        if not isinstance(raw, dict):
+            continue
+        name = str(raw.get("name") or "").strip() or _display_name_from_capability_id(cap_id).replace(" ", "-")
+        description_short = str(raw.get("description_short") or "").strip()
+        capsule_text = str(raw.get("capsule_text") or "").strip()
+        tags = [str(x).strip() for x in (raw.get("tags") if isinstance(raw.get("tags"), (list, tuple)) else []) if str(x).strip()]
+        requires_capabilities = [
+            str(x).strip()
+            for x in (raw.get("requires_capabilities") if isinstance(raw.get("requires_capabilities"), (list, tuple)) else [])
+            if str(x).strip()
+        ]
+        out[cap_id] = {
+            "capability_id": cap_id,
+            "kind": "skill",
+            "name": name,
+            "description_short": description_short,
+            "tags": ["skill", "builtin", *tags],
+            "source_id": "cccc_builtin",
+            "source_tier": "builtin",
+            "source_uri": "",
+            "source_record_id": name,
+            "source_record_version": "",
+            "updated_at_source": now_iso,
+            "last_synced_at": now_iso,
+            "sync_state": "builtin",
+            "install_mode": "builtin",
+            "install_spec": {},
+            "requirements": {},
+            "license": "",
+            "trust_tier": "builtin",
+            "qualification_status": _QUAL_QUALIFIED,
+            "qualification_reasons": [],
+            "health_status": "builtin",
+            "enable_supported": True,
+            "capsule_text": capsule_text or f"Skill: {name}\nSummary: {description_short}".strip(),
+            "requires_capabilities": requires_capabilities,
+        }
+    return out
+
+
 def _ensure_curated_catalog_records(catalog_doc: Dict[str, Any], *, policy: Dict[str, Any]) -> bool:
     records = catalog_doc.get("records") if isinstance(catalog_doc.get("records"), dict) else {}
     if not isinstance(records, dict):
         records = {}
-    curated = _build_curated_records_from_policy(policy)
+    curated = {
+        **_build_builtin_skill_records(),
+        **_build_curated_records_from_policy(policy),
+    }
     if not curated:
         return False
 

src/cccc/daemon/ops/capability_ops/_search.py

@@ -11,8 +11,10 @@
 from ....kernel.actors import get_effective_role
 from ....kernel.capabilities import (
     BUILTIN_CAPABILITY_PACKS,
+    BUILTIN_CAPSULE_SKILLS,
     CORE_TOOL_NAMES,
     all_builtin_pack_ids,
+    all_builtin_skill_ids,
     resolve_visible_tool_names,
 )
 from ....kernel.context import ContextStorage
@@ -264,9 +266,64 @@ def _build_builtin_search_records() -> List[Dict[str, Any]]:
                 "tool_names": [str(x).strip() for x in tuple(pack.get("tool_names") or ()) if str(x).strip()],
             }
         )
+    for cap_id in all_builtin_skill_ids():
+        skill = BUILTIN_CAPSULE_SKILLS.get(cap_id, {})
+        out.append(
+            {
+                "capability_id": cap_id,
+                "kind": "skill",
+                "name": str(skill.get("name") or cap_id),
+                "description_short": str(skill.get("description_short") or ""),
+                "tags": list(skill.get("tags") or []),
+                "source_id": "cccc_builtin",
+                "source_tier": "builtin",
+                "source_uri": "",
+                "trust_tier": "builtin",
+                "qualification_status": "qualified",
+                "sync_state": "fresh",
+                "enable_supported": True,
+            }
+        )
     return out
 
 
+def _is_builtin_search_record(item: Dict[str, Any]) -> bool:
+    return str(item.get("source_id") or "").strip() == "cccc_builtin"
+
+
+def _skill_capsule_preview(value: Any, *, max_lines: int = 4, max_chars: int = 420) -> str:
+    text = str(value or "").strip()
+    if not text:
+        return ""
+    raw_lines = [str(raw or "").strip() for raw in text.splitlines() if str(raw or "").strip()]
+    if not raw_lines:
+        return ""
+    protocol_start = next(
+        (
+            idx
+            for idx, line in enumerate(raw_lines)
+            if str(line).strip().lower() in {"protocol:", "workflow:", "steps:", "playbook:"}
+        ),
+        -1,
+    )
+    if protocol_start >= 0:
+        selected = [line for line in raw_lines[protocol_start + 1 :] if line]
+    else:
+        selected = [
+            line
+            for line in raw_lines
+            if not str(line).strip().lower().startswith(("you are ", "use this skill "))
+        ]
+    if not selected:
+        selected = list(raw_lines)
+    merged = "\n".join(selected[:max_lines])
+    if len(merged) <= max_chars:
+        return merged
+    if max_chars <= 3:
+        return merged[:max_chars]
+    return merged[: max_chars - 3].rstrip() + "..."
+
+
 def _search_matches(query: str, item: Dict[str, Any]) -> bool:
     q = str(query or "").strip().lower()
     if not q:
@@ -581,7 +638,7 @@ def _rank(row: Dict[str, Any]) -> Tuple[int, int, int, str]:
             recent_count = int(recent.get("success_count") or 0)
             recent_ts = str(recent.get("last_success_at") or "")
             cap_id = str(row.get("capability_id") or "")
-            builtin_bias = 0 if cap_id.startswith("pack:") else 1
+            builtin_bias = 0 if _is_builtin_search_record(row) else 1
             return (
                 blocked_penalty,
                 builtin_bias,
@@ -883,7 +940,7 @@ def handle_capability_search(args: Dict[str, Any]) -> DaemonResponse:
 
         def _rank(item: Dict[str, Any]) -> Tuple[int, int, int, int, int, str]:
             cap_id = str(item.get("capability_id") or "")
-            is_builtin = 0 if cap_id.startswith("pack:") else 1
+            is_builtin = 0 if _is_builtin_search_record(item) else 1
             name_key = str(item.get("name") or cap_id).lower()
             enabled_bias = 0 if cap_id in enabled_set else 1
             qualification = str(item.get("qualification_status") or "").strip().lower()
@@ -1285,6 +1342,7 @@ def _scope_mismatch_for_capability(capability_id: str) -> bool:
                     "capability_id": cap_id,
                     "name": str(rec.get("name") or cap_id),
                     "description_short": str(rec.get("description_short") or ""),
+                    "capsule_preview": _skill_capsule_preview(rec.get("capsule_text")),
                     "source_id": str(rec.get("source_id") or ""),
                     "source_uri": str(rec.get("source_uri") or ""),
                     "policy_level": _effective_policy_level(
@@ -1309,6 +1367,7 @@ def _scope_mismatch_for_capability(capability_id: str) -> bool:
                     "capability_id": cap_id,
                     "name": str(rec.get("name") or cap_id),
                     "description_short": str(rec.get("description_short") or ""),
+                    "capsule_preview": _skill_capsule_preview(rec.get("capsule_text")),
                     "source_id": str(rec.get("source_id") or ""),
                     "policy_level": _effective_policy_level(
                         policy,