@warpgogol/forge 4.1.5 → 4.2.1

package/AGENTS.md

@@ -17,7 +17,7 @@ Packet 000 will add the portable `forge/program@1` control plane under `os/progr
 
 | Module | Commands | Source |
 | --- | --- | --- |
-| `forgeCoreModule` | `create`, `doctor`, `upgrade`, `forge.agents.generate`, `scaffold`, `port.scaffold`, `skill.validate`, `skill.list`, `port.validate`, `profile.validate`, `dev`, `build`, `validate`, `pinned.validate`, `pinned.init`, `package.health`, `docs.archive`, `forge.autonomy.validate` | `os/core/` |
+| `forgeCoreModule` | `create`, `doctor`, `upgrade`, `forge.agents.generate`, `scaffold`, `port.scaffold`, `skill.validate`, `skill.list`, `port.validate`, `profile.validate`, `dev`, `build`, `validate`, `pinned.validate`, `pinned.init`, `package.health`, `docs.archive`, `forge.autonomy.validate`, `forge.public-surface.validate` | `os/core/` |
 | `forgeRfcModule` | `rfc.list`, `rfc.validate`, `rfc.create`, `rfc.verification.emit`, `rfc.verification.refresh`, etc. | `os/rfc/` |
 | `forgeWorkflowModule` | `workflow.lint`, `workflow.list`, `workflow.amend.list` | `os/workflow/` |
 | `forgeNamingModule` | `naming.convention.lint` | `os/naming/` |
@@ -61,6 +61,7 @@ Skill packs MAY declare additional Compass contract blocks beyond the built-in `
 - **Add tool-generated/imported/historical dirs to `NAMING_CONVENTION_EXEMPT_DIRS`.** Directories containing tool-generated files (e.g. `docs/performance` with timestamp-based names), imported specification documents (e.g. `docs/specs` with `01-PBP-System-Specification.md`), and archived RFCs (e.g. `docs/rfcs/archive`) should be added to `NAMING_CONVENTION_EXEMPT_DIRS` in `os/naming/naming-convention.ts` to avoid false-positive kebab-case violations on files whose naming is controlled by external tools or conventions.
 - **Use `%s` not `%B` for git log delimiter parsing.** When parsing `git log --format` output with `\x1f`-delimited fields, use `%s` (subject only) instead of `%B` (full body). `%B` includes newlines which break the per-line `split("\x1f")` parsing, causing all entries to be silently skipped. Discovered during RFC-1053 `metrics-rfc.ts` implementation.
 - **Chicken-and-egg with self-referential acceptance probes.** When an RFC's acceptance probe checks for a file that is created by `rfc.implement.stamp` itself (e.g. `docs/metrics/rfcs/<rfc-id>.metrics.yaml`), `rfc.verification.emit` will always report "fail" before stamping because the file doesn't exist yet. Solution: generate the file manually first (e.g. via a node script calling the generator function), re-emit evidence, then stamp. The stamp's `RFC-IMP-06` check requires evidence to be "pass" before proceeding. Discovered during RFC-1053 stamping.
+- **AC evidence annotations must be bare file paths without em-dash suffixes.** `rfc.validate` (V-27) requires `(evidence: <file:line>)` or `(evidence: test: <path>)` annotations. The evidence parser treats everything after the prefix as a literal file path — adding descriptive text after an em-dash (e.g. `(evidence: test: packages/forge/src/tests/public-surface.test.ts — SURFACE-02 tests)`) causes "evidence references a file that does not exist" errors. Keep evidence annotations to `evidence: file: <path>` or `evidence: test: <path>` only. Discovered during RFC-1080 stamping.
 
 ## Program packet control plane (RFC-0856)
 

package/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+All notable changes to `@warpgogol/forge` are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+For the full commit history, see the [GitHub releases page](https://github.com/syrokomskyi/forge/releases).
+
+## [4.1.6] — 2026-09-12
+
+### Changed
+
+- Rewritten README with new positioning: "AI can write the code. Forge keeps the project engineered."
+- Restructured documentation into `docs/` with concepts, guides, reference, and maintainers sections (RFC-1080)
+- Updated `package.json` description and keywords to reflect repository-native governance positioning
+
+### Added
+
+- `docs/` directory with 13 documentation files
+- `CONTRIBUTING.md` — contributor guide
+- `SECURITY.md` — security policy
+- `CHANGELOG.md` — this file
+- `forge public-surface.validate` command — consistency check for README/package.json alignment
+
+### Fixed
+
+- Removed "dependency-free" claim from README (package has runtime dependencies: `yaml`, `zod`, `ajv`, `picomatch`, `trash`, `@aws-sdk/client-s3`)
+- Removed Node.js v22.x references from README (package requires `>=24 <25`)
+- Removed contradictory "No programming, no terminal, no commands" claim
+
+### Removed
+
+- Deleted stale `warpgogol-forge-2.15.0.tgz` from package root

package/CONTRIBUTING.md

@@ -0,0 +1,36 @@
+# Contributing to @warpgogol/forge
+
+Forge is developed in the [warpgogol/werkstatt](https://github.com/syrokomskyi/werkstatt) monorepo. The standalone [syrokomskyi/forge](https://github.com/syrokomskyi/forge) repo is auto-generated by `repo-extract` — do not open PRs there.
+
+## Development setup
+
+```sh
+git clone https://github.com/syrokomskyi/werkstatt.git
+cd werkstatt
+pnpm install
+```
+
+## Project structure
+
+- `packages/forge/src/` — portable core (no `@warpgogol/*` imports)
+- `packages/forge/os/` — ForgeModule registrations and command handlers
+- `packages/forge/bin/` — CLI entrypoint
+- `packages/forge/skills/` — skill definitions
+- `packages/forge/profiles/` — stack profiles
+
+## Making changes
+
+1. Create an RFC for architectural changes (`forge rfc.create`)
+2. Implement the change
+3. Add or update tests
+4. Run `pnpm exec forge doctor` and `pnpm exec forge rfc.validate`
+5. Run `pnpm run build:check` for type checking
+6. Commit via `ecosystem.commit`
+
+## Publishing
+
+Publishing is automated via `repo-extract` + GitHub Actions CI. See [docs/maintainers/publishing.md](docs/maintainers/publishing.md).
+
+## License
+
+Apache-2.0. By contributing, you agree that your contributions are licensed under the same license.