Architecture position

Harness & Governance

Use the runtime environment to control tools, permissions, side effects, budgets, human approval, recovery, and platform differences.

What controls permissions, runtime boundaries, side effects, platform adaptation, and recovery?

Concept calibration

Harness

What it is: The runtime control environment that hosts models, tools, state, permissions, logs, budgets, human approval, and recovery.
What it is not: It can constrain risk and preserve evidence, but it cannot directly prevent model hallucinations.

Skill

What it is: A reusable capability package containing instructions, resources, operating boundaries, versioning, and compatibility metadata.
What it is not: It is not merely a prompt, and its scripts must not be assumed safe to execute automatically.

Tool

What it is: A constrained capability an agent can invoke through explicit arguments, permissions, and result contracts.
What it is not: A tool is not the same as MCP; a local function, command, or HTTP client can also be a tool.

Cross-Platform Adapters & Migration

Build capability, directory, and permission adapters for Codex, Claude Code, and WorkBuddy.

One thing to completeMake the same Forge Skill pass compatibility tests on all three platforms.

Before you begin, Forge already hasThe accepted solution from Module 14, Identity, Permissions, Security & Supply Chain, is this chapter’s starting point.

After this chapter, Forge canDeploy the same Forge Skill to three platforms through adapters.

Smallest recovery pointGenerate a platform-difference report before performing any installation or write.

Download this chapter labPython 3.12 · pytest · Pydantic · SQLite · deterministic Mock

Stage capability chain

01Describe required tools, resources, and approvals with a platform-neutral contract02Map the canonical Skill contract to Codex paths, tool declarations, and approval policy03Generate a Claude Code command allowlist and reject required capabilities that cannot be represented04Map capabilities to WorkBuddy workspace permissions while preserving read/write distinctions05Normalize three platform plans into comparable and auditable configuration records06Distinguish blocking gaps from acceptable degradation in an explainable compatibility report07Use one contract suite to check install paths, non-escalation, and capability coverage before release

Each step adds one verifiable capability; every later step begins from code and tests accepted in the previous step.

Concept calibration\n\nPut the concepts used in this module back inside their engineering boundaries before you work with the code.\n\n
\n\n### Harness harness\n\n- What it is: The runtime control environment that hosts models, tools, state, permissions, logs, budgets, human approval, isolation, and recovery.\n- What it is not: It can reduce risk, reject actions, and preserve evidence, but it cannot guarantee that model output is always correct or replace domain acceptance checks.\n- Relationship to adjacent concepts: The agent loop runs inside the harness; tool, memory, and MCP connections obey its policies; observability records execution and evaluation judges behavior.\n- Where it lives in HeatStack Forge: The Forge harness manages workspace, tools, approval queue, budget, checkpoints, audit logs, and rollback, separating model suggestions from real side effects.\n- Typical misuse and correction: A common misuse treats a system prompt as a security boundary. Enforce permissions, paths, network access, secrets, budgets, and rollback outside the model.\n\n### Skill skill\n\n- What it is: A reusable capability package containing instructions, resources, operating boundaries, versioning, and compatibility metadata that an agent platform can discover, install, or reference.\n- What it is not: It is not merely a prompt, and bundled scripts are not automatically trusted; execution remains constrained by platform, tool contracts, and permission policy.\n- Relationship to adjacent concepts: A prompt may be part of a Skill, a Skill may reference tools, the harness controls installation and runtime boundaries, and adapters handle platform differences.\n- Where it lives in HeatStack Forge: Forge packages requirement extraction as a Skill with a manifest, tests, resource inventory, and risk notes, then adapts it to three target platforms.\n- Typical misuse and correction: A common misuse copies one prompt file and claims cross-platform compatibility. Declare dependencies, entry points, resources, versions, permissions, and acceptance tests.\n\n### Tool tool\n\n- What it is: A constrained capability an agent invokes through explicit arguments, permissions, execution boundaries, and result contracts, such as a function, command, database query, or HTTP client.\n- What it is not: A tool is not MCP or any arbitrary script. A protocol can expose capability, while the harness still decides whether invocation is allowed and how side effects are handled.\n- Relationship to adjacent concepts: The agent loop selects tools, schemas constrain arguments, the harness enforces permission and isolation, and verification checks whether results advanced the goal.\n- Where it lives in HeatStack Forge: Forge stores tool contracts and risk levels, produces a change plan before execution, waits for approval on high-risk writes, and records results and recovery data.\n- Typical misuse and correction: A common misuse lets the model invent arguments from a tool name. Use strict schemas, deterministic validation, timeouts, idempotency keys, and refusal tests.\n\n

STAGE 01

Describe required tools, resources, and approvals with a platform-neutral contract

Start with a concrete problem

How can we declare which capabilities a Skill needs in a platform-neutral way, distinguishing required from optional?

You are building a cross-platform adapter layer for the Forge platform, and you need to let the same Skill determine whether a platform satisfies its capability requirements during installation.

The codebase currently has no forge/adapters package and no capability model, so the tests test_required_capabilities_are_reported and test_optional_capability_is_not_a_blocker fail at import time.

You need to create a platform-neutral contract model: use CapabilityRequirement to represent a single capability need (with a name and whether it is required), use SkillContract to represent all capability needs of a Skill, and implement missing_capabilities to compute missing required capabilities.

The key decision is that when a capability is marked optional, its absence on a platform should not block installation.

Make a prediction

When implementing the required_names method, which approach correctly distinguishes required from optional capabilities?

Return all capability names regardless of the required flag.
Return only capability names where required=True.
Return only capability names where required=False.
Return tuples of capability name and required flag.

Reasoning guide: The correct approach is to return only capability names where required=True, because missing_capabilities should report only missing required capabilities; missing optional capabilities should not be installation blockers.

What it is

What a platform-neutral capability contract is

A platform-neutral capability contract is a set of data structures that declare which external capabilities a Skill needs at runtime, without caring how those capabilities are implemented on a specific platform.

CapabilityRequirement encapsulates a capability name and a boolean flag required, which defaults to True, meaning the capability is required.

SkillContract aggregates all capability requirements of a Skill and provides a required_names method to extract the set of names of all required capabilities.

The missing_capabilities function takes a contract and a set of available capabilities, and returns all missing required capabilities.

What it is not

What a platform-neutral capability contract is not

It is not a platform mapping table; it does not translate capability names into platform-specific APIs or configuration.

It is not an installer; it does not execute any installation logic or check whether the platform actually has these capabilities.

It contains no platform-specific implementation details; it only describes the requirements themselves.

How it relates to neighboring concepts

Relationships among contract components

SkillContract contains multiple CapabilityRequirement objects, each with a name and a required flag.

The required_names method iterates over all requirements, filters out those with required=True, and returns their names as a set.

missing_capabilities calls required_names to get the set of required capabilities, then subtracts the available capabilities set to obtain the missing required capabilities.

Boundary decision for this stage: The contract model only describes requirements; it does not handle platform mapping or installation. Determining whether a platform meets the requirements is done by missing_capabilities, but the actual installation decision is made by the upper-level Harness based on the set of missing capabilities.

Experiment: platform-adapters-01-canonical-capability-model
Input: Software delivery: add a feature to a frontend repository, modify code, and add tests.
Evidence: evidence/platform-adapters/01-canonical-capability-model/
Gate: Pending acceptance

Worked example

Goal: Demonstrate defining CapabilityRequirement and SkillContract, and implementing missing_capabilities to correctly distinguish required and optional capabilities.

Suppose we have a code review Skill that needs the read_files capability to read code, while the git capability is optional for direct version control operations.

We first define the CapabilityRequirement dataclass with name and required fields, where required defaults to True.

Then we define the SkillContract dataclass with skill_id and a tuple of capabilities, and implement the required_names method to return only names of capabilities with required=True.

Finally, we implement the missing_capabilities function, which takes a contract and a set of available capabilities, and returns the set difference between required capabilities and available capabilities.

Implementation steps

