@ahmed-g-gad/apothem 0.1.1

package/src/apothem/conformity/workflow_concurrency_grep.py

@@ -0,0 +1,283 @@
+# SPDX-License-Identifier: MIT
+
+"""Enforce concurrency + per-job timeout discipline on GitHub workflows.
+
+Why this validator exists. The workflow reliability contract requires
+every push- or pull_request-triggered workflow to declare a top-level
+``concurrency:`` block (to coalesce redundant runs on the same ref)
+AND every job declares a
+``timeout-minutes:`` ceiling (to prevent runaway jobs from monopolising
+the runner pool). Deployment-class workflows (release / publish /
+deploy) reverse the cancellation polarity: mid-deploy cancellation
+risks partial-state hazards, so ``cancel-in-progress: false`` is
+mandatory.
+
+Detection. Walk ``<root>/.github/workflows/*.yml``. For each workflow:
+
+1. Inspect ``on:`` for ``push`` or ``pull_request`` triggers; skip
+   workflows without either (manual / scheduled workflows are out of
+   scope for concurrency discipline).
+2. Require a top-level ``concurrency:`` mapping with a ``group:`` key
+   and a ``cancel-in-progress:`` flag.
+3. For deployment workflows (filename matches ``*release*`` /
+   ``*publish*`` / ``*deploy*``) require ``cancel-in-progress: false``;
+   for all others require ``cancel-in-progress: true``.
+4. For every job in ``jobs:``, require ``timeout-minutes:`` with
+   ``N <= 30`` (short jobs) or ``N <= 90`` (full-matrix jobs — detected
+   heuristically via the presence of a ``strategy.matrix`` block).
+
+Drift classes. ``missing-concurrency-block``,
+``missing-cancel-in-progress-flag``, ``cancel-in-progress-wrong-value``,
+``missing-job-timeout``, ``job-timeout-exceeds-ceiling``.
+
+Tolerance. When ``<root>/.github/workflows/`` does not exist, exit 0 with
+``not-yet-materialised: true`` — the workflows tree has not been
+authored yet and the discipline does not yet apply.
+
+Exit semantics. Exits 0 when every inspected workflow is conformant;
+exits 2 with a JSON enumeration of per-workflow + per-job drift when
+any drift is detected.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any, Final
+
+import yaml
+
+GREP_NAME: Final[str] = "workflow-concurrency-grep"
+RULE_ANCHOR: Final[str] = "workflow concurrency + per-job timeouts"
+
+EXIT_PASS: Final[int] = 0
+EXIT_FAIL: Final[int] = 2
+
+SHORT_JOB_CEILING_MINUTES: Final[int] = 30
+FULL_MATRIX_JOB_CEILING_MINUTES: Final[int] = 90
+
+DEPLOYMENT_NAME_MARKERS: Final[tuple[str, ...]] = ("release", "publish", "deploy")
+
+
+@dataclass(frozen=True)
+class Finding:
+    """One concurrency / timeout drift instance inside a workflow."""
+
+    workflow: str
+    job: str | None
+    drift_class: str
+    detail: str
+    rule: str = RULE_ANCHOR
+
+
+@dataclass(frozen=True)
+class GrepResult:
+    grep: str
+    root: str
+    not_yet_materialised: bool
+    workflow_count: int
+    passed: bool
+    findings: list[Finding] = field(default_factory=list)
+
+    def to_json(self) -> str:
+        payload: dict[str, Any] = {
+            "grep": self.grep,
+            "root": self.root,
+            "not-yet-materialised": self.not_yet_materialised,
+            "workflow-count": self.workflow_count,
+            "passed": self.passed,
+            "findings": [asdict(f) for f in self.findings],
+        }
+        return json.dumps(payload, indent=2)
+
+
+def _is_deployment_workflow(path: Path) -> bool:
+    """Detect deployment-class workflows by filename marker."""
+    stem = path.stem.lower()
+    return any(marker in stem for marker in DEPLOYMENT_NAME_MARKERS)
+
+
+def _has_push_or_pr_trigger(on_block: object) -> bool:
+    """Return True iff ``on:`` declares a push or pull_request trigger.
+
+    The ``on:`` key admits multiple shapes — a string (``on: push``), a
+    list (``on: [push, pull_request]``), or a mapping (``on: {push: {...}}``).
+    """
+    if isinstance(on_block, str):
+        return on_block in ("push", "pull_request")
+    if isinstance(on_block, list):
+        return any(t in ("push", "pull_request") for t in on_block)
+    if isinstance(on_block, dict):
+        return "push" in on_block or "pull_request" in on_block
+    return False
+
+
+def _job_is_full_matrix(job: dict[str, Any]) -> bool:
+    """Heuristic: a job carrying ``strategy.matrix`` is a full-matrix job."""
+    strategy = job.get("strategy")
+    if not isinstance(strategy, dict):
+        return False
+    return "matrix" in strategy
+
+
+def _check_workflow(path: Path) -> list[Finding]:
+    """Inspect one workflow file; return its drift findings."""
+    findings: list[Finding] = []
+    workflow_name = path.name
+    try:
+        doc = yaml.safe_load(path.read_text(encoding="utf-8"))
+    except yaml.YAMLError as exc:
+        findings.append(
+            Finding(
+                workflow=workflow_name,
+                job=None,
+                drift_class="yaml-parse-error",
+                detail=f"failed to parse workflow: {exc}",
+            )
+        )
+        return findings
+    if not isinstance(doc, dict):
+        return findings
+    # PyYAML coerces the bare key `on` to boolean True (the YAML 1.1
+    # legacy-bool surface). Inspect both forms.
+    on_block = doc.get("on") if "on" in doc else doc.get(True)
+    if not _has_push_or_pr_trigger(on_block):
+        return findings
+    is_deploy = _is_deployment_workflow(path)
+    concurrency = doc.get("concurrency")
+    if concurrency is None:
+        findings.append(
+            Finding(
+                workflow=workflow_name,
+                job=None,
+                drift_class="missing-concurrency-block",
+                detail="top-level concurrency: block absent",
+            )
+        )
+    elif isinstance(concurrency, dict):
+        if "cancel-in-progress" not in concurrency:
+            findings.append(
+                Finding(
+                    workflow=workflow_name,
+                    job=None,
+                    drift_class="missing-cancel-in-progress-flag",
+                    detail="concurrency block lacks cancel-in-progress key",
+                )
+            )
+        else:
+            cip = concurrency["cancel-in-progress"]
+            expected = not is_deploy
+            if cip is not expected:
+                findings.append(
+                    Finding(
+                        workflow=workflow_name,
+                        job=None,
+                        drift_class="cancel-in-progress-wrong-value",
+                        detail=(
+                            f"deployment workflow requires cancel-in-progress: false (got {cip!r})"
+                            if is_deploy
+                            else f"non-deployment workflow requires cancel-in-progress: true (got {cip!r})"
+                        ),
+                    )
+                )
+    jobs = doc.get("jobs")
+    if not isinstance(jobs, dict):
+        return findings
+    for job_name, job in jobs.items():
+        if not isinstance(job, dict):
+            continue
+        # Reusable-workflow callers declare `uses:` at job level with no
+        # inline `steps:` sequence. The called reusable workflow owns its
+        # timeout-minutes ceiling, so the caller cannot declare one. This
+        # mirrors the harden-runner reusable-workflow exemption.
+        if "uses" in job and "steps" not in job:
+            continue
+        timeout = job.get("timeout-minutes")
+        if timeout is None:
+            findings.append(
+                Finding(
+                    workflow=workflow_name,
+                    job=str(job_name),
+                    drift_class="missing-job-timeout",
+                    detail="job declares no timeout-minutes ceiling",
+                )
+            )
+            continue
+        if not isinstance(timeout, int):
+            findings.append(
+                Finding(
+                    workflow=workflow_name,
+                    job=str(job_name),
+                    drift_class="missing-job-timeout",
+                    detail=f"timeout-minutes is not an integer: {timeout!r}",
+                )
+            )
+            continue
+        ceiling = (
+            FULL_MATRIX_JOB_CEILING_MINUTES
+            if _job_is_full_matrix(job)
+            else SHORT_JOB_CEILING_MINUTES
+        )
+        if timeout > ceiling:
+            findings.append(
+                Finding(
+                    workflow=workflow_name,
+                    job=str(job_name),
+                    drift_class="job-timeout-exceeds-ceiling",
+                    detail=f"timeout-minutes={timeout} exceeds ceiling={ceiling}",
+                )
+            )
+    return findings
+
+
+def check(root: Path) -> GrepResult:
+    """Walk ``<root>/.github/workflows/*.yml``; return aggregated result.
+
+    Pre-conditions: ``root`` is a directory path.
+    Post-conditions: ``result.passed`` is True iff every push-/PR-
+    triggered workflow declares conformant concurrency + per-job
+    timeouts, OR the workflows directory does not yet exist.
+    """
+    workflows_dir = root / ".github" / "workflows"
+    if not workflows_dir.is_dir():
+        return GrepResult(
+            grep=GREP_NAME,
+            root=str(root),
+            not_yet_materialised=True,
+            workflow_count=0,
+            passed=True,
+            findings=[],
+        )
+    workflow_files = sorted(
+        list(workflows_dir.glob("*.yml")) + list(workflows_dir.glob("*.yaml"))
+    )
+    findings: list[Finding] = []
+    for path in workflow_files:
+        findings.extend(_check_workflow(path))
+    return GrepResult(
+        grep=GREP_NAME,
+        root=str(root),
+        not_yet_materialised=False,
+        workflow_count=len(workflow_files),
+        passed=not findings,
+        findings=findings,
+    )
+
+
+def _read_input(argv: list[str]) -> Path:
+    if len(argv) >= 2:
+        return Path(argv[1])
+    return Path.cwd()
+
+
+def _main(argv: list[str]) -> int:
+    root = _read_input(argv)
+    result = check(root)
+    print(result.to_json())
+    return EXIT_PASS if result.passed else EXIT_FAIL
+
+
+if __name__ == "__main__":
+    sys.exit(_main(sys.argv))

package/src/apothem/harnesses/README.md

@@ -0,0 +1,63 @@
+<!-- SPDX-License-Identifier: MIT -->
+
+# harnesses
+
+> **Role.** Per-harness adapter subpackages. Each adapter translates the shared `apothem` corpus into one AI tool's native configuration on disk. Harness identity, entry-point paths, target declarations, docs coverage, package-data expectations, and capability support live in `apothem.lib.harness_registry`; `pyproject.toml` mirrors the same entry-point set.
+
+## The `HarnessAdapter` protocol
+
+`HarnessAdapter` is defined in the foundation layer at [`lib/harness_protocol.py`](../lib/harness_protocol.py) and re-exported by `__init__.py`, so `from apothem.harnesses import HarnessAdapter` stays the public import path every concrete adapter satisfies. The lifecycle contract is intentionally small; registry metadata carries the public identity, docs, capability, package-data, and target-path obligations:
+
+| Member | Contract |
+|--------|----------|
+| `name` | Canonical kebab-case harness identifier (e.g. `'claude-code'`). |
+| `output_path` | Absolute path to the target configuration file. |
+| `install(profile)` | Materialize the harness configuration from the shared profile dict and return a structured materialization run when the adapter writes through the shared driver. |
+| `update(profile)` | Re-materialize the harness configuration from an updated profile dict and return the same structured run surface. |
+| `uninstall()` | Remove the harness configuration file if present. |
+| `is_installed()` | Return `True` if the harness configuration file exists on disk. |
+| `verify()` | Return `True` if the installed harness configuration is valid. |
+
+## Adapter subpackage shape
+
+Each harness subpackage carries the same core module set: `__init__.py` (the adapter class), `install.py`, `uninstall.py`, `update.py`, and `verify.py`. Adapters that render a native configuration file also carry `materializer.py`. Template-propagation and conversion behavior is declared in `lib/propagation-manifest.yaml`.
+
+## The seventeen harnesses
+
+| Harness | Native config target | Shape |
+|---------|----------------------|-------|
+| `claude_code` | `~/.claude/settings.json`, `~/.claude/{agents,rules,skills,statuslines,output-styles}/`, plus `~/.claude/apothem/{templates,hooks}/` | Native Claude Code adapter; command prompts are wrapped as skills. |
+| `antigravity` | `~/.gemini/GEMINI.md` plus `~/.gemini/antigravity-cli/plugins/apothem/` | Antigravity CLI plugin adapter (no materializer). |
+| `codex` | `~/.codex/AGENTS.md`, `~/.codex/hooks.json`, `~/.codex/hooks/`, `~/.codex/agents/*.toml`, `~/.agents/skills/`, `~/.config/apothem/{rules,templates}/` | Native Codex adapter; does not write `config.toml`. |
+| `cursor` | `<project>/.cursor/rules/apothem-rules.mdc` | Project-scope manifest adapter. |
+| `gemini_cli` | `<project>/GEMINI.md` plus `<project>/.gemini/{commands,skills,agents,apothem}/` | Project-scope manifest adapter with TOML command conversion. |
+| `github_copilot` | `<project>/.github/copilot-instructions.md` | Project-scope manifest adapter. |
+| `hermes` | `~/.hermes/config.yaml` plus `~/.hermes/apothem/` | Materializer (native MCP via `auxiliary.mcp`); support cohorts under `~/.hermes/apothem/`. |
+| `kimi_code` | `<project>/AGENTS.md` plus `<project>/.kimi-code/apothem/` | Project-scope manifest adapter; native agent memory. |
+| `open_claw` | `~/.openclaw/openclaw.json` plus `~/.openclaw/apothem/` | Support cohorts under `~/.openclaw/apothem/`; no config keys authored (name-allowlist skills, CLI MCP). |
+| `opencode` | `~/.config/opencode/opencode.json`, `commands/`, `skills/`, `agents/`, `apothem/` | Materializer plus native commands, skills, and agents. |
+| `qwen_code` | `~/.qwen/settings.json`, `~/.qwen/QWEN.md`, `commands/`, `skills/`, `agents/`, `apothem/` | Materializer plus native hooks, commands, skills, agents, context anchor, and support cohorts. |
+| `windsurf` | `<project>/.devin/rules/apothem-rules.md` | Project-scope manifest adapter (Devin Desktop preferred surface; `.windsurf/rules/` fallback). |
+| `codebuddy` | `<project>/.codebuddy/rules/apothem-rules.md` | Project-scope manifest adapter. |
+| `kiro` | `<project>/.kiro/steering/apothem-rules.md` | Project-scope manifest adapter. |
+| `trae` | `<project>/.trae/rules/apothem-rules.md` | Project-scope manifest adapter. |
+| `zed` | `<project>/.rules` | Project-scope manifest adapter; flat project-root file. |
+| `glm` | `<project>/.apothem/providers/glm.toml` | Project-scope provider adapter (GLM / Z.ai model backend; TOML config only). |
+
+## Conventions
+
+- Adapters consume their propagation contract from `lib/propagation-manifest.yaml` when they copy or convert shared cohorts.
+- Registry rows are the source of truth for the exact seventeen public IDs, package keys, adapter entry points, docs pages, test fixtures, package-data keys, target declarations, and capability states.
+- The `~/.gemini/` user-scope home namespace belongs to the `antigravity` adapter; the `gemini_cli` adapter is project-scope and writes only under the operator-supplied `--project <path>` root, so the two never collide on the shared Gemini home.
+- Project-scope adapters (`cursor`, `gemini_cli`, `github_copilot`, `codebuddy`, `kiro`, `trae`, `windsurf`, `zed`) opt in via `requires_project = True`; `output_path` is a display-only sentinel and the concrete target resolves per-invocation through `resolve_output_path(project)`. The CLI rejects any lifecycle invocation that omits `--project <path>`, and `is_installed` / `verify` return `False` when no project is supplied.
+- The shared install driver validates every manifest source and target before writing, reports created/updated/unchanged/skipped/warning/error outcomes, supports dry-run, and projects unsupported or discovery-pending registry capability cells as warnings.
+- Existing matching targets are backed up before replacement. Shared discovery directories are merged child-by-child so unrelated operator-authored entries survive Apothem updates, and unchanged generated content is left untouched.
+- The `claude_code` adapter deliberately does **not** manage the operator-owned memory file at the harness root; governance reaches that harness through the propagated `rules/` tree and the `SessionStart` hook, never by rewriting the operator's memory.
+- The `codex` adapter resolves the harness home through the `CODEX_HOME` environment variable, defaulting to the user-scope root when the variable is unset.
+
+## Related
+
+- [`lib/harness_materializer.py`](../lib/harness_materializer.py) — shared building blocks for the single-file materializers.
+- [`lib/harness_protocol.py`](../lib/harness_protocol.py) — the `HarnessAdapter` Protocol contract, defined in the foundation layer and re-exported here.
+- [`lib/harness_registry.py`](../lib/harness_registry.py) — central exact-seventeen registry and adapter contract metadata.
+- [`lib/propagation-manifest.yaml`](../lib/propagation-manifest.yaml) — the propagation contract consumed by manifest-driven adapters.

package/src/apothem/harnesses/__init__.py

@@ -0,0 +1,16 @@
+# SPDX-License-Identifier: MIT
+
+"""Apothem harness adapter protocol — public re-export.
+
+Every concrete adapter must implement :class:`HarnessAdapter`. The protocol
+is defined in the foundation layer at :mod:`apothem.lib.harness_protocol` and
+re-exported here, so ``from apothem.harnesses import HarnessAdapter`` stays the
+stable public import path for adapters, tests, and documentation — the
+foundation declares the contract, this consumer package re-exposes it. The
+adapters are declared in :mod:`apothem.lib.harness_registry`; the
+``pyproject.toml`` entry-point group mirrors that registry exactly.
+"""
+
+from __future__ import annotations
+
+from apothem.lib.harness_protocol import HarnessAdapter as HarnessAdapter

package/src/apothem/harnesses/_shared/README.md

@@ -0,0 +1,36 @@
+<!-- SPDX-License-Identifier: MIT -->
+
+# _shared
+
+> **Role.** The cross-adapter shared-infrastructure package. Logic recurring across three or more harness adapters is hoisted here so each adapter holds only its harness-specific identity and scope. The underscore prefix keeps this package out of the `apothem.harnesses` entry-point namespace — it is shared machinery, not a registrable adapter.
+
+## What lives here
+
+`install_driver.py` is the shared propagation driver every adapter's `install.py` delegates to. It carries the install recipe once: load a harness's rules from `lib/propagation-manifest.yaml`, sweep stale top-level paths from earlier layouts, then apply each install entry in declaration order. The driver supplies:
+
+- The structured materialization-result surface (`MaterializationResult` / `MaterializationRun`) with deterministic per-outcome counts.
+- The safe-write primitives: path validation against an allowed root, backup-before-replace, atomic swap, no-op detection.
+- The directory-replace and stale-sweep primitives.
+- The operator-owned merge path: sentinel-block merge for Markdown anchors, key-preserving merge for JSON.
+- The destructive-authorization gate.
+- The per-mode entry appliers (`write_text`, `replace_tree`, `merge_tree_entries`, `command_skills`, and the per-harness agent/command converters).
+
+Scope is expressed by which root the caller supplies — a user-scope harness root or a project-scope project root.
+
+## Conventions
+
+- Writes go through the safe-write primitives — never bypass them with a raw `Path.write_*`.
+- Targets whose ownership class is vendor-reserved or immutable are refused outright; operator-owned non-additive overwrites route through the authorization gate with a unified diff.
+- The hoist threshold is structural similarity across **three or more** adapters, not mere topical overlap; genuinely per-harness logic stays in the adapter subpackage.
+- The package name stays underscore-prefixed; nothing here registers as an adapter or joins the `apothem.harnesses` entry-point group.
+- This package is in `mypy --strict` scope.
+
+## Operating in this folder
+
+Add or change a primitive here only when the behavior is shared by three or more adapters; a one-adapter need belongs in that adapter's own module. Preserve the structured result/run surface — callers depend on the outcome vocabulary (`created` / `updated` / `unchanged` / `skipped` / `warning` / `error`) and the dry-run contract — so extend it additively rather than redefining existing outcomes. Validate with `python -m ruff check`, `python -m mypy src/apothem/harnesses/`, the conformity gate (`python -m apothem.conformity.gate --all .`), and `python -m pytest` (the adapter round-trip integration suite exercises this driver through every adapter).
+
+## Related
+
+- [`../../lib/propagation-manifest.yaml`](../../lib/propagation-manifest.yaml) — the propagation contract the driver loads.
+- [`../../lib/harness_materializer.py`](../../lib/harness_materializer.py) — managed-block merge building blocks.
+- [`../../lib/frontmatter.py`](../../lib/frontmatter.py) — agent/command field extraction used by the converters.

package/src/apothem/harnesses/_shared/__init__.py

@@ -0,0 +1,12 @@
+# SPDX-License-Identifier: MIT
+
+"""Shared install infrastructure for harness adapters.
+
+Holds the common propagation-driver logic every harness adapter's
+``install.py`` delegates to: manifest-rule loading, source/target path
+resolution, the copytree ignore-filter builder, the directory-replace
+primitive, the stale-sweep primitive, and the install/plan orchestrators.
+The underscore-prefixed package name keeps it out of the
+``apothem.harnesses`` entry-point namespace — it is shared infrastructure,
+not a registrable adapter.
+"""