v4.0.0

609 commits, 1 contributor.

Upgrade notes

• sinks: compose a ref from declared parts, not from a Go default (acb157b)

• ai-policy: rename the llm bridge to ai-policy (2cfd6f0)

  pf-bridge llm is now pf-bridge ai-policy; the
  pf-bridge-llm binary is now pf-bridge-aipolicy.

• ai: read org.projectfile.ai (16a2cc1)

  a document declaring org.projectfile.llm is no longer
  read; rename the key to org.projectfile.ai.

• fragments: inherit live at generate, no committed cache (acec2f1)

  --refresh and core.Options.Refresh are gone; generate now
  reaches the forge by default (--offline preserves committed sections), and
  docs/.d/.inherited/ is no longer written or read.

• results on stdout, one colour decision and a network timeout (0aa38e6)

  result lines move from stderr to stdout.

• forge: take the network timeout from the shared --timeout (6e068d7)

  forge push no longer declares its own --timeout; the
  persistent flag of the same name replaces it.

• module: move the module to projectfile.org/projectfile/bridge/v4 (a9eb9b2)

  the Go module path is now projectfile.org/projectfile/bridge/v4.

Highlights

pf-bridge-<os>-<arch> is now one standalone binary that includes every bridge, so a single download is the whole tool. The single-bridge binaries no longer ship as loose release assets; they come together in pf-bridge-bridges-<version>-<os>-<arch>.tar.gz with a dispatcher that runs the binaries beside it. Extract the archive anywhere; deleting that directory uninstalls it.

Features