Create the file forge/adapters/__init__.py with the content """Cross-platform adapter contracts.""".
Create the file forge/adapters/capabilities.py and import dataclass.
Define the CapabilityRequirement dataclass with @dataclass(frozen=True) and fields name: str and required: bool = True.
Define the SkillContract dataclass with fields skill_id: str and capabilities: tuple[CapabilityRequirement, ...].
Implement the required_names method in SkillContract to return frozenset(item.name for item in self.capabilities if item.required).
Define the missing_capabilities function to return contract.required_names() - available.

Verified solution code: forge/adapters/__init__.py

"""Cross-platform adapter contracts."""

Verified solution code: forge/adapters/capabilities.py

from dataclasses import dataclass

@dataclass(frozen=True)
class CapabilityRequirement:
    name: str
    required: bool = True

@dataclass(frozen=True)
class SkillContract:
    skill_id: str
    capabilities: tuple[CapabilityRequirement, ...]

    def required_names(self) -> frozenset[str]:
        return frozenset(item.name for item in self.capabilities if item.required)

def missing_capabilities(contract: SkillContract, available: set[str]) -> frozenset[str]:
    return contract.required_names() - available

python -m pytest -q tests/test_stage.py

Run the real tests

..                                                                       [100%]
2 passed in <duration>s

Why this implementation

The if item.required condition in the required_names method ensures that only required capabilities are included, while optional capabilities are ignored.

missing_capabilities uses set difference to subtract the available capabilities from the required capabilities, yielding the missing required capabilities.

When the available capabilities include all required capabilities, the difference is an empty set, indicating no missing required capabilities.

Guided practice

Complete the required_names method so that it returns only capability names marked as required.

Open the file forge/adapters/capabilities.py.
Locate the required_names method inside the SkillContract class.
Modify the method body to add an if item.required condition to the generator expression.
Save the file and run the test command.

Progressive hints

Hint 1: The generator expression currently is item.name for item in self.capabilities; you need to add a filter condition.
Hint 2: The filter condition should check whether item.required is true.
Hint 3: After modification, it should be item.name for item in self.capabilities if item.required.

Success criteria

The required_names method returns a set containing only names of capabilities with required=True.
Running python -m pytest -q tests/test_stage.py results in both tests passing.

Fault injection and diagnosis

In the fault lab, we provide a defective implementation of forge/adapters/capabilities.py where the required_names method ignores the required flag and returns all capability names. When running the test test_optional_capability_is_not_a_blocker, the optional capability git is incorrectly treated as required, causing an assertion failure. You need to diagnose and fix this defect.

This stage has established the capability contract model and clarified the distinction between required and optional capabilities. By inspecting the implementation of the required_names method, you can locate the defect: it fails to filter on the required flag. The fix is to add an if item.required condition to the generator expression so that the method returns only required capabilities.

Verified fault contract

Target test: test_optional_capability_is_not_a_blocker
Faulty file: forge/adapters/capabilities.py

Diagnosis order

Run the faulty command python -m pytest -q ../tests/test_stage.py::test_optional_capability_is_not_a_blocker and observe the test failure.
Examine the failure output: missing_capabilities returns frozenset({'git'}) while the expected result is an empty set.
Inspect the required_names method in forge/adapters/capabilities.py and notice that it returns all capability names without checking the required flag.
Confirm the defect: the generator expression in required_names is missing the if item.required condition.

Fix principle: Modify the required_names method to add an if item.required condition to the generator expression so that it returns only required capability names. The corrected code is: return frozenset(item.name for item in self.capabilities if item.required).

python -m pytest -q ../tests/test_stage.py::test_optional_capability_is_not_a_blocker

Transfer challenge

In the office research scenario, you need to model a ‘document review’ skill. This skill requires the read_files capability to read documents, while the git capability is optional for version control integration.

Changed condition: Change the scenario from the software delivery code review skill to the office research document review skill, and adjust the capability requirements: read_files is required and git is optional.

Use CapabilityRequirement and SkillContract to create a contract for the ‘document review’ skill, with read_files required and git optional. Then call missing_capabilities with the available capabilities set {"read_files"} and verify that it returns an empty set.

Success criteria

The created SkillContract contains two CapabilityRequirement objects: read_files with required=True and git with required=False.
Calling missing_capabilities(contract, {"read_files"}) returns frozenset(), indicating no missing required capabilities.

Run the real tests

python -m pytest -q tests/test_stage.py

Run the real tests

..                                                                       [100%]
2 passed in <duration>s

Design explanation question: Why does the required_names method need to check the required flag? What impact would returning all capability names have on platform compatibility assessment?

A strong answer should include

The required_names method checks the required flag to distinguish required capabilities from optional ones, ensuring that only required capabilities are used in the missing calculation.
If it returned all capability names, missing optional capabilities would also be reported as missing, causing a platform to be incorrectly judged as incompatible and blocking installation.

Mastery evidence

Passes both test_required_capabilities_are_reported and test_optional_capability_is_not_a_blocker.
Can explain the role of the if item.required condition in required_names and why missing optional capabilities should not block installation.
Successfully creates a contract in the office scenario and verifies that missing_capabilities returns an empty set.

STAGE 02

Map the canonical Skill contract to Codex paths, tool declarations, and approval policy

Start with a concrete problem

From canonical contract to Codex install plan

You need to implement the plan_codex function in forge/adapters/codex.py to convert a SkillContract into a CodexInstallPlan.

Currently, both tests test_codex_path_and_tools_are_mapped and test_codex_write_approval_is_preserved fail because the module does not exist yet.

The key decision is that the target path must follow Codex’s skills/<skill_id>/SKILL.md structure, the tool list must come from the contract requirements, and the approval mode must be fixed as ask-before-writes.

If the approval mode is incorrectly set to full-access, it bypasses confirmation before writes, leading to permission escalation.

Make a prediction

When implementing plan_codex, how should the approval mode be handled?

Dynamically decide based on available capabilities
Always set to ask-before-writes
Set to full-access to simplify installation
Pass as a parameter from the caller

Reasoning guide: The correct option is “Always set to ask-before-writes”. The adapter must preserve security semantics and cannot escalate permissions due to platform differences.

What it is

Adapter is a translator of security semantics

The adapter maps capability requirements from the canonical contract into a platform-specific install plan while keeping permission boundaries unchanged.

For Codex, this means generating the correct directory path, tool declarations, and approval mode.

The approval mode ask-before-writes ensures that any write operation requires user confirmation, which is an implicit security requirement of the contract.

What it is not

Adapter is not a permission decision-maker

The adapter cannot arbitrarily change permission modes, even if installation succeeds, it must not escalate permissions.

It does not perform the installation or verify that the platform actually enforces the approval mode.

The adapter only generates a plan; actual execution is controlled by the Harness.

How it relates to neighboring concepts

Relationship between contract, adapter, and Harness

SkillContract defines capability requirements, the adapter converts them into a platform plan, and the Harness executes and enforces permissions.

The missing_capabilities function checks whether available capabilities satisfy the contract; if not, it should raise an exception.

The target path is constructed from home and skill_id, and the tool list comes from the contract’s required_names().

Boundary decision for this stage: The adapter must preserve security semantics and cannot escalate permissions; the approval mode is fixed as ask-before-writes, even if the platform supports a more permissive mode.

Experiment: platform-adapters-02-codex-adapter
Input: Software delivery: add a feature to a frontend repository, modify code, and add tests.
Evidence: evidence/platform-adapters/02-codex-adapter/
Gate: Pending acceptance

Worked example

Goal: Demonstrate implementing plan_codex to generate the correct target path, tool list, and approval mode.

First, create the file forge/adapters/codex.py and define the CodexInstallPlan dataclass and the plan_codex function.

In the function, call missing_capabilities to check whether all required capabilities are available; if any are missing, raise a ValueError.

Then construct a CodexInstallPlan with target path {home}/skills/{skill_id}/SKILL.md, tool list as the sorted required capability names, and approval mode ask-before-writes.

Implementation steps

Create the file forge/adapters/codex.py.
Import dataclass and SkillContract, missing_capabilities.
Define the CodexInstallPlan dataclass with fields target_path, tools, and approval_mode.
Implement the plan_codex function, check for missing capabilities, and return the plan.

Verified solution code: forge/adapters/codex.py

from dataclasses import dataclass
from forge.adapters.capabilities import SkillContract, missing_capabilities

