elementary-assertions 1.0.1 → 1.0.2

package/CHANGELOG.md

@@ -3,13 +3,51 @@
 ## Unreleased
 
 ### Added
-- package-contract lock for MIT licensing and packaged `LICENSE` file.
-- `v1.0.0` metadata-flip release-gate evidence recorded in TODO (tests, pack dry-run, clean-install smoke roots).
+- (none)
 
 ### Changed
-- `docs/NPM_RELEASE.md` now defines both pre-`1.0.0` Git-tag installs and `1.0.0+` npmjs publication steps.
-- `TODO.md` now includes Phase 17 (`1.0.0` publication readiness).
-- package metadata moved to `version: 1.0.0` with `"private": false` for npmjs publication readiness.
+- (none)
+
+## v1.0.2 - 2026-02-15
+
+### Added
+- `.editorconfig` for repository-wide LF/indent/newline consistency.
+- `CONTRIBUTING.md` and `SECURITY.md` repository policy documents.
+- `scripts/ensure-clean-worktree.js` plus release-check npm scripts for safer local release gating.
+- `.github/workflows/release.yml` manual release-check workflow with optional npm publish gate.
+- `scripts/smoke-release.js` and `npm run smoke:release` for local tarball-based smoke execution.
+- baseline lint setup (`.eslintrc.cjs`, `npm run lint`, ESLint dev dependency).
+- package engine floor metadata (`"engines": { "node": ">=24.0.0" }`) plus contract test coverage.
+- additional governance/quality docs: `docs/GUARANTEES.md`, `docs/BASELINE_TEST_RUN.md`, `docs/STATUSQUO.md`.
+
+### Changed
+- CI install step now uses `npm ci` for deterministic dependency installation.
+- `README.md` documentation index now links `CONTRIBUTING.md` and `SECURITY.md`.
+- Release/workflow docs now reference local smoke helper and optional CI-assisted release checks.
+- `npm run ci:check` now includes lint before test/report/pack checks.
+- CI workflow now uses concurrency cancellation, npm cache, and explicit lint gate.
+- `README.md`, `CONTRIBUTING.md`, `docs/NPM_RELEASE.md`, and `docs/REPO_WORKFLOWS.md` now align on Node.js `>=24`.
+- `README.md` documentation index now includes guarantees, baseline-test, and status snapshot docs.
+
+## v1.0.1 - 2026-02-15
+
+### Added
+- First npmjs publication of `elementary-assertions`.
+- Phase 17 publication evidence recorded in `TODO.md` (npmjs version/dist-tag checks and publish timestamp).
+
+### Changed
+- Publish-safe manifest normalization applied for CLI bin path format (`bin/elementary-assertions.js` without `./`) before npmjs publication.
+- Release discipline preserved: `v1.0.0` tag kept intact; publish fix shipped as patch `v1.0.1`.
+
+### Release Evidence
+- Release commit: `b1883933e29132c4c0bc11818a921db053facda2`
+- Tag: `v1.0.1`
+- npmjs verification:
+  - `npm view elementary-assertions version` -> `1.0.1`
+  - `npm view elementary-assertions dist-tags.latest` -> `1.0.1`
+- Smoke roots:
+  - `C:\code\elementary-assertions-smoke-test\v1.0.1-git-smoke-20260215-174021`
+  - `C:\code\elementary-assertions-smoke-test\v1.0.1-npmjs-smoke-20260215-174021`
 
 ## v0.1.12 - 2026-02-15
 

package/README.md

@@ -18,6 +18,11 @@ The library is conservative by design:
 
 Its authoritative boundary ends at elementary assertions. Anything beyond this layer (concept models, norms, governance, domain interpretation) is explicitly downstream.
 
+## Requirements
+
+- Node.js `>=24`
+- npm
+
 ## What this package is
 
 elementary-assertions is an assertion compiler that sits directly after linguistic relation extraction.