• core: show native language names in the cross-language bar (35e1190)
• security: add GPG fingerprint, reporting guidance, acknowledged vulnerabilities (cde42be)
• security: derive gpg-fingerprint from the network when unset (189d07d)
• security: note absence of a bug bounty programme when unset (8d4c246)
• i18n: move localized docs to docs// and add default-language (cca4500)
• readme: improve generator with platforms, variants, collection bar and merged header (6b767d4)
• bridge: wrap localized docs in textlint terminology disable (635be0c)
• contributing: merge workflow and commits into a Conventions section (54e9cf6)
• readme: drive the related-projects bar from links[] tagged 'related' (f57453a)
• pfmodel: add priority field for link and shield ordering (73d4fa1)
• readme: order badges and links by priority (d5f2fb8)
• support: order links by priority in SUPPORT.md (f3464fc)
• contributing: order forge stars and socials by priority (884cf6e)
• derive: address forge mirrors by capability, not by slug (15d229d)
• scan: propose capability tags from the forge host table (e767a9d)
• scan: name the shields route family, and add --force (528b432)
• forge: add the badges route families to the mirror links (838c823)
• readme: rank installation and usage groups by priority (2fc9d01)
• registries: compose a pull reference per container registry (5fb44af)
• sync: let --force rewrite a file whose fields already agree (f7dfa6d)
• sink: compose pull references from sinks, replacing the registry model (e1391b3)
• bridge: localize prose links and add a generated-file footer (377ade7)
• bridge: localize scan/derive link labels per declared language (e96a8d4)
• bridge/support: render paid-support as a SUPPORT.md block (5c7219c)
• fragments: localize assembled documents per org.projectfile.i18n (5a43813)
• i18n: translate feature fragments to Spanish and Ukrainian (2aa2017)
• i18n: localized link labels, GitHub issues link, llm-generator doc (0e23d81)
• i18n: localize identity summary and description (a29431e)
• fragments: localize inherited sections from the parent's published documents (a04bc15)
• readme: group install commands per sink with joined fences (cd90818)
• readme: curate Links by readme tag and list docs/how-to articles (1240e5b)
• dispatcher: annotate --list with descriptions, skip platform artifacts (52d00f1)
• pfmodel: parse org.projectfile.llm extension namespace (3e8b8d1)
• bridge: add pf-bridge-llm — render LLM.md from org.projectfile.llm (5484376)
• bridge: cross-link LLM.md from readme and contributing (4148d30)
• llm: render AI_POLICY.md with the three-direction shape (106a7e6)
• ai-policy: make default activity coverage and internal-practice link explicit (e8a04a8)
• bridge: add --preview flag (55c46b9)
• bridge: make the generated-from-projectfile footer opt-in (9e5712e)
• bridge: add See also section from project-authored links (6600436)
• readme: localize the related bar prefix and drop the self link (4825923)
• ignore: generate .textlintignore and .fdignore (207f6c5)
• check: derive the check sweep from the project manifest (56531c5)
• ocisinks: compose the own artifact through a sink's selfref (453c445)
• forge: filter push by forge, support scp-style URLs (ca3cf2b)
• readme: label the ssh artifact kind (ac02194)
• release: add riscv64 binary to published matrix (a99eadf)
• vulnerabilities: fan out suppress list to audit-ci.jsonc (b1fe4a7)
• derive: infer Docker Hub and GHCR links from resolved sinks (a09d0e7)
• bridge: add shard.yml sync bridge for Crystal projects (f228946)
• forge: declare Codeberg and GitHub mirrors and enable GitHub CI (5863f25)
• ci: build linux/amd64, arm64 and riscv64 images (1ce3ae1)
• ci: sign and attest the published image with cosign (b48bbe8)
• readme: resolve badge hrefs per language and CI-matrix series (0363e14)
• forges: rank alias claims by link priority (a45be94)
• scan: materialize forge link and repository templates (0f640dd)
• derive: releases alias from repositories[releases=true] (11ec24c)
• scan: sinks scanner materializes package-registry links (83a056c)
• ci: sign released binaries with the org GPG key (907efbb)
• publish: push to Docker Hub (fd38608)
• readme: prefer identity.description over summary in basics (41d1e16)
• readme: summarise inherited features as one note naming each parent (e18b24a)
• readme: lead the building block with declared groups, keep derived goals (37799d6)
• readme: fan command sections over per-node matrix axes too (a9a45cc)
• readme: label the action artifact kind (7efc375)
• readme: per-cell groups render one headed fence per matrix cell (b84b94e)
• readme: optional title gives a section group its own heading (dfeb1a8)
• readme: fleet default platforms for an image declaring none (754a0ec)
• readme: inputs table from an action artifact's action.yaml (0dad9b4)
• readme: axis-args keeps matrix axes as Dockerfile ARG lines (e43925c)
• readme: one runnable line per fan-out, variants listed below it (523deb1)
• readme: render a localized ci goal description in the reader’s language (f64bcc6)
• readme: embed a declared file as a section group's fence (1c6df5c)
• fragments: let a conventions shell opt out of inheritance (6f3127c)
• readme: quote USAGE.md's top-level help and first example (fc4edc9)
• readme: name the packaged upstream and keep its license apart (8b11a8b)
• rootflags: bind -V to --version on every bridge binary (bcca94e)
• readme: join same-sink groups and show channel titles only when there is a choice (c477877)
• readme: recognise a help capture by its console command line (bf4f9af)
• readme: quote only the top-level help in Usage, link USAGE.md for examples (8e8fa0b)
• readme: name each registry’s platforms on its install heading (d6b3346)
• readme: label an npm or PyPI package by its registry (841e9d7)
• readme: name the command an artifact exports on its line (e432585)
• fragments: assemble fragment documents under docs/ (0d69aed)
• readme: link companion documents by their title (1da87d8)
• readme: continue a single fence with a group that carries no prose (0953e24)
• readme: list a group’s published matrix cells under its fence (3053449)
• readme: render the Building section as docs/BUILD.md behind build-doc (11f5118)
• contributing: link docs/BUILD.md once the readme renders it (c69cdd1)
• badges: render each badge on the documents it declares (89e165b)
• release-notes: render release notes from git (63b4038)
• release-notes: pin README install and usage blocks to the release (9c5d9be)
• release-notes: adaptive elapsed time in the summary line from a template (0cf8256)
• release-notes: publish the per-forge half of a release body (a8eeb9b)
• release-notes: compare against the previous release the forge lists (cd5127e)
• derive: expose stable version parts as org.projectfile.semver (7ce9e4a)
• release-notes: split Verify per artifact kind and check the installed binary (fd74162)
• release-notes: apply an installation entry’s release prefix and postfix on the release page (d42db3d)
• release-notes: pin images by digest and list per-platform digests (59885fc)
• release-notes: show per-platform size change against the previous release (dd109cf)
• release-notes: list package changes from the attested SBOM (5fae330)
• release-notes: configure shown commit sections from the projectfile (27b5866)
• release-notes: attach files named by release.attach to the release (2886863)
• npm: name the package after a declared npm package artifact (1c3e545)
• bridge: name the repositories[].packages entry as the package manifest source (ff301a8)
• npm: take cpu and os from the npm artifact before the project-level platform lists (01651c4)
• forge: push branch and tag protection derived from release branches (2b2702c)
• forge: set the origin default branch to release.trunk (c06adaf)
• release-notes: check every downloaded binary against the signed SHA256SUMS (27b00bf)
• bridge: scope the registry to one command so every bridge can share a binary (90f0aec)
• dispatch: run every subcommand in-process, with a lookup build for the sibling binaries (913c66a)
• release: ship one standalone pf-bridge and an archive of the single-bridge binaries (39200f0)
• release: tag releases with a v prefix (3ecf5f7)