@dataclass(frozen=True)
class CodexInstallPlan:
    target_path: str
    tools: tuple[str, ...]
    approval_mode: str

def plan_codex(contract: SkillContract, available: set[str], home: str) -> CodexInstallPlan:
    missing = missing_capabilities(contract, available)
    if missing:
        raise ValueError("Codex missing capabilities: " + ", ".join(sorted(missing)))
    if not home or ".." in home.replace("\\", "/").split("/"):
        raise ValueError("unsafe Codex home")
    return CodexInstallPlan(f"{home.rstrip('/')}/skills/{contract.skill_id}/SKILL.md", tuple(sorted(contract.required_names())), "ask-before-writes")

python -m pytest -q tests/test_stage.py

Run the real tests

..                                                                       [100%]
2 passed in <duration>s

Why this implementation

The target path uses home and skill_id to ensure it conforms to Codex’s directory structure.

The tool list comes from contract.required_names(), sorted for determinism.

The approval mode is hardcoded as ask-before-writes to preserve security semantics.

Guided practice

Fix the approval mode in plan_codex to always be ask-before-writes.

Open forge/adapters/codex.py.
Locate the return statement that constructs CodexInstallPlan.
Change the approval_mode argument from full-access to ask-before-writes.
Run the tests to confirm they pass.

Progressive hints

The approval mode is the third field of CodexInstallPlan.
The security boundary requires confirmation before writes.
Do not dynamically change the approval mode based on available capabilities.

Success criteria

test_codex_write_approval_is_preserved passes.
plan_codex returns approval_mode as ask-before-writes.

Fault injection and diagnosis

In the failure fixture fixtures/failure.json, the plan_codex function in forge/adapters/codex.py hardcodes the approval mode as full-access, causing the test test_codex_write_approval_is_preserved to fail. You need to diagnose and fix this permission escalation defect.

This stage has taught that the adapter must preserve security semantics and cannot escalate permissions. By inspecting the return value of plan_codex, you can see that the approval mode is incorrectly set to full-access, while the correct value should be ask-before-writes. Fixing the defect requires changing the hardcoded string to the correct approval mode.

Verified fault contract

Target test: test_codex_write_approval_is_preserved
Faulty file: forge/adapters/codex.py

Diagnosis order

Run the faulty command python -m pytest -q ../tests/test_stage.py::test_codex_write_approval_is_preserved and observe the assertion failure.
Inspect the return statement in plan_codex in forge/adapters/codex.py and notice that approval_mode is set to full-access.
Compare with the canonical contract’s security requirement and confirm that the approval mode should be ask-before-writes.
Modify the code to change full-access to ask-before-writes.

Fix principle: In forge/adapters/codex.py, change the approval_mode field of the returned CodexInstallPlan from full-access to ask-before-writes. This ensures the generated install plan requires confirmation before writes, preserving security semantics.

python -m pytest -q ../tests/test_stage.py::test_codex_write_approval_is_preserved

Transfer challenge

In the music scenario, you need to generate a Codex install plan for a “release planning” skill. This skill requires the write_files capability, and the available capability set includes write_files and read_files.

Changed condition: Change the skill from the security review scenario to the music release planning scenario, and change the capability requirement to write_files.

Use the plan_codex function to generate a Codex install plan for skill ID release-planning. Pass the available capability set {"write_files", "read_files"} and home path C:/Users/dev/.codex. Verify that the generated plan’s target path ends with /skills/release-planning/SKILL.md, the tool list contains write_files, and the approval mode is ask-before-writes.

Success criteria

The plan’s target path ends with /skills/release-planning/SKILL.md.
The plan’s tool list contains write_files.
The plan’s approval mode is ask-before-writes.

Run the real tests

python -m pytest -q tests/test_stage.py

Run the real tests

..                                                                       [100%]
2 passed in <duration>s

Design explanation question: Why must the Codex adapter preserve the ask-before-writes approval mode instead of dynamically adjusting it based on platform capabilities?

A strong answer should include

The approval mode is part of the security semantics, and the adapter cannot escalate permissions.
Dynamic adjustment could lead to write operations without confirmation, increasing risk.
Preserving a fixed approval mode ensures consistent behavior across platforms.

Mastery evidence

Passes both test_codex_path_and_tools_are_mapped and test_codex_write_approval_is_preserved.
Can explain why the adapter must preserve the ask-before-writes approval mode and cannot escalate permissions.
In the music scenario transfer challenge, correctly generates a Codex install plan containing the write_files tool and approval mode ask-before-writes.

STAGE 03

Generate a Claude Code command allowlist and reject required capabilities that cannot be represented

Start with a concrete problem

Generate a command allowlist for Claude Code and reject required capabilities that cannot be represented

The repository currently has only a Codex adapter and no Claude adapter, so the tests fail immediately when importing forge.adapters.claude.

You need to create forge/adapters/claude.py and implement the plan_claude function, which maps capability requirements from a skill contract to a list of tools allowed by Claude Code.

If a required capability cannot be represented in Claude Code, the adapter must raise a ValueError instead of defaulting to generic shell access.

The goal of this stage is to make two tests pass: test_known_capabilities_map_to_tools and test_unknown_required_capability_is_rejected.

Make a prediction

When the adapter encounters a required capability that cannot be mapped to a Claude Code tool, what is the safest action?

Default to Bash, because Bash can execute any command
Raise an exception and refuse to generate a plan
Ignore the capability and continue generating the plan
Log a warning and map to a read-only tool

Reasoning guide: The correct option is ‘Raise an exception and refuse to generate a plan’. Defaulting to Bash widens permissions and may allow the model to perform unintended actions; ignoring the capability prevents the skill from working correctly; mapping to a read-only tool is also inaccurate. The adapter must explicitly reject required capabilities it cannot represent to ensure safety and semantic correctness.

What it is

Explicit capability mapping table

An explicit capability mapping table is a dictionary from capability names to platform tool names, for example {"read_files": "Read", "write_files": "Edit", "shell": "Bash"}.

The adapter only allows capabilities listed in the mapping table; any capability not in the table is considered unrepresentable and must be rejected.

This design makes capability boundaries clear, avoids accidental permission widening, and facilitates auditing and testing.

What it is not

Not an alias for generic shell access

The explicit mapping table is not a mechanism that defaults unknown capabilities to Bash, which would lose capability constraints.

It is also not an open set that can be arbitrarily extended; adding a new mapping requires considering whether the platform truly supports that capability.

The mapping table only handles name conversion; it does not perform permission checks or execution isolation, which are handled by the Harness layer.

How it relates to neighboring concepts

Relationship with skill contract and platform plan

The skill contract (SkillContract) defines which capabilities a skill needs; the adapter reads these capabilities and converts them into a list of tools allowed by the platform.

The ClaudePlan returned by plan_claude contains the skill file path and the allowed tools tuple for later deployment.

If a capability in the contract is not in the mapping table, the adapter detects the missing capability using the missing_capabilities function and raises a ValueError.

Boundary decision for this stage: The adapter must reject required capabilities it cannot represent rather than widen permissions; this ensures the safety and semantic correctness of the platform plan.

Experiment: platform-adapters-03-claude-code-adapter
Input: Software delivery: add a feature to a frontend repository, modify code, and add tests.
Evidence: evidence/platform-adapters/03-claude-code-adapter/
Gate: Pending acceptance

Worked example

Goal: Demonstrate implementing plan_claude with an explicit mapping table and rejection of unknown required capabilities.

We first define the mapping table CAPABILITY_TO_TOOL, mapping read_files to Read, write_files to Edit, and shell to Bash.

Then we implement plan_claude: first compute the set of representable capabilities, then use missing_capabilities to find capabilities in the contract that are missing.

If any are missing, raise a ValueError containing the missing capability names; otherwise generate a sorted tuple of tools and return a ClaudePlan.

Implementation steps

Create the file forge/adapters/claude.py.
Define the CAPABILITY_TO_TOOL dictionary.
Define the ClaudePlan dataclass with skill_path and allowed_tools.
Implement the plan_claude function, checking for missing capabilities and raising an exception.
Run the tests to verify.

Verified solution code: forge/adapters/claude.py

from dataclasses import dataclass
from forge.adapters.capabilities import SkillContract, missing_capabilities

