b3-prosaic 0.4.1__tar.gz

b3_prosaic-0.4.1/AGENTS.md

@@ -0,0 +1,16 @@
+# Prosaic
+
+Prosaic is a Python 3.11+ canonical Markdown distribution engine. Generic prose
+parsing, target adapters, rendering, configuration, import, manifests, packages,
+and read-only tool catalogue discovery belong here. Model execution belongs in
+Prosaic Runtime; workflow orchestration belongs in Prosaic Harness or consumers.
+
+Production code is under `src/prosaic/` and must not execute TypeScript or Node.
+Keep serialized camelCase contracts and existing on-disk formats compatible.
+Never execute catalogue manifests here; discovery is read-only configuration.
+
+Use apply_patch for edits. Run `.venv/bin/python -m pytest` for the full suite.
+For differential tests, bootstrap the immutable v0.2.0 TypeScript reference with
+`.venv/bin/python scripts/verify_migration.py`. Node/npm are test-only oracles.
+Build with `.venv/bin/python -m build`, and verify the installed wheel using
+`scripts/wheel_smoke.py`. Preserve unrelated user changes and historic evidence.

b3_prosaic-0.4.1/CHANGELOG.md

@@ -0,0 +1,138 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+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).
+
+## [Unreleased]
+
+- Abort apply and package deployment before output reconciliation when source
+  enumeration or reads fail; a missing canonical source cannot remove managed outputs.
+- Replace generated files atomically, preserve file permissions, and retain
+  correctly sequenced backups through symlink project aliases.
+- Add read-only project validation and safe versioned CI diagnostics, with
+  CommonMark bundle links, explicit source failures and configured loss severity.
+- Serialize project provenance mutations with persistent OS-backed locks and
+  reserve their coordination inode throughout filesystem operations.
+- Prepare `b3-prosaic` 0.4.1 for the public package-index channel, preserving
+  Python imports, CLI commands and historical artifact identities.
+
+## [0.3.2] - 2026-10-10
+
+- Export pure validate_artifact_definition for explicit canonical kinds and
+  frontmatter, preserving existing validation/discovery contracts and extensions.
+
+## [0.3.0] - 2026-10-01
+
+### Changed
+
+- Replaced the TypeScript implementation with Python 3.11+, retaining the
+  `prosaic` distribution, repository, import module, and CLI names.
+- Installation now uses pip, pipx, or uv; npm distribution and the JavaScript
+  library API are retired. Python APIs use snake_case; serialized contract keys,
+  Markdown/configuration formats, ownership manifests, and CLI commands remain.
+- Python CI, wheel/source distributions, frozen TypeScript differential checks,
+  original CLI suites, and installed-wheel checks replace the Node build.
+- Preserved the 0.2.0 read-only `tools` catalogue and its safety limits.
+- Reject dangling symlink escapes and bound cyclic package-directory traversal.
+
+### Migration evidence and limits
+
+- Fresh local checks: 432 Python tests, 55 original CLI tests across 13 suites,
+  265 Runtime tests, 107 Harness tests, and ten installed-wheel smoke checks.
+- Runtime/Harness offline and live workflow trials exercised Python Prosaic.
+- Echelon with Codex authored, reviewed, repaired, and validated the reverse-text
+  CLI spec, stopping at the expected semi-mode human approval checkpoint.
+- Full Echelon design/planning/publication and Claude remain untested. Local
+  forced-read tool-choice limitations occur with both TS and Python inspectors.
+- Previous TypeScript sources and releases remain recoverable in Git history
+  and the v0.2.0 tag; production consumer pins/installers are not changed here.
+
+## [0.2.0] - 2026-10-01
+
+### Added
+
+- Read-only neutral CLI-tool catalogue: `prosaic tools`, `discoverTools` and
+  `ToolManifest`; bounded YAML manifests, closed string-argument schemas,
+  deterministic discovery and fail-closed duplicate/symlink checks. Discovery
+  never installs, probes, executes or grants tool access.
+
+### Changed
+
+- Apache-2.0 licensing, with third-party attribution retained.
+- CI uses the installed default Jest reporter rather than an unavailable reporter.
+- Refreshed the tracked verification receipts with the full release test suite.
+
+The earlier entries below describe features already included in v0.1.0; they
+were previously left in the Unreleased section.
+
+### Added
+
+- `prosaic import` CLI command for reverse-engineering existing tool-specific prose files into neutral source.
+- Auto-detection of tool format from directory conventions (e.g., `.claude/`, `.cursor/`) with fallback to explicit `--format` flag.
+- Round-trip verification: after import, re-deploys neutralized artifacts to the originating tool and compares byte-for-byte against the original, reporting fidelity per file.
+- Portability warnings for absolute paths, project-relative paths, unknown frontmatter keys, and tool-only data with concrete remediation suggestions.
+- Per-target `overrides:` section for non-invertible or unknown keys, ensuring zero silent data loss.
+- Support for multi-file skill and subagent bundles with resource re-association and internal reference rewriting.
+- Companion metadata file consumption and per-target fidelity level reporting (fully-invertible, invertible-with-overrides, normalized-equivalent).
+- Genuine-foreign round-trip conformance oracle (SC-003): round-trips against hand-authored/captured foreign files committed under `conformance-fixtures/import-foreign/` — one static artifact per import-stable target — so re-deploying the neutralized artifact must reproduce the committed original byte-for-byte. Decoupled from the live serializer, this oracle catches serializer drift the self-referential conformance oracle cannot.
+- Testing commands documented: `npm run test:benchmark`, `npm run test:cross-env`, `npm run test:deterministic` for NFR verification.
+- Measured-runtime import-safety evidence under `tests/safety/import/`: the real end-to-end `importRun` is exercised against a genuinely-foreign corpus (`conformance-fixtures/import-foreign/`, never produced by the tool's own forward pipeline) with syscall-level filesystem instrumentation (`fs-instrument.ts`) rather than hand-maintained counters. Covers source-level idempotency (NFR-002, SC-006), no-silent-drop across the full registry (NFR-005, SC-002), single-command auto-detect import per target (SC-001), the neutralize→gate→round-trip conformance gate (NFR-008), and preview/dry-run zero-mutation guarantees (FR-069).
+- All 48 delivery tasks complete (100%); all 114 canonical requirements fulfilled or deferred-safe per spec-guard audit.
+- `prosaic resolve <artifactId> --target <targetId>` CLI subcommand: resolves an artifact-target pair's execution settings (model, reasoning effort, tools, execution type) as structured JSON on stdout, without writing any file or invoking a network call or LLM. Exits 1 with an `error: <message>` line on an unregistered target or an unresolvable artifact.
+- Library API export `resolveExecutionData(opts: ResolveOptions): ResolveExecutionResult` and the lower-level pure function `resolveExecution(artifact, descriptor): ResolvedExecutionData`, both newly exported from the package root, for external orchestrators (e.g. Echelon) that need resolved execution settings without parsing generated provider files. `resolveExecutionData` never throws; callers branch on `result.ok` and, on failure, `result.errorKind` (`'unregistered-target' | 'artifact-not-found' | 'internal'`).
+- New exported types: `ResolvedExecutionData`, `ResolveExecutionResult`, `ResolveOptions`, and the `ArtifactNotFoundError` error class.
+- Resolution reuses the same neutral-to-concrete translation logic already used for file presentation (`translateNeutral`/`applyOverrides`/`resolveDeploymentType`), so resolved values never diverge from what `apply` would generate for the same artifact-target pair; an untranslatable neutral property is reported with `status: "unresolved"` rather than omitted.
+- Library API export `runtimeCapabilityFor(desc: TargetDescriptor): RuntimeCapabilityDeclaration`, newly exported from the package root, plus `Registry.runtimeCapability(id: string)`, for querying a target's declared runtime-invocation acceptance (model, reasoning effort, tools, execution type) ahead of calling `resolveExecutionData`/`resolveExecution`. Each of the 4 fields reports `'accepts' | 'rejects' | 'unknown'`; an absent declaration, or an absent individual field, always reports `'unknown'` rather than assuming `'accepts'`. `Registry.runtimeCapability` throws `UnknownTargetError` for an unregistered target id, matching `.get()`/`.supports()`. New exported types: `RuntimeCapabilityDeclaration`, `RuntimeCapabilityFlag`, and the `RUNTIME_CAPABILITY_FLAGS` const. No built-in target currently declares a `runtimeCapability` value, so every built-in target reports all-`'unknown'` today; declaring per-target values is a separate follow-up.
+- `examples/` directory with five self-contained, runnable example projects — `01-basic-write-preview-revert`, `02-multi-artifact-type`, `03-import`, `04-resolve`, and `05-multi-repository` — each pairing a narrative `README.md` with a project runnable using only files inside its own directory and no network access. Discoverable from a new `## Examples` section in the root `README.md` and indexed in `examples/README.md`.
+- Example Verification Check (`tests/examples/examples.test.ts`, auto-discovered by the existing Jest `testMatch`): runs every example's declared CLI steps and byte-diffs live output against a committed Expected-Output Record, reporting a coverage gap (never a silent pass) for any example missing its `example.manifest.json`, and naming exactly one divergence-failure per byte-mismatched step.
+- `prosaic inspect <artifactId>` CLI subcommand and library API export `inspectArtifact(opts: InspectOptions): InspectionResult`, both newly exported from the package root: a supported, machine-readable "inspect" capability that returns one discovered artifact's full neutral data (identifier, type, frontmatter, body, bundle root, bundled resources) as structured JSON, without writing any file or invoking a network call. Follows the same never-throws, discover-then-find, JSON-on-stdout pattern as `resolve`; an optional `--json` CLI flag is accepted for compatibility but never changes output, since output is unconditionally machine-readable. `resources`/`bundleRoot` are always present (`[]`/`null` for a standalone artifact), never omitted. Identifier lookup is exact case-sensitive comparison; a nonexistent identifier and a discovery-validation-dropped identifier both report the same `errorKind: 'artifact-not-found'` result in this release — distinguishing the two causes is deferred to a future revision. New exported types: `InspectedArtifact`, `InspectedResource`, `InspectionResult`, `InspectOptions`. No `--target` option exists on this command; inspect returns target-neutral, pre-translation data only.
+- `model_tier` optional frontmatter field (rule, skill, subagent, command): a permissive-string field for declaring a coarse capability tier (e.g. `fast`, `balanced`, `strong`, `ultra`, or any other string) without naming a concrete model. Validated at Discovery identically to `effort`; visible verbatim via `inspect`; passed through unchanged into every target's rendered output with no Prosaic-defined tier-to-model mapping — deliberately excluded from the Neutral Behavior Vocabulary (`NEUTRAL_KEYS`), so it is never translated or stripped. See [Target On-Disk Contracts](docs/target-contracts.md) for the full neutral-adjacent frontmatter vocabulary.
+- `prosaic package deploy <packageId> [--dry-run]` CLI subcommand: a generic, application-agnostic package deployment mechanism, distinct from and coexisting unmodified alongside `apply`/`render`/`inspect`/`import`/`revert`. An application maintainer declares one or more named packages (`id`, `sourceRoot`, `destinationRoot`) under a new optional `packages:` config array; `packages` is fully optional and a project declaring none behaves identically to a project without this feature. Deployment copies a declared package's Neutral Artifact Tree (`commands/`, `subagents/`) byte-identical with no render-pipeline translation, and its Package Runtime Tree (every other top-level entry, any file type) verbatim, never parsed or classified as a Prosaic artifact. Provenance-tracked via the existing manifest (package-specific identifier), idempotent, dry-run previewable, reconciles obsolete files on redeploy without ever touching an unmanaged Foreign Path, and backs up content-changing overwrites (up to 3 prior versions, matching render-target retention). Every filesystem mutation is containment-checked and destination-isolated from sibling packages and existing render targets. See [Package Deployment](docs/packages.md).
+- `prosaic package revert <packageId> [--dry-run]` CLI subcommand (Should-Have): mirrors the provenance-guarded revert behavior already provided for render-target output, removing exactly the files recorded as belonging to the declared package while never touching a Foreign Path; `--dry-run` previews the removal, writing 0 files.
+- Library API export `deployPackage(opts: PackageDeployOptions): PackageDeployReport` and `revertPackage(opts: PackageRevertOptions): PackageRevertReport`, both from `src/package/run.ts`, plus the `PackageDeclaration`, `PackageDeployOptions`, `PackageDeployReport`, `PackageRevertOptions`, `PackageRevertReport`, `PackageValidationError`, and `UnknownPackageError` types/classes, for programmatic package deployment and revert.
+- Global `--color` / `--no-color` CLI flag to force terminal color on or off (auto-detected by default), accepted by `apply`, `import`, and `revert`.
+- Standard `NO_COLOR` and `FORCE_COLOR` environment support, including `FORCE_COLOR=0` (disable) and `NO_COLOR`-wins-over-`FORCE_COLOR` precedence.
+- Per-stream TTY-gated ANSI color styling of previews, run summaries, warnings, and errors (stdout and stderr resolved independently) via a plain-by-default, zero-runtime-dependency ANSI helper.
+- Per-state color coding (created / overwrite / error / unchanged) plus an underlined path style, each paired with a non-color text/glyph signal for accessibility.
+- ASCII glyph fallback (`[ok]`, `[drop]`, `->`) so non-interactive and legacy/non-UTF terminals stay ASCII-only.
+- Aligned run-summary counts and a grouped portability report with one remediation line per warning, deterministic at any terminal width.
+
+### Changed
+
+- README "Existing Repositories" adoption guide now points at the shipped `prosaic import` command for reverse-importing native tool directories, replacing the earlier "no import command yet" / "reverse import is not in the current CLI" notes that predated the import feature.
+- Warning lines now use the structured format `warning[<kind>] <artifact> → <target>: <message>` (the arrow is `->` in plain mode); error lines consistently begin with `error: `.
+
+### Performance
+
+- Measured: 100 artifacts × 30 targets distributed in ~816 ms (threshold: 30 000 ms); byte-identical output verified across 510 files on darwin/Node 26.
+- Cross-environment reproducibility confirmed: deterministic render verified across Linux and macOS (NFR-007, NFR-009).
+- Measured-runtime coverage evidence for resolve (NFR-002, NFR-004): 51 runtime-capable targets compared field-by-field against the FR-003 presentation translation outcome across 153 field comparisons with 0 divergent values, and all 51 targets carry at least 1 passing fixture test — both captured to `test-results/resolve-presentation-parity-nfr002.json` and `test-results/resolve-conformance-nfr004.json`.
+- Measured-runtime crash-resilience evidence for resolve (NFR-001): `resolveExecutionData()` driven over a 39-case multi-axis malformed-input corpus (malformed frontmatter YAML, malformed `prosaic.config.yaml`, binary/NUL/huge/deeply-nested content, adversarial target/artifact ids, non-`Error` registry faults) with 0 uncaught crashes — every attempt yields either a valid resolution or a structured `errorKind` — captured to `test-results/resolve-malformed-input-nfr001.json`.
+- Measured-runtime crash-resilience evidence for inspect (NFR-001): `inspectArtifact()` driven over a 40-case multi-axis malformed-input corpus (malformed frontmatter YAML, malformed `prosaic.config.yaml`, binary/NUL/huge/deeply-nested content, adversarial artifact ids, an unreadable-config fault) with 0 uncaught crashes — every attempt yields either a valid inspection or a structured `errorKind` — captured to `test-results/inspect-malformed-input-nfr001.json`.
+- Benchmark artifacts committed to `test-results/` for auditable CI history across iterations.
+- Full `test-results/` suite re-verified with no regressions; all NFR/SC evidence artifacts refreshed with new `recordedAt` timestamps and unchanged pass outcomes.
+- Verified styled-run wall-clock stays within 5% of the plain baseline (NFR-006).
+
+## [0.1.0] - 2026-07-09
+
+### Added
+
+- `prosaic apply` CLI command with `--dry-run`, `--targets`, and `--types` flags for distributing MD-prose artifacts to AI coding tool targets.
+- `prosaic revert` CLI command for removing only Prosaic-managed files using the recorded path manifest.
+- `prosaic.config.yaml` configuration schema: `source`, `targets`, `artifactTypes`, `lossyPolicy`, `backupRetention`.
+- Support for four artifact types: `rule`, `skill`, `subagent`, `command` — classified by source directory or explicit `type:` frontmatter.
+- First-class skill and subagent bundle distribution with internal reference rewriting to prevent broken links.
+- Neutral behavior vocabulary (`execution`, `visibility`, `tools`, `color`, …) translated into per-target concrete frontmatter, with a per-target `overrides:` escape hatch.
+- 40+ AI coding tool targets with per-target path, name, frontmatter, argument, and whole-file format rewriting.
+- Idempotent apply: byte-identical output on re-apply with zero changed files.
+- Non-destructive backup strategy: backups before every overwrite; missing or corrupt manifest aborts all deletion.
+- Project-root containment: all writes and deletes confined to the project root; symlink escapes are refused.
+- Lossy transformation detection: every skipped or lossy transformation emits a named warning.
+- Managed-paths manifest tracking all Prosaic-written files for safe selective revert.
+- Extension workflow: adding a target requires only a data edit plus a conformance fixture (see `docs/add-a-target.md`).
+
+### Security
+
+- Symlink escape prevention: path resolution refuses any write or delete outside the project root.

b3_prosaic-0.4.1/LICENSE

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

b3_prosaic-0.4.1/MANIFEST.in

@@ -0,0 +1,6 @@
+include CHANGELOG.md AGENTS.md
+recursive-include docs *.md
+recursive-include scripts *.py *.cjs
+recursive-include conformance-fixtures *
+recursive-include examples *.md *.yaml *.yml *.json
+global-exclude __pycache__ *.py[cod] .DS_Store

b3_prosaic-0.4.1/NOTICE

@@ -0,0 +1,5 @@
+Prosaic
+
+This project is distributed under the Apache License, Version 2.0; see LICENSE.
+Third-party dependencies retain their own licenses and attribution notices.
+Previously published versions and tags retain the license notices shipped with them.

b3_prosaic-0.4.1/PKG-INFO

@@ -0,0 +1,209 @@
+Metadata-Version: 2.4
+Name: b3-prosaic
+Version: 0.4.1
+Summary: Canonical Markdown prose distribution engine
+License-Expression: Apache-2.0
+Project-URL: Repository, https://github.com/B3Cognition/prosaic
+Project-URL: Issues, https://github.com/B3Cognition/prosaic/issues
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: pyuca>=1.2
+Requires-Dist: markdown-it-py<5,>=3.0
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: build>=1; extra == "test"
+Requires-Dist: setuptools>=77; extra == "test"
+Requires-Dist: wheel>=0.45; extra == "test"
+Requires-Dist: packaging>=24; extra == "test"
+Dynamic: license-file
+
+# Prosaic
+
+Author canonical Markdown-with-YAML prose once; distribute it to 40 AI coding
+targets. Prosaic also inspects neutral artifacts for Prosaic Runtime and Harness.
+
+## Install
+
+Prosaic 0.4.1 is a Python 3.11+ candidate. Its public distribution is `b3-prosaic`; the
+repository, Python import module and CLI remain `prosaic`. There is no Node.js
+runtime dependency. The normal package-index channel starts with this release.
+
+```sh
+uv tool install 'b3-prosaic==0.4.1'
+# Alternative:
+pipx install 'b3-prosaic==0.4.1'
+```
+
+The GitHub release provides the same qualified wheel and source archive as the
+package index. Use a fresh virtual environment or reinstall a pipx/uv tool when
+migrating from the old `prosaic` distribution: old and new distributions share
+import files and must not coexist. PyPI's unrelated `prosaic` project is not this
+SDK. Historical release names and bytes remain unchanged. npm installation and
+the JavaScript library API are retired; remove its old CLI and check
+`command -v prosaic` when switching a global installation.
+
+## Quick start
+
+Create `.prosaic/commands/greet.md`:
+
+```markdown
+---
+description: Greet the user
+---
+Say hello to $ARGUMENTS.
+```
+
+Then preview and distribute it:
+
+```sh
+prosaic apply --targets claude-code --dry-run
+prosaic apply --targets claude-code
+prosaic inspect commands/greet.md
+prosaic resolve commands/greet.md --target claude-code
+prosaic revert --targets claude-code --dry-run
+```
+
+Canonical source directories are `rules/`, `skills/`, `subagents/`, and
+`commands/`. Skill/subagent bundles retain their companion resources and
+internal references.
+
+## Configuration and commands
+
+Existing filenames and keys remain supported: `prosaic.config.yaml`,
+`prosaic.config.yml`, `.prosaic.yaml`, `source`, `targets`, `artifactTypes`,
+`lossyPolicy`, `backupRetention`, and `packages`. Markdown and manifest formats
+are unchanged.
+
+```yaml
+source: .prosaic
+targets: [claude-code, codex-cli]
+artifactTypes: [rule, skill, subagent, command]
+lossyPolicy: warn
+backupRetention: 3
+```
+
+```sh
+prosaic apply --dry-run
+prosaic apply
+prosaic revert --dry-run
+prosaic revert
+prosaic import ./foreign --format claude-code --dry-run
+prosaic resolve commands/deploy.md --target claude-code
+prosaic inspect subagents/reviewer.md --json
+prosaic validate --json --strict --targets claude-code
+prosaic tools --source .prosaic
+prosaic package deploy my-package --dry-run
+prosaic package revert my-package --dry-run
+```
+
+`inspect`, `resolve`, and `tools` emit JSON. Import warnings go to stderr;
+apply warnings remain on stdout. Explicit `--color` / `--no-color`,
+`NO_COLOR`, and `FORCE_COLOR` retain the CLI presentation contract.
+
+See [read-only validation](docs/validation.md), [package deployment](docs/packages.md), [target contracts](docs/target-contracts.md),
+[adding a target](docs/add-a-target.md), and [examples](examples/README.md).
+
+## Neutral CLI-tool catalogue
+
+`prosaic tools` lists sorted YAML/YML manifests from `<source>/tools`;
+`--directory <path>` selects an explicit directory. Discovery is bounded,
+non-recursive and read-only. It never resolves executables, probes, installs,
+executes, or grants access. Malformed/duplicate/oversized/symlinked manifests
+fail closed. The Python API is `discover_tools(directory)`.
+
+Execution belongs in Prosaic Runtime with operator-configured grants.
+See the [companion CLI-tool guide](https://github.com/B3Cognition/prosaic-runtime/blob/main/docs/cli-tools.md).
+
+### Declarations are not permission grants
+
+When executing through the companion Runtime/Harness, an agent can declare
+`tools: [analyze_spec]` in Markdown frontmatter. That requests a tool; it does
+not install it, trust its manifest, grant filesystem/network access, or enable
+an OS sandbox. Installing an executable or listing it with `prosaic tools` also
+grants nothing.
+
+The operator must independently configure Runtime `allowed_tools` and trust
+the manifest directory via `tool_directories`. The host then grants the tool
+and narrow `read_roots` in a Runtime invocation or Harness agent step. Missing
+grants deny access. Markdown and model output cannot expand these permissions.
+
+Runtime 0.5.2+ and Harness 0.4.2+ support `cli_sandbox: {mode: required}`
+in **Runtime YAML, not Markdown**. This isolates custom CLI subprocesses/probes
+with macOS Seatbelt or Linux Bubblewrap, not Python callbacks or native coding
+providers. It defaults to off;
+upgrading Prosaic alone does not activate it. See the
+[sandboxed Runtime example](https://github.com/B3Cognition/prosaic-runtime/blob/main/examples/README.md#sandboxed-cli-tools-runtime-052)
+or [sandboxed Harness workflow](https://github.com/B3Cognition/prosaic-harness/blob/main/examples/README.md#sandboxed-cli-workflow-harness-042)
+for installation, all permission layers and offline verification.
+
+## Python API
+
+```python
+from pathlib import Path
+from prosaic import (apply, inspect_artifact, resolve_execution_data, discover_tools,
+                     validate_artifact_definition, validate_project)
+
+root = Path('/path/to/project')
+inspection = inspect_artifact(root, 'subagents/reviewer.md')
+preview = apply(root, cli={'targets': ['claude-code']}, dry_run=True)
+project_report = validate_project(root, {'targets': ['claude-code']}, strict=True)
+resolved = resolve_execution_data(root, 'commands/deploy.md', 'claude-code')
+catalogue = discover_tools(root / '.prosaic/tools')
+validation = validate_artifact_definition('subagent', {
+    'name': 'reviewer', 'description': 'Review supplied prose',
+})
+```
+
+`validate_artifact_definition(kind, frontmatter)` performs pure canonical validation
+for explicit `rule`, `skill`, `subagent`, or `command` definitions. It returns
+`{'ok': True, 'frontmatter': ...}` with a shallow metadata copy, or
+`{'ok': False, 'field': ..., 'reason': ...}`. A supplied `type` must match `kind`;
+an absent `type` stays absent. Validation retains extension metadata and never
+reads files or executes tools. Runtime applies its execution constraints separately.
+
+Python function names use snake_case; serialized contract keys retain camelCase.
+Registry injection, configuration precedence, target registration and pipeline
+operations remain available. This package distributes/inspects prose; it does
+not execute models or orchestrate application workflows.
+
+## Development and verification
+
+```sh
+python3 -m venv .venv
+.venv/bin/python -m pip install -e '.[test]'
+.venv/bin/python scripts/verify_migration.py
+.venv/bin/python -m pytest
+.venv/bin/python -m build
+python3 -m venv .wheel-test
+.wheel-test/bin/python -m pip install dist/b3_prosaic-0.4.1-py3-none-any.whl
+.wheel-test/bin/python scripts/wheel_smoke.py
+```
+
+The verifier restores immutable TS v0.2.0 from this repository's Git history,
+runs Python differential/golden tests and original CLI suites through Python,
+and records `parity-results/latest.json`. Node/npm are required only for the
+frozen oracle, never for installed usage. Python CI covers 3.11, 3.12 and 3.13.
+Use `--consumers ../prosaic-runtime ../prosaic-harness --freeze-consumers`
+for tests against immutable consumer snapshots.
+
+[Validation history](docs/parity-status.md) and
+[0.3.0 migration notes](docs/release-0.3.0.md) distinguish completed trials
+from untested workflows. Runtime/Harness live staged/preloaded workflows passed.
+Echelon + Codex authored, reviewed, repaired, and validated a reverse-text CLI
+spec, stopping at its expected human approval checkpoint. Full design/planning/
+publication, Claude, and delivery remain untested. The local endpoint's direct
+forced-read limitation reproduced with TS and Python inspectors; see
+[diagnosis](docs/tool-choice-diagnosis.md).
+
+## Safety and license
+
+Ownership manifests, integrity checks, contained paths, bounded backups, and
+read-only dry runs protect application files. Python additionally rejects
+dangling symlink escapes and bounds cyclic package-directory traversal. No
+production consumer pin or global CLI installation is changed by this release.
+The previous TS implementation remains recoverable from `v0.2.0`.
+
+Apache-2.0; original attribution is retained in LICENSE and NOTICE.