Bug fixes

• readme: restore blank line after Links heading (a44b964)
• readme: regenerate badges for shields.io static/v1 (42a734b)
• git: untrack the .makefile/bootstrap build marker (9d0d87b)
• readme: advertise real local entry points in the Building section (f66ffcd)
• cff: stop CITATION.cff stacking one SPDX block per sync run (b927c3a)
• readme: admit a readme-tagged non-goal into the entry-point list (b3bcaaa)
• reuse: unify the header every generator writes (cd8309f)
• cff: tidy the CITATION.cff pedigree banner (7767b68)
• codeowners: stop the REUSE header stacking on every write (93c148c)
• reuse: mark every generated Markdown file, whatever its policy (56076a0)
• contributing: repair author links, localize labels, trim dogmatic text (7418d16)
• scan: overwrite link label and preferred under --force (fda368f)
• docs: point docs references at the project's /docs, not the spec (bd7d1fe)
• bridge/core: disable English-only lint rules for localized docs (0bff42b)
• bridge/support: drop external MCVE link from SUPPORT.md (1ad596e)
• contributing: drop the redundant inline TOC link (be8ca36)
• bridge/core: reword localized-rules comment to clear misspell lint (41c629f)
• bridge: derive localized issues link in git-remotes scan (3b032f5)
• bridge: translate the Issues noun to Ukrainian as Задачі (ba3b8ce)
• fragments: blank-line seam between REUSE header and textlint wrap (fd3df4b)
• drop '# Stack:' line from generated banners (08b835a)
• readme: quote matrix axis values as code spans (c0d18d0)
• fragments: carry textlint directive pairs in translated fragment sources (702ae87)
• readme: give install and usage their own sink heading verbs (c0c5666)
• bridge: last generator bugs from FOCUS (8441650)
• bridge: rename ai-policy binary/package dir to match its CLI name (0d95b00)
• ai-policy: add language to disclosure-trailer fenced block (2d67f7d)
• dockerfile: key apt cache mounts by arch, not just series (19ca6d3)
• bridge: drop scaffold-once, use marker gate everywhere (fa29c7b)
• support: drop duplicate See also section from SUPPORT.md (74b0a39)
• contributing: link the issues tracker even when a forge label is set (8df4780)
• localize: give a body with no trailing newline exactly one (34253ea)
• fragments: drop the parent's language bar when nesting its document (3fe1a81)
• go: bump toolchain directive to 1.26.6 (36fffa1)
• deps: bump projectfile/core to v2.9.4 (b28af09)
• derive: stop warning about image sinks on projects with no image (77a04c4)
• bridge: wrap the AI_POLICY project-name line in textlint-disable (b7086fc)
• fragments: drop parent version from inherited section headings (6e1327e)
• pyproject: preserve header and comments, gate Documentation URL on the main-documentation tag (8bc0b4e)
• ignore: apply exclude so an inherited pattern can be dropped (247a982)
• ignore: emit re-includes after the patterns they answer (836cfea)
• ignore: honour the documented generate list (b385fb2)
• ignore: fall back .containerignore to docker: when unset (03ce3ce)
• readme: call a website artifact a Site (8a6461b)
• yamllint: emit only what the projectfile declares (6cb5a3e)
• container: declare the full b19 build-arg surface (7e4ccbf)
• ci: add gsa node to enforce build-binaries before auto-gsa (b0ca449)
• update .makefile/library submodule (disable check-outdated-go memoisation) (2a96521)
• ci: opt into the binary release pipeline explicitly (a47b0a7)
• fragments: defer variant warning until document has content (d8a27d9)
• deps: bump golang.org/x/crypto v0.54.0 → v0.56.0 (1493711)
• deps: bump kiota.ch/projectfile/core/v2 to v2.9.7 (e66c32e)
• build-binaries: stop writing duplicate unsuffixed binaries into dist/ (b6c6b71)
• bump core to 2.10.3 (cfab4d0)
• ocisinks: list only the sinks a publish route pushes to (bfef8aa)
• ignore: emit ignore outputs in global alphabetical order (4316a0e)
• scaffold: backfill a plain label for unlabeled bugs/homepage/documentation links (50f6e2d)
• ignore: extract dist/ literal into a test constant (c7f8dd7)
• sync: make the projectfile authoritative in sync mode (2a7aa6a)
• npm: skip repository and bugs when package.json already agrees (e42ad63)
• cleanup dirnames for dockerignore (bf20dd7)
• derive: remove package-registry inference pass (f9aceed)
• derive: fan out package-registry links per CI matrix axis (20f2fe6)
• forge: declare only existing forges (c7f2284)
• pf-cli optimize fuckup (5d16d79)
• deps: bump projectfile/core to v2.11.1 (1450375)
• deps: bump projectfile/core to v2.11.2 (df45991)
• deps: bump projectfile/core to v2.12.0 (019614a)
• readme: drop badges that name a CI-matrix series, don't fan out (bd6f658)
• scan: gap-fill a proposed link priority (03357dc)
• ci: matrix the binaries-are-signed node (406560c)
• deps: bump projectfile/core to v2.12.3 (bf303c6)
• deps: bump projectfile/core to v2.13.0 (9bd9b84)
• deps: bump github.com/ProtonMail/go-crypto to v1.5.1 (561aa6c)
• cli: rewrite pf-bridge help with categories and ro/rw tags (73b3779)
• cli: show real cache paths, entries, and freshness (c44c47e)
• cli: report forge push per repository (a67e41c)
• cli: friendlier bridge errors and empty-state guidance (dffc5e9)
• cli: ask identity.name directly with slug/title/summary hints (4e51d02)
• cli: update list rendering test for ro/rw tags (1117512)
• deps: bump go-crypto v1.5.1 -> v1.5.2 (980a3cd)
• sinks: promote a lone fallback sink to primary (75383b1)
• scan: --force keeps the tags a scanner proposed for the issue tracker (b891998)
• readme: honour matrix.exclude when fanning out command lines (92d4372)
• readme: drop the action inputs table when the action ref is unresolved (90eaccb)
• fragments: order fragments by file stem (74937db)
• fragments: keep an inherit: false document flat (1544f7b)
• readme: keep USAGE.md lint directives out of the usage excerpt (e2de45f)
• readme: read upstream where the parser keeps it (002496c)
• bridgerun: gate interactive prompts on a terminal stdin (7e69d7c)
• buildinfo: derive the version from Go build info when unstamped (0c65178)
• scanners: run the forge and sinks scanners only where a projectfile exists (1b6437f)
• reject an unknown shell in pf-bridge completion (fe20537)
• report a flag typed before the pf-bridge command (31327e0)
• keep per-bridge runs non-interactive without a terminal (fb41824)
• readme: spell Docker Hub references without the docker.io host (7eb753b)
• readme: name inherited parents without the heading prefix (0549b4c)
• readme: drop a lone sink heading outside Installation (4741073)
• readme: let a series example name any value of its matrix axis (7551847)
• deps: update projectfile core to v2.15.0 (249a9d8)
• readme: percent-encode spaces in badge link destinations (c2162c7)
• sync: never read a synced file back into the projectfile (63c56c7)
• readme: name series line by the image part and mark its values (4001da6)
• release-notes: count only feat fragments as new, root fragment links (5716016)
• forge: rewind the request body before a retry (2f81eec)
• release-notes: verify offline cosign signatures without the transparency log (aae94a1)
• release-notes: name the token source and stop early without one (fa29649)
• release-notes: render magnets as links, fenced where the forge strips the scheme (36f1356)
• dispatch: skip -<uname -m> release copies during discovery (1b8bba2)
• assert on a here-string, not a grep -q pipeline (62a8d75)
• deps: bump charm.land/bubbletea/v2 to v2.1.0 (9c13779)
• container: restore M6E_VERSION in final image (39a810f)
• bridge: default sync converges without destroying file data (90d99d6)
• deps: bump projectfile/core to v2.16.0 (2947808)
• deps: bump core to 2.18.0 (46ed1d4)
• npm: skip a non-SemVer identity.version instead of writing it (87f0f5c)
• net: retry every network crossing on core's shared policy (251e0eb)
• security: suppress CVE-2026-92392 in the Ubuntu cURL (5dfaa8e)
• security: generate the scanner ignore files from the projectfile (a5e54da)
• ci: sign every binary cell in one job (54c671e)
• build: fetch public Go modules through proxy.golang.org (5d7b84f)
• build: copy every root Go file into the image build (43165eb)