CAPABILITY_TO_TOOL = {"read_files":"Read", "write_files":"Edit", "shell":"Bash"}

@dataclass(frozen=True)
class ClaudePlan:
    skill_path: str
    allowed_tools: tuple[str, ...]

def plan_claude(contract: SkillContract, root: str) -> ClaudePlan:
    representable = set(CAPABILITY_TO_TOOL)
    missing = missing_capabilities(contract, representable)
    if missing:
        raise ValueError("Claude adapter cannot represent: " + ", ".join(sorted(missing)))
    tools = tuple(sorted(CAPABILITY_TO_TOOL[name] for name in contract.required_names()))
    return ClaudePlan(f"{root.rstrip('/')}/.claude/skills/{contract.skill_id}/SKILL.md", tools)

python -m pytest -q tests/test_stage.py

Run the real tests

..                                                                       [100%]
2 passed in <duration>s

Why this implementation

The mapping table is explicit, so only listed capabilities are accepted, preventing unknown capabilities from being accidentally mapped to dangerous tools.

The missing_capabilities function from capabilities.py compares contract requirements with the representable set and returns the missing capability names.

Raising a ValueError instead of silently ignoring ensures that callers immediately detect incompatibility issues.

Guided practice

Complete the CAPABILITY_TO_TOOL mapping and add rejection logic for unknown required capabilities.

In forge/adapters/claude.py, define the CAPABILITY_TO_TOOL dictionary with mappings for read_files, write_files, and shell.
Import the missing_capabilities function.
In plan_claude, compute the representable set and the missing set.
If missing is non-empty, raise a ValueError with a message containing “cannot represent” and the missing capability names.
Otherwise, generate a sorted tuple of tools and return a ClaudePlan.

Progressive hints

Hint 1: missing_capabilities(contract, representable) returns a set of capability names in the contract that are not in representable.
Hint 2: The exception message format should be "Claude adapter cannot represent: " + ", ".join(sorted(missing)).
Hint 3: The tools tuple needs to be sorted, using sorted(CAPABILITY_TO_TOOL[name] for name in contract.required_names()).

Success criteria

test_known_capabilities_map_to_tools passes: for a contract requiring only read_files, allowed_tools equals ("Read",).
test_unknown_required_capability_is_rejected passes: for a contract requiring database_admin, a ValueError is raised with a message containing “cannot represent”.

Fault injection and diagnosis

The current forge/adapters/claude.py has a defect: unknown capabilities are defaulted to Bash, causing test_unknown_required_capability_is_rejected to fail. The test expects the adapter to reject unrepresentable capabilities, but it actually accepts database_admin and returns the Bash tool.

This stage has introduced the explicit mapping table and the mechanism for rejecting unknown capabilities, so you can locate the problem by examining the mapping logic in plan_claude. The failure fixture fixtures/failure.json clearly states that the defect is ‘Use Bash as the default mapping for unknown capabilities’, and the fix is to reject missing capabilities instead.

Verified fault contract

Target test: test_unknown_required_capability_is_rejected
Faulty file: forge/adapters/claude.py

Diagnosis order

Run the faulty command python -m pytest -q ../tests/test_stage.py::test_unknown_required_capability_is_rejected and observe the assertion failure.
Inspect the plan_claude implementation in forge/adapters/claude.py and notice that CAPABILITY_TO_TOOL.get(name, "Bash") defaults unknown capabilities to Bash.
Compare with the expected behavior: unknown capabilities should cause a ValueError, not be mapped.
Modify the code to use missing_capabilities to detect missing capabilities and raise an exception.

Fix principle: In plan_claude, first compute representable = set(CAPABILITY_TO_TOOL), then call missing_capabilities(contract, representable) to get the set of missing capabilities. If the set is non-empty, raise ValueError("Claude adapter cannot represent: " + ", ".join(sorted(missing))). Otherwise, generate the tools tuple normally.

python -m pytest -q ../tests/test_stage.py::test_unknown_required_capability_is_rejected

Transfer challenge

In the office scenario, there is a ‘document review’ skill that requires both read_files and write_files capabilities. Use plan_claude to generate a plan for this skill and verify that allowed_tools includes Read and Edit.

Changed condition: Change the skill contract’s capability requirements from a single read_files to requiring both read_files and write_files, and verify that the generated tool list contains the two corresponding tools.

Write a test or script that creates SkillContract("doc_review", (CapabilityRequirement("read_files"), CapabilityRequirement("write_files"))), calls plan_claude(contract, "/work"), and asserts that the returned allowed_tools equals ("Edit", "Read") (note the sorting).

Success criteria

The generated allowed_tools tuple contains Read and Edit, and the order is ("Edit", "Read").
Calling plan_claude does not raise an exception, and the returned ClaudePlan instance’s skill_path attribute ends with /work/.claude/skills/doc_review/SKILL.md.

Run the real tests

python -m pytest -q tests/test_stage.py

Run the real tests

..                                                                       [100%]
2 passed in <duration>s

Design explanation question: Why can’t unknown capabilities be defaulted to Bash? Explain from the perspectives of least privilege and semantic correctness.

A strong answer should include

Defaulting to Bash grants the model the ability to execute arbitrary commands, violating the principle of least privilege.
Unknown capabilities may have specific semantics, and mapping them to Bash leads to behavior that does not meet expectations, breaking the skill contract.
Explicit rejection allows callers to detect incompatibility issues early, avoiding surprises at runtime.

Mastery evidence

Passes both test_known_capabilities_map_to_tools and test_unknown_required_capability_is_rejected.
Can explain the importance of explicit capability mapping: it prevents unknown capabilities from being accidentally mapped to dangerous tools, ensuring adapter safety and semantic correctness.
In the office scenario transfer challenge, successfully generates a plan containing Read and Edit for a skill requiring both read_files and write_files.

STAGE 04

Map capabilities to WorkBuddy workspace permissions while preserving read/write distinctions

Start with a concrete problem

Derive WorkBuddy workspace access level from capability requirements

The repository currently lacks forge/adapters/workbuddy.py, so the tests fail immediately when importing plan_workbuddy with ModuleNotFoundError: No module named 'forge.adapters.workbuddy'.

This stage requires creating that file and implementing the plan_workbuddy function to decide the WorkBuddy workspace access level based on the Skill’s capability requirements.

If the Skill requires the write_files capability, the workspace access level should be write; otherwise it must remain read, without defaulting to elevated permissions.

The tests test_write_skill_receives_write_access and test_read_only_skill_stays_read_only verify the write and read-only scenarios respectively.

Make a prediction

Before implementing plan_workbuddy, predict: what happens if the adapter always requests write access?

All Skills work correctly because write access is more powerful.
Read-only Skills unexpectedly receive write access, violating the principle of least privilege.
All tests pass because tests do not check the access level.
The adapter throws an exception because it cannot handle read-only Skills.

Reasoning guide: The correct answer is the second option. If the adapter always requests write access, read-only Skills unexpectedly receive write access, violating the principle of least privilege, and the test test_read_only_skill_stays_read_only fails.

What it is

What the WorkBuddy adapter is

The WorkBuddy adapter is a component that maps a Skill’s capability requirements to a WorkBuddy workspace access level.

It receives a SkillContract object, checks whether it includes the write_files capability, and then produces a WorkBuddyPlan containing the configuration path and access level.

The adapter must derive the access level from capability requirements rather than hardcoding write or read.

What it is not

What the WorkBuddy adapter is not

It is not a general permission management system, nor does it perform actual write operations.

It does not automatically elevate permissions or ignore the Skill’s capability requirements.

It does not handle the shell capability; if shell is detected, it raises a ValueError because the WorkBuddy profile does not expose shell.

How it relates to neighboring concepts

Relationships with other components

plan_workbuddy depends on the required_names() method of SkillContract to obtain the set of capability names.

WorkBuddyPlan is a frozen dataclass with two fields: config_path and workspace_access.

The test file tests/test_stage.py imports plan_workbuddy and verifies its behavior, so the adapter must match the test expectations.

Boundary decision for this stage: The adapter must decide the access level based on the presence of the write_files capability, without defaulting to elevated permissions; it must also reject the shell capability because WorkBuddy does not support shell.

