docs(semark): align skill guidance with check-semark.mjs

.agents/skills/semark-protocol/references/audit.md

@@ -22,6 +22,21 @@ Do not infer semantic inaccuracy from wording alone. Read more evidence when a f
 depends on behavior.
 Use the implementation, related types, callers, and tests as evidence when necessary.
 
+## Map checker labels to audit categories
+
+When the repository uses `scripts/check-semark.mjs`, translate checker labels in the
+`[label]` field to audit categories:
+
+| Checker label | Audit categories |
+| --- | --- |
+| `readme-coverage` | `README_MISSING`, `README_NAME_INVALID` |
+| `file-signature` | `FILE_SIGNATURE_MISSING`, `FILE_SIGNATURE_POSITION`, `FILE_SIGNATURE_FORMAT`, `TSDOC_INVALID`, `TAG_ORDER_INVALID`, `LENGTH_LIMIT` |
+| `method-signature` | `METHOD_SIGNATURE_MISSING`, `METHOD_SIGNATURE_POSITION`, `METHOD_SIGNATURE_FORMAT`, `TSDOC_INVALID`, `TAG_ORDER_INVALID`, `LENGTH_LIMIT` |
+| `comment-policy` | `COMMENT_UNAUTHORIZED`, `DIRECTIVE_INVALID` |
+
+Use `SIGNATURE_STALE`, `NAME_AMBIGUOUS`, and `CONFIGURATION_INVALID` when the finding
+does not map to a checker label.
+
 ## Use stable finding categories
 
 - `README_MISSING`

.agents/skills/semark-protocol/references/install.md

@@ -73,9 +73,14 @@ existing comment.
 
 ## Add validation
 
-If the repository uses Oxlint, configure the GitHub Packages registry for the
-`@paperkeel` scope. Install `@paperkeel/oxlint-plugin-semark`. Load it through
-`jsPlugins` and enable `semark/valid` in the root Oxlint configuration.
+Add the smallest local tool that can check the configured scope, placement, tags,
+order, lengths, directives, and comment policy. This repository uses
+`scripts/check-semark.mjs` through `pnpm semark:check`.
+
+In other repositories that use Oxlint, you may optionally install
+`@paperkeel/oxlint-plugin-semark`. Configure the GitHub Packages registry for the
+`@paperkeel` scope. Load the plugin through `jsPlugins` and enable `semark/valid` in
+the root Oxlint configuration.
 
 Keep the scope-to-registry mapping in the project `.npmrc` file. Keep the token mapping
 in the trusted user-level `.npmrc` file. Do not commit a package token.
@@ -85,12 +90,9 @@ For GitHub Actions, grant the consuming repository read access under the package
 `actions/setup-node` with the GitHub Packages registry and `@paperkeel` scope. Pass
 the repository `GITHUB_TOKEN` as `NODE_AUTH_TOKEN` to the dependency installation step.
 
-Use a repository-local validator for requirements outside the Oxlint rule boundary.
-These requirements can include README coverage, migration scope, exclusions, naming,
-and changed-code signature updates.
-
-If the repository does not use Oxlint, add the smallest local tool that can check the
-configured scope, placement, tags, order, lengths, directives, and comment policy.
+Use a repository-local validator for requirements outside the local-script or Oxlint
+rule boundary. These requirements can include README coverage, migration scope,
+exclusions, naming, and changed-code signature updates.
 
 Make the check return a nonzero status for violations. Report the file, source location,
 and violation type.

.agents/skills/semark-protocol/rules/method-signature.md

@@ -1,16 +1,22 @@
 # Method signatures
 
-Add one method signature to each callable implementation with a stable source location.
-Coverage includes:
+Add one method signature to each callable implementation with a block body and a
+stable source location. Coverage includes:
 
 - function declarations
+- generator functions (`function*`)
 - class methods and constructors
 - accessors
-- named function expressions
-- arrow functions or function expressions assigned to a variable or property
+- named function expressions with a block body
+- arrow functions or function expressions assigned to a variable or property when the
+  body is a block
 - object methods
 - callbacks with a block body