Performance

• fragments: batch and parallelize parent fetches (eb0c403)
• container: declare M6E_VERSION next to the user stage (3d74a7d)

Reverts

• undo local submodule edit (fix belongs in m6e/library) (1ccc531)

Dependencies

• 8 dependency updates

Installation

Container image

Pull the published container image:

docker pull ghcr.io/projectfile-org/bridge:v4.0.0

Prebuilt binary

Download the prebuilt binary for your platform from this release:

mkdir -p ~/.local/bin
curl --fail --location --output ~/.local/bin/pf-bridge https://github.com/projectfile-org/bridge/releases/download/v4.0.0/pf-bridge-$(uname -s | tr A-Z a-z)-$(uname -m)
chmod +x ~/.local/bin/pf-bridge
~/.local/bin/pf-bridge --help

Published for: linux/amd64, linux/arm64, linux/riscv64, darwin/amd64, darwin/arm64

Usage

pf-bridge

$ pf-bridge --help
pf-bridge — keep every project file in sync with your projectfile document

A projectfile (projectfile.yaml) is the single source of truth for a project:
identity, people, links, and tool config. pf-bridge copies that data out
into the files each tool already reads — README.md, package.json,
CITATION.cff, forge settings — and reads two-way files back.
Spec: https://projectfile.org/specification/