Experiment: platform-adapters-04-workbuddy-adapter
Input: Software delivery: add a feature to a frontend repository, modify code, and add tests.
Evidence: evidence/platform-adapters/04-workbuddy-adapter/
Gate: Pending acceptance

Worked example

Goal: Demonstrate implementing plan_workbuddy to decide access level based on the write_files capability.

First, we need to create the file forge/adapters/workbuddy.py and define the WorkBuddyPlan dataclass and the plan_workbuddy function.

Inside the function, we call contract.required_names() to get the set of capability names, then check whether it contains write_files.

If it does, the access level is write; otherwise it is read. Additionally, if the shell capability is detected, we raise a ValueError.

Finally, we return a WorkBuddyPlan instance with the configuration path {workspace}/.workbuddy/{skill_id}.json, making sure to strip trailing slashes from the workspace path.

Implementation steps

Create the file forge/adapters/workbuddy.py.
Import dataclass and SkillContract.
Define the WorkBuddyPlan dataclass with fields config_path and workspace_access.
Implement plan_workbuddy to obtain the capability name set, check for shell and write_files, and return the appropriate plan.

Verified solution code: forge/adapters/workbuddy.py

from dataclasses import dataclass
from forge.adapters.capabilities import SkillContract

@dataclass(frozen=True)
class WorkBuddyPlan:
    config_path: str
    workspace_access: str

def plan_workbuddy(contract: SkillContract, workspace: str) -> WorkBuddyPlan:
    required = contract.required_names()
    if "shell" in required:
        raise ValueError("WorkBuddy profile does not expose shell")
    access = "write" if "write_files" in required else "read"
    return WorkBuddyPlan(f"{workspace.rstrip('/')}/.workbuddy/{contract.skill_id}.json", access)

python -m pytest -q tests/test_stage.py

Run the real tests

..                                                                       [100%]
2 passed in <duration>s

Why this implementation

contract.required_names() returns a set containing all capability names required by the Skill.

By checking "write_files" in required, we can determine whether the Skill needs write access.

If the shell capability is detected, we raise a ValueError because the WorkBuddy profile does not support shell.

The configuration path uses workspace.rstrip('/') to ensure there are no trailing slashes.

Guided practice

Fix plan_workbuddy to return read access when write_files is absent.

Open the file forge/adapters/workbuddy.py.
Examine the assignment logic for the access level in the plan_workbuddy function.
Ensure that when write_files is not in the capability set, the access level is read.
Run the tests with python -m pytest -q tests/test_stage.py to verify the fix.

Progressive hints

Hint 1: Use the conditional expression access = "write" if "write_files" in required else "read".
Hint 2: Do not forget to check for the shell capability and raise an exception.
Hint 3: Ensure the configuration path is correctly concatenated using workspace.rstrip('/').

Success criteria

Test test_write_skill_receives_write_access passes.
Test test_read_only_skill_stays_read_only passes.

Fault injection and diagnosis

In the failure fixture fixtures/failure.json, forge/adapters/workbuddy.py has an injected defect: plan_workbuddy always returns workspace_access="write", ignoring the Skill’s actual capability requirements. Running the test test_read_only_skill_stays_read_only fails because a read-only Skill receives write access.

This stage has taught how to derive the access level from capability requirements, so we can recognize that the adapter ignores the capability set and fix it to decide based on the presence of write_files. The implementation in forge/adapters/workbuddy.py is directly constrained by test_read_only_skill_stays_read_only, so we can use the verified boundary mechanism to locate this fault.

Verified fault contract

Target test: test_read_only_skill_stays_read_only
Faulty file: forge/adapters/workbuddy.py

Diagnosis order

Run the failing test command python -m pytest -q ../tests/test_stage.py::test_read_only_skill_stays_read_only and observe the assertion failure.
Inspect the plan_workbuddy function in forge/adapters/workbuddy.py and notice it hardcodes the return value "write".
Compare with the expected behavior: it should check whether write_files is in contract.required_names().
Fix the function to dynamically decide the access level based on the capability set.

Fix principle: Modify the plan_workbuddy function to use required = contract.required_names() to obtain the capability set, then set access = "write" if "write_files" in required else "read", and keep the check for the shell capability.

python -m pytest -q ../tests/test_stage.py::test_read_only_skill_stays_read_only

Transfer challenge

In the office scenario, there is a ‘read-only report’ skill that requires only the read_files capability. Use plan_workbuddy to generate a plan for this skill and verify that the workspace access level is read.

Changed condition: Change the skill’s capability requirement from the guided practice’s write_files capability to a read-only file capability, i.e., only read_files, so the access level should be read.

Write a test or script that creates a SkillContract with only the read_files capability, then calls plan_workbuddy and asserts that the returned workspace_access is read.

Success criteria

The created SkillContract must contain only the read_files capability.
After calling plan_workbuddy, the returned workspace_access must be read.
The returned config_path must correctly concatenate the workspace path and skill ID, without trailing slashes.

Run the real tests

python -m pytest -q tests/test_stage.py

Run the real tests

..                                                                       [100%]
2 passed in <duration>s

Design explanation question: Why shouldn’t a read-only Skill receive write access? What are the consequences if the adapter always requests write access?

A strong answer should include

A read-only Skill only needs to read files and does not need to modify them, so granting write access expands the attack surface.
If the adapter always requests write access, then even if the Skill does not need to write, it could accidentally modify files, leading to data corruption or security vulnerabilities.
Follow the principle of least privilege: grant only the minimum permissions necessary to complete the task.

Mastery evidence

Passes tests test_write_skill_receives_write_access and test_read_only_skill_stays_read_only.
Can explain why a read-only Skill should not receive write access and the importance of the principle of least privilege.
Successfully repaired the adapter in the fault lab to dynamically decide the access level based on capability requirements.

STAGE 05

Normalize three platform plans into comparable and auditable configuration records

Start with a concrete problem

How do we unify different platform install plans into comparable configuration records?

The file forge/adapters/config.py does not exist yet, so the normalize_plan function is missing, causing the tests to fail at import time.

We need to implement a normalization function that takes a platform identifier and an install plan dataclass, and returns a dictionary containing schemaVersion and configuration.

The key decision is that normalization must validate the platform identifier; otherwise unknown platforms can slip into release configuration, creating audit and deployment risks.

Make a prediction

When implementing normalize_plan, what should the function do if an unknown platform identifier like “mystery-agent” is passed?

Serialize and return the configuration record directly, because normalization only handles format conversion
Raise ValueError, because normalization must validate the platform identifier
Return a configuration record with a default platform field
Ignore the platform field and only serialize the plan dataclass

Reasoning guide: The correct option is to raise ValueError. Normalization is not just format conversion; it must ensure the platform identifier belongs to the supported adapter registry, otherwise unknown platforms enter release configuration and undermine auditability and deployment safety.

What it is

What normalized platform configuration is

Normalized platform configuration is the process of converting different platform install plans into a unified structure containing platform identifier, schema version, and configuration data.

It must validate that the platform identifier is in the supported adapter registry and check that the plan is a dataclass containing an install path.

The normalized configuration record is comparable, auditable, and can be safely consumed by downstream deployment processes.

What it is not

What normalized platform configuration is not

Normalization is not simple serialization; it cannot accept arbitrary platform names without validation.

Normalization does not perform installation or modify plan content; it only converts the plan to a standard format and ensures basic constraints.

Normalization is not the platform adapter itself; it does not handle platform-specific communication protocols or authentication logic.

How it relates to neighboring concepts

Relationships with other components

The normalization function normalize_plan is directly called by the test file tests/test_stage.py, which expects it to validate the platform and return the correct schemaVersion.

It relies on Python’s dataclasses module to serialize the plan dataclass and checks that the plan contains an install path field.

The normalized configuration record will be used by subsequent deployment processes, so the platform identifier must be valid.

Boundary decision for this stage: Normalization must validate the platform identifier and reject unknown platforms; it must also check that the plan is a dataclass and contains an install path, otherwise raise the appropriate exception.

Experiment: platform-adapters-05-normalized-platform-config
Input: Software delivery: add a feature to a frontend repository, modify code, and add tests.
Evidence: evidence/platform-adapters/05-normalized-platform-config/
Gate: Pending acceptance

