A patch release. It fixes two reproducibility problems that a real adoption of v1.20.0 turned up, and adds a project-owned way to declare the build outputs that a project's records cite. Nothing changes for a project that does neither.
Three changes, each stated with the problem it answers. The repository's changelog entry, linked at the end of this page, is the authoritative text.
The Windows self-test gives one verdict on any console
The command engines print UTF-8. The PowerShell self-test read them back through the console pipe, and PowerShell decodes a program's output with the console's code page, so on a console left at code page 437 three multibyte cases failed on the transport rather than on anything they assert: 243 of 246 passed there, 246 of 246 under UTF-8, from the same tree. Each child process now runs with its output redirected to files that are read back as UTF-8, which takes the console out of the path and changes no global console setting. The engines themselves did not change.
Build outputs can be declared in the link check
A record may cite a file that the project's build produces. That file is not in version control, so in a clean checkout, and in CI, the reference cannot resolve and the link check called it broken. Ignoring the path would also hide real mistakes beside it, so the distinction is declared: a reference matching a declared pattern is counted, printed as Declared build output, UNVERIFIED, and excused only while it fails to resolve. Once the build has run, the file exists and the reference is checked like any other.
The declaration lives in a project-owned file
The portable manifest under scripts/ carries the same key as an upstream default, left empty. Declaring outputs there would make the whole manifest locally modified, so a sync would skip it and the project would stop receiving manifest updates until it forced one, which would erase the declaration. Declarations therefore go in .ai/context/link-policy.json, a file that sync never copies. The two lists are combined, so a project that already declared in the manifest keeps working.
Who is affected
Read the row that describes your project. Most projects need no action beyond a normal update.
A project whose records cite its own build output
Its link check fails in any clean checkout, including CI, until the output is declared.
Action: Add the narrowest pattern that covers the citation to .ai/context/link-policy.json.
Anyone running the PowerShell self-test on a console that is not UTF-8
The verdict no longer depends on the console code page.
Action: Nothing. Update to take the fix.
A project that declares nothing and builds nothing
The release is additive: it sees exactly what it saw before.
Action: Nothing beyond the normal update.
A project updating from before v1.20.0
It also takes the v1.20.0 changes, including a stricter waiver format at task closure.
Action: Read the v1.20.0 compatibility notes before applying.
Upgrade safely
The sequence below is the repository's upgrade guide applied to this release. Nothing in it needs --force, and the guide's rule is to treat the upgrade as one commit you can revert in one step.
Start from a clean tree. Commit or stash your own work first.
Download the archive and its checksum, and verify before you extract anything.
Extract, then run the sync as a dry run. It writes nothing. Read the counters: new, updated, unchanged, locally modified, and removed in source.
Apply only when the numbers say what you expect. Customized files are skipped, not overwritten.
Run the project's own validation, then commit the upgrade on its own with the version in the message.
Verify and extract on POSIX bash
sha256sum -c forgeos-1.20.1.tar.gz.sha256
tar -xzf forgeos-1.20.1.tar.gz
Verify and extract on Windows PowerShell
(Get-FileHash -Algorithm SHA256 forgeos-1.20.1.tar.gz).Hash
tar -xzf forgeos-1.20.1.tar.gz
If your project has already adopted ForgeOS, forgeos update --target <project> performs the same dry run and refuses a target that never adopted. The first-time route is on the install page. Install guide.Upgrade guide for this tag.
Declaring generated outputs
Only a project that cites its own build output needs this. The declaration goes in .ai/context/link-policy.json. The file is optional, it belongs to the project, and it survives every update.
Each entry is a regular expression matched against the repository-relative path as written in the reference. Anchor it with ^ unless you mean otherwise.
A pattern covers its own path and nothing beside it: ^dist/ does not cover dist-old/, mydist/, or distribution/.
Prefer the narrowest pattern that covers what your records actually cite, so a typo in a different path still fails.
A declared reference that does not resolve is reported as Declared build output, UNVERIFIED. The check ran no build and confirmed nothing; the word is deliberate.
To verify that the outputs exist, run your normal build and run the check again. A path that now resolves is checked like any other and leaves the UNVERIFIED section.
How this differs from ignoring a path
Situation
Ignoring a path
Declaring an output
The reference is counted
No, skipped entirely
Yes
The reference is reported
No
Yes, in its own section
The file exists
Not applicable
Checked like any other path
The file is missing
Excused silently
Excused, and said out loud
An undeclared path, or a missing source file
Fails
Still fails
Verify this release
The value your machine prints, the value in the checksum file, and the value below must all agree. The archive is a sync source, not a product bundle, and the same tag builds byte-identical archives on Windows and POSIX.
What is published, what is not proven, what is planned
ForgeOS is in public preview. This page claims no autonomous understanding of a project's documents and no production maturity: the evidence is the repository's own use and a small number of adoptions.
Published
In v1.20.1
shipped
The self-test reports the same verdict under code page 437 and under UTF-8.
Declared build outputs through .ai/context/link-policy.json, with the UNVERIFIED report.
Carried from v1.20.0: staged task closure with conflict preservation, a brief that measures and reports its own size, and one mandatory-rule contract across both shells.
Not yet proven
Limits the release states
not proven
The new declaration key is exercised by test fixtures rather than by the blueprint's own content, which declares no generated outputs.
Independence from the console code page is asserted from a forced code page 437 inside one case; a code page the tests never see is untested.
The acceptance behind v1.20.0 was not independently reviewed, and this patch does not change that.
The operational closure trial on a real adopted project is still pending.
macOS is not claimed: no job runs there.
Planned
Not built
deferred
Package-manager channels, each deferred with its blocker named.
A documented compatibility matrix of which adopted versions may upgrade to which.
A rendered changelog page derived from the repository's own record.
A read-only dashboard, only after the machine-readable status contract proves stable.