Usage:
  pf-bridge <bridge> [args]   run one bridge (e.g. readme, npm, forge)
  pf-bridge all [flags]       update every file from the projectfile [rw]
  pf-bridge check [flags]     verify declared files match, write nothing [ro]
  pf-bridge to all            write projectfile out to every file [rw]
  pf-bridge from all          read every two-way file back in [rw]
  pf-bridge --list            list installed bridges
  pf-bridge completion SHELL  print completion script (bash|zsh|fish)

[rw] updates files, [ro] only reads or compares. `check` without names
covers the bridges this project declares; `check <name>…` narrows it,
`check --all` covers every installed bridge instead.

Shared flags (also accepted after a bridge name):
  --check, --dry-run, --force, --create-all, --fail-on-drift, --offline,
  --quiet, --verbose. Each has a PF_BRIDGE_* env equivalent.
  Drift warns by default; --fail-on-drift makes it fatal.

Tools:
  cache                Manage the local SPDX and include cache
  forge                Push projectfile metadata out to the repository forge
  init                 Scaffold a new projectfile document (prefer pf-cli init)
  release-notes        Render release notes from git
  scan                 Run scanners to refresh projectfile metadata from filesystem signals
Package manifests:
  composer   [rw]  composer.json — two-way sync
  npm        [rw]  package.json — two-way sync
  pyproject  [rw]  pyproject.toml — two-way sync
  shard      [rw]  shard.yml — two-way sync