Worked example

Goal: Demonstrate implementing a basic version of normalize_plan, including platform validation and dataclass serialization.

First, create the file forge/adapters/config.py and import asdict and is_dataclass from the dataclasses module.

Then define the normalize_plan function that takes a platform identifier and a plan object, and returns a normalized dictionary.

Inside the function, first check if the platform identifier is in the supported set; if not, raise ValueError.

Next, check if the plan object is a dataclass; if not, raise TypeError.

Finally, use asdict to convert the dataclass to a dictionary, check that it contains a key ending with path, and return a dictionary with platform, schema version, and configuration.

Implementation steps

Create the file forge/adapters/config.py.
Import asdict and is_dataclass.
Define the normalize_plan function.
Add platform validation logic.
Add dataclass check and path check.
Return the normalized dictionary.

Verified solution code: forge/adapters/config.py

from dataclasses import asdict, is_dataclass

def normalize_plan(platform: str, plan: object) -> dict[str, object]:
    if platform not in {"codex", "claude-code", "workbuddy"}:
        raise ValueError("unknown platform")
    if not is_dataclass(plan):
        raise TypeError("adapter plan must be a dataclass")
    values = asdict(plan)
    if not any(key.endswith("path") for key in values):
        raise ValueError("adapter plan lacks install path")
    return {"platform": platform, "schemaVersion": 1, "configuration": values}

python -m pytest -q tests/test_stage.py

Run the real tests

..                                                                       [100%]
2 passed in <duration>s

Why this implementation

Platform validation ensures that only supported platforms (codex, claude-code, workbuddy) can pass normalization; unknown platforms are immediately rejected.

The dataclass check prevents serialization errors from non-dataclass objects, and the path check ensures the plan contains an install path, which is required for deployment.

The returned dictionary contains platform, schemaVersion, and configuration fields, satisfying the test’s assertion that schemaVersion is 1.

Guided practice

Add a platform registry check to the existing implementation so that unknown platforms raise ValueError.

Open the file forge/adapters/config.py.
Add platform validation code at the beginning of the normalize_plan function.
Use if platform not in {"codex", "claude-code", "workbuddy"}: to check if the platform is supported.
If the platform is not supported, raise ValueError("unknown platform").
Run the tests to confirm test_unknown_platform_is_rejected passes.

Progressive hints

Hint: The platform set should include all implemented adapter platform names.
Hint: The exception message must contain the substring “unknown” to satisfy the test assertion.
Hint: Validation should be placed at the very beginning of the function to avoid processing invalid platforms.

Success criteria

test_unknown_platform_is_rejected passes.
test_known_platform_is_normalized still passes.

Fault injection and diagnosis

In the failure fixture fixtures/failure.json, the normalize_plan function in forge/adapters/config.py lacks platform registry validation, causing the unknown platform mystery-agent to be serialized into a seemingly valid configuration record. The test test_unknown_platform_is_rejected fails because the function does not raise the expected ValueError.

The core mechanism of this stage is validating the platform identifier during normalization. By checking whether the platform is in the supported adapter registry, we can reject unknown platforms and fix the failure. The learner has already understood the necessity of platform validation and can implement the corresponding check logic.

Verified fault contract

Target test: test_unknown_platform_is_rejected
Faulty file: forge/adapters/config.py

Diagnosis order

Run the faulty command python -m pytest -q ../tests/test_stage.py::test_unknown_platform_is_rejected and observe the test failure.
Inspect the normalize_plan function in forge/adapters/config.py and notice that it serializes the platform name directly without validation.
Confirm that the test expects an unknown platform to raise ValueError, but the current function does not raise any exception.
Identify the root cause: normalization is mistaken for validation, and the platform registry check is missing.

Fix principle: Add platform validation at the beginning of the normalize_plan function: if platform not in {"codex", "claude-code", "workbuddy"}: raise ValueError("unknown platform"). This immediately rejects unknown platforms and makes the test pass.

python -m pytest -q ../tests/test_stage.py::test_unknown_platform_is_rejected

Transfer challenge

In the music creation scenario, you need to use normalize_plan to normalize a Codex platform install plan. The plan dataclass is Plan, containing a target_path field.

Changed condition: Change the plan’s target path from the default /skills/a to /skills/music-release, while keeping the platform as codex.

Write a test or script that calls normalize_plan("codex", Plan("/skills/music-release")) and verifies that the returned schemaVersion is 1 and the configuration contains the correct target_path.

Success criteria

Call normalize_plan with platform codex and plan Plan("/skills/music-release").
Assert that the returned dictionary’s platform field equals codex.
Assert that the returned dictionary’s schemaVersion equals 1.
Assert that the returned dictionary’s configuration field contains target_path with value /skills/music-release.

Run the real tests

python -m pytest -q tests/test_stage.py

Run the real tests

..                                                                       [100%]
2 passed in <duration>s

Design explanation question: Why must normalization include platform validation? What risk arises if unknown platforms are accepted?

A strong answer should include

Platform validation ensures that only supported platforms can enter configuration records, preventing deployment failures or security vulnerabilities from unknown platforms.
Accepting unknown platforms breaks configuration auditability because downstream processes cannot identify the platform, potentially leading to incorrect operations or data corruption.
Separating normalization from validation results in configuration records that appear valid but are actually unusable, increasing debugging costs.

Mastery evidence

Passes both test_known_platform_is_normalized and test_unknown_platform_is_rejected.
Can explain the difference between normalization and validation: normalization handles format conversion, while validation ensures platform identifier legality.
Successfully uses normalize_plan in the transfer challenge with a different platform and path, and verifies the returned result.

STAGE 06

Distinguish blocking gaps from acceptable degradation in an explainable compatibility report

Start with a concrete problem

A platform missing an optional capability is incorrectly marked incompatible

In the previous stage, you normalized raw platform configurations into a unified SkillContract, where each capability carries a required flag.

Now you need to implement the evaluate function to generate a CompatibilityReport based on the platform’s actually available capabilities, and the report must distinguish blocking gaps from acceptable degradations.

The file forge/adapters/compatibility.py does not exist yet, so running the tests will immediately raise ModuleNotFoundError because the test file tests/test_stage.py tries to import evaluate.

If you naively put every missing capability into blockers, then a platform missing the optional capability git will also be marked incompatible, which violates the contract semantics.

Make a prediction

Before implementing evaluate, predict: if a platform lacks a capability marked optional (e.g., git), what should CompatibilityReport.compatible be?

False, because any missing capability means the platform is incomplete
True, because missing optional capabilities should not block compatibility
False, but put the missing item into degradations
True, but put the missing item into blockers

Reasoning guide: The correct answer is True: missing optional capabilities should only be recorded as degradations and do not affect overall compatibility. Only missing required capabilities cause compatible=False.

What it is

A compatibility report is a diff analysis between contract and platform capabilities

CompatibilityReport is an immutable dataclass containing a compatible boolean, a blockers tuple, and a degradations tuple.

The evaluate function iterates over each CapabilityRequirement in the SkillContract and checks whether its name is in the available set.

For each missing capability, it decides whether to put it into blockers or degradations based on its required flag.

The final compatible value depends only on whether blockers is empty, not on degradations.

What it is not

A compatibility report is not a simple list of missing capabilities

It does not lump all missing capabilities together but preserves the required/optional semantics of each capability.

It does not modify the platform configuration or automatically install missing capabilities; it only performs a static evaluation.

It does not guarantee that the platform will succeed at runtime; it only reflects static contract-level compatibility.

How it relates to neighboring concepts

Relationship with existing components

SkillContract and CapabilityRequirement come from forge/adapters/capabilities.py, which are not modified in this stage.

The evaluate function is called directly by the test file tests/test_stage.py, and the tests expect the returned CompatibilityReport fields to match exactly.

Later stages may use this report to decide whether to allow deployment or trigger a migration process.

Boundary decision for this stage: Only when a missing capability’s required attribute is True should it be added to blockers; otherwise it goes into degradations, and compatible depends solely on whether blockers is empty.

Experiment: platform-adapters-06-compatibility-loss-report
Input: Software delivery: add a feature to a frontend repository, modify code, and add tests.
Evidence: evidence/platform-adapters/06-compatibility-loss-report/
Gate: Pending acceptance