@@ -203,8 +208,13 @@ For non-public developer quality tooling (`npm run dev:*`), see `docs/DEV_TOOLIN
 - Repository workflow policies: `docs/REPO_WORKFLOWS.md`
 - Release flow: `docs/NPM_RELEASE.md`
 - Developer tooling (non-public): `docs/DEV_TOOLING.md`
+- Guarantees: `docs/GUARANTEES.md`
+- Baseline test run: `docs/BASELINE_TEST_RUN.md`
+- Status snapshot guide: `docs/STATUSQUO.md`
 - Release notes template: `docs/RELEASE_NOTES_TEMPLATE.md`
 - Changelog: `CHANGELOG.md`
+- Contributing guide: `CONTRIBUTING.md`
+- Security policy: `SECURITY.md`
 
 ## License
 

package/SECURITY.md

@@ -0,0 +1,19 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+Report vulnerabilities privately via GitHub Security Advisories for this repository.
+
+Include:
+- affected version
+- reproduction steps
+- expected vs actual behavior
+- potential impact
+
+## Scope
+
+Security-relevant issues include:
+- input-validation bypasses
+- unintended data exposure in logs or responses
+- authn/authz bypasses (if present in your project)
+- dependency or supply-chain risks in release flow

package/docs/BASELINE_TEST_RUN.md

@@ -0,0 +1,33 @@
+# Baseline Test Run
+
+Purpose: define a stable end-to-end verification baseline, even where external dependencies can vary.
+
+## Verify Stable Invariants
+
+- CLI/API wiring works end-to-end.
+- State-changing commands persist expected changes.
+- Rejected/no-op paths do not mutate persisted state.
+- Required output envelope fields are present.
+- Exit codes follow contract (`0` success, non-zero failure).
+
+## Do Not Over-Constrain External Surfaces
+
+Avoid hard-locking:
+- exact wording of externally influenced text
+- full byte-identical outputs from unstable external services
+- incidental ordering not declared as part of contract
+
+## Recommended Baseline Strategy
+
+1. Define fixture(s).
+2. Run command sequence.
+3. Assert invariant checkpoints.
+4. Capture result summary (counts/flags/hashes) instead of fragile full-output strings.
+5. Keep one deterministic smoke path in CI (`npm run smoke:release` + release smoke checks).
+
+## Suggested Run Checklist
+
+- `npm run lint`
+- `npm test`
+- `npm run pack:check`
+- `npm run smoke:release`

package/docs/GUARANTEES.md

@@ -0,0 +1,28 @@
+# Guarantees
+
+This file defines core behavior guarantees for `elementary-assertions`.
+
+## Core Guarantees
+
+- Deterministic behavior:
+  - identical input + options produce identical output within the same version, under documented determinism scope.
+- Fail-fast validation:
+  - malformed input is rejected explicitly.
+- Clear authority boundary:
+  - persisted output is authoritative.
+  - view/tooling outputs are derived and non-authoritative.
+- Stable error surface:
+  - validation failures use stable error codes for consumer branching.
+
+## Non-Goals
+
+`elementary-assertions` does not implicitly provide:
+- hidden retries
+- silent auto-repair of invalid input
+- implicit mutation of persisted state from read-only commands
+- undocumented public API surfaces
+
+## Design Rule
+
+Prefer small, explicit mechanics over broad abstractions.
+If behavior is important, make it contract-tested.

package/docs/NPM_RELEASE.md

@@ -2,8 +2,7 @@
 
 This document defines the release flow for `elementary-assertions`.
 
-Current distribution status (until npmjs publish is executed): consumers install as a Git dependency pinned to a tag (or commit).
-After npmjs publication: publish to npmjs while keeping Git-tag installs supported.
+Current distribution status: published to npmjs; Git-tag installs remain supported.
 `files` is used to keep both Git installs and npm tarballs deterministic.
 
 Examples (consumer `package.json`):
@@ -31,11 +30,12 @@ Golden baseline freeze metadata is maintained in `test/artifacts/README.md`.
 - `package.json` `files` is the primary packlist control.
 - `.npmignore` is an additional safeguard for local non-package files.
 
-## 0) Preconditions
-
-- Working tree clean.
-- `npm test` passes.
-- If `runElementaryAssertions` is used in smoke tests, ensure any required `wikipedia-title-index` endpoint is reachable.
+## 0) Preconditions
+
+- Working tree clean.
+- Node.js `>=24`.
+- `npm test` passes.
+- If `runElementaryAssertions` is used in smoke tests, ensure any required `wikipedia-title-index` endpoint is reachable.
 
 ## 1) Prepare release branch
 
@@ -81,7 +81,7 @@ Cleanup after local pack steps:
 Remove-Item -Force .\elementary-assertions-*.tgz
 ```
 
-## 5) Smoke install checks (pre-tag)
+## 5) Smoke install checks (pre-tag, Git install path)
 
 Create a clean workspace and install from the commit hash you intend to tag.
 Use the shared smoke script so API/CLI checks and render parity are enforced together.
@@ -137,7 +137,7 @@ git tag -a vX.Y.Z -m "vX.Y.Z"
 git push origin vX.Y.Z
 ```
 
-## 8) Post-tag verification (install from tag)
+## 8) Post-tag verification (install from tag, Git path)
 
 ```powershell
 $SmokeRoot = "C:\code\elementary-assertions-smoke-test\vX.Y.Z-posttag-smoke-$(Get-Date -Format yyyyMMdd-HHmmss)"