Citation and ownership:
  cff          [rw]  CITATION.cff — two-way sync
  codeowners   [rw]  CODEOWNERS — two-way sync
  funding      [ro]  FUNDING.yml — one-way render
  fundingjson  [ro]  funding.json — one-way render
Documentation:
  ai-policy     [ro]  AI_POLICY.md — one-way render
  coc           [ro]  CODE_OF_CONDUCT.md — one-way render
  contributing  [ro]  CONTRIBUTING.md — one-way render
  dei           [ro]  DEI.md — one-way render
  fragments     [ro]  FEATURES.md, ROADMAP.md, … assembled from docs/<name>.d fragments (one-way render)
  readme        [ro]  README.md — one-way render
  security      [ro]  SECURITY.md — one-way render
  support       [ro]  SUPPORT.md — one-way render
Repository setup:
  browserslist     [ro]  .browserslistrc — one-way render
  gitattributes    [ro]  .gitattributes — one-way render
  ignore           [ro]  .claudeignore, .containerignore, .dockerignore, .fdignore, .gitignore, .npmignore, .textlintignore — one-way render
  license          [ro]  LICENSE + LICENSES/<spdx>.txt (one-way render, always overwrite)
  releaserc        [ro]  .releaserc.yaml — one-way render
  vulnerabilities  [ro]  .grype.yaml, .trivyignore, audit-ci.jsonc, osv-scanner.toml — one-way render
  yamllint         [ro]  .yamllint — one-way render

Help per bridge: pf-bridge <bridge> --help

Examples and every command’s help are in Usage.

Verify

Check that what you downloaded is what this project published.

Container image

The signature proves this project’s CI built and pushed the image; the attestation carries its software bill of materials.

COSIGN_KEY=https://kiota.ch/damian-buho/metadata/raw/branch/main/keys/ci-cosign-key.pub
cosign verify --key "$COSIGN_KEY" --insecure-ignore-tlog=true ghcr.io/projectfile-org/bridge:v4.0.0
cosign verify-attestation --key "$COSIGN_KEY" --insecure-ignore-tlog=true --type cyclonedx ghcr.io/projectfile-org/bridge:v4.0.0

Prebuilt binary

The signature proves the binary is the one the maintainer’s release key signed.

gpg --keyserver hkps://keys.openpgp.org --recv-keys 8F89CBF7C8D51F8BEC7533C00925F8F79EBD3257
curl --fail --location --output pf-bridge.asc https://github.com/projectfile-org/bridge/releases/download/v4.0.0/pf-bridge-$(uname -s | tr A-Z a-z)-$(uname -m).asc
gpg --verify pf-bridge.asc pf-bridge

Full changes: 3.7.0...v4.0.0