Worked example

Goal: Demonstrate how to implement evaluate to produce a CompatibilityReport with blockers and degradations.

Suppose a skill contract requires read_files (required) and git (optional), and the platform provides only read_files.

The correct evaluation result should be compatible=True, blockers=(), degradations=('git',).

When implementing, first collect missing required and optional capabilities separately, then construct the report.

Implementation steps

Create the file forge/adapters/compatibility.py.
Define the CompatibilityReport dataclass with fields compatible, blockers, and degradations.
Implement the evaluate function: iterate over contract.capabilities, and for each missing item, classify it based on the required flag.
Sort the classified results to ensure determinism, then return CompatibilityReport(not blockers, blockers, degradations).

Verified solution code: forge/adapters/compatibility.py

from dataclasses import dataclass
from forge.adapters.capabilities import SkillContract

@dataclass(frozen=True)
class CompatibilityReport:
    compatible: bool
    blockers: tuple[str, ...]
    degradations: tuple[str, ...]

def evaluate(contract: SkillContract, available: set[str]) -> CompatibilityReport:
    blockers = tuple(sorted(item.name for item in contract.capabilities if item.required and item.name not in available))
    degradations = tuple(sorted(item.name for item in contract.capabilities if not item.required and item.name not in available))
    return CompatibilityReport(not blockers, blockers, degradations)

python -m pytest -q tests/test_stage.py

Run the real tests

..                                                                       [100%]
2 passed in <duration>s

Why this implementation

The test test_required_gap_blocks_compatibility verifies that when a required capability is missing, compatible is False.

The test test_optional_gap_is_reported_as_degradation verifies that when an optional capability is missing, compatible is True and degradations contains that capability.

Guided practice

Fix evaluate so that optional gaps go into degradations instead of blockers.

Open forge/adapters/compatibility.py and check whether the current implementation puts all missing capabilities into blockers.
Modify the list comprehension to add the condition if item.required to filter required capabilities.
Create another list comprehension for optional capabilities with the condition if not item.required.
Ensure both tuples are sorted, then rerun the tests.

Progressive hints

Note that the required field of CapabilityRequirement defaults to True.
Both blockers and degradations should be tuples with stable element order.
The value of compatible is not blockers, not not missing.

Success criteria

test_required_gap_blocks_compatibility passes.
test_optional_gap_is_reported_as_degradation passes.

Fault injection and diagnosis

The current implementation in forge/adapters/compatibility.py puts every missing capability into blockers, causing a platform missing the optional capability git to be incorrectly marked incompatible. Running the test test_optional_gap_is_reported_as_degradation fails because the assertion report.compatible is True does not hold.

The core of this stage is to distinguish required and optional capabilities, and the fault is exactly the loss of that distinction. By inspecting the conditions in the list comprehensions inside the evaluate function, you can locate the missing if item.required filter. After the fix, the test will pass.

Verified fault contract

Target test: test_optional_gap_is_reported_as_degradation
Faulty file: forge/adapters/compatibility.py

Diagnosis order

Run python -m pytest -q ../tests/test_stage.py::test_optional_gap_is_reported_as_degradation and observe the failure output.
In the failure message, see CompatibilityReport(compatible=False, blockers=('git',), degradations=()), which shows that git was placed into blockers.
Open forge/adapters/compatibility.py and inspect the list comprehension in the evaluate function to confirm that it does not differentiate based on the required flag.
Fix the code so that missing required capabilities go into blockers and missing optional capabilities go into degradations.

Fix principle: Modify the evaluate function to use two separate conditions, if item.required and if not item.required, to generate blockers and degradations, then return CompatibilityReport(not blockers, blockers, degradations).

python -m pytest -q ../tests/test_stage.py::test_optional_gap_is_reported_as_degradation

Transfer challenge

In the music creation scenario, you need to evaluate the compatibility of a ‘track management’ skill on a certain platform. The skill contract requires read_files as required and git as optional, and the platform provides only read_files.

Changed condition: Change the skill contract’s capability set from the default example to the music scenario’s ‘track management’ skill while keeping the required/optional flags unchanged.

Use the evaluate function to assess the compatibility between this skill contract and the platform’s available capability set, and verify the result.

Success criteria

The returned CompatibilityReport.compatible is True.
The returned CompatibilityReport.degradations contains git, and blockers is empty.

Run the real tests

python -m pytest -q tests/test_stage.py

Run the real tests

..                                                                       [100%]
2 passed in <duration>s

Design explanation question: Why shouldn’t missing optional capabilities block compatibility? Explain the impact of this design on platform adaptation decisions, referencing the semantics of blockers and degradations in CompatibilityReport.

A strong answer should include

Missing optional capabilities only affect partial functionality; the platform can still accomplish core tasks, so they should not block overall compatibility.
Putting missing items into degradations allows callers to understand potential limitations while still permitting deployment to proceed.
If all missing capabilities were treated as blockers, the evaluation would be overly conservative and miss usable platforms.

Mastery evidence

Passes both test_required_gap_blocks_compatibility and test_optional_gap_is_reported_as_degradation.
Can explain the difference between blockers and degradations and why optional gaps do not block compatibility.
In the music scenario transfer challenge, correctly uses evaluate to obtain compatible=True and degradations containing git.

STAGE 07

Use one contract suite to check install paths, non-escalation, and capability coverage before release

Start with a concrete problem

How do we automatically check adapter plans for security and capability requirements?

In the previous stage, we generated a compatibility report, but the report only describes differences and does not prevent unsafe adapter releases.

Now we need to implement a conformance check function check_plan that takes a platform name, a configuration dictionary, and a set of required capabilities, and returns a ConformanceResult.

If the configuration lacks an install path, does not cover the required capabilities, or has approval_mode set to full-access while the required capabilities do not include unattended_write, it must be marked as failed with specific errors.

The codebase currently has no forge/adapters/conformance.py file, so the tests fail at import time.

Make a prediction

Before implementing check_plan, predict: if we only check that the configuration is non-empty, will test_permission_escalation_fails_conformance pass?

Yes, because the configuration is non-empty and contains capabilities.
No, because the full-access approval mode grants permissions beyond the required capabilities.
Yes, because the test only checks that passed is False.
No, because the configuration lacks target_path.

Reasoning guide: The correct answer is ‘No, because the full-access approval mode grants permissions beyond the required capabilities.’ The test passes approval_mode as full-access but the required capability is only read_files, which is a permission escalation and must be rejected. Checking only non-emptiness cannot detect this semantic violation.

What it is

What conformance checking is

Conformance checking is semantic validation of the configuration plan generated by an adapter to ensure it meets security and capability contracts.

It checks three key dimensions: whether the install path exists and is non-empty, whether the required capabilities are declared by the configuration, and whether the approval mode causes permission escalation.

The check result is returned via the ConformanceResult dataclass, containing the platform name, whether it passed, and a tuple of errors.

What it is not

What conformance checking is not

It is not just checking whether the configuration dictionary is non-empty or fields exist, because correct shape does not imply semantic safety.

It does not perform the actual installation or modify system state; it only statically analyzes the plan.

It cannot replace domain acceptance or guarantee that model output is always correct; it only verifies that the adapter plan conforms to predefined rules.

How it relates to neighboring concepts

Relationship to other components

check_plan uses the configuration dictionary and required capabilities set as inputs, which come from the Skill metadata and the adapter-generated plan.

The errors tuple of ConformanceResult is asserted by tests, for example test_permission_escalation_fails_conformance checks that errors contains “permission escalation”.

This check resides in forge/adapters/conformance.py, and together with capabilities.py, compatibility.py, etc., forms the adapter layer.

Boundary decision for this stage: Conformance checks must validate semantics, including non-escalation and capability coverage, not just configuration shape. If we only check non-emptiness, we would approve an adapter that grants undeclared full-access, leading to security risks.

Experiment: platform-adapters-07-adapter-conformance-suite
Input: Software delivery: add a feature to a frontend repository, modify code, and add tests.
Evidence: evidence/platform-adapters/07-adapter-conformance-suite/
Gate: Pending acceptance

Worked example