-- hooks and exported callables
+- hooks and exported callables with a block body
+
+Expression-bodied arrow functions and single-expression callbacks are out of scope for
+`scripts/check-semark.mjs` in this repository. Repositories with a different validator
+may enforce them.
 
 Do not add a separate signature to an overload declaration without a body. The
 implementation signature documents the complete overload behavior. Exclude ambient

.agents/skills/semark-protocol/rules/source-scope.md

@@ -1,7 +1,16 @@
 # Source scope
 
-Apply Semark to hand-authored `.ts`, `.tsx`, `.mts`, and `.cts` files. Include source
-files, tests, build scripts, and TypeScript configuration files in this scope.
+Apply Semark to hand-authored `.ts`, `.tsx`, `.mts`, and `.cts` files in the
+configured source roots.
+
+Default source roots:
+
+- repository root, non-recursive: only top-level TypeScript files
+- `apps/**`, recursive
+- `packages/**`, recursive
+
+Files in other directories, such as `scripts/`, are out of scope unless the
+repository configuration extends the roots.
 
 Exclude these files by default:
 

.agents/skills/semark-protocol/rules/validation.md

@@ -19,12 +19,17 @@ the descriptions.
 Check unauthorized comments and invalid directives in every Semark installation. Apply
 this check to the configured source scope.
 
-If the repository uses Oxlint, load `@paperkeel/oxlint-plugin-semark` through
-`jsPlugins`. Enable `semark/valid` as an error.
+Repositories may validate Semark with a local script or with Oxlint.
 
-Use repository validation for requirements outside the Oxlint rule boundary. These
-requirements include README coverage, semantic accuracy, naming, exclusions, migration
-scope, and changed-code signature updates.
+This repository uses `scripts/check-semark.mjs` through `pnpm semark:check`.
+
+In other repositories that use Oxlint, you may optionally load
+`@paperkeel/oxlint-plugin-semark` through `jsPlugins` and enable `semark/valid` as an
+error. The Oxlint plugin is not required here.
+
+Use repository validation for requirements outside the local-script or Oxlint rule
+boundary. These requirements include README coverage, semantic accuracy, naming,
+exclusions, migration scope, and changed-code signature updates.
 
 Run the configured Semark check before you complete a change. Correct violations that
 your change causes.

.github/workflows/ci.yml

@@ -28,9 +28,6 @@ jobs:
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
 
-      - name: Validate Semark Protocol
-        run: pnpm semark:check
-
       - name: Check source
         run: pnpm check
 

.github/workflows/release.yml

@@ -50,7 +50,6 @@ jobs:
         run: |
           test "$DEPLOY_SHA" = "$GITHUB_SHA" || { echo "The release event does not match the target commit." >&2; exit 1; }
           test "$DEPLOY_SHA" = "$(git rev-parse HEAD)" || { echo "The checkout does not match the release commit." >&2; exit 1; }
-          pnpm semark:check
           pnpm check
           pnpm build
           pnpm exec wrangler deploy --dry-run --config apps/api/wrangler.jsonc

AGENTS.md

@@ -47,4 +47,7 @@ or keep source comments except Semark file signatures, method signatures, and
 approved directives. Update an affected signature in the same change as the
 documented behavior. All applicable TypeScript files in the root, `apps/*`, and
 `packages/*` comply. Declaration-only `.d.ts` files use the protocol default
-exclusion. Run `pnpm semark:check` before you complete a change.
+exclusion. Validate Semark with `scripts/check-semark.mjs` through
+`pnpm semark:check`. This repository does not use the
+`@paperkeel/oxlint-plugin-semark` Oxlint plugin. Run `pnpm check` before each
+commit; it includes Semark validation.

package.json

@@ -20,7 +20,7 @@
 	"scripts": {
 		"bootstrap:check": "node scripts/check-bootstrap-boundary.mjs",
 		"build": "pnpm -r --if-present build",
-		"check": "pnpm bootstrap:check && pnpm format:check && pnpm lint && pnpm typecheck && pnpm test",
+		"check": "pnpm semark:check && pnpm bootstrap:check && pnpm format:check && pnpm lint && pnpm typecheck && pnpm test",
 		"dev": "alchemy dev --stage dev",
 		"deploy": "alchemy deploy --stage prod --yes",
 		"format": "oxfmt .",