@@ -164,7 +164,22 @@ npm view elementary-assertions version
 npm view elementary-assertions dist-tags.latest
 ```
 
-- Run a clean-install smoke check from npmjs package after publish (same smoke-root naming convention).
+- For every newly published release, run a clean-install smoke check from npmjs package (same smoke-root naming convention):
+
+```powershell
+$SmokeRoot = "C:\code\elementary-assertions-smoke-test\vX.Y.Z-npmjs-smoke-$(Get-Date -Format yyyyMMdd-HHmmss)"
+New-Item -ItemType Directory -Path $SmokeRoot -Force | Out-Null
+Set-Location $SmokeRoot
+npm init -y | Out-Null
+
+npm i elementary-assertions@X.Y.Z
+node C:\code\elementary-assertions\scripts\release-smoke-check.js --repo-root C:\code\elementary-assertions --smoke-root $SmokeRoot --out-root (Join-Path $SmokeRoot "rendered")
+npm ls elementary-assertions
+```
+
+- Mandatory release evidence for each published version:
+  - one Git-install smoke root (`vX.Y.Z-git-smoke-*`)
+  - one npmjs-install smoke root (`vX.Y.Z-npmjs-smoke-*`)
 
 ## Failure rule
 
@@ -175,3 +190,11 @@ Ship a new patch version with a new tag.
 
 Create/update release notes using:
 - `docs/RELEASE_NOTES_TEMPLATE.md`
+
+## Optional CI-assisted release check
+
+The repository also provides a manual GitHub Actions workflow:
+
+- `.github/workflows/release.yml`
+
+It validates tag format/ancestry, runs quality gates, verifies package version vs tag, runs release smoke, and can optionally publish to npmjs when `publish_to_npm=true` and `NPM_TOKEN` is configured.

package/docs/REPO_WORKFLOWS.md

@@ -36,7 +36,8 @@ This benchmark is advisory for repo workflow only (trend watching) and is not a
 ## CI gates (repo workflow)
 
 Current CI workflow gates on:
-- `npm install`
+- `npm ci`
+- `npm run lint`
 - `npm test`
 - dev report script execution:
   - `npm run dev:report:metrics`
@@ -46,3 +47,23 @@ Current CI workflow gates on:
 - packed-tarball clean-install smoke check via `scripts/release-smoke-check.js`
 
 These are repository quality gates and release hygiene checks, not package runtime contract.
+
+## Local release preflight (repo workflow)
+
+Run local preflight checks before tagging:
+
+```powershell
+npm run release:check
+```
+
+This command enforces:
+- clean git worktree (`scripts/ensure-clean-worktree.js`)
+- repository quality gates via `npm run ci:check`
+
+Optional local smoke helper:
+
+```powershell
+npm run smoke:release
+```
+
+This creates a temporary local smoke workspace under `test/_smoke/`, installs from a packed tarball, and runs `scripts/release-smoke-check.js`.

package/docs/STATUSQUO.md

@@ -0,0 +1,21 @@
+# Status Quo
+
+Use this file as a concise operational snapshot of repository state.
+
+Update it when significant milestones are reached.
+
+Suggested structure:
+
+- Repo status:
+  - branch and sync state
+  - major pending workstreams
+- Runtime status:
+  - key commands currently working
+  - known setup constraints
+- Quality status:
+  - latest local check results (for example: `npm run ci:check`)
+  - known flaky areas (if any)
+- Documentation status:
+  - docs updated in the latest cycle
+
+Keep this file factual and short.

package/package.json

@@ -1,7 +1,27 @@
 {
   "name": "elementary-assertions",
-  "version": "1.0.1",
+  "version": "1.0.2",
+  "description": "Deterministic, auditable assertion-construction layer for Node.js.",
+  "keywords": [
+    "nlp",
+    "assertions",
+    "determinism",
+    "linguistics",
+    "validation"
+  ],
+  "author": "svenschaefer",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/svenschaefer/elementary-assertions.git"
+  },
+  "bugs": {
+    "url": "https://github.com/svenschaefer/elementary-assertions/issues"
+  },
+  "homepage": "https://github.com/svenschaefer/elementary-assertions#readme",
   "license": "MIT",
+  "engines": {
+    "node": ">=24.0.0"
+  },
   "private": false,
   "type": "commonjs",
   "main": "./src/index.js",
@@ -21,12 +41,18 @@
     "docs/",
     "README.md",
     "CHANGELOG.md",
-    "LICENSE"
+    "LICENSE",
+    "SECURITY.md"
   ],
   "scripts": {
+    "lint": "eslint src bin test scripts",
     "test": "node --test \"test/**/*.test.js\"",
     "test:unit": "node --test \"test/unit/**/*.test.js\"",
     "test:integration": "node --test \"test/integration/**/*.test.js\"",
+    "pack:check": "npm pack --dry-run",
+    "smoke:release": "node scripts/smoke-release.js",
+    "ci:check": "npm run lint && npm test && npm run dev:report:metrics && npm run dev:report:hotspots && npm run dev:report:maturity && npm run pack:check",
+    "release:check": "node scripts/ensure-clean-worktree.js && npm run ci:check",
     "benchmark:core": "node scripts/benchmark-run-from-relations.js",
     "dev:check": "node scripts/dev-check.js",
     "dev:report:metrics": "node scripts/dev-report-metrics.js",
@@ -42,5 +68,8 @@
     "ajv-formats": "^3.0.1",
     "js-yaml": "^4.1.1",
     "linguistic-enricher": "1.1.35"
+  },
+  "devDependencies": {
+    "eslint": "^8.57.0"
   }
 }