From ac361a0b2338ea6c4060c8bb894582a963437e49 Mon Sep 17 00:00:00 2001 From: Kristopher Cargile Date: Mon, 12 Oct 2026 06:18:30 -0600 Subject: [PATCH 01/14] intro commit-signing.md (#5) Signed-off-by: Kristopher Cargile --- docs/TOC.md | 1 + docs/ops/README.md | 7 +- docs/ops/commit-signing.md | 135 +++++++++++++++++++++++++++++++++++++ 3 files changed, 139 insertions(+), 4 deletions(-) create mode 100644 docs/ops/commit-signing.md diff --git a/docs/TOC.md b/docs/TOC.md index 8ae2fbf..437d709 100644 --- a/docs/TOC.md +++ b/docs/TOC.md @@ -21,6 +21,7 @@ Canonical entry point for OEI Core documentation. Update this file whenever a do ## Operations - [Operations guide](./ops/README.md) +- [Commit signing (DCO + cryptographic signatures)](./ops/commit-signing.md) ## Registry diff --git a/docs/ops/README.md b/docs/ops/README.md index d2a6b78..9c4cf66 100644 --- a/docs/ops/README.md +++ b/docs/ops/README.md @@ -12,10 +12,9 @@ Decisions about operational approach belong in `adr/`. ## Contents -| Document | Purpose | -| -------- | ------- | - -No operational documents are currently tracked here. +| Document | Purpose | +| ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | +| [Commit signing (DCO + cryptographic signatures)](./commit-signing.md) | Explains OEI's two independent commit checks, setup for signing, and remediation/troubleshooting steps. | ## Authorship diff --git a/docs/ops/commit-signing.md b/docs/ops/commit-signing.md new file mode 100644 index 0000000..65f4541 --- /dev/null +++ b/docs/ops/commit-signing.md @@ -0,0 +1,135 @@ +# Commit Signing (DCO + Cryptographic Signatures) + +## Why this exists + +OEI repositories enforce two independent, unrelated checks on every commit: +a **DCO sign-off** and a **cryptographic signature**. Their git flags look +almost identical (`-s` vs `-S`), which makes them easy to conflate, but +satisfying one does nothing for the other. This doc exists because that +confusion cost real troubleshooting time during OEI repository bootstrap +work and will cost it again for anyone who hits it cold. + +## The two mechanisms + +| | DCO Sign-off | Cryptographic Signature | +| ------------------- | ---------------------------------------------------------------------- | ---------------------------------------------------- | +| **Proves** | You have the right to contribute this code under the project's license | This commit genuinely came from you, unaltered | +| **Mechanism** | A `Signed-off-by:` trailer in the commit message (plain text) | A GPG or SSH signature embedded in the commit object | +| **Flag** | `git commit -s` | `git commit -S` | +| **Enforced by** | The DCO GitHub App, as a required status check | The repo's branch ruleset ("Require signatures") | +| **Checked against** | Nothing, it is just text in the message | A signing key registered to your GitHub account | + +Both at once: `git commit -S -s`, or set `commit.gpgsign true` globally and +always pass `-s` explicitly (sign-off is never automatic, even with +`gpgsign` on). + +## One-time setup: cryptographic signing + +SSH-based signing is simpler than GPG if you do not already have a GPG key +you use for this. + +1. Generate a key if you do not already have one you want to use: + +```sh +ssh-keygen -t ed25519 -C "your-email@example.com" -f ~/.ssh/git_signing_key +``` + +2. On GitHub: **Settings -> SSH and GPG keys -> New SSH key**. Set **Key + type: Signing Key**, not Authentication Key. This is the single most + common failure point: an SSH key already added for authentication + (cloning, pushing) is a separate registration from one GitHub trusts + for signature verification, even when it is the same key file. Adding + it once as an auth key does not cover this; it has to be added again, + explicitly as a signing key. +3. Configure git to use it: + +```sh +git config --global gpg.format ssh +git config --global user.signingkey ~/.ssh/git_signing_key.pub +git config --global commit.gpgsign true +``` + +4. Optional, for local verification only. Set up an allowed signers file so + `git log --show-signature` can actually check things locally instead of + erroring: + +```sh +mkdir -p ~/.config/git +echo "your-email@example.com $(cat ~/.ssh/git_signing_key.pub)" >> ~/.config/git/allowed_signers +git config --global gpg.ssh.allowedSignersFile ~/.config/git/allowed_signers +``` + +Step 4 is not required for GitHub to accept your signed commits. GitHub +verifies independently against keys registered on your account. It only +affects whether your own local `git log` can confirm a signature. + +## Fixing commits that are missing one or both + +If you already committed without sign-off and/or signature, the fix is a +rebase, not individual amends: rewrite the range, then force-push. + +**Add DCO sign-off to existing commits:** + +```sh +git rebase --signoff --gpg-sign origin/develop +git push --force-with-lease origin +``` + +`--signoff` during a rebase is idempotent. Commits that already have a +correct `Signed-off-by:` trailer are left unchanged, so this is safe across +a whole branch. + +**Add cryptographic signatures to existing commits** (safe to run even on +commits that already have correct sign-off; this only touches signatures): + +```sh +git rebase --root --exec "git commit --amend --no-edit -S" +git push --force-with-lease origin +``` + +Both can be combined in one amend if doing both at once from scratch: +`git commit --amend --no-edit -S -s`. + +Before rewriting history on a shared or already-merged branch, confirm +nobody else has work based on the commits you are about to rewrite, and +that nothing (release tags, published provenance attestations) is already +pointing at SHAs you are changing. A `--root` rebase touches everything. + +## Troubleshooting + +**`git log --show-signature` says "No signature" but you are sure you +signed it.** +Check the raw commit object before trusting that message: + +```sh +git cat-file commit HEAD | head -5 +``` + +If you see a `gpgsig` line, the commit is signed. The "No signature" output +is a local verification failure, usually because +`gpg.ssh.allowedSignersFile` is not configured (setup step 4). This does +not mean GitHub will reject the push. + +**Push rejected: "Commits must have verified signatures."** +First confirm this is the signature check and not the DCO check. They fail +with different check names/messages (`DCO / DCO` vs ruleset signature +violation). If it is the signature check: + +1. Confirm local config: `git config --get commit.gpgsign`, + `git config --get gpg.format`, and `git config --get user.signingkey` + should all return values, and the signing key path should exist. +2. Confirm via `git cat-file` (above) that commits contain a `gpgsig` line. +3. If both are true, the likely cause is key registration on GitHub as + Authentication only, not Signing. Re-add the same key with key type + Signing Key. + +**Push rejected: `DCO / DCO` check listing commit hashes.** +That is the sign-off check, unrelated to cryptographic signatures. Those +commits are missing `Signed-off-by:` trailers. Fix with the `--signoff` +rebase above. + +## Common mistake + +Running `git commit -s` when a push is rejected for "Commits must have +verified signatures." This fixes nothing because `-s` only affects DCO +sign-off. Read the exact failing check before choosing a fix. From f3bbfa7802e13cf3e45cb0cb86be56fa8f1a6bda Mon Sep 17 00:00:00 2001 From: Kristopher Cargile Date: Tue, 20 Oct 2026 04:53:11 -0600 Subject: [PATCH 02/14] Update settings and README for improved configuration and clarity Signed-off-by: Kristopher Cargile --- .vscode/settings.json | 6 ++++-- README.md | 40 +++++++++++++++++++--------------------- 2 files changed, 23 insertions(+), 23 deletions(-) diff --git a/.vscode/settings.json b/.vscode/settings.json index d447689..b758315 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -40,11 +40,12 @@ "agentic", "Algorythmic", "Cargile", + "grouprunfinder", "openendurance", "protip", "redocly", - "untriaged", "ulidx", + "untriaged", "upvote" ], "psi-header.config": { @@ -95,6 +96,7 @@ "https://json.schemastore.org/": true, "https://json-schema.org/": true, "https://developer.microsoft.com/json-schemas/": true, - "https://docs.renovatebot.com/renovate-schema.json": true + "https://docs.renovatebot.com/renovate-schema.json": true, + "https://unpkg.com/@changesets": true } } diff --git a/README.md b/README.md index 59fc59c..8c3b8ea 100644 --- a/README.md +++ b/README.md @@ -17,29 +17,27 @@ Early / pre-release. APIs will change without notice until version `1.0` is ship OEI Core is a monorepo of independently publishable npm packages. It contains the shared substrate that OEI products build on, not product-specific logic. - - -| Package | Description | -|---|---| -| [`@openendurance/core`](packages/core) | Domain models and other common utilities. | -| [`@openendurance/core-validation`](packages/core-validation) | Validation logic. | +| Package | Description | +| ------------------------------------------------------------ | ----------------------------------------- | +| [`@openendurance/core`](packages/core) | Domain models and other common utilities. | +| [`@openendurance/core-validation`](packages/core-validation) | Validation logic. | ## Repository Layout -| Path | Purpose | -|---|---| -| [`packages/`](packages) | Independently publishable npm packages — the actual platform-layer code. | -| [`apps/`](apps) | Deployable applications built on the packages in this repo. | -| [`docs/`](docs) | Project knowledge base. | -| [`docs/adr/`](docs/adr) | Architecture decision records. | -| [`docs/arch/`](docs/arch) | Architecture and system-design documentation. | -| [`docs/ops/`](docs/ops) | Operational standards and procedures. | -| [`docs/registry/`](docs/registry) | Reference registries (schemas, service catalogs, etc.). | -| [`docs/generated/`](docs/generated) | Generated documentation artifacts — do not hand-edit. | -| [`fixtures/`](fixtures) | Shared test fixtures used across packages. | -| [`scripts/`](scripts) | Repo-level tooling and automation scripts. | -| [`.devcontainer/`](.devcontainer) | Devcontainer definition for a consistent local/cloud dev environment. | -| [`.github/`](.github) | CI/CD workflows and repository automation. | +| Path | Purpose | +| ----------------------------------- | ------------------------------------------------------------------------ | +| [`packages/`](packages) | Independently publishable npm packages — the actual platform-layer code. | +| [`apps/`](apps) | Deployable applications built on the packages in this repo. | +| [`docs/`](docs) | Project knowledge base. | +| [`docs/adr/`](docs/adr) | Architecture decision records. | +| [`docs/arch/`](docs/arch) | Architecture and system-design documentation. | +| [`docs/ops/`](docs/ops) | Operational standards and procedures. | +| [`docs/registry/`](docs/registry) | Reference registries (schemas, service catalogs, etc.). | +| [`docs/generated/`](docs/generated) | Generated documentation artifacts — do not hand-edit. | +| [`fixtures/`](fixtures) | Shared test fixtures used across packages. | +| [`scripts/`](scripts) | Repo-level tooling and automation scripts. | +| [`.devcontainer/`](.devcontainer) | Devcontainer definition for a consistent local/cloud dev environment. | +| [`.github/`](.github) | CI/CD workflows and repository automation. | ## Why this Exists @@ -93,7 +91,7 @@ SPDX-License-Identifier: Apache-2.0 ---
- Made with ⛰️💙 in Colorado USA + Made with 💙 in Colorado, USA

From de7aa1a85b8c048092a090e64ef8744a5532fc1b Mon Sep 17 00:00:00 2001 From: Kristopher Cargile Date: Tue, 20 Oct 2026 05:13:34 -0600 Subject: [PATCH 03/14] Add Core Publish Readiness Registry and update TOC Signed-off-by: Kristopher Cargile --- docs/TOC.md | 1 + docs/registry/README.md | 7 ++-- .../core-publish-readiness-registry.md | 40 +++++++++++++++++++ 3 files changed, 45 insertions(+), 3 deletions(-) create mode 100644 docs/registry/core-publish-readiness-registry.md diff --git a/docs/TOC.md b/docs/TOC.md index 437d709..82bec44 100644 --- a/docs/TOC.md +++ b/docs/TOC.md @@ -26,6 +26,7 @@ Canonical entry point for OEI Core documentation. Update this file whenever a do ## Registry - [Registry guide](./registry/README.md) +- [Core publish readiness registry](./registry/core-publish-readiness-registry.md) ## Wiki diff --git a/docs/registry/README.md b/docs/registry/README.md index 328dbf2..b7a1784 100644 --- a/docs/registry/README.md +++ b/docs/registry/README.md @@ -12,10 +12,11 @@ Generated output belongs in `generated/`. ## Contents -| Document | Purpose | -| -------- | ------- | +| Document | Purpose | +| ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | +| [Core publish readiness registry](./core-publish-readiness-registry.md) | Tracks in-progress work to bring `core` to publish-ready parity with `config-dev` and `config-ort`. | -No registries are currently tracked here. +Additional registries may be added as new tracked concerns emerge. ## Authorship diff --git a/docs/registry/core-publish-readiness-registry.md b/docs/registry/core-publish-readiness-registry.md new file mode 100644 index 0000000..8451a15 --- /dev/null +++ b/docs/registry/core-publish-readiness-registry.md @@ -0,0 +1,40 @@ +# Core Publish Readiness Registry + +Tracks publish-readiness work required to bring OEI Core to the same baseline used by `config-dev` and `config-ort`. + +## Scope + +- Repository: `core` +- Baseline references: `config-dev`, `config-ort` +- Initial source: user-provided checklist on 2026-10-20 + +## Status Legend + +- `Not Audited`: listed but not yet verified in-repo +- `Needs Work`: verified and currently incomplete or incorrect +- `Looks Complete`: verified and appears complete (spot-check only) +- `Blocked`: cannot verify without external context or permissions + +## Workstream Tracker + +| ID | Workstream | Requested Check | Status | Evidence | Notes | +| ------ | ---------------------- | ---------------------------------------------------------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | +| CR-001 | Governance docs | AGENTS.md completion | Needs Work | `AGENTS.md` contains only placeholder text. | Replace with full repository guidance aligned to current standards. | +| CR-002 | Linting | Biome configuration correctness | Needs Work | `biome.json` lacks canonical excludes for build artifacts (`dist`, `coverage`, `*.tsbuildinfo`). | Align file-scoping and ignore behavior with `config-dev` baseline. | +| CR-003 | TypeScript | Root tsconfig correctness and npm-based shared config usage | Needs Work | `tsconfig.json` is fully local and does not extend `@openendurance/config-typescript/*`. | Refactor to extend published npm preset and keep only local overrides. | +| CR-004 | Formatting | Prettier and Jest shared config usage from npm packages | Needs Work | No `.prettierrc*` or `prettier.config.*`; no `jest.config.*`; no `@openendurance/config-prettier` / `@openendurance/config-jest` usage. | Add shared-config consumption and package dependencies where required. | +| CR-005 | Lint workflow | Split scanning between Biome and Prettier | Needs Work | Split exists (`lint:prettier` + Biome paths), but root lint wiring differs from `config-dev` canonical shape. | Standardize root lint commands and keep markdown/yaml under Prettier checks. | +| CR-006 | Packaging and release | npm publishing setup, provenance, packaged `/dist`, workflows | Needs Work | No `.github/workflows/ci.yml` or release workflow; `packages/core/package.json` is `private: true` and has no `publishConfig.provenance`. | Add CI/release workflows, publishing metadata, and first-release bootstrap plan. | +| CR-007 | Dependency maintenance | Renovate configuration quality spot-check | Needs Work | `renovate.json` is close, but includes stale package match (`@types/lodash`) not present in repo. | Prune stale rules and validate grouping/automerge intent against current deps. | +| CR-008 | Task orchestration | Turbo configuration spot-check at root and package levels | Needs Work | Root `turbo.json` includes boundaries/tags not reflected in package tags; package tag is `core`. | Reconcile boundary taxonomy and task model to intended enforcement. | +| CR-009 | Package metadata | package.json completeness per package and root | Needs Work | `packages/core-validation` has no `package.json`; `packages/core/package.json` is not publish-ready (`private`, `UNLICENSED`, missing publish settings). | Finalize publishable metadata for each package and align root/package responsibilities. | +| CR-010 | Documentation | Root README and package README completeness | Needs Work | Root `README.md` includes incorrect badge/repo references (`openendurance/fkt`) and links to missing files; package READMEs are empty. | Correct root links/badges and add package-level install/usage documentation. | +| CR-011 | Agent guidance | Add `.github/copilot-instructions.md` synthesized from AGENTS guidance | Needs Work | `.github/copilot-instructions.md` is missing. | Create concise instruction file derived from finalized AGENTS guidance. | +| CR-012 | Ownership model | CODEOWNERS granularity using org groups | Needs Work | `CODEOWNERS` has only a single wildcard owner mapping. | Replace with layered, path-specific ownership model similar to `config-dev`. | + +## Audit Log + +| Date | Change | Author | +| ---------- | -------------------------------------------------------------------------------------------- | ------- | +| 2026-10-20 | Initialized registry from user-provided readiness list. | Copilot | +| 2026-10-20 | Completed audit of listed checklist items; all items remain open and require follow-up work. | Copilot | From ff5b424eddf58ee14ed8d3439fb5fd36acce79cb Mon Sep 17 00:00:00 2001 From: Kristopher Cargile Date: Tue, 20 Oct 2026 05:17:32 -0600 Subject: [PATCH 04/14] Add CI workflow configuration for pull requests and pushes (#6) * Add CI workflow configuration for pull requests and pushes Signed-off-by: Kristopher Cargile * Update concurrency group for CI workflow Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: Kristopher Cargile * Modify lint task fallback in CI workflow Update lint task fallback to use dynamic SHA based on event. Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: Kristopher Cargile --------- Signed-off-by: Kristopher Cargile Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: Kristopher Cargile --- .github/workflows/ci.yml | 94 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 94 insertions(+) create mode 100644 .github/workflows/ci.yml diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..ad18fdf --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,94 @@ +name: CI + +on: + pull_request: + branches: [main, develop, release/*, hotfix/*] + paths-ignore: + - "**/README.md" + - ".vscode/**" + - ".devcontainer/**" + - ".claude/**" + - ".husky/**" + - "scripts/*" + push: + branches: [main, develop, release/*, hotfix/*] + paths-ignore: + - "**/README.md" + - ".vscode/**" + - ".devcontainer/**" + - ".claude/**" + - ".husky/**" + - "docs/**" + - "scripts/*" + +permissions: + contents: read + +concurrency: + group: ci-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }} + cancel-in-progress: ${{ github.event_name == 'pull_request' }} + +jobs: + ci: + runs-on: ubuntu-latest + if: ${{ github.actor != 'dependabot[bot]' }} + steps: + - name: Checkout + uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Setup pnpm + uses: pnpm/action-setup@v4 + with: + run_install: false + + - name: Setup Node + uses: actions/setup-node@v4 + with: + node-version: 24 + cache: pnpm + + - name: Determine whether CI tasks are affected + id: turbo_ignore + shell: bash + run: | + set +e + pnpm dlx turbo-ignore --task=lint --fallback="${{ github.event_name == 'push' && github.event.before || github.event.pull_request.base.sha }}" + exit_code=$? + set -e + + if [ "$exit_code" -eq 0 ]; then + echo "run_ci=false" >> "$GITHUB_OUTPUT" + echo "No affected packages detected for lint task." + elif [ "$exit_code" -eq 1 ]; then + echo "run_ci=true" >> "$GITHUB_OUTPUT" + echo "Affected packages detected. Running CI checks." + else + echo "turbo-ignore failed unexpectedly (exit ${exit_code})." + exit "$exit_code" + fi + + - name: Install deps + if: steps.turbo_ignore.outputs.run_ci == 'true' + run: pnpm install --frozen-lockfile + + - name: Lint + if: steps.turbo_ignore.outputs.run_ci == 'true' + run: pnpm lint + + - name: Build + if: steps.turbo_ignore.outputs.run_ci == 'true' + run: pnpm build + + - name: Typecheck + if: steps.turbo_ignore.outputs.run_ci == 'true' + run: pnpm typecheck + + - name: Test + if: steps.turbo_ignore.outputs.run_ci == 'true' + run: pnpm test + + - name: Skipped summary + if: steps.turbo_ignore.outputs.run_ci == 'false' + run: echo "CI checks skipped because no relevant package changes were detected." From 868194dbf1f8578a2c9c391db3fc535e7e305810 Mon Sep 17 00:00:00 2001 From: Kristopher Cargile Date: Tue, 20 Oct 2026 05:25:51 -0600 Subject: [PATCH 05/14] Add tracking for license compliance CI and publish artifact hardening to readiness registry Signed-off-by: Kristopher Cargile --- .../core-publish-readiness-registry.md | 39 ++++++++++--------- 1 file changed, 21 insertions(+), 18 deletions(-) diff --git a/docs/registry/core-publish-readiness-registry.md b/docs/registry/core-publish-readiness-registry.md index 8451a15..eab8cbb 100644 --- a/docs/registry/core-publish-readiness-registry.md +++ b/docs/registry/core-publish-readiness-registry.md @@ -17,24 +17,27 @@ Tracks publish-readiness work required to bring OEI Core to the same baseline us ## Workstream Tracker -| ID | Workstream | Requested Check | Status | Evidence | Notes | -| ------ | ---------------------- | ---------------------------------------------------------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | -| CR-001 | Governance docs | AGENTS.md completion | Needs Work | `AGENTS.md` contains only placeholder text. | Replace with full repository guidance aligned to current standards. | -| CR-002 | Linting | Biome configuration correctness | Needs Work | `biome.json` lacks canonical excludes for build artifacts (`dist`, `coverage`, `*.tsbuildinfo`). | Align file-scoping and ignore behavior with `config-dev` baseline. | -| CR-003 | TypeScript | Root tsconfig correctness and npm-based shared config usage | Needs Work | `tsconfig.json` is fully local and does not extend `@openendurance/config-typescript/*`. | Refactor to extend published npm preset and keep only local overrides. | -| CR-004 | Formatting | Prettier and Jest shared config usage from npm packages | Needs Work | No `.prettierrc*` or `prettier.config.*`; no `jest.config.*`; no `@openendurance/config-prettier` / `@openendurance/config-jest` usage. | Add shared-config consumption and package dependencies where required. | -| CR-005 | Lint workflow | Split scanning between Biome and Prettier | Needs Work | Split exists (`lint:prettier` + Biome paths), but root lint wiring differs from `config-dev` canonical shape. | Standardize root lint commands and keep markdown/yaml under Prettier checks. | -| CR-006 | Packaging and release | npm publishing setup, provenance, packaged `/dist`, workflows | Needs Work | No `.github/workflows/ci.yml` or release workflow; `packages/core/package.json` is `private: true` and has no `publishConfig.provenance`. | Add CI/release workflows, publishing metadata, and first-release bootstrap plan. | -| CR-007 | Dependency maintenance | Renovate configuration quality spot-check | Needs Work | `renovate.json` is close, but includes stale package match (`@types/lodash`) not present in repo. | Prune stale rules and validate grouping/automerge intent against current deps. | -| CR-008 | Task orchestration | Turbo configuration spot-check at root and package levels | Needs Work | Root `turbo.json` includes boundaries/tags not reflected in package tags; package tag is `core`. | Reconcile boundary taxonomy and task model to intended enforcement. | -| CR-009 | Package metadata | package.json completeness per package and root | Needs Work | `packages/core-validation` has no `package.json`; `packages/core/package.json` is not publish-ready (`private`, `UNLICENSED`, missing publish settings). | Finalize publishable metadata for each package and align root/package responsibilities. | -| CR-010 | Documentation | Root README and package README completeness | Needs Work | Root `README.md` includes incorrect badge/repo references (`openendurance/fkt`) and links to missing files; package READMEs are empty. | Correct root links/badges and add package-level install/usage documentation. | -| CR-011 | Agent guidance | Add `.github/copilot-instructions.md` synthesized from AGENTS guidance | Needs Work | `.github/copilot-instructions.md` is missing. | Create concise instruction file derived from finalized AGENTS guidance. | -| CR-012 | Ownership model | CODEOWNERS granularity using org groups | Needs Work | `CODEOWNERS` has only a single wildcard owner mapping. | Replace with layered, path-specific ownership model similar to `config-dev`. | +| ID | Workstream | Requested Check | Status | Evidence | Notes | +| ------ | -------------------------- | ---------------------------------------------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | +| CR-001 | Governance docs | AGENTS.md completion | Needs Work | `AGENTS.md` contains only placeholder text. | Replace with full repository guidance aligned to current standards. | +| CR-002 | Linting | Biome configuration correctness | Needs Work | `biome.json` lacks canonical excludes for build artifacts (`dist`, `coverage`, `*.tsbuildinfo`). | Align file-scoping and ignore behavior with `config-dev` baseline. | +| CR-003 | TypeScript | Root tsconfig correctness and npm-based shared config usage | Needs Work | `tsconfig.json` is fully local and does not extend `@openendurance/config-typescript/*`. | Refactor to extend published npm preset and keep only local overrides. | +| CR-004 | Formatting | Prettier and Jest shared config usage from npm packages | Needs Work | No `.prettierrc*` or `prettier.config.*`; no `jest.config.*`; no `@openendurance/config-prettier` / `@openendurance/config-jest` usage. | Add shared-config consumption and package dependencies where required. | +| CR-005 | Lint workflow | Split scanning between Biome and Prettier | Needs Work | Split exists (`lint:prettier` + Biome paths), but root lint wiring differs from `config-dev` canonical shape. | Standardize root lint commands and keep markdown/yaml under Prettier checks. | +| CR-006 | Packaging and release | npm publishing setup, provenance, packaged `/dist`, workflows | Needs Work | `.github/workflows/ci.yml` now exists, but no release workflow is present; `packages/core/package.json` is `private: true` and has no `publishConfig.provenance`. | Add release workflow, publishing metadata, and first-release bootstrap plan. | +| CR-007 | Dependency maintenance | Renovate configuration quality spot-check | Needs Work | `renovate.json` is close, but includes stale package match (`@types/lodash`) not present in repo. | Prune stale rules and validate grouping/automerge intent against current deps. | +| CR-008 | Task orchestration | Turbo configuration spot-check at root and package levels | Needs Work | Root `turbo.json` includes boundaries/tags not reflected in package tags; package tag is `core`. | Reconcile boundary taxonomy and task model to intended enforcement. | +| CR-009 | Package metadata | package.json completeness per package and root | Needs Work | `packages/core-validation` has no `package.json`; `packages/core/package.json` is not publish-ready (`private`, `UNLICENSED`, missing publish settings). | Finalize publishable metadata for each package and align root/package responsibilities. | +| CR-010 | Documentation | Root README and package README completeness | Needs Work | Root `README.md` includes incorrect badge/repo references (`openendurance/fkt`) and links to missing files; package READMEs are empty. | Correct root links/badges and add package-level install/usage documentation. | +| CR-011 | Agent guidance | Add `.github/copilot-instructions.md` synthesized from AGENTS guidance | Needs Work | `.github/copilot-instructions.md` is missing. | Create concise instruction file derived from finalized AGENTS guidance. | +| CR-012 | Ownership model | CODEOWNERS granularity using org groups | Needs Work | `CODEOWNERS` has only a single wildcard owner mapping. | Replace with layered, path-specific ownership model similar to `config-dev`. | +| CR-013 | License compliance CI | Track migration of license scanning workflow to ORT-based checks | Needs Work | `.github/workflows/ci.yml` is present but no ORT/license-compliance workflow is defined in `.github/workflows/`. | Add explicit ORT license-compliance workflow and policy source pinning strategy. | +| CR-014 | Publish artifact hardening | Ensure `dist` package contents are deterministic and source-aligned | Needs Work | `packages/core/dist/` contains files not present in `packages/core/src/` (e.g., `oeiEntityMetadata.*`), indicating stale build output risk. | Add clean/prepack guardrails and verify publish artifact contract before first release. | ## Audit Log -| Date | Change | Author | -| ---------- | -------------------------------------------------------------------------------------------- | ------- | -| 2026-10-20 | Initialized registry from user-provided readiness list. | Copilot | -| 2026-10-20 | Completed audit of listed checklist items; all items remain open and require follow-up work. | Copilot | +| Date | Change | Author | +| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | +| 2026-10-20 | Initialized registry from user-provided readiness list. | Copilot | +| 2026-10-20 | Completed audit of listed checklist items; all items remain open and require follow-up work. | Copilot | +| 2026-10-20 | Added approved additional findings: ORT license-compliance workflow tracking and publish artifact hardening; excluded commit-history remediation tracking per operator direction. | Copilot | From 048cf5428a27ce3172c8461b48b192b1e1cc9397 Mon Sep 17 00:00:00 2001 From: Kristopher Cargile Date: Tue, 20 Oct 2026 05:36:04 -0600 Subject: [PATCH 06/14] Update AGENTS.md with comprehensive core-specific guidance and mark CR-001 as complete Signed-off-by: Kristopher Cargile --- AGENTS.md | 89 ++++++++++++++++++- .../core-publish-readiness-registry.md | 33 +++---- 2 files changed, 105 insertions(+), 17 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index adf3fce..ef70685 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,3 +1,90 @@ # AGENTS.md -This is the OEI Core project. +## What this repo is + +Shared foundational TypeScript libraries for Open Endurance Initiative (OEI) +products and platform services. + +This repository is a pnpm + Turborepo monorepo that contains publishable npm +packages used as platform-layer building blocks (domain primitives, shared +types, and validation contracts). It is not a single deployable application. + +This repo has high blast radius relative to its size. Changes to shared +packages can propagate into multiple OEI product repositories the next time +they update dependency ranges. + +## Package layout + +| Package | Purpose | +| -------------------------------- | ------------------------------------------------------------- | +| `@openendurance/core` | Core domain primitives and shared types used across products. | +| `@openendurance/core-validation` | Validation package surface. | + +Package source lives under `packages//src`. + +Package build output lives under `packages//dist` and is generated. +Do not treat `dist` as source of truth. + +## Documentation + +The `docs/` tree is the durable project knowledge base. + +- `docs/README.md` explains documentation conventions +- `docs/TOC.md` is the canonical documentation index +- `docs/adr/` stores immutable architecture decisions +- `docs/arch/` stores current-state architecture documentation +- `docs/ops/` stores operational runbooks and procedures +- `docs/generated/` is reserved for generated artifacts only +- `docs/registry/` stores continuously updated tracking registries +- `docs/wiki/` stores living notes and working references + +## Branching and commits + +- GitHub Flow: feature branches -> PR into `develop` -> `develop` -> `main`. +- Breaking changes do not land directly on `main`. +- Every commit requires both a DCO sign-off and a cryptographic signature. +- If generating commits on someone's behalf, verify signing config first: + `git config --get commit.gpgsign`. + +## Tooling + +- Package manager: `pnpm` only (`preinstall` enforces this). +- Monorepo orchestration: `turbo`. +- Primary language: TypeScript. +- Formatting/linting is intentionally split by file type: + - JS/TS/JSON/JSONC: Biome + - Markdown/YAML: Prettier +- Typical repo health commands: + - `pnpm lint` + - `pnpm build` + - `pnpm typecheck` + - `pnpm test` + +CI is defined in `.github/workflows/ci.yml` and is scoped to repository health +checks (lint, build, typecheck, test). Keep CI focused and avoid coupling it +to deployment steps. + +## Releases + +- Changesets controls versioning and changelogs. +- Package publishing should use npm provenance (`publishConfig.provenance: true`) + at the package level for publishable packages. +- Changes to publishing metadata, release workflows, package names, exported + entrypoints, or packaged file lists should be treated as sensitive. + +## This is a public OSS repository + +Apache-2.0 licensed. Contribution process, code of conduct, and security +reporting are owned at the OEI organization level rather than duplicated in +each repository. + + + +# This is NOT the Turborepo you know + +Turborepo configuration, task behavior, and CLI commands can vary between installed versions and may differ from your training data. Resolve the `turbo` package from this file's directory or relevant workspace; in monorepos, it may not be visible from the repository root. For example, run `node -p "require.resolve('turbo/package.json')"` from a workspace that depends on `turbo`. + +Read `docs/README.md` inside that installed package first, then read the relevant pages from its `docs/` directory before changing Turborepo configuration or commands. Heed deprecation notices. These bundled docs match the installed package version and are available without network access. + +This block is written and re-added by `turbo` before repository-scoped commands when an AI agent is detected. In the Turborepo source repository, its template is defined in `crates/turborepo-cli/src/cli/agent_guidance.rs`. Removing the managed block while updates are enabled means a later qualifying invocation will add it again. Set `"agentGuidance": false` in the root `turbo.json` or `turbo.jsonc` to opt out; this does not remove an existing block. Keep the block committed with your work to avoid an uncommitted change on the next agent invocation. + diff --git a/docs/registry/core-publish-readiness-registry.md b/docs/registry/core-publish-readiness-registry.md index eab8cbb..7cdd8f4 100644 --- a/docs/registry/core-publish-readiness-registry.md +++ b/docs/registry/core-publish-readiness-registry.md @@ -17,22 +17,22 @@ Tracks publish-readiness work required to bring OEI Core to the same baseline us ## Workstream Tracker -| ID | Workstream | Requested Check | Status | Evidence | Notes | -| ------ | -------------------------- | ---------------------------------------------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | -| CR-001 | Governance docs | AGENTS.md completion | Needs Work | `AGENTS.md` contains only placeholder text. | Replace with full repository guidance aligned to current standards. | -| CR-002 | Linting | Biome configuration correctness | Needs Work | `biome.json` lacks canonical excludes for build artifacts (`dist`, `coverage`, `*.tsbuildinfo`). | Align file-scoping and ignore behavior with `config-dev` baseline. | -| CR-003 | TypeScript | Root tsconfig correctness and npm-based shared config usage | Needs Work | `tsconfig.json` is fully local and does not extend `@openendurance/config-typescript/*`. | Refactor to extend published npm preset and keep only local overrides. | -| CR-004 | Formatting | Prettier and Jest shared config usage from npm packages | Needs Work | No `.prettierrc*` or `prettier.config.*`; no `jest.config.*`; no `@openendurance/config-prettier` / `@openendurance/config-jest` usage. | Add shared-config consumption and package dependencies where required. | -| CR-005 | Lint workflow | Split scanning between Biome and Prettier | Needs Work | Split exists (`lint:prettier` + Biome paths), but root lint wiring differs from `config-dev` canonical shape. | Standardize root lint commands and keep markdown/yaml under Prettier checks. | -| CR-006 | Packaging and release | npm publishing setup, provenance, packaged `/dist`, workflows | Needs Work | `.github/workflows/ci.yml` now exists, but no release workflow is present; `packages/core/package.json` is `private: true` and has no `publishConfig.provenance`. | Add release workflow, publishing metadata, and first-release bootstrap plan. | -| CR-007 | Dependency maintenance | Renovate configuration quality spot-check | Needs Work | `renovate.json` is close, but includes stale package match (`@types/lodash`) not present in repo. | Prune stale rules and validate grouping/automerge intent against current deps. | -| CR-008 | Task orchestration | Turbo configuration spot-check at root and package levels | Needs Work | Root `turbo.json` includes boundaries/tags not reflected in package tags; package tag is `core`. | Reconcile boundary taxonomy and task model to intended enforcement. | -| CR-009 | Package metadata | package.json completeness per package and root | Needs Work | `packages/core-validation` has no `package.json`; `packages/core/package.json` is not publish-ready (`private`, `UNLICENSED`, missing publish settings). | Finalize publishable metadata for each package and align root/package responsibilities. | -| CR-010 | Documentation | Root README and package README completeness | Needs Work | Root `README.md` includes incorrect badge/repo references (`openendurance/fkt`) and links to missing files; package READMEs are empty. | Correct root links/badges and add package-level install/usage documentation. | -| CR-011 | Agent guidance | Add `.github/copilot-instructions.md` synthesized from AGENTS guidance | Needs Work | `.github/copilot-instructions.md` is missing. | Create concise instruction file derived from finalized AGENTS guidance. | -| CR-012 | Ownership model | CODEOWNERS granularity using org groups | Needs Work | `CODEOWNERS` has only a single wildcard owner mapping. | Replace with layered, path-specific ownership model similar to `config-dev`. | -| CR-013 | License compliance CI | Track migration of license scanning workflow to ORT-based checks | Needs Work | `.github/workflows/ci.yml` is present but no ORT/license-compliance workflow is defined in `.github/workflows/`. | Add explicit ORT license-compliance workflow and policy source pinning strategy. | -| CR-014 | Publish artifact hardening | Ensure `dist` package contents are deterministic and source-aligned | Needs Work | `packages/core/dist/` contains files not present in `packages/core/src/` (e.g., `oeiEntityMetadata.*`), indicating stale build output risk. | Add clean/prepack guardrails and verify publish artifact contract before first release. | +| ID | Workstream | Requested Check | Status | Evidence | Notes | +| ------ | -------------------------- | ---------------------------------------------------------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | +| CR-001 | Governance docs | AGENTS.md completion | Looks Complete | `AGENTS.md` now contains full core-specific guidance for scope, tooling, branching, docs, and release expectations. | Spot-check complete; refine over time as repo conventions evolve. | +| CR-002 | Linting | Biome configuration correctness | Needs Work | `biome.json` lacks canonical excludes for build artifacts (`dist`, `coverage`, `*.tsbuildinfo`). | Align file-scoping and ignore behavior with `config-dev` baseline. | +| CR-003 | TypeScript | Root tsconfig correctness and npm-based shared config usage | Needs Work | `tsconfig.json` is fully local and does not extend `@openendurance/config-typescript/*`. | Refactor to extend published npm preset and keep only local overrides. | +| CR-004 | Formatting | Prettier and Jest shared config usage from npm packages | Needs Work | No `.prettierrc*` or `prettier.config.*`; no `jest.config.*`; no `@openendurance/config-prettier` / `@openendurance/config-jest` usage. | Add shared-config consumption and package dependencies where required. | +| CR-005 | Lint workflow | Split scanning between Biome and Prettier | Needs Work | Split exists (`lint:prettier` + Biome paths), but root lint wiring differs from `config-dev` canonical shape. | Standardize root lint commands and keep markdown/yaml under Prettier checks. | +| CR-006 | Packaging and release | npm publishing setup, provenance, packaged `/dist`, workflows | Needs Work | `.github/workflows/ci.yml` now exists, but no release workflow is present; `packages/core/package.json` is `private: true` and has no `publishConfig.provenance`. | Add release workflow, publishing metadata, and first-release bootstrap plan. | +| CR-007 | Dependency maintenance | Renovate configuration quality spot-check | Needs Work | `renovate.json` is close, but includes stale package match (`@types/lodash`) not present in repo. | Prune stale rules and validate grouping/automerge intent against current deps. | +| CR-008 | Task orchestration | Turbo configuration spot-check at root and package levels | Needs Work | Root `turbo.json` includes boundaries/tags not reflected in package tags; package tag is `core`. | Reconcile boundary taxonomy and task model to intended enforcement. | +| CR-009 | Package metadata | package.json completeness per package and root | Needs Work | `packages/core-validation` has no `package.json`; `packages/core/package.json` is not publish-ready (`private`, `UNLICENSED`, missing publish settings). | Finalize publishable metadata for each package and align root/package responsibilities. | +| CR-010 | Documentation | Root README and package README completeness | Needs Work | Root `README.md` includes incorrect badge/repo references (`openendurance/fkt`) and links to missing files; package READMEs are empty. | Correct root links/badges and add package-level install/usage documentation. | +| CR-011 | Agent guidance | Add `.github/copilot-instructions.md` synthesized from AGENTS guidance | Needs Work | `.github/copilot-instructions.md` is missing. | Create concise instruction file derived from finalized AGENTS guidance. | +| CR-012 | Ownership model | CODEOWNERS granularity using org groups | Needs Work | `CODEOWNERS` has only a single wildcard owner mapping. | Replace with layered, path-specific ownership model similar to `config-dev`. | +| CR-013 | License compliance CI | Track migration of license scanning workflow to ORT-based checks | Needs Work | `.github/workflows/ci.yml` is present but no ORT/license-compliance workflow is defined in `.github/workflows/`. | Add explicit ORT license-compliance workflow and policy source pinning strategy. | +| CR-014 | Publish artifact hardening | Ensure `dist` package contents are deterministic and source-aligned | Needs Work | `packages/core/dist/` contains files not present in `packages/core/src/` (e.g., `oeiEntityMetadata.*`), indicating stale build output risk. | Add clean/prepack guardrails and verify publish artifact contract before first release. | ## Audit Log @@ -41,3 +41,4 @@ Tracks publish-readiness work required to bring OEI Core to the same baseline us | 2026-10-20 | Initialized registry from user-provided readiness list. | Copilot | | 2026-10-20 | Completed audit of listed checklist items; all items remain open and require follow-up work. | Copilot | | 2026-10-20 | Added approved additional findings: ORT license-compliance workflow tracking and publish artifact hardening; excluded commit-history remediation tracking per operator direction. | Copilot | +| 2026-10-20 | Completed CR-001 by replacing placeholder `AGENTS.md` with a core-specific guidance document; marked CR-001 as `Looks Complete`. | Copilot | From 2c17c6d80e0e44c1dbf183520f34608223d2009f Mon Sep 17 00:00:00 2001 From: Kristopher Cargile Date: Tue, 20 Oct 2026 05:40:54 -0600 Subject: [PATCH 07/14] Finalize core agent guidance documentation and add GitHub Copilot instructions Signed-off-by: Kristopher Cargile --- .changeset/smart-roses-sleep.md | 5 ++ .github/copilot-instructions.md | 87 +++++++++++++++++++ .../core-publish-readiness-registry.md | 3 +- 3 files changed, 94 insertions(+), 1 deletion(-) create mode 100644 .changeset/smart-roses-sleep.md create mode 100644 .github/copilot-instructions.md diff --git a/.changeset/smart-roses-sleep.md b/.changeset/smart-roses-sleep.md new file mode 100644 index 0000000..9d7c610 --- /dev/null +++ b/.changeset/smart-roses-sleep.md @@ -0,0 +1,5 @@ +--- +"@openendurance/core": patch +--- + +Finalize core agent guidance docs (AGENTS + Copilot instructions) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000..b693bb6 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,87 @@ +# GitHub Copilot Instructions + +## What this repo is + +Shared foundational TypeScript libraries for Open Endurance Initiative (OEI) +products and platform services. + +This repository is a pnpm + Turborepo monorepo with publishable npm packages +that serve as platform-layer building blocks (domain primitives, shared types, +and validation contracts). It is not a single deployable application. + +**This repo has high blast radius relative to its size.** Changes to shared +packages can affect multiple OEI product repositories when dependency ranges +are updated. + +## Package layout + +| Package | Purpose | +| -------------------------------- | ------------------------------------------------------------- | +| `@openendurance/core` | Core domain primitives and shared types used across products. | +| `@openendurance/core-validation` | Validation package surface. | + +Package source lives under `packages//src`. + +Package build output lives under `packages//dist` and is generated. +Do not treat `dist` as source of truth. + +## Documentation + +The `docs/` tree is the durable knowledge base for this repository. + +- `docs/README.md` explains documentation conventions +- `docs/TOC.md` is the canonical docs index +- `docs/adr/` stores immutable architecture decisions +- `docs/arch/` stores current-state architecture documentation +- `docs/ops/` stores operational runbooks and procedures +- `docs/generated/` is for generated artifacts only +- `docs/registry/` stores continuously maintained tracking registries +- `docs/wiki/` stores living notes and working references + +## Branching and commits + +- GitHub Flow: feature branches -> PR into `develop` -> `develop` -> `main`. +- Breaking changes never land directly on `main`. +- Every commit requires both a DCO sign-off and a cryptographic signature. +- If generating commits on someone's behalf, check signing config first: + `git config --get commit.gpgsign`. + +## Tooling + +- Package manager: `pnpm` only (`preinstall` enforces this). +- Monorepo task orchestration: `turbo`. +- Primary language: TypeScript. +- Linting and formatting are intentionally split by file type: + - JS/TS/JSON/JSONC: Biome + - Markdown/YAML: Prettier + +Use repo scripts where possible: + +- `pnpm lint` +- `pnpm build` +- `pnpm typecheck` +- `pnpm test` + +CI lives in `.github/workflows/ci.yml` and should remain focused on repository +health checks (lint, build, typecheck, test), not deployment orchestration. + +## Releases + +- Changesets controls versioning and changelogs. +- Publishable packages should use npm provenance + (`publishConfig.provenance: true`) at the package level. +- Treat changes to package names, exports, publish metadata, and release + workflow behavior as sensitive. + +## Editorial posture + +- Prefer small, targeted edits over broad rewrites. +- Keep docs synchronized with package reality. +- If a change affects package behavior, exports, release flow, or ownership, + update docs and registries in the same work item. + +## This is a public OSS repository + +Apache-2.0 licensed. Contribution process, code of conduct, and security +reporting are managed at the OEI organization level and should not be +needlessly duplicated per repository. diff --git a/docs/registry/core-publish-readiness-registry.md b/docs/registry/core-publish-readiness-registry.md index 7cdd8f4..82968b6 100644 --- a/docs/registry/core-publish-readiness-registry.md +++ b/docs/registry/core-publish-readiness-registry.md @@ -29,7 +29,7 @@ Tracks publish-readiness work required to bring OEI Core to the same baseline us | CR-008 | Task orchestration | Turbo configuration spot-check at root and package levels | Needs Work | Root `turbo.json` includes boundaries/tags not reflected in package tags; package tag is `core`. | Reconcile boundary taxonomy and task model to intended enforcement. | | CR-009 | Package metadata | package.json completeness per package and root | Needs Work | `packages/core-validation` has no `package.json`; `packages/core/package.json` is not publish-ready (`private`, `UNLICENSED`, missing publish settings). | Finalize publishable metadata for each package and align root/package responsibilities. | | CR-010 | Documentation | Root README and package README completeness | Needs Work | Root `README.md` includes incorrect badge/repo references (`openendurance/fkt`) and links to missing files; package READMEs are empty. | Correct root links/badges and add package-level install/usage documentation. | -| CR-011 | Agent guidance | Add `.github/copilot-instructions.md` synthesized from AGENTS guidance | Needs Work | `.github/copilot-instructions.md` is missing. | Create concise instruction file derived from finalized AGENTS guidance. | +| CR-011 | Agent guidance | Add `.github/copilot-instructions.md` synthesized from AGENTS guidance | Looks Complete | `.github/copilot-instructions.md` now exists with core-specific repo scope, tooling, branching, release, and editorial guidance aligned to `AGENTS.md`. | Keep synchronized with `AGENTS.md` as conventions evolve. | | CR-012 | Ownership model | CODEOWNERS granularity using org groups | Needs Work | `CODEOWNERS` has only a single wildcard owner mapping. | Replace with layered, path-specific ownership model similar to `config-dev`. | | CR-013 | License compliance CI | Track migration of license scanning workflow to ORT-based checks | Needs Work | `.github/workflows/ci.yml` is present but no ORT/license-compliance workflow is defined in `.github/workflows/`. | Add explicit ORT license-compliance workflow and policy source pinning strategy. | | CR-014 | Publish artifact hardening | Ensure `dist` package contents are deterministic and source-aligned | Needs Work | `packages/core/dist/` contains files not present in `packages/core/src/` (e.g., `oeiEntityMetadata.*`), indicating stale build output risk. | Add clean/prepack guardrails and verify publish artifact contract before first release. | @@ -42,3 +42,4 @@ Tracks publish-readiness work required to bring OEI Core to the same baseline us | 2026-10-20 | Completed audit of listed checklist items; all items remain open and require follow-up work. | Copilot | | 2026-10-20 | Added approved additional findings: ORT license-compliance workflow tracking and publish artifact hardening; excluded commit-history remediation tracking per operator direction. | Copilot | | 2026-10-20 | Completed CR-001 by replacing placeholder `AGENTS.md` with a core-specific guidance document; marked CR-001 as `Looks Complete`. | Copilot | +| 2026-10-20 | Completed CR-011 by adding `.github/copilot-instructions.md` synthesized from `AGENTS.md`; marked CR-011 as `Looks Complete`. | Copilot | From 90185fc19ccdd0dcc097c9b95fdd337e07750be9 Mon Sep 17 00:00:00 2001 From: Kristopher Cargile Date: Tue, 20 Oct 2026 06:09:02 -0600 Subject: [PATCH 08/14] Update lint:root script to use prettier for file checks Signed-off-by: Kristopher Cargile --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index 7a151d3..4b21ab9 100644 --- a/package.json +++ b/package.json @@ -23,7 +23,7 @@ "format:prettier": "pnpm exec prettier --write \"**/*.{md,yml,yaml}\"", "lint": "pnpm run lint:root && pnpm run lint:prettier && pnpm turbo run lint", "lint:prettier": "pnpm exec prettier --check \"**/*.{md,yml,yaml}\"", - "lint:root": "pnpm exec biome lint --files-ignore-unknown $(find . -maxdepth 1 -type f -print)", + "lint:root": "pnpm exec prettier --check package.json biome.json tsconfig.json turbo.json renovate.json lint-staged.config.mjs", "pre-commit": "lint-staged", "preinstall": "npx only-allow pnpm", "prepare": "husky", From 76d096516d5a8b62f1b6d4ce2bb3986e537b9e73 Mon Sep 17 00:00:00 2001 From: Kristopher Cargile Date: Tue, 20 Oct 2026 06:04:12 -0600 Subject: [PATCH 09/14] Revise core publish readiness registry checks Updated the status and evidence for various checks in the core publish readiness registry. Notable changes include the completion of AGENTS.md and adjustments to biome configuration and TypeScript settings. Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: Kristopher Cargile --- docs/registry/core-publish-readiness-registry.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/registry/core-publish-readiness-registry.md b/docs/registry/core-publish-readiness-registry.md index 82968b6..868f2d6 100644 --- a/docs/registry/core-publish-readiness-registry.md +++ b/docs/registry/core-publish-readiness-registry.md @@ -20,7 +20,7 @@ Tracks publish-readiness work required to bring OEI Core to the same baseline us | ID | Workstream | Requested Check | Status | Evidence | Notes | | ------ | -------------------------- | ---------------------------------------------------------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | | CR-001 | Governance docs | AGENTS.md completion | Looks Complete | `AGENTS.md` now contains full core-specific guidance for scope, tooling, branching, docs, and release expectations. | Spot-check complete; refine over time as repo conventions evolve. | -| CR-002 | Linting | Biome configuration correctness | Needs Work | `biome.json` lacks canonical excludes for build artifacts (`dist`, `coverage`, `*.tsbuildinfo`). | Align file-scoping and ignore behavior with `config-dev` baseline. | +| CR-002 | Linting | Biome configuration correctness | Not Audited | `biome.json` enables VCS ignore-file support; `.gitignore` excludes `*.tsbuildinfo`, `coverage/`, and `dist/`. | Artifact exclusions are configured; verify remaining configuration against the `config-dev` baseline. | | CR-003 | TypeScript | Root tsconfig correctness and npm-based shared config usage | Needs Work | `tsconfig.json` is fully local and does not extend `@openendurance/config-typescript/*`. | Refactor to extend published npm preset and keep only local overrides. | | CR-004 | Formatting | Prettier and Jest shared config usage from npm packages | Needs Work | No `.prettierrc*` or `prettier.config.*`; no `jest.config.*`; no `@openendurance/config-prettier` / `@openendurance/config-jest` usage. | Add shared-config consumption and package dependencies where required. | | CR-005 | Lint workflow | Split scanning between Biome and Prettier | Needs Work | Split exists (`lint:prettier` + Biome paths), but root lint wiring differs from `config-dev` canonical shape. | Standardize root lint commands and keep markdown/yaml under Prettier checks. | From fea3a0250a929f496bbf2d6fc8f0d00036424356 Mon Sep 17 00:00:00 2001 From: Kristopher Cargile Date: Tue, 20 Oct 2026 06:12:22 -0600 Subject: [PATCH 10/14] address linter issues in CI Signed-off-by: Kristopher Cargile --- docs/README.md | 1 - .../core-publish-readiness-registry.md | 32 +++++++++---------- docs/wiki/README.md | 1 - pnpm-workspace.yaml | 10 +++--- 4 files changed, 21 insertions(+), 23 deletions(-) diff --git a/docs/README.md b/docs/README.md index 480a8a9..69b23fe 100644 --- a/docs/README.md +++ b/docs/README.md @@ -40,4 +40,3 @@ Start with `TOC.md` for a navigable index of all documents. - Update `TOC.md` whenever a document is added, removed, or renamed - Add a `TOC.md` entry for every new registry or ADR; leave section headers present even when empty - Each subdirectory has its own README with authorship and update guidance, including `wiki/` - diff --git a/docs/registry/core-publish-readiness-registry.md b/docs/registry/core-publish-readiness-registry.md index 868f2d6..c7c96be 100644 --- a/docs/registry/core-publish-readiness-registry.md +++ b/docs/registry/core-publish-readiness-registry.md @@ -17,22 +17,22 @@ Tracks publish-readiness work required to bring OEI Core to the same baseline us ## Workstream Tracker -| ID | Workstream | Requested Check | Status | Evidence | Notes | -| ------ | -------------------------- | ---------------------------------------------------------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | -| CR-001 | Governance docs | AGENTS.md completion | Looks Complete | `AGENTS.md` now contains full core-specific guidance for scope, tooling, branching, docs, and release expectations. | Spot-check complete; refine over time as repo conventions evolve. | -| CR-002 | Linting | Biome configuration correctness | Not Audited | `biome.json` enables VCS ignore-file support; `.gitignore` excludes `*.tsbuildinfo`, `coverage/`, and `dist/`. | Artifact exclusions are configured; verify remaining configuration against the `config-dev` baseline. | -| CR-003 | TypeScript | Root tsconfig correctness and npm-based shared config usage | Needs Work | `tsconfig.json` is fully local and does not extend `@openendurance/config-typescript/*`. | Refactor to extend published npm preset and keep only local overrides. | -| CR-004 | Formatting | Prettier and Jest shared config usage from npm packages | Needs Work | No `.prettierrc*` or `prettier.config.*`; no `jest.config.*`; no `@openendurance/config-prettier` / `@openendurance/config-jest` usage. | Add shared-config consumption and package dependencies where required. | -| CR-005 | Lint workflow | Split scanning between Biome and Prettier | Needs Work | Split exists (`lint:prettier` + Biome paths), but root lint wiring differs from `config-dev` canonical shape. | Standardize root lint commands and keep markdown/yaml under Prettier checks. | -| CR-006 | Packaging and release | npm publishing setup, provenance, packaged `/dist`, workflows | Needs Work | `.github/workflows/ci.yml` now exists, but no release workflow is present; `packages/core/package.json` is `private: true` and has no `publishConfig.provenance`. | Add release workflow, publishing metadata, and first-release bootstrap plan. | -| CR-007 | Dependency maintenance | Renovate configuration quality spot-check | Needs Work | `renovate.json` is close, but includes stale package match (`@types/lodash`) not present in repo. | Prune stale rules and validate grouping/automerge intent against current deps. | -| CR-008 | Task orchestration | Turbo configuration spot-check at root and package levels | Needs Work | Root `turbo.json` includes boundaries/tags not reflected in package tags; package tag is `core`. | Reconcile boundary taxonomy and task model to intended enforcement. | -| CR-009 | Package metadata | package.json completeness per package and root | Needs Work | `packages/core-validation` has no `package.json`; `packages/core/package.json` is not publish-ready (`private`, `UNLICENSED`, missing publish settings). | Finalize publishable metadata for each package and align root/package responsibilities. | -| CR-010 | Documentation | Root README and package README completeness | Needs Work | Root `README.md` includes incorrect badge/repo references (`openendurance/fkt`) and links to missing files; package READMEs are empty. | Correct root links/badges and add package-level install/usage documentation. | -| CR-011 | Agent guidance | Add `.github/copilot-instructions.md` synthesized from AGENTS guidance | Looks Complete | `.github/copilot-instructions.md` now exists with core-specific repo scope, tooling, branching, release, and editorial guidance aligned to `AGENTS.md`. | Keep synchronized with `AGENTS.md` as conventions evolve. | -| CR-012 | Ownership model | CODEOWNERS granularity using org groups | Needs Work | `CODEOWNERS` has only a single wildcard owner mapping. | Replace with layered, path-specific ownership model similar to `config-dev`. | -| CR-013 | License compliance CI | Track migration of license scanning workflow to ORT-based checks | Needs Work | `.github/workflows/ci.yml` is present but no ORT/license-compliance workflow is defined in `.github/workflows/`. | Add explicit ORT license-compliance workflow and policy source pinning strategy. | -| CR-014 | Publish artifact hardening | Ensure `dist` package contents are deterministic and source-aligned | Needs Work | `packages/core/dist/` contains files not present in `packages/core/src/` (e.g., `oeiEntityMetadata.*`), indicating stale build output risk. | Add clean/prepack guardrails and verify publish artifact contract before first release. | +| ID | Workstream | Requested Check | Status | Evidence | Notes | +| ------ | -------------------------- | ---------------------------------------------------------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | +| CR-001 | Governance docs | AGENTS.md completion | Looks Complete | `AGENTS.md` now contains full core-specific guidance for scope, tooling, branching, docs, and release expectations. | Spot-check complete; refine over time as repo conventions evolve. | +| CR-002 | Linting | Biome configuration correctness | Not Audited | `biome.json` enables VCS ignore-file support; `.gitignore` excludes `*.tsbuildinfo`, `coverage/`, and `dist/`. | Artifact exclusions are configured; verify remaining configuration against the `config-dev` baseline. | +| CR-003 | TypeScript | Root tsconfig correctness and npm-based shared config usage | Needs Work | `tsconfig.json` is fully local and does not extend `@openendurance/config-typescript/*`. | Refactor to extend published npm preset and keep only local overrides. | +| CR-004 | Formatting | Prettier and Jest shared config usage from npm packages | Needs Work | No `.prettierrc*` or `prettier.config.*`; no `jest.config.*`; no `@openendurance/config-prettier` / `@openendurance/config-jest` usage. | Add shared-config consumption and package dependencies where required. | +| CR-005 | Lint workflow | Split scanning between Biome and Prettier | Needs Work | Split exists (`lint:prettier` + Biome paths), but root lint wiring differs from `config-dev` canonical shape. | Standardize root lint commands and keep markdown/yaml under Prettier checks. | +| CR-006 | Packaging and release | npm publishing setup, provenance, packaged `/dist`, workflows | Needs Work | `.github/workflows/ci.yml` now exists, but no release workflow is present; `packages/core/package.json` is `private: true` and has no `publishConfig.provenance`. | Add release workflow, publishing metadata, and first-release bootstrap plan. | +| CR-007 | Dependency maintenance | Renovate configuration quality spot-check | Needs Work | `renovate.json` is close, but includes stale package match (`@types/lodash`) not present in repo. | Prune stale rules and validate grouping/automerge intent against current deps. | +| CR-008 | Task orchestration | Turbo configuration spot-check at root and package levels | Needs Work | Root `turbo.json` includes boundaries/tags not reflected in package tags; package tag is `core`. | Reconcile boundary taxonomy and task model to intended enforcement. | +| CR-009 | Package metadata | package.json completeness per package and root | Needs Work | `packages/core-validation` has no `package.json`; `packages/core/package.json` is not publish-ready (`private`, `UNLICENSED`, missing publish settings). | Finalize publishable metadata for each package and align root/package responsibilities. | +| CR-010 | Documentation | Root README and package README completeness | Needs Work | Root `README.md` includes incorrect badge/repo references (`openendurance/fkt`) and links to missing files; package READMEs are empty. | Correct root links/badges and add package-level install/usage documentation. | +| CR-011 | Agent guidance | Add `.github/copilot-instructions.md` synthesized from AGENTS guidance | Looks Complete | `.github/copilot-instructions.md` now exists with core-specific repo scope, tooling, branching, release, and editorial guidance aligned to `AGENTS.md`. | Keep synchronized with `AGENTS.md` as conventions evolve. | +| CR-012 | Ownership model | CODEOWNERS granularity using org groups | Needs Work | `CODEOWNERS` has only a single wildcard owner mapping. | Replace with layered, path-specific ownership model similar to `config-dev`. | +| CR-013 | License compliance CI | Track migration of license scanning workflow to ORT-based checks | Needs Work | `.github/workflows/ci.yml` is present but no ORT/license-compliance workflow is defined in `.github/workflows/`. | Add explicit ORT license-compliance workflow and policy source pinning strategy. | +| CR-014 | Publish artifact hardening | Ensure `dist` package contents are deterministic and source-aligned | Needs Work | `packages/core/dist/` contains files not present in `packages/core/src/` (e.g., `oeiEntityMetadata.*`), indicating stale build output risk. | Add clean/prepack guardrails and verify publish artifact contract before first release. | ## Audit Log diff --git a/docs/wiki/README.md b/docs/wiki/README.md index 57bc4b2..1d3a888 100644 --- a/docs/wiki/README.md +++ b/docs/wiki/README.md @@ -36,4 +36,3 @@ Do not reuse or renumber existing values. ## Update Contract Add and maintain wiki content here as it is authored. Follow the naming above, and update `TOC.md` when new wiki pages are introduced. - diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml index 0deca16..933a19e 100644 --- a/pnpm-workspace.yaml +++ b/pnpm-workspace.yaml @@ -1,7 +1,7 @@ packages: - - "apps/*" - - "packages/*" + - "apps/*" + - "packages/*" allowBuilds: - '@parcel/watcher': true - protobufjs: true - unrs-resolver: true + "@parcel/watcher": true + protobufjs: true + unrs-resolver: true From efa4ee5a75c9f3484841fea2b66b26b00a84070b Mon Sep 17 00:00:00 2001 From: Kristopher Cargile Date: Tue, 20 Oct 2026 06:19:53 -0600 Subject: [PATCH 11/14] set Jest to passWithNoTests Signed-off-by: Kristopher Cargile --- packages/core/package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/core/package.json b/packages/core/package.json index 20929bf..f5186b2 100644 --- a/packages/core/package.json +++ b/packages/core/package.json @@ -24,7 +24,7 @@ "build:ci": "pnpm build", "clean": "rm -rf .turbo coverage dist node_modules *.tsbuildinfo", "lint": "pnpm exec biome lint", - "test": "NODE_NO_WARNINGS=1 jest", + "test": "NODE_NO_WARNINGS=1 jest --passWithNoTests", "typecheck": "tsc --noEmit", "watch": "tsc -w" }, From 396ae79e950210b1c93dcae19bab0ce965ecb96b Mon Sep 17 00:00:00 2001 From: Kristopher Cargile Date: Tue, 20 Oct 2026 06:25:15 -0600 Subject: [PATCH 12/14] Fix signing key path in commit-signing.md Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: Kristopher Cargile --- docs/ops/commit-signing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/ops/commit-signing.md b/docs/ops/commit-signing.md index 65f4541..627fb76 100644 --- a/docs/ops/commit-signing.md +++ b/docs/ops/commit-signing.md @@ -45,7 +45,7 @@ ssh-keygen -t ed25519 -C "your-email@example.com" -f ~/.ssh/git_signing_key ```sh git config --global gpg.format ssh -git config --global user.signingkey ~/.ssh/git_signing_key.pub +git config --global user.signingkey ~/.ssh/git_signing_key git config --global commit.gpgsign true ``` From a1246aba07ef5ef16f171964972fc626d591a1d8 Mon Sep 17 00:00:00 2001 From: Kristopher Cargile Date: Tue, 20 Oct 2026 06:25:33 -0600 Subject: [PATCH 13/14] Revise commit signing command in documentation Update commit signing instructions for rebase. Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: Kristopher Cargile --- docs/ops/commit-signing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/ops/commit-signing.md b/docs/ops/commit-signing.md index 627fb76..2d41afb 100644 --- a/docs/ops/commit-signing.md +++ b/docs/ops/commit-signing.md @@ -83,7 +83,7 @@ a whole branch. commits that already have correct sign-off; this only touches signatures): ```sh -git rebase --root --exec "git commit --amend --no-edit -S" +git rebase --force-rebase --gpg-sign origin/develop git push --force-with-lease origin ``` From ed29972f04dd97f89aefd0da716bbafcf5adc172 Mon Sep 17 00:00:00 2001 From: Kristopher Cargile Date: Tue, 20 Oct 2026 06:25:46 -0600 Subject: [PATCH 14/14] Fix command for checking commit signature Update command to check commit signature in documentation. Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: Kristopher Cargile --- docs/ops/commit-signing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/ops/commit-signing.md b/docs/ops/commit-signing.md index 2d41afb..3fb002f 100644 --- a/docs/ops/commit-signing.md +++ b/docs/ops/commit-signing.md @@ -102,7 +102,7 @@ signed it.** Check the raw commit object before trusting that message: ```sh -git cat-file commit HEAD | head -5 +git cat-file commit HEAD | sed -n '1,/^$/p' ``` If you see a `gpgsig` line, the commit is signed. The "No signature" output