frontmattering 0.4.2__tar.gz → 0.4.4__tar.gz

frontmattering-0.4.4/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,11 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security report
+    url: https://github.com/frontmattering/frontmattering/blob/main/SECURITY.md
+    about: Report a vulnerability privately per SECURITY.md (do not open a public issue).
+  - name: Licensing / commercial enquiry
+    url: mailto:hello@frontmattering.com
+    about: Questions about professional, organizational, or commercial licensing.
+  - name: Support and usage help
+    url: https://github.com/frontmattering/frontmattering/blob/main/SUPPORT.md
+    about: How to get help and what support is offered.

frontmattering-0.4.4/.github/ISSUE_TEMPLATE/doc_confusion.yml

@@ -0,0 +1,18 @@
+name: Documentation confusion
+description: Something in the docs, README, or CLI output was unclear or misleading.
+title: "[docs] "
+labels: ["documentation"]
+body:
+  - type: input
+    id: where
+    attributes:
+      label: Where (file / URL / command)
+      placeholder: "e.g. README.md 'First-hour path', or `frontmattering brief` output"
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: What you expected vs. what the docs said
+    validations:
+      required: true

frontmattering-0.4.4/.github/ISSUE_TEMPLATE/pilot_report.yml

@@ -0,0 +1,54 @@
+name: Fresh-start pilot report
+description: Report a cold-start run on your own Markdown corpus. Facts only — no fix required.
+title: "[pilot] "
+labels: ["pilot-report"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for piloting Frontmattering. Report only what you observed — this is evidence collection, not a support request.
+  - type: input
+    id: env
+    attributes:
+      label: OS / Python version
+      placeholder: "e.g. Ubuntu 24.04 / Python 3.12.3"
+    validations:
+      required: true
+  - type: dropdown
+    id: install
+    attributes:
+      label: "`pip install frontmattering` result"
+      options: ["Succeeded", "Failed"]
+    validations:
+      required: true
+  - type: dropdown
+    id: doctor
+    attributes:
+      label: "`frontmattering doctor` result"
+      options: ["PASS", "FAIL", "Did not run"]
+    validations:
+      required: true
+  - type: input
+    id: corpus
+    attributes:
+      label: Number of Markdown files in your corpus
+    validations:
+      required: true
+  - type: textarea
+    id: flow
+    attributes:
+      label: init → promote → tether → validate → brief outcome
+      placeholder: "What happened at each step; the validate verdict (GO/NO-GO) and brief status (FRESH/STALE/UNTETHERED)."
+    validations:
+      required: true
+  - type: textarea
+    id: first_error
+    attributes:
+      label: First confusing error message (verbatim, if any)
+  - type: dropdown
+    id: understood
+    attributes:
+      label: Did you understand FRESH / STALE / UNTETHERED?
+      options: ["Yes, all three", "Partly", "No"]
+    validations:
+      required: true

frontmattering-0.4.4/.github/ISSUE_TEMPLATE/runtime_ci_report.yml

@@ -0,0 +1,30 @@
+name: Runtime gate / CI report
+description: Report using the validate-only runtime artifact or the frontmattering gate in CI.
+title: "[runtime] "
+labels: ["runtime-gate"]
+body:
+  - type: input
+    id: env
+    attributes:
+      label: OS / Python version / CI provider
+      placeholder: "e.g. GitHub Actions ubuntu-latest / Python 3.11"
+    validations:
+      required: true
+  - type: textarea
+    id: invocation
+    attributes:
+      label: How you invoked the gate
+      placeholder: "e.g. python frontmattering-runtime.pyz validate docs --format json"
+    validations:
+      required: true
+  - type: dropdown
+    id: outcome
+    attributes:
+      label: Gate outcome
+      options: ["Passed as expected", "Failed as expected", "Unexpected pass", "Unexpected fail", "Crashed / error"]
+    validations:
+      required: true
+  - type: textarea
+    id: detail
+    attributes:
+      label: Output / error (verbatim)

{frontmattering-0.4.2 → frontmattering-0.4.4}/.github/workflows/ci.yml

@@ -44,6 +44,8 @@ jobs:
       - name: Exception taxonomy
         run: python kernel/tools/check_kernel_exception_taxonomy.py
       - name: Pilot-readiness contract
+        env:
+          FRONTMATTERING_PUBLIC_SURFACE: "1"
         run: python kernel/tools/check_pilot_readiness.py
       - name: Release cleanliness
         run: python kernel/tools/check_kernel_cleanliness.py --release
@@ -59,9 +61,11 @@ jobs:
         with:
           python-version: '3.12'
       - name: Build tooling
-        run: python -m pip install --upgrade pip build
+        run: python -m pip install --upgrade pip build twine
       - name: Build distributions
         run: python -m build
+      - name: Twine check
+        run: python -m twine check dist/*
       - name: Inspect and smoke-test wheel
         run: |
           python - <<'PY'

frontmattering-0.4.4/.github/workflows/publish.yml

@@ -0,0 +1,45 @@
+name: publish
+
+# Trusted Publishing to PyPI via OIDC — no long-lived API tokens.
+#
+# ONE-TIME OWNER SETUP (required before this can succeed):
+#   1. PyPI -> project "frontmattering" -> Publishing -> add a GitHub publisher:
+#        owner: frontmattering, repo: frontmattering,
+#        workflow: publish.yml, environment: pypi
+#   2. GitHub -> repo Settings -> Environments -> create environment "pypi".
+#
+# Until that setup exists this runs on manual dispatch only, so it never fails
+# spuriously. Once configured, publish from tags by adding:
+#   on:
+#     push:
+#       tags: ["v*"]
+on:
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: Tag to build and publish (e.g. v0.4.4)
+        required: true
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.tag }}
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build and check distributions
+        run: |
+          python -m pip install --upgrade pip build twine
+          python -m build
+          python -m twine check dist/*
+      - name: Publish to PyPI (OIDC Trusted Publishing)
+        uses: pypa/gh-action-pypi-publish@release/v1

{frontmattering-0.4.2 → frontmattering-0.4.4}/.github/workflows/release.yml

@@ -26,6 +26,8 @@ jobs:
       - name: Install build dependencies
         run: python -m pip install --upgrade pip build
       - name: Verify release tree
+        env:
+          FRONTMATTERING_PUBLIC_SURFACE: "1"
         run: |
           python -m pip install -e .
           python kernel/tools/test_verify_kernel.py

frontmattering-0.4.4/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+## 0.4.4
+
+- **Fixed the published first-hour path.** The quickstart now initializes at the repository root (`frontmattering init .`); the previous `init docs` form left the promoted document outside the selected corpus, and `promote docs/*.md` passed multiple files to a single-file command.
+- **`promote --in-place` is now transactional.** Promoting a file outside the selected corpus fails before any write with `FRONTMATTERING-AUTHORING-TARGET-OUTSIDE-CORPUS`, and any post-write failure restores the file to its original bytes — no command mutates an input file and then exits nonzero.
+- **Validate-only runtime CLI corrected.** `validate --help` prints usage and exits 0 (previously returned a vacuous GO report over zero paths); `validate` with no path is now a usage error instead of silently validating the current directory.
+- `frontmattering validate` with no paths prints an explicit "validating current working directory" notice.
+- Added a `markdown-plugins` optional extra (`pip install "frontmattering[markdown-plugins]"`) so the optional markdown-it plugins are a named, opt-in capability.
+- Added `Commercial` and `License` project URLs.
+- Removed stale v0.4.2 release-note artifacts from the source distribution.
+- Added a PyPI Trusted Publishing workflow (OIDC) and `twine check` in CI; CI is green across Python 3.10–3.13 (fixed `benchmark_harness` and the `.git`-inclusive distribution-receipt check; scoped the public-surface pilot-readiness gate).
+- No frontmatter-schema, validator trust-semantics, or canonical-model (`v0.1.5`) changes.
+
+## 0.4.3
+
+- README/PyPI long description: install instruction is now `pip install frontmattering` instead of a local wheel path.
+- Public license summary now states the 30-day evaluation permission (LICENSE.md §2), not only the paid-commercial requirement.
+- Fixed `frontmattering doctor`: the AI_INDEX currency check embedded Python- and terminal-width-sensitive argparse output (usage-line wrapping and positional `.required`), producing a spurious FAIL on any environment other than the one the index was frozen on. Index generation is now deterministic — whitespace-normalized command signatures and `required` derived from `nargs` — so `doctor` passes across supported Python versions.
+- Removed the residual `-pypi-clear` publication marker from internal version strings.
+- No validator, frontmatter-schema, runtime-parity, or canonical-model (`v0.1.5`) changes.
+- Both wheel and sdist are published for this version.
+
+## 0.4.2
+
+- Removed the mistaken MIT component license expression after confirming the package contains Frontmattering-owned source and normal runtime dependencies, not vendored third-party source.
+- Replaced third-party notices with a dependency-only notice for PyYAML and markdown-it-py.
+- Removed the v0.4.1 publication hold.
+- Preserved clean public identity: package, import package, and CLI are all `frontmattering`.
+
+## 0.4.1
+
+- Corrected public notices and added 30-day professional/organizational evaluation permission.
+- Added verbatim redistribution permission for unmodified official package artifacts.
+- Marked publication as held pending third-party provenance clarification; superseded by v0.4.2 after code ownership was confirmed.
+
+## 0.4.0
+
+- Clean public rebrand to Frontmattering.
+- Project package, import package, and CLI are now `frontmattering`.
+- Removed old public CLI/import/package aliases.
+- Replaced the previous permissive project license with Frontmattering Individual Use License v1.0 plus commercial-license requirement.
+- Preserved validator/runtime/body-tether/trust-profile behavior from the internal v0.3.6 line.

{frontmattering-0.4.2 → frontmattering-0.4.4}/MANIFEST.in

@@ -14,9 +14,6 @@ include SUPPORT.md
 include THIRD_PARTY_NOTICES.md
 include TRADEMARKS.md
 include REPOSITORY_STATUS.md
-include RELEASE_NOTES_v0_*.md
-include FRONTMATTERING_v0_4_2_RELEASE_SUMMARY.md
-include FRONTMATTERING_V0_4_2_DELIVERY_NOTE.md
 recursive-include .github *.md *.yml *.yaml
 recursive-include benchmarks/cold_start_v1 *.md *.yaml *.json *.py
 recursive-include contracts *.md

{frontmattering-0.4.2 → frontmattering-0.4.4}/PKG-INFO

@@ -1,12 +1,14 @@
 Metadata-Version: 2.4
 Name: frontmattering
-Version: 0.4.2
+Version: 0.4.4
 Summary: Governed frontmatter, freshness tethers, and validate-only runtime gates for agent-facing Markdown
 Author: Lasse T.
 License-Expression: LicenseRef-FRONTMATTERING-Individual-Use-1.2
 Project-URL: Homepage, https://frontmattering.com
 Project-URL: Repository, https://github.com/frontmattering/frontmattering
 Project-URL: Issues, https://github.com/frontmattering/frontmattering/issues
+Project-URL: Commercial, https://github.com/frontmattering/frontmattering/blob/main/COMMERCIAL_LICENSE_REQUIRED.md
+Project-URL: License, https://github.com/frontmattering/frontmattering/blob/main/LICENSE.md
 Keywords: markdown,frontmatter,documentation,governance,ai-agents,validation
 Classifier: Development Status :: 3 - Alpha
 Classifier: Environment :: Console
@@ -28,6 +30,8 @@ License-File: THIRD_PARTY_NOTICES.md
 License-File: TRADEMARKS.md
 Requires-Dist: PyYAML>=6.0
 Requires-Dist: markdown-it-py>=4.0.0
+Provides-Extra: markdown-plugins
+Requires-Dist: mdit-py-plugins>=0.4.0; extra == "markdown-plugins"
 Dynamic: license-file
 
 # Frontmattering
@@ -36,30 +40,34 @@ Frontmattering makes Markdown safer for agents.
 
 It adds governed frontmatter, task routing, body/frontmatter freshness tethers, and a vendorable validate-only runtime gate so an agent can consume a compact brief without silently relying on stale documentation.
 
-## Install from a local distribution
+## Install
 
 ```bash
-python -m pip install frontmattering-0.4.2-py3-none-any.whl
+python -m pip install frontmattering
 frontmattering --version
 frontmattering doctor
 ```
 
 ## First-hour path
 
+Initialize governance at your repository root; your Markdown lives under `docs/` (the default corpus is `docs/**/*.md`). `promote` takes one file per call, and exactly one document is the router.
+
 ```bash
-frontmattering init docs --set-id MYDOCS --title "My docs"
+frontmattering init . --set-id MYDOCS --title "My docs"
 frontmattering promote docs/INDEX.md --profile router --in-place
-frontmattering promote docs/*.md --profile guide --in-place
-frontmattering tether update --add docs
-frontmattering validate docs
-frontmattering brief docs
+frontmattering promote docs/GUIDE.md --profile guide --in-place
+frontmattering tether update --add .
+frontmattering validate .
+frontmattering brief .
 ```
 
+Promote each additional document with its own `frontmattering promote <file> --profile guide --in-place` call. Promoting a file that is not inside the selected corpus fails before the file is touched (`FRONTMATTERING-AUTHORING-TARGET-OUTSIDE-CORPUS`).
+
 For strict freshness enforcement, set `validation_profile: trust` in `.frontmattering/project.yaml`, then run:
 
 ```bash
-frontmattering validate docs
-frontmattering brief docs
+frontmattering validate .
+frontmattering brief .
 ```
 
 ## Runtime gate
@@ -73,7 +81,7 @@ The runtime artifact is validate-only. It does not expose init, promote, new, in
 
 ## License
 
-Frontmattering is source-available. It is free for individual natural persons within the scope of `LICENSE.md`. Professional, organizational, commercial, client, employer, CI/CD, hosted, managed-service, platform, consulting, or revenue-connected use requires a paid commercial license.
+Frontmattering is source-available. It is free for individual personal use within the scope of `LICENSE.md`. Professional, organizational, employer, client, CI/CD, hosted, managed-service, platform, consulting, or revenue-connected use is permitted for a 30-day evaluation period under `LICENSE.md`; continued use after the evaluation requires a paid commercial license.
 
 Frontmattering is not open-source software under the Open Source Definition because professional and organizational use is restricted without a commercial license.
 
@@ -88,4 +96,4 @@ A `STALE` or `UNTETHERED` summary must not be relied on without reading the body
 
 ## Publication status
 
-This v0.4.2 package is a PyPI-clear technical candidate after license/notice cleanup. Custom license text should still receive legal review before paid commercial sales.
+This v0.4.4 package hardens the first-hour path: the quickstart initializes at the repository root, `promote --in-place` is transactional (it fails before mutation when a target is outside the selected corpus, `FRONTMATTERING-AUTHORING-TARGET-OUTSIDE-CORPUS`), and the validate-only runtime corrects its `--help` and no-path behavior. No frontmatter-schema or canonical-model (`v0.1.5`) changes. Custom license text should still receive legal review before paid commercial sales.

frontmattering-0.4.4/README.md

@@ -0,0 +1,63 @@
+# Frontmattering
+
+Frontmattering makes Markdown safer for agents.
+
+It adds governed frontmatter, task routing, body/frontmatter freshness tethers, and a vendorable validate-only runtime gate so an agent can consume a compact brief without silently relying on stale documentation.
+
+## Install
+
+```bash
+python -m pip install frontmattering
+frontmattering --version
+frontmattering doctor
+```
+
+## First-hour path
+
+Initialize governance at your repository root; your Markdown lives under `docs/` (the default corpus is `docs/**/*.md`). `promote` takes one file per call, and exactly one document is the router.
+
+```bash
+frontmattering init . --set-id MYDOCS --title "My docs"
+frontmattering promote docs/INDEX.md --profile router --in-place
+frontmattering promote docs/GUIDE.md --profile guide --in-place
+frontmattering tether update --add .
+frontmattering validate .
+frontmattering brief .
+```
+
+Promote each additional document with its own `frontmattering promote <file> --profile guide --in-place` call. Promoting a file that is not inside the selected corpus fails before the file is touched (`FRONTMATTERING-AUTHORING-TARGET-OUTSIDE-CORPUS`).
+
+For strict freshness enforcement, set `validation_profile: trust` in `.frontmattering/project.yaml`, then run:
+
+```bash
+frontmattering validate .
+frontmattering brief .
+```
+
+## Runtime gate
+
+```bash
+frontmattering runtime pack --out frontmattering-runtime.pyz
+python frontmattering-runtime.pyz validate docs --format json
+```
+
+The runtime artifact is validate-only. It does not expose init, promote, new, index, tether update, or authoring surfaces.
+
+## License
+
+Frontmattering is source-available. It is free for individual personal use within the scope of `LICENSE.md`. Professional, organizational, employer, client, CI/CD, hosted, managed-service, platform, consulting, or revenue-connected use is permitted for a 30-day evaluation period under `LICENSE.md`; continued use after the evaluation requires a paid commercial license.
+
+Frontmattering is not open-source software under the Open Source Definition because professional and organizational use is restricted without a commercial license.
+
+Runtime dependency status is recorded in `THIRD_PARTY_NOTICES.md`; project notices are recorded in `NOTICE`.
+
+## Claim boundary
+
+A `FRESH` brief means the current body bytes and canonical trust-bearing frontmatter fields match their mechanical tether. It does not prove semantic summary correctness, human approval, external adoption, or production suitability.
+
+A `STALE` or `UNTETHERED` summary must not be relied on without reading the body.
+
+
+## Publication status
+
+This v0.4.4 package hardens the first-hour path: the quickstart initializes at the repository root, `promote --in-place` is transactional (it fails before mutation when a target is outside the selected corpus, `FRONTMATTERING-AUTHORING-TARGET-OUTSIDE-CORPUS`), and the validate-only runtime corrects its `--help` and no-path behavior. No frontmatter-schema or canonical-model (`v0.1.5`) changes. Custom license text should still receive legal review before paid commercial sales.

{frontmattering-0.4.2 → frontmattering-0.4.4}/benchmarks/cold_start_v1/tools/build_arms.py

@@ -19,7 +19,7 @@ def main()->int:
     ap=argparse.ArgumentParser(); ap.add_argument('--output',type=Path,required=True); ns=ap.parse_args()
     out=ns.output.resolve()
     if out.exists(): shutil.rmtree(out)
-    frontmattering_arm=out/'frontmattering_brief_arm'; baseline=out/'baseline'; frontmattering_arm.mkdir(parents=True); baseline.mkdir(parents=True)
+    frontmattering_arm=out/'frontmattering'; baseline=out/'baseline'; frontmattering_arm.mkdir(parents=True); baseline.mkdir(parents=True)
     records=[]
     for src in sorted(SOURCE.glob('*.md')):
         raw=src.read_bytes(); _,body=split_frontmatter(raw)

{frontmattering-0.4.2 → frontmattering-0.4.4}/kernel/AI_INDEX.json

@@ -62,7 +62,7 @@
         "description": "Process exit code documented by the command implementation.",
         "type": "int"
       },
-      "signature": "frontmattering brief [-h] [--task TASK]\n                            [--section {summary,blocks,traps,limits,do-not,trust,reading-order,defects,claim-boundary}]\n                            [--include-dev] [--format {markdown,json}]\n                            [paths ...]",
+      "signature": "frontmattering brief [-h] [--task TASK] [--section {summary,blocks,traps,limits,do-not,trust,reading-order,defects,claim-boundary}] [--include-dev] [--format {markdown,json}] [paths ...]",
       "summary": "==SUPPRESS==",
       "type": "function"
     },
@@ -188,7 +188,7 @@
         "description": "Process exit code documented by the command implementation.",
         "type": "int"
       },
-      "signature": "frontmattering index [-h]\n                            {build,rebuild,update,check,status,delete} ...",
+      "signature": "frontmattering index [-h] {build,rebuild,update,check,status,delete} ...",
       "summary": "==SUPPRESS==",
       "type": "function"
     },
@@ -232,7 +232,7 @@
         "description": "Process exit code documented by the command implementation.",
         "type": "int"
       },
-      "signature": "frontmattering init [-h] --set-id SET_ID --title TITLE [--force]\n                           directory",
+      "signature": "frontmattering init [-h] --set-id SET_ID --title TITLE [--force] directory",
       "summary": "==SUPPRESS==",
       "type": "function"
     },
@@ -360,7 +360,7 @@
         "description": "Process exit code documented by the command implementation.",
         "type": "int"
       },
-      "signature": "frontmattering new [-h]\n                          [--profile {contract,evidence,guide,registry,release,router,spec}]\n                          --title TITLE [--summary SUMMARY] [--force]\n                          path",
+      "signature": "frontmattering new [-h] [--profile {contract,evidence,guide,registry,release,router,spec}] --title TITLE [--summary SUMMARY] [--force] path",
       "summary": "==SUPPRESS==",
       "type": "function"
     },
@@ -416,7 +416,7 @@
         "description": "Process exit code documented by the command implementation.",
         "type": "int"
       },
-      "signature": "frontmattering parse [-h] [--output OUTPUT] [--batch]\n                            [--security-profile {permissive,moderate,strict}]\n                            [--allows-html]\n                            path",
+      "signature": "frontmattering parse [-h] [--output OUTPUT] [--batch] [--security-profile {permissive,moderate,strict}] [--allows-html] path",
       "summary": "==SUPPRESS==",
       "type": "function"
     },
@@ -494,7 +494,7 @@
         "description": "Process exit code documented by the command implementation.",
         "type": "int"
       },
-      "signature": "frontmattering promote [-h]\n                              --profile {contract,evidence,guide,registry,release,router,spec}\n                              [--title TITLE] [--output OUTPUT] [--in-place]\n                              [--check] [--format {markdown,json}]\n                              input",
+      "signature": "frontmattering promote [-h] --profile {contract,evidence,guide,registry,release,router,spec} [--title TITLE] [--output OUTPUT] [--in-place] [--check] [--format {markdown,json}] input",
       "summary": "==SUPPRESS==",
       "type": "function"
     },
@@ -545,7 +545,7 @@
         "description": "Process exit code documented by the command implementation.",
         "type": "int"
       },
-      "signature": "frontmattering query [-h] [--index INDEX] [--task TASK]\n                            [--authority AUTHORITY] [--role ROLE]\n                            [--target TARGET]",
+      "signature": "frontmattering query [-h] [--index INDEX] [--task TASK] [--authority AUTHORITY] [--role ROLE] [--target TARGET]",
       "summary": "==SUPPRESS==",
       "type": "function"
     },
@@ -615,7 +615,7 @@
         "description": "Process exit code documented by the command implementation.",
         "type": "int"
       },
-      "signature": "frontmattering schema [-h] [--output OUTPUT] [--check PATH] [--vscode]\n                             [paths ...]",
+      "signature": "frontmattering schema [-h] [--output OUTPUT] [--check PATH] [--vscode] [paths ...]",
       "summary": "==SUPPRESS==",
       "type": "function"
     },

{frontmattering-0.4.2/kernel/frontmattering/resources → frontmattering-0.4.4/kernel}/KERNEL_ACCEPTANCE_REPORT.md

@@ -64,7 +64,7 @@ template_contract:
 
 spec: FRONTMATTERING_FRONTMATTER_SPEC_v0_1_5.md
 spec_sha256: cb4f431d6326a04a2b30d5d1b4a99c301342b017799953b12740acf5b110b023
-kernel_files_sha256: 713befd933348e6ee6331c4748d2d0eab8a7650cf175832c70d8cebd7b2c55bb
+kernel_files_sha256: 9b7d957b66556be1065436769851956afec7cd179cd6c8a85e9aa1e4457aa58e
 
 classes_total: 101
 ok: 101  missing_fixture: 0  wrong_finding: 0  not_rejected: 0  rejected_valid: 0

frontmattering-0.4.4/kernel/frontmattering/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.4.4"

{frontmattering-0.4.2 → frontmattering-0.4.4}/kernel/frontmattering/__main__.py

@@ -138,6 +138,8 @@ def selected_format(args: argparse.Namespace) -> str:
 
 
 def command_validate(args: argparse.Namespace) -> int:
+    if not args.paths:
+        print(f"No paths supplied; validating current working directory: {Path.cwd()}", file=sys.stderr)
     try:
         report = build_report(args.paths)
     except ToolingError as exc:
@@ -719,7 +721,7 @@ def _parse_one_document(path: Path, args: argparse.Namespace) -> tuple[dict, int
     metadata.pop("security", None)
     payload = {
         "schema_version": "frontmattering_document_ir/v0_3",
-        "distribution_version": "0.4.2",
+        "distribution_version": "0.4.4",
         "canonical_model_version": "0.1.5",
         "source": {
             "path": str(path),
@@ -772,7 +774,7 @@ def command_parse(args: argparse.Namespace) -> int:
             dest.parent.mkdir(parents=True, exist_ok=True)
             dest.write_text(json.dumps(_json_safe(payload), indent=2, sort_keys=True, ensure_ascii=False)+"\n", encoding="utf-8")
             records.append({"source": rel.as_posix()[:-8], "ir": rel.as_posix(), "source_sha256": payload["source"]["sha256"]})
-        manifest = {"schema_version":"frontmattering_ir_batch_manifest/v0_3","distribution_version":"0.4.2-pypi-clear","source_root":str(path),"document_count":len(records),"records":records,"selection":selection.payload(),"claim_boundary":"Disposable deterministic projection; source Markdown remains authoritative."}
+        manifest = {"schema_version":"frontmattering_ir_batch_manifest/v0_3","distribution_version":"0.4.4","source_root":str(path),"document_count":len(records),"records":records,"selection":selection.payload(),"claim_boundary":"Disposable deterministic projection; source Markdown remains authoritative."}
         (out_root/"manifest.json").write_text(json.dumps(manifest,indent=2,sort_keys=True)+"\n",encoding="utf-8")
         print(f"document_ir_batch_written={out_root} documents={len(records)}")
         return terminal
@@ -936,13 +938,20 @@ def validate(targets: list[str]) -> dict[str, Any]:
     }
 
 
+USAGE = "usage: frontmattering-runtime validate <path> [<path> ...] [--format json]"
+
+
 def _parse_args(argv: list[str]) -> tuple[str, list[str], str]:
+    if len(argv) >= 2 and argv[1] in ("-h", "--help"):
+        return "help", [], "json"
     if len(argv) < 2 or argv[1] != "validate":
         return "usage", [], "json"
     paths: list[str] = []
     fmt = "json"
     i = 2
     while i < len(argv):
+        if argv[i] in ("-h", "--help"):
+            return "help", [], fmt
         if argv[i] == "--format":
             if i + 1 >= len(argv) or argv[i + 1] not in {"json"}:
                 return "bad_format", [], fmt
@@ -951,14 +960,24 @@ def _parse_args(argv: list[str]) -> tuple[str, list[str], str]:
         else:
             paths.append(argv[i])
             i += 1
+    if not paths:
+        return "no_paths", [], fmt
     return "validate", paths, fmt
 
 
 def main(argv: list[str] | None = None) -> int:
     argv = list(sys.argv if argv is None else argv)
     action, paths, _fmt = _parse_args(argv)
+    if action == "help":
+        print(USAGE)
+        print("\nValidate-only runtime surface. Requires at least one path (file or directory).", file=sys.stdout)
+        return 0
     if action == "usage":
-        print("usage: frontmattering-runtime validate <path> [<path> ...] [--format json]", file=sys.stderr)
+        print(USAGE, file=sys.stderr)
+        return 2
+    if action == "no_paths":
+        print(USAGE, file=sys.stderr)
+        print("error: validate requires at least one path", file=sys.stderr)
         return 2
     if action == "bad_format":
         print("frontmattering-runtime only supports --format json", file=sys.stderr)
@@ -1019,7 +1038,7 @@ def _runtime_wrapper() -> str:
         "runtime_builder": "frontmattering.__main__.command_runtime_pack",
     }
     return RUNTIME_WRAPPER_TEMPLATE.replace(
-        "__KERNEL_VERSION__", "0.4.2"
+        "__KERNEL_VERSION__", "0.4.4"
     ).replace(
         "__RUNTIME_BUILD_MANIFEST__", json.dumps(manifest, sort_keys=True)
     )
@@ -1066,7 +1085,7 @@ def command_runtime_pack(args: argparse.Namespace) -> int:
         "schema_version": "frontmattering_runtime_pack_report/v0_2",
         "runtime_artifact": str(out),
         "canonical_model_version": "0.1.5",
-        "kernel_version": "0.4.2",
+        "kernel_version": "0.4.4",
         "artifact_format": "python_zipapp",
         "surface": "validate_only",
         "artifact_sha256": hashlib.sha256(artifact_bytes).hexdigest(),
@@ -1104,7 +1123,7 @@ def build_parser() -> argparse.ArgumentParser:
         prog="frontmattering",
         description="Govern and orient load-bearing Markdown with Frontmattering canonical model v0.1.5 frontmatter.",
     )
-    parser.add_argument("--version", action="version", version="frontmattering distribution v0.4.2; canonical model v0.1.5")
+    parser.add_argument("--version", action="version", version="frontmattering distribution v0.4.4; canonical model v0.1.5")
     sub = parser.add_subparsers(dest="command", required=True, parser_class=StrictArgumentParser)
 
     init = sub.add_parser("init", help="Initialize a small Frontmattering document set and package router.")

{frontmattering-0.4.2 → frontmattering-0.4.4}/kernel/frontmattering/promotion.py

@@ -9,7 +9,7 @@ from typing import Any
 
 import yaml
 
-from .authoring import load_project, refresh_router_task_catalog, starter_frontmatter, _remove_generated_starter_router
+from .authoring import load_project, refresh_router_task_catalog, starter_frontmatter, _remove_generated_starter_router, _project_paths, _project_root
 from .harness_errors import ToolingError
 from .markdown.api import parse_markdown_text
 
@@ -158,13 +158,37 @@ def promote_document(
                 "Choose another --output path or use --in-place intentionally.",
                 error_id="FRONTMATTERING-PROMOTE-OUTPUT-EXISTS",
             )
+        in_place = destination.resolve() == input_path.resolve()
+        project = load_project(destination.parent)
+        # Preflight (fail-closed, before any mutation): an in-place promotion must
+        # target a file the project actually governs. Otherwise the catalog refresh
+        # below cannot see the promoted document and fails *after* rewriting the
+        # file — the non-transactional trap. Fail here, before touching the file.
+        if in_place and destination.resolve() not in set(_project_paths(project)):
+            raise ToolingError(
+                "Promotion target is outside the selected corpus",
+                str(destination),
+                "The project's corpus selection does not include this file, so promoting it in place would rewrite a file the project will not govern and cannot refresh.",
+                "Initialize the project at the repository root (`frontmattering init .`) or add this file's directory to the corpus include globs in .frontmattering/project.yaml.",
+                {"project_root": str(_project_root(project)), "corpus_include": (project.get("_selection") or {}).get("include") or []},
+                error_id="FRONTMATTERING-AUTHORING-TARGET-OUTSIDE-CORPUS",
+            )
+        original_bytes = destination.read_bytes() if in_place else None
         _atomic_write(destination, output)
         receipt["terminal_state"] = "WRITTEN"
-        project = load_project(destination.parent)
-        if profile == "router":
-            removed = _remove_generated_starter_router(project, replacement_path=destination)
-            receipt["removed_starter_router_paths"] = [str(path) for path in removed]
-            refresh_router_task_catalog(load_project(destination.parent))
-        else:
-            refresh_router_task_catalog(project)
+        committed = False
+        try:
+            project = load_project(destination.parent)
+            if profile == "router":
+                removed = _remove_generated_starter_router(project, replacement_path=destination)
+                receipt["removed_starter_router_paths"] = [str(path) for path in removed]
+                refresh_router_task_catalog(load_project(destination.parent))
+            else:
+                refresh_router_task_catalog(project)
+            committed = True
+        finally:
+            # Transactional guarantee: any post-write failure must not leave the
+            # in-place target mutated. On success this is a no-op.
+            if not committed and in_place and original_bytes is not None:
+                _atomic_write(destination, original_bytes)
     return receipt