Goal: Demonstrate implementing the basic parts of check_plan: checking install path and capability coverage.

We start by creating the forge/adapters/conformance.py file from scratch and defining the ConformanceResult dataclass.

First, implement the install path check: find an item in the configuration dictionary whose key ends with ‘path’, and if its value is not a non-empty string, add the error “install path missing”.

Then implement the capability coverage check: get the capabilities list from the configuration, and if the required capabilities set is not a subset of it, add the error “required capability missing”.

Implementation steps

Create the file forge/adapters/conformance.py.
Import dataclass and define the ConformanceResult dataclass with fields platform, passed, and errors.
Define the check_plan function and initialize an errors list.
Use next and a generator expression to find an item whose key ends with ‘path’, and check that its value is a non-empty string.
Get the capabilities set from the configuration and check that required_capabilities is a subset of it.
Return ConformanceResult(platform, not errors, tuple(errors)).

Verified solution code: forge/adapters/conformance.py

from dataclasses import dataclass

@dataclass(frozen=True)
class ConformanceResult:
    platform: str
    passed: bool
    errors: tuple[str, ...]

def check_plan(platform: str, configuration: dict[str, object], required_capabilities: set[str]) -> ConformanceResult:
    errors: list[str] = []
    path_value = next((value for key, value in configuration.items() if key.endswith("path")), "")
    if not isinstance(path_value, str) or not path_value:
        errors.append("install path missing")
    declared = set(configuration.get("capabilities", ()))
    if declared and not required_capabilities.issubset(declared):
        errors.append("required capability missing")
    if configuration.get("approval_mode") == "full-access" and "unattended_write" not in required_capabilities:
        errors.append("permission escalation")
    return ConformanceResult(platform, not errors, tuple(errors))

python -m pytest -q tests/test_stage.py

Run the real tests

..                                                                       [100%]
2 passed in <duration>s

Why this implementation

The install path check ensures that the adapter plan specifies a valid target path, avoiding installation to unknown locations.

The capability coverage check ensures that the adapter declares at least the capabilities required by the Skill, otherwise runtime may fail due to missing permissions.

These two checks form the basis of semantic validation, but they do not yet handle permission escalation.

Guided practice

Add a permission escalation check so full-access fails when unattended_write is not required.

In the check_plan function, after the capability coverage check, add a permission escalation check.
Check if configuration.get(“approval_mode”) equals “full-access”.
Also check if “unattended_write” is not in required_capabilities.
If both conditions are true, append “permission escalation” to the errors list.
Run the test test_permission_escalation_fails_conformance to verify the result.

Progressive hints

Use configuration.get(“approval_mode”) to get the approval mode.
Use not in to check if “unattended_write” is not in required_capabilities.
The error message must match the test assertion, i.e., “permission escalation”.

Success criteria

test_permission_escalation_fails_conformance passes.
test_safe_plan_conforms still passes.

Fault injection and diagnosis

The current faulty version of conformance.py only checks if the configuration is non-empty, so it incorrectly approves a full-access plan. Running the test test_permission_escalation_fails_conformance fails because the plan grants permissions beyond the required capabilities. You need to diagnose and fix this defect. The executable fault fixture modifies forge/adapters/conformance.py and is reliably reproduced by test_permission_escalation_fails_conformance.

This stage has already implemented install path and capability coverage checks, but lacks the permission escalation check. The faulty version is missing this critical semantic validation, causing the full-access plan to be incorrectly passed. By adding the permission escalation check, we can prevent unsafe adapter releases.

Verified fault contract

Target test: test_permission_escalation_fails_conformance
Faulty file: forge/adapters/conformance.py

Diagnosis order

Run the command python -m pytest -q ../tests/test_stage.py::test_permission_escalation_fails_conformance and observe the test failure.
Look at the test code and see that it passes approval_mode as full-access but the required capability is only read_files.
Inspect the faulty version of check_plan and notice that it only checks if the configuration is non-empty, without checking the relationship between approval mode and required capabilities.
Confirm the defect: the missing permission escalation check causes the full-access plan to be incorrectly passed.

Fix principle: In the check_plan function, add a permission escalation check: if configuration.get(“approval_mode”) == “full-access” and “unattended_write” not in required_capabilities, append “permission escalation” to the errors list. This way, a full-access plan is rejected when unattended_write is not required.

python -m pytest -q ../tests/test_stage.py::test_permission_escalation_fails_conformance

Transfer challenge

In the office research scenario, a WorkBuddy adapter plan is configured for read-only access with required capability read_files. Use check_plan to check this plan and verify that passed is True.

Changed condition: Change the scenario from the software delivery Codex platform to the office research WorkBuddy platform, and adjust the configuration to read-only access.

Write a Python script or interactive call that uses the check_plan function to check the following plan: platform is “workbuddy”, configuration is {“target_path”:“/skills/office”, “capabilities”:[“read_files”], “approval_mode”:“ask-before-writes”}, and required_capabilities is {“read_files”}. Verify that the returned ConformanceResult has passed set to True.

Success criteria

After calling check_plan, the returned ConformanceResult object has passed equal to True.
The errors tuple is empty, indicating no conformance errors.

Run the real tests

python -m pytest -q tests/test_stage.py

Run the real tests

..                                                                       [100%]
2 passed in <duration>s

Design explanation question: Why must conformance checks include permission escalation? What risk arises if conformance checks only validate configuration shape?

A strong answer should include

Permission escalation means the adapter grants more permissions than the Skill actually needs, for example full-access approval mode allows automatic writes while the Skill only needs to read files.
If only configuration shape is validated, an attacker or misconfiguration could grant excessive permissions, leading to unauthorized operations or data leakage.
Checking permission escalation enforces the principle of least privilege and reduces security risks.

Mastery evidence

Passes both test_safe_plan_conforms and test_permission_escalation_fails_conformance.
Can explain why conformance checks must include permission escalation checks, not just configuration shape validation.
In transferChallenge, successfully uses check_plan to verify that a WorkBuddy plan in the office scenario passes the check.

Complete the chapter

Deploy the same Forge Skill to three platforms through adapters.

FORGE / LOCAL CHECK

Local lab self-check

Not started
2Reading
3Lab downloaded
4Test result read
5Local check passed

verification.json is parsed only in this browser and is never uploaded. This checks the lab contract; it is not server certification or third-party endorsement.

Choose verification.json

Primary layer

Depends on

Provides to

Governed by

Concept calibration

Harness

Skill

Tool

Cross-Platform Adapters & Migration

Start with a concrete problem

How can we declare which capabilities a Skill needs in a platform-neutral way, distinguishing required from optional?

Make a prediction

What it is

What a platform-neutral capability contract is

What it is not

What a platform-neutral capability contract is not

How it relates to neighboring concepts

Relationships among contract components

Start with a concrete problem

From canonical contract to Codex install plan

Make a prediction

What it is

Adapter is a translator of security semantics

What it is not

Adapter is not a permission decision-maker

How it relates to neighboring concepts

Relationship between contract, adapter, and Harness

Start with a concrete problem

Generate a command allowlist for Claude Code and reject required capabilities that cannot be represented

Make a prediction

What it is

Explicit capability mapping table

What it is not

Not an alias for generic shell access

How it relates to neighboring concepts

Relationship with skill contract and platform plan

Start with a concrete problem

Derive WorkBuddy workspace access level from capability requirements

Make a prediction

What it is

What the WorkBuddy adapter is

What it is not

What the WorkBuddy adapter is not

How it relates to neighboring concepts

Relationships with other components

Start with a concrete problem

How do we unify different platform install plans into comparable configuration records?

Make a prediction

What it is

What normalized platform configuration is

What it is not

What normalized platform configuration is not

How it relates to neighboring concepts

Relationships with other components

Start with a concrete problem

A platform missing an optional capability is incorrectly marked incompatible

Make a prediction

What it is

A compatibility report is a diff analysis between contract and platform capabilities

What it is not

A compatibility report is not a simple list of missing capabilities

How it relates to neighboring concepts

Relationship with existing components

Start with a concrete problem

How do we automatically check adapter plans for security and capability requirements?

Make a prediction

What it is

What conformance checking is

What it is not

What conformance checking is not

How it relates to neighboring concepts

Relationship to other components