flowharness-portability 0.1.0__tar.gz

flowharness_portability-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

flowharness_portability-0.1.0/PKG-INFO

@@ -0,0 +1,24 @@
+Metadata-Version: 2.4
+Name: flowharness-portability
+Version: 0.1.0
+Summary: Portability context (ARTIFACT_PORTABILITY_SPEC §0) — the canonical artifact model + the flowharness/v1 lossless sidecar codec
+License-Expression: Apache-2.0
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: flowharness-core==0.1.0
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/flowharness-ai
+Description-Content-Type: text/markdown
+
+# flowharness-portability
+
+Portability context — the canonical artifact model and the `flowharness/v1` lossless sidecar codec. Provides the domain layer for importing and exporting evaluation artifacts across different AI harness systems, with per-harness reader/renderer adapters for the hub-and-spoke architecture.
+
+This is an **internal library package** of the FlowHarness toolchain, published to PyPI as a transitive dependency of [`flowharness`](https://github.com/flowharness-ai) (the scan CLI) and [`flowharness-ci-runner`](https://github.com/flowharness-ai). Install those packages instead of depending on `flowharness-portability` directly.
+
+> **Note:** this package currently installs a top-level module named `portability`. Prefer `uvx` (isolated environments) over `pip install` into a shared venv until the 0.2 module-namespace rename lands.
+
+**License:** Apache-2.0  
+**Homepage:** https://github.com/flowharness-ai

flowharness_portability-0.1.0/README.md

@@ -0,0 +1,10 @@
+# flowharness-portability
+
+Portability context — the canonical artifact model and the `flowharness/v1` lossless sidecar codec. Provides the domain layer for importing and exporting evaluation artifacts across different AI harness systems, with per-harness reader/renderer adapters for the hub-and-spoke architecture.
+
+This is an **internal library package** of the FlowHarness toolchain, published to PyPI as a transitive dependency of [`flowharness`](https://github.com/flowharness-ai) (the scan CLI) and [`flowharness-ci-runner`](https://github.com/flowharness-ai). Install those packages instead of depending on `flowharness-portability` directly.
+
+> **Note:** this package currently installs a top-level module named `portability`. Prefer `uvx` (isolated environments) over `pip install` into a shared venv until the 0.2 module-namespace rename lands.
+
+**License:** Apache-2.0  
+**Homepage:** https://github.com/flowharness-ai

flowharness_portability-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[project]
+name = "flowharness-portability"
+version = "0.1.0"
+readme = "README.md"
+description = "Portability context (ARTIFACT_PORTABILITY_SPEC §0) — the canonical artifact model + the flowharness/v1 lossless sidecar codec"
+requires-python = ">=3.12"
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = ["flowharness-core==0.1.0"]
+
+[project.urls]
+Homepage = "https://github.com/flowharness-ai"
+
+[build-system]
+requires = ["uv_build>=0.9.0,<0.10.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "portability"
+
+[tool.uv.sources.flowharness-core]
+workspace = true

flowharness_portability-0.1.0/pyproject.toml.orig

@@ -0,0 +1,29 @@
+[project]
+name = "flowharness-portability"
+version = "0.1.0"
+readme = "README.md"
+description = "Portability context (ARTIFACT_PORTABILITY_SPEC §0) — the canonical artifact model + the flowharness/v1 lossless sidecar codec"
+requires-python = ">=3.12"
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+# Internal deps pin ==0.1.0: the six OSS packages version in lockstep (release.yml builds
+# them from one tag), and [tool.uv.sources] workspace=true overrides these locally.
+dependencies = ["flowharness-core==0.1.0"]
+
+[project.urls]
+Homepage = "https://github.com/flowharness-ai"
+
+[build-system]
+requires = ["uv_build>=0.9.0,<0.10.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "portability"
+
+[tool.uv.sources]
+flowharness-core = { workspace = true }

flowharness_portability-0.1.0/src/portability/__init__.py

@@ -0,0 +1,6 @@
+"""Portability context (ARTIFACT_PORTABILITY_SPEC §0).
+
+The canonical artifact model (the hub of the hub-and-spoke) and the ``flowharness/v1``
+lossless sidecar codec. Per-harness reader/renderer adapters live in this context's
+``domain``/``infrastructure``. Imports stdlib + ``core`` only.
+"""

flowharness_portability-0.1.0/src/portability/application/registry.py

@@ -0,0 +1,71 @@
+"""HarnessRendererRegistry — name-keyed registry of the shipped harness renderers (spec §4.4).
+
+Mirrors rendering's ``AdapterRegistry`` shape: a name->renderer map plus an ordered list
+(registration order is the presentation order surfaced by ``GET /v1/rendering/harnesses``).
+``register`` / ``lookup`` / ``names`` + a seed-then-``freeze`` lifecycle. A new harness is
+added by registering its renderer — no central switch. Application layer: only the endpoint
+selects renderers; the portability domain never needs the registry.
+
+A post-freeze ``register`` raises ``core.DomainError("harness_registry_frozen")`` (D-3.4): a
+NEW code, portability-local. Rendering's twin raises ``RenderingError`` in ITS context; the
+two contexts keep distinct error conventions rather than share one code.
+"""
+
+from core import DomainError
+from portability.domain.agentharnesses import AgentHarnessRenderer
+from portability.domain.agents_md import AgentsMdRenderer
+from portability.domain.claude_code import ClaudeCodeRenderer
+from portability.domain.continue_ import ContinueRenderer
+from portability.domain.cursor import CursorRenderer
+from portability.domain.opencode import OpenCodeRenderer
+from portability.domain.renderer import HarnessRenderer
+
+__all__ = ["HarnessRendererRegistry", "build_harness_registry"]
+
+
+class HarnessRendererRegistry:
+    """A mutable-at-seed-time, frozen-at-runtime registry of harness renderers, keyed by name."""
+
+    __slots__ = ("_frozen", "_order", "_renderers")
+
+    def __init__(self) -> None:
+        self._renderers: dict[str, HarnessRenderer] = {}
+        self._order: list[str] = []
+        self._frozen = False
+
+    def register(self, renderer: HarnessRenderer) -> None:
+        if self._frozen:
+            raise DomainError("harness_registry_frozen")
+        name = renderer.name()
+        if name not in self._renderers:
+            self._order.append(name)
+        self._renderers[name] = renderer
+
+    def lookup(self, name: str) -> HarnessRenderer | None:
+        return self._renderers.get(name)
+
+    def names(self) -> tuple[str, ...]:
+        return tuple(self._order)
+
+    def freeze(self) -> None:
+        self._frozen = True
+
+
+def build_harness_registry() -> HarnessRendererRegistry:
+    """A fresh registry seeded with the six shipped renderers in fixed presentation order.
+
+    Left UNFROZEN — the composition root (``wire_portability``, T4) freezes it. Order is
+    ``claude_code`` then ``agentharnesses`` then ``agents_md`` then ``cursor`` then ``continue``
+    then ``opencode`` (registration order == presentation order); ``agents_md`` is the render-only
+    AGENTS.md adapter added by PR-13D, ``cursor`` the render-only ``.cursor/`` adapter added by
+    PR-13E, and ``continue``/``opencode`` the render-only ``.continue/``/``.opencode/`` adapters
+    added by PR-13F (completing the six-harness set).
+    """
+    registry = HarnessRendererRegistry()
+    registry.register(ClaudeCodeRenderer())
+    registry.register(AgentHarnessRenderer())
+    registry.register(AgentsMdRenderer())
+    registry.register(CursorRenderer())
+    registry.register(ContinueRenderer())
+    registry.register(OpenCodeRenderer())
+    return registry

flowharness_portability-0.1.0/src/portability/domain/__init__.py

@@ -0,0 +1,37 @@
+"""Portability domain — the canonical artifact model + the flowharness/v1 sidecar codec.
+
+Stdlib + ``core`` only (no Pydantic/SQLAlchemy/network/proto). Frozen value objects;
+content-addressed ids via ``core.ContentHashable``; float-free, canonical-JSON-safe.
+"""
+
+from portability.domain.artifact import (
+    CanonicalArtifact,
+    Provenance,
+    Resource,
+    Scope,
+    ScopeKind,
+)
+from portability.domain.bundle import ArtifactBundle, Blob, blob_hash
+from portability.domain.capability import Capability, CapabilityProfile
+from portability.domain.kinds import ArtifactKind, Outcome
+from portability.domain.renderer import HarnessRenderer
+from portability.domain.sidecar import SIDECAR_VERSION, decode_bundle, encode_bundle
+
+__all__ = [
+    "SIDECAR_VERSION",
+    "ArtifactBundle",
+    "ArtifactKind",
+    "Blob",
+    "CanonicalArtifact",
+    "Capability",
+    "CapabilityProfile",
+    "HarnessRenderer",
+    "Outcome",
+    "Provenance",
+    "Resource",
+    "Scope",
+    "ScopeKind",
+    "blob_hash",
+    "decode_bundle",
+    "encode_bundle",
+]

flowharness_portability-0.1.0/src/portability/domain/agentharnesses/__init__.py

@@ -0,0 +1,7 @@
+"""agentharnesses adapter — the first per-harness reader/renderer over the canonical model."""
+
+from portability.domain.agentharnesses.profile import AGENTHARNESSES_PROFILE
+from portability.domain.agentharnesses.reader import AgentHarnessReader
+from portability.domain.agentharnesses.renderer import AgentHarnessRenderer
+
+__all__ = ["AGENTHARNESSES_PROFILE", "AgentHarnessReader", "AgentHarnessRenderer"]

flowharness_portability-0.1.0/src/portability/domain/agentharnesses/profile.py

@@ -0,0 +1,22 @@
+"""The agentharnesses CapabilityProfile (ARTIFACT_PORTABILITY_SPEC §4).
+
+agentharnesses natively expresses only skills (+ bundled resources) under a progressive-
+disclosure tree with frontmatter. It has no native tool/mcp/agent/hook/command/permission
+concept — those degrade to a documented stub on the native surface and are preserved
+losslessly in the .flowharness/ sidecar.
+"""
+
+from portability.domain.capability import Capability, CapabilityProfile
+
+AGENTHARNESSES_PROFILE = CapabilityProfile(
+    harness="agentharnesses",
+    version="agentharnesses/1",
+    supported=frozenset(
+        {
+            Capability.FRONTMATTER,
+            Capability.NATIVE_SKILLS,
+            Capability.EXECUTABLE_RESOURCES,
+            Capability.HIERARCHICAL_MERGE,
+        }
+    ),
+)

flowharness_portability-0.1.0/src/portability/domain/agentharnesses/reader.py

@@ -0,0 +1,210 @@
+"""AgentHarnessReader (ARTIFACT_PORTABILITY_SPEC §0.2) — the spoke→hub parse for agentharnesses.
+
+Two modes:
+- **sidecar** (lossless): if the always-on ``.flowharness/`` sidecar is present, decode it —
+  every artifact kind round-trips byte-for-byte, closing ``parse(render(b)) == b``.
+- **native** (best-effort ingest): a sidecar-less, real-world agentharnesses directory
+  (``HARNESS.md`` + ``skills/**/SKILL.md`` + ``references/``) parsed into the skill/rule/
+  knowledge slice. Tolerant — never raises on content. Each file is assigned to its nearest
+  enclosing skill leaf; markdown ``references/*.md`` become knowledge; routing files and
+  non-markdown reference files are NOT ingested (emit the sidecar for full fidelity).
+
+A present ``.flowharness/manifest.json`` selects the STRICT sidecar path — a malformed or
+wrong-version sidecar is a hard error, not a silent native fallback. Stdlib + core only.
+"""
+
+import re
+from collections.abc import Mapping
+
+from portability.domain.artifact import (
+    CanonicalArtifact,
+    Provenance,
+    Resource,
+)
+from portability.domain.bundle import ArtifactBundle, Blob, blob_hash
+from portability.domain.kinds import ArtifactKind
+from portability.domain.sidecar import MANIFEST_PATH, decode_bundle
+
+_SOURCE = "agentharnesses"
+_HARNESS_FILE = "HARNESS.md"
+_LEAF_DETECTORS = ".leaf-detectors"
+_FRONTMATTER = re.compile(r"^---\s*\n(.*?)\n---\s*\n?(.*)", re.DOTALL)
+
+
+def _unquote(value: str) -> str:
+    if len(value) >= 2 and value[0] == value[-1] and value[0] in "'\"":
+        inner = value[1:-1]
+        return inner.replace("''", "'") if value[0] == "'" else inner
+    return value
+
+
+def _read_frontmatter(data: bytes) -> tuple[dict[str, str], str]:
+    text = data.decode("utf-8", "replace")
+    match = _FRONTMATTER.match(text)
+    if match is None:
+        return {}, text.strip()
+    fields: dict[str, str] = {}
+    for line in match.group(1).splitlines():
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#") or ":" not in stripped:
+            continue
+        key, _, value = stripped.partition(":")
+        fields[key.strip()] = _unquote(value.strip())
+    return fields, match.group(2).strip()
+
+
+def _spec(fields: Mapping[str, str]) -> dict[str, object]:
+    description = fields.get("description", "")
+    return {"description": description} if description else {}
+
+
+def _media(data: bytes) -> str:
+    try:
+        data.decode("utf-8")
+    except UnicodeDecodeError:
+        return "binary"
+    return "text"
+
+
+def _nonblank(value: str | None, fallback: str) -> str:
+    # A non-blank display title (CanonicalArtifact rejects a blank title); fall back so the
+    # tolerant reader never raises on a missing/whitespace name.
+    return value.strip() if value and value.strip() else fallback
+
+
+def _skill_leaf_names(files: Mapping[str, bytes]) -> frozenset[str]:
+    # The filenames that mark a `skill` leaf — declared in .leaf-detectors, not built in
+    # (agentharnesses has no built-in leaf types). Default to SKILL.md when unstated.
+    raw = files.get(_LEAF_DETECTORS)
+    names: set[str] = set()
+    if raw is not None:
+        for line in raw.decode("utf-8", "replace").splitlines():
+            stripped = line.strip()
+            if stripped.startswith("#") or "=" not in stripped:
+                continue
+            leaf_type, _, rel = stripped.partition("=")
+            if leaf_type.strip() == "skill" and rel.strip():
+                names.add(rel.strip())
+    return frozenset(names or {"SKILL.md"})
+
+
+def _assign_resources(files: Mapping[str, bytes], skill_paths: list[str]) -> dict[str, list[str]]:
+    # Assign each non-leaf file to its NEAREST enclosing skill dir, so a parent skill never
+    # absorbs a nested child skill's files (and a child's SKILL.md is never a parent resource).
+    skill_path_set = set(skill_paths)
+    dirs_by_depth = sorted({p.rsplit("/", 1)[0] for p in skill_paths}, key=len, reverse=True)
+    out: dict[str, list[str]] = {skill_dir: [] for skill_dir in dirs_by_depth}
+    for path in sorted(files):
+        if path in skill_path_set:
+            continue
+        for skill_dir in dirs_by_depth:
+            if path.startswith(skill_dir + "/"):
+                out[skill_dir].append(path)
+                break
+    return out
+
+
+class AgentHarnessReader:
+    def name(self) -> str:
+        return _SOURCE
+
+    def parse(self, files: Mapping[str, bytes]) -> ArtifactBundle:
+        if MANIFEST_PATH in files:
+            return decode_bundle(files)  # the always-on lossless sidecar
+        return self._parse_native(files)
+
+    def _parse_native(self, files: Mapping[str, bytes]) -> ArtifactBundle:
+        leaf_names = _skill_leaf_names(files)
+        skill_paths = sorted(
+            path
+            for path in files
+            if path.startswith("skills/") and path.rsplit("/", 1)[-1] in leaf_names
+        )
+        resources_by_dir = _assign_resources(files, skill_paths)
+        consumed: set[str] = set(skill_paths)
+        for paths in resources_by_dir.values():
+            consumed.update(paths)
+        blobs: dict[str, bytes] = {}
+        artifacts: list[CanonicalArtifact] = []
+
+        artifacts.extend(self._parse_harness(files, consumed))
+        for skill_path in skill_paths:
+            skill_dir = skill_path.rsplit("/", 1)[0]
+            artifacts.append(
+                self._parse_skill(skill_path, skill_dir, files, resources_by_dir[skill_dir], blobs)
+            )
+        artifacts.extend(self._parse_references(files, consumed))
+
+        blob_objs = tuple(Blob(content_hash=h, data=d) for h, d in sorted(blobs.items()))
+        return ArtifactBundle(artifacts=tuple(artifacts), blobs=blob_objs)
+
+    def _parse_harness(
+        self, files: Mapping[str, bytes], consumed: set[str]
+    ) -> list[CanonicalArtifact]:
+        data = files.get(_HARNESS_FILE)
+        if data is None:
+            return []
+        consumed.add(_HARNESS_FILE)
+        fields, body = _read_frontmatter(data)
+        return [
+            CanonicalArtifact(
+                kind=ArtifactKind.RULE,
+                title=_nonblank(fields.get("name"), "harness"),
+                spec=_spec(fields),
+                body=body,
+                provenance=Provenance(source_harness=_SOURCE, source_ref=_HARNESS_FILE),
+            )
+        ]
+
+    def _parse_skill(
+        self,
+        skill_path: str,
+        skill_dir: str,
+        files: Mapping[str, bytes],
+        resource_paths: list[str],
+        blobs: dict[str, bytes],
+    ) -> CanonicalArtifact:
+        fields, body = _read_frontmatter(files[skill_path])
+        resources: list[Resource] = []
+        for path in resource_paths:
+            data = files[path]
+            content_hash = blob_hash(data)
+            blobs[content_hash] = data
+            resources.append(
+                Resource(
+                    relpath=path[len(skill_dir) + 1 :],
+                    content_hash=content_hash,
+                    media=_media(data),
+                )
+            )
+        name = _nonblank(fields.get("name"), _nonblank(skill_dir.rsplit("/", 1)[-1], "skill"))
+        return CanonicalArtifact(
+            kind=ArtifactKind.SKILL,
+            title=name,
+            spec=_spec(fields),
+            body=body,
+            triggers=(name,),
+            resources=tuple(resources),
+            provenance=Provenance(source_harness=_SOURCE, source_ref=skill_path),
+        )
+
+    def _parse_references(
+        self, files: Mapping[str, bytes], consumed: set[str]
+    ) -> list[CanonicalArtifact]:
+        out: list[CanonicalArtifact] = []
+        for path in sorted(files):
+            base = path.rsplit("/", 1)[-1]
+            if path in consumed or base.startswith(".") or base == "REFERENCES.md":
+                continue
+            if path.startswith("references/") and path.endswith(".md"):
+                fields, body = _read_frontmatter(files[path])
+                out.append(
+                    CanonicalArtifact(
+                        kind=ArtifactKind.KNOWLEDGE,
+                        title=_nonblank(fields.get("title"), _nonblank(base, "reference")),
+                        spec=_spec(fields),
+                        body=body,
+                        provenance=Provenance(source_harness=_SOURCE, source_ref=path),
+                    )
+                )
+        return out