prompt-linker 0.8.0__tar.gz

prompt_linker-0.8.0/.gitignore

@@ -0,0 +1,40 @@
+# --- prompt-linker generated artifacts ---
+# Compiled instruction sets are DERIVED STATE: regenerate, never hand-edit.
+# (See Docs/PromptLinker.md §6 — the compiled artifact must never be committed.)
+compiled/
+compiled-annotated/
+*.compiled.md
+.prompt-linker-cache/
+
+# --- Python ---
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+env/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# --- Node ---
+node_modules/
+npm-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+*.tgz
+
+# --- Claude Code (personal/local only; shared .claude/settings.json is committed) ---
+.claude/settings.local.json
+
+# --- Editors / OS ---
+.vscode/
+.idea/
+*.swp
+.DS_Store
+Thumbs.db

prompt_linker-0.8.0/CHANGELOG.md

@@ -0,0 +1,94 @@
+# Changelog
+
+All notable changes to **prompt-linker** are recorded here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+Group entries under `Added`, `Changed`, `Deprecated`, `Removed`, `Fixed`, or `Security`.
+Keep an `[Unreleased]` section at the top; on release, rename it to the new version + date and
+start a fresh `[Unreleased]`.
+
+## [Unreleased]
+
+### Changed
+- The published source archive (sdist) now ships only consumer-relevant files.
+  `[tool.hatch.build.targets.sdist]` excludes git-tracked maintainer-only directories
+  (`Roadmap/private/`, `Docs/private/`) and repo scaffolding not meant to travel with the tool or enter
+  a consuming repo's agent context (`CLAUDE.md`, `.claude/`, `.github/`). The public `Docs/` describe
+  the security scan at the level of which classes of injection are caught and the hard-fail vs advisory
+  contract; lower-level internal notes live in the repo only. The wheel was already limited to the
+  package modules.
+
+### Added
+- **Content-addressed default output.** With no `--out`, `compile` writes to
+  `compiled/<name>-<config-hash>/` and prints that path, so distinct builds never collide and a host
+  can freeze a run by recording it (§7.3, resolves PC-OQ-4). The new **`config-hash`** fingerprints the
+  bindings **plus** the text of every source and inlined impl (stamped in the header next to
+  `resolution-hash`), so editing an impl body yields a fresh dir — a frozen build is never silently
+  overwritten.
+- **`compile --force`** and a fail-closed overwrite guard: writing over a non-empty directory that
+  prompt-linker did not generate (no build marker) is refused unless `--force`; overwriting a previous
+  build is always allowed (derived state).
+- **`check --deep`**: a configuration-level (cross-file) coherence pass on top of the per-file one.
+  All compiled files are reviewed together, so partner blocks inlined into *different* files (a writer
+  in one, a reader in another) are still cross-checked — closing the per-file pass's structural blind
+  spot (Verification §2.1).
+- The annotated build now embeds each block's **contract signature** in its block marker, giving the
+  coherence check the contract as context. It is framed as *context, not ground truth* — a block may
+  not fit its placement, so the reviewer judges the assembled text on its own merits (Verification
+  §2.1, PromptLinker §7.4).
+
+### Changed
+- Resolved the slot-granularity open question (was PC-OQ-1): contract size is the configuration
+  author's call, not the tool's. Documented the actual requirement instead — a `contract.md` must
+  state Input / Output / Invariant concretely enough that substitutability is checkable (PromptLinker
+  §4.2); moved the item from Roadmap "Open questions" to "Done".
+- Resolved the impl-composition open question (was PC-OQ-2): a slot binds **exactly one** impl;
+  ordered multi-impl binding stays unsupported. Sequencing or layering a cross-cutting concern is done
+  by **slot composition** — multiple slots, each its own contract (PromptLinker §4.1); moved from
+  Roadmap "Open questions" to "Done".
+- Resolved the cross-contract-dependencies open question (was PC-OQ-3): decided **against** a formal
+  `provides`/`requires` capability system. Partner-contract coupling is covered by the AI coherence
+  check instead, strengthened by the embedded-contract context and `check --deep` (above); moved from
+  Roadmap "Open questions" to "Done" and retired the related "partnership enforcement" backlog item.
+- Resolved the artifact-location open question (was PC-OQ-4) as a boundary: the linker emits a
+  content-addressed artifact and prints its path (above); the host records that path and points its
+  agent at it. `compile`'s default `--out` is no longer the fixed `compiled/` directory. Moved from
+  Roadmap "Open questions" to "Done"; trimmed the "per-run freeze record" backlog item to its
+  remaining host-side half.
+- Resolved the partial-recompilation open question (was PC-OQ-5): **full recompile**, always —
+  per-contract dependency tracking is rejected (it reintroduces cached staleness, §4.3, for a
+  non-existent cost). Output-level dedup is already provided by the content-addressed dir (PC-OQ-4).
+  Doc-only; moved from Roadmap "Open questions" to "Done".
+- Resolved the per-slot-binding open question (was PC-OQ-6): binding stays **per-contract by
+  principle** — a slot names a contract *type*, never an implementation (Liskov substitutability, §2),
+  so per-slot / named-slot binding is declined, not deferred. With this, **all PC-OQ-1..6 are
+  resolved** and Roadmap "Open questions" is empty. Doc-only.
+
+## [0.8.0] — 2026-06-25
+
+First documented release. Establishes the working linker, the verification layers, and the CLI.
+
+### Added
+- **Deterministic linker** (`compiler.py`): a symbol table built fresh each run from front-matter
+  identity (`contract:` / `impl:`), layered resolution `defaults → preset → overrides`, slot
+  inlining, static-file mirroring, and a provenance `GENERATED` header (resolved bindings +
+  resolution hash + origin).
+- **Structural verifier**: fail-closed coverage / identity / fit checks, the §8 override-layer rule
+  (overrides may touch only run-local contracts), preset `extends` with cycle detection, and
+  location-vs-identity advisories.
+- **Deterministic security scan** (Verification §3.2): invisible/bidi control-character hard-fail,
+  capability-envelope screens (`network` / `tools` / `secrets`), and additional injection heuristics.
+- **AI verifier** (`check.py`): opt-in conformance / coherence / security passes via Claude with
+  structured (JSON-schema) output; all model-boundary failures funnelled into `LinkError`. `--library`
+  and `--security` modes.
+- **CLI** (`cli.py`): `compile`, `verify`, `check`, with shared `--preset` / `--set` overrides and
+  `--annotated` debug builds.
+- **Examples**: runnable `StarterTemplate` and `TestConfiguration` configurations.
+- **Docs**: `PromptLinker.md` (design), `Verification.md`, `Commands.md`, `Errors.md`.
+- **Quality gates**: `pytest` suite (77 tests), `ruff` (line length 100), `mypy --strict`, wired into
+  GitHub Actions CI (Python 3.11 / 3.12).
+
+[Unreleased]: https://github.com/ega-ega/prompt-linker/compare/v0.8.0...HEAD
+[0.8.0]: https://github.com/ega-ega/prompt-linker/releases/tag/v0.8.0

prompt_linker-0.8.0/Docs/Commands.md

@@ -0,0 +1,105 @@
+# Prompt Linker — CLI commands
+
+Every command takes the form:
+
+```
+prompt-linker <command> [ROOT] [options]
+```
+
+`ROOT` is a **configuration** directory — it holds `Linker.yaml`, `skeletons/`, and `contracts/`
+(see [`PromptLinker.md`](./PromptLinker.md)). It defaults to the current directory. Installed via
+`pipx`/`uvx` the entry point is `prompt-linker`; from a source checkout use
+`PYTHONPATH=src python -m prompt_linker.cli`.
+
+There are three commands: **`verify`** and **`compile`** are deterministic and use no model tokens;
+**`check`** is the opt-in, model-using AI verifier.
+
+## Shared options
+
+These apply to all three commands and select the resolution (`defaults → preset → overrides`, §3a):
+
+| Option | Meaning |
+|---|---|
+| `--preset NAME` | Resolve from a named preset in the manifest (overrides the manifest's own `preset:`). |
+| `--set CONTRACT=IMPL` | Per-contract override; repeatable. Run-local contracts only — overriding a shared-state-coupled contract is an error (§8). |
+
+---
+
+## `verify`
+
+```
+prompt-linker verify [ROOT] [--preset NAME] [--set CONTRACT=IMPL ...]
+```
+
+Proves the configuration is coherent and **writes nothing**. It runs exactly the checks `compile`
+runs — coverage, symbol-table integrity, contract fit, the §8 split — plus the deterministic
+**security scan** (injection screens: invisible/bidi characters and capability-envelope violations;
+[`Verification.md`](./Verification.md) §3.2).
+
+**Fail closed:** any violation prints `prompt-linker: <message>` to stderr and exits **1**; non-fatal
+advisories print `prompt-linker: warning: <message>` and exit **0**. Every message is catalogued in
+[`Errors.md`](./Errors.md).
+
+---
+
+## `compile`
+
+```
+prompt-linker compile [ROOT] [--preset NAME] [--set CONTRACT=IMPL ...] [--out DIR] [--annotated] [--force]
+```
+
+Resolves the manifest, verifies (same checks as `verify`), inlines the chosen implementations into the
+skeletons, and writes the result. Compiled output is **derived state** — gitignored, regenerated,
+never hand-edited (§6). The whole `skeletons/` tree is compiled and mirrored into the output dir, and
+a final line reports the output dir and its `config-hash`.
+
+| Option | Meaning |
+|---|---|
+| `--out DIR` | Output directory under ROOT. **Omitted → content-addressed:** `compiled/<name>-<config-hash>/`, so distinct builds never collide and a host can freeze a run by recording that path (§7.3, Roadmap PC-OQ-4). An explicit `--out` writes there verbatim — the caller then manages freeze. |
+| `--annotated` | Emit a **debug build** with per-block `<!-- block: … -->` markers, for the AI verifier — **never a runtime artifact** (its header is stamped `ANNOTATED BUILD — NOT for a runtime agent`). Point it at a separate `--out`. |
+| `--force` | Overwrite a non-empty `--out` that prompt-linker did **not** generate. By default the compiler **fails closed** rather than clobber a directory without its build marker (e.g. a mistaken `--out src`); overwriting a *previous* prompt-linker build is always allowed (derived state, §6). |
+
+The **`config-hash`** identifies the *artifact* (resolved bindings **plus** the text of every source
+and inlined impl), so editing an impl's body yields a fresh hash and a fresh output dir — a previously
+frozen build is never silently overwritten. It is distinct from the header's `resolution-hash`, which
+fingerprints the *bindings* only.
+
+The release artifact (plain `compile`) is flat and clean — no per-block markers, no authoring
+scaffolding (§6).
+
+---
+
+## `check`
+
+```
+prompt-linker check [ROOT] [--preset NAME] [--set CONTRACT=IMPL ...] [--library] [--security] [--deep]
+```
+
+The **AI verifier** — behavioral checks a deterministic pass cannot make ([`Verification.md`](./Verification.md)
+§2, §3.3). Opt-in and model-using: install the extra (`pip install "prompt-linker[ai]"`) and set
+`ANTHROPIC_API_KEY`; model `claude-opus-4-8`. It is **read-only** — it judges and reports, and never
+edits artifacts. Output goes to stdout; exit is **1** if there are any findings, **0** otherwise.
+
+Default (no flags) runs two passes:
+
+- **conformance** — does each *selected* implementation actually satisfy its contract? One judgment
+  per unique `(contract, impl)` pair (deduped).
+- **coherence** — do the inlined blocks of each compiled file fit together (and not assume something
+  an earlier phase never produced)? Each block carries its **contract signature** as context for this
+  judgment — context, not ground truth: a block may sit in a placement its contract does not fit, so
+  the verifier judges the text on its own merits.
+
+| Option | Meaning |
+|---|---|
+| `--library` | Run conformance over **every** implementation of every contract (a source-level audit), not just the selected ones. Skips coherence (nothing is assembled). |
+| `--security` | Also run the AI **injection review** — per implementation (anchored to its capability envelope) and over each whole compiled artifact (catches injection split across blocks). |
+| `--deep` | Add a **configuration-level (cross-file) coherence** pass on top of the per-file one — all compiled files are reviewed together, so partner blocks that land in *different* files are still cross-checked (a writer in one file, a reader in another). Catches the cross-contract mismatch the per-file pass structurally cannot see ([`Verification.md`](./Verification.md) §2.1; Roadmap PC-OQ-3). No effect with `--library`, or when only one file has slots. |
+
+---
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| `0` | Success. Advisories may have been printed as warnings. |
+| `1` | A deterministic violation (`verify`/`compile`), or the AI verifier reported at least one finding (`check`), or a usage/parse error. |

prompt_linker-0.8.0/Docs/Errors.md

@@ -0,0 +1,112 @@
+# Prompt Linker — Compilation errors & advisories
+
+Every check the linker performs, the exact message it emits, why it fires, and how to fix it. The
+design rationale for each rule is in [`PromptLinker.md`](./PromptLinker.md) (section refs below).
+
+## How errors surface
+
+- **Errors fail closed.** Any violation raises a typed `LinkError`; the linker writes **nothing** and
+  exits non-zero (§7.1). `verify` and `compile` run the *same* checks — `verify` just writes nothing.
+  CLI output: `prompt-linker: <message>` on stderr, exit code **1**.
+- **Advisories never block.** Non-fatal issues print `prompt-linker: warning: <message>` on stderr and
+  compilation still succeeds (exit **0**).
+- Messages below show interpolated parts as `<…>`; the literal text is what you can search for.
+
+Checks run in this order (so the *first* failure is the one you see): parse/load → index (symbol
+table) → resolve → gather sources → verify.
+
+---
+
+## Parse / load
+
+| Message | When | Fix |
+|---|---|---|
+| `no manifest at <path>` | No `Linker.yaml` at the ROOT directory. | Run against a configuration directory, or add `Linker.yaml`. |
+| `<path>: top level must be a mapping` | `Linker.yaml` is not a YAML mapping (e.g. a list or scalar). | Make the top level `key: value` pairs. |
+| `<path>: presets must be a mapping` | `presets:` is present but not a mapping of name → bindings. | Use `presets:\n  name:\n    contract: impl`. |
+| `<path>: overrides: expected a mapping` | `overrides:` (or a preset body) is not a mapping. | Use `contract: impl` pairs. |
+| `<path>: preset '<name>': expected a mapping` | A preset body is not a mapping. | Same — `contract: impl` pairs under the preset. |
+| `front-matter must be a mapping` | A file's `--- … ---` front-matter parses to a non-mapping. | Put `key: value` pairs between the `---` fences. |
+| `bad --set '<item>'; expected CONTRACT=IMPL` | A CLI `--set` argument is malformed (missing `=`, empty side). | Pass `--set contract=impl`. |
+
+---
+
+## Index — building the symbol table (§4.3, §7.1)
+
+The linker scans `contracts/**/*.md`, reads each file's front-matter identity, and builds
+`(contract, impl) → path`. Identity is the front-matter, not the path.
+
+| Message | When | Fix |
+|---|---|---|
+| `no implementation library at <base>` | The configuration has no `contracts/` directory. | Create `contracts/` with at least the contracts your skeletons reference. |
+| `<path>: missing contract: in front-matter` | A file under `contracts/` has no `contract:` key. | Add `contract: <id>` front-matter (and `impl:` if it is an implementation). |
+| `multiple definition of (<contract>, <impl>): <a> and <b> (§7.1)` | Two files declare the same `(contract, impl)` — a duplicate symbol. | Remove or re-identify one. Location does not disambiguate; the identity does. |
+| `contract '<contract>' defined twice: <a> and <b>` | Two `contract.md`-style files declare the same contract id. | Keep one canonical `contract.md` per contract. |
+| `<path>: class '<cls>' must be 'run-local' or 'shared-state-coupled' (§8)` | A contract's `class:` is an unknown value. | Use exactly `run-local` or `shared-state-coupled`. |
+
+---
+
+## Resolve — manifest → binding set (§3a)
+
+| Message | When | Fix |
+|---|---|---|
+| `unknown preset '<name>'; known presets: <known>` | `--preset`/manifest `preset:` names a preset not in `presets:`. | Use one of the listed names, or define it. |
+| `preset inheritance cycle through '<name>'` | A preset's `extends:` chain loops back on itself. | Break the cycle in the `extends:` chain. |
+
+---
+
+## Gather sources (§4.5)
+
+| Message | When | Fix |
+|---|---|---|
+| `no skeletons directory at <base>` | The configuration has no `skeletons/` directory. | Add `skeletons/` with at least one skeleton or static file. |
+| `no skeleton or static files under <base>` | `skeletons/` exists but is empty. | Put a skeleton (a file with `{{ slot: … }}`) or a static file under it. |
+
+---
+
+## Verify — coherence of the resolution (§7.1, §8)
+
+Run for every contract referenced by a slot in any skeleton.
+
+| Message | When | Fix |
+|---|---|---|
+| `contract '<contract>' is referenced by a skeleton but unbound` | A slot references a contract with no binding (no default, no preset value, no override). | Give the contract a `default:`, set it in the preset, or pass `--set`. |
+| `contract '<contract>' is bound but has no contracts/<contract>/contract.md` | A binding names a contract that has no `contract.md` signature. | Add `contracts/<contract>/contract.md` (front-matter `contract:` + `class:`). |
+| `contract '<contract>' bound to impl '<impl>', but no such implementation exists in the symbol table (§7.1)` | The chosen impl is not defined for that contract. | Fix the impl name in the preset/override, or add the impl file with matching front-matter. |
+| `contract '<contract>' is shared-state-coupled; it cannot be set in the override layer — shared-state-coupled bindings are environment-global (§8)` | An `overrides:`/`--set` entry targets a `shared-state-coupled` contract. | Set it in the preset (the environment-global layer), not as a per-run override. Only run-local contracts are overridable. |
+
+---
+
+## Advisories (non-fatal)
+
+These print as `warning:` and do **not** block compilation.
+
+| Message | When | Note |
+|---|---|---|
+| `orphan contract '<contract>': defined but referenced by no skeleton` | A contract exists in the library but no skeleton has a slot for it. | Harmless; remove the contract if it is dead, or add the slot if it was forgotten. |
+| `impl (<contract>, <impl>) lives at <rel>, not the conventional contracts/<contract>/<impl>.md` | A file's location disagrees with its declared identity. | Resolution still works (identity is the front-matter, §4.3); move the file to keep the tree tidy. |
+
+---
+
+## Security scan — deterministic (in `verify`; Verification §3.2)
+
+Runs over selected impl bodies (envelope-aware) plus skeleton/static text. Two outcomes:
+
+- **Hard-fail (fail-closed)** — raised together as one error, `prompt-linker: security scan: <N> hard
+  finding(s) — injection risk (Verification §3.2):` with one line per finding (each names the detector,
+  the `<file>:<line>`, and what to fix). Exit **1**, nothing is written. Caught classes: invisible/bidi
+  control characters, and impls that break their contract's declared `allow` envelope (§3.1).
+- **Advisory** — `prompt-linker: warning: security [<kind>] <file>:<line>: <detail>`; never blocks
+  (exit **0**). Review each; declaring an `allow` envelope promotes a real policy to a hard-fail.
+
+The **exact** per-finding catalog is kept in the repo only, not in the published package. Maintainers:
+see `Docs/private/Errors.md` and the `compiler.py` comments.
+
+## Security & behavioral — AI verifier (`check`; Verification §2, §3.3)
+
+`prompt-linker check` is model-using and opt-in. Its findings are reported to stdout (non-zero exit on
+any), not raised as `LinkError`. The one hard error it can raise:
+
+| Message | When | Fix |
+|---|---|---|
+| `the AI verifier needs the 'anthropic' package — install it with pip install "prompt-linker[ai]" …` | `check` invoked without the optional `anthropic` dependency. | `pip install "prompt-linker[ai]"`, and set `ANTHROPIC_API_KEY`. |