@aefree/pi-plastic 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -5,6 +5,23 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project follows semantic versioning for public package releases.
 
+## [0.5.0] - 2026-08-05
+
+### Added
+
+- Added dynamically loadable `plastic_workspaceDiff` for bounded pending review: one machine-readable status pass, per-file text/binary/unavailable outcomes, selected-path and private-file policy, and intentional file/output limits.
+
+### Changed
+
+- Kept GNU/POSIX `diff` as the only text-diff backend, improved `PI_PLASTIC_DIFF_EXECUTABLE`/bare-PATH diagnostics (including Windows-like missing-diff guidance), and removed unused Git diff fallback code.
+- Made workspace `plastic_diffFile` use machine-readable pending status for private/new, added, changed, moved, and deleted comparisons; status revision IDs materialize safe bases and `--nodata` base failures now explain recovery.
+- Updated diff routing guidance: changed listing uses `plastic_status`, one file uses `plastic_diffFile`, pending review uses `plastic_workspaceDiff`, and explicit historical pairs use `plastic_diffRevisions`.
+
+- Replaced the optional `@aefree/pi-repo-search` integration with `@aefree/pi-file-discovery`. Plastic ignore/cloak data is now an advisory file-discovery filter: only roots with readable ignore/cloak files emit `filterDecision: "applied"` records with a nearest-workspace `filterBoundary`; no-op roots are omitted and unavailable or malformed filter data degrades to generic discovery as routine execution hygiene.
+- Register the optional Plastic filter through the package-qualified global capability-registry rendezvous instead of importing `pi-file-discovery` from Plastic's separate module root. Registration remains session-scoped, transactional, and safe against stale shutdown tokens.
+- Excluded development-only tests and behavioral evals from published npm artifacts.
+- Publish verified GitHub releases to npm through resumable OIDC trusted-publishing automation, and canonicalized the package repository URL for GitHub identity matching.
+
 ## [0.4.0] - 2026-08-01
 
 ### Added

package/README.md

@@ -8,9 +8,9 @@ When Pi starts inside a Plastic workspace, this package adds a themed `Plastic <
 
 The extension owns only the `plastic-branch` status key. It does not replace Pi's footer or suppress Pi's Git branch display, so Git and Plastic information can appear together in nested workspaces. If the Plastic marker exists but neither the selector nor `cm` yields a branch, the footer shows `Plastic branch unavailable`. Non-Plastic directories show no Plastic status.
 
-## Repository-search policy
+## File-discovery filter
 
-When `@aefree/pi-repo-search` is also installed, Pi session startup registers the independent `plastic.ignore-files` repository-search policy. The marker-based policy discovers readable `ignore.conf` and `cloaked.conf` only from the nearest Plastic workspace to each requested root, then adds them as ripgrep ignore files without replacing native ripgrep/Git-ignore behavior. The integration is optional: without `pi-repo-search`, all Plastic tools and skills still load and only this policy registration is omitted. It does not register workflow guidance or perform Plastic CLI readiness checks; owning `plastic_*` tools validate their own workspace and CLI requirements.
+When `@aefree/pi-file-discovery` is also loaded, Pi session startup registers the independent advisory `plastic.ignore-files` file-discovery filter through the package-qualified capability-registry rendezvous key. The packages may have separate module roots; Plastic does not import file-discovery from its own root. It discovers readable `ignore.conf` and `cloaked.conf` only from the nearest Plastic workspace to each requested root, then supplies them as ripgrep ignore files without replacing native ripgrep/Git-ignore behavior. A root is emitted only when it has at least one readable ignore/cloak file; each emitted root declares `filterDecision: "applied"`, decision code `plastic_ignore_files_applied`, and that workspace as its `filterBoundary`. No-op Plastic roots are omitted from mixed requests, and a request with no effective ignore/cloak records is `not_applicable`. The integration is optional: without `pi-file-discovery`, all Plastic tools and skills still load and no filter registry is created. Missing, malformed, or unavailable Plastic filter data degrades to generic discovery; `pi-file-discovery` owns that execution hygiene and disclosure behavior. It does not register workflow guidance or perform Plastic CLI readiness checks; owning `plastic_*` tools validate their own workspace and CLI requirements.
 
 
 ## Mutation execution
@@ -32,6 +32,7 @@ Removing the approval layer does not relax Plastic safety guards. Command allowl
 - `plastic_patch`
 - `plastic_diffRevisions`
 - `plastic_diffFile`
+- `plastic_workspaceDiff`
 - `plastic_branchCreate`
 - `plastic_switchBranch`
 - `plastic_merge`
@@ -53,7 +54,7 @@ Removing the approval layer does not relax Plastic safety guards. Command allowl
 
 ## Dynamic tool loading
 
-The package exposes 28 public `plastic_*` tools. `plastic_workspaceCreate` is intentionally not registered or discoverable until the package provides a paired, safe workspace-cleanup capability. `plastic_tool_search` is a package-owned loader that searches the explicit Plastic capability catalog, reports bounded matches and safety guidance, and additively enables selected tools for the next model request.
+The package exposes 29 public `plastic_*` tools. `plastic_workspaceCreate` is intentionally not registered or discoverable until the package provides a paired, safe workspace-cleanup capability. `plastic_tool_search` is a package-owned loader that searches the explicit Plastic capability catalog, reports bounded matches and safety guidance, and additively enables selected tools for the next model request.
 
 The default **balanced** session set keeps `plastic_tool_search`, `plastic_status`, and `plastic_currentBranch` active. The other Plastic tools remain registered but inactive until selected; built-in and other-extension tools are not removed. Previous loader additions on the active session branch are restored on startup, resume, fork, and reload.
 
@@ -62,7 +63,7 @@ For controlled comparisons, set `PI_PLASTIC_TOOL_LOADING_MODE` before starting P
 ```bash
 PI_PLASTIC_TOOL_LOADING_MODE=balanced    # default production candidate
 PI_PLASTIC_TOOL_LOADING_MODE=loader-only # maximum initial schema reduction
-PI_PLASTIC_TOOL_LOADING_MODE=all-active  # all 28 currently exposed tools; loader omitted
+PI_PLASTIC_TOOL_LOADING_MODE=all-active  # all 29 currently exposed tools; loader omitted
 ```
 
 Pi 0.82 and newer use canonical `sourceInfo` provenance to identify this package's effective tools before deferring, restoring, or activating them. If canonical provenance or ownership of the effective loader cannot be proven, `pi-plastic` fails safe: it preserves the complete current active set exactly, does not defer, remove, or activate any `plastic_*` name, and an effective package loader can only report known tools that are already active rather than activating inactive names. On sourceInfo-capable Pi instances, providers without native deferred definitions still receive the complete current active set after a loader call. Reload or restart Pi after source edits; source files are not watched automatically.
@@ -70,7 +71,7 @@ Pi 0.82 and newer use canonical `sourceInfo` provenance to identify this package
 ## Safety behavior
 
 - `plastic_branchCreate` supports an explicit parent branch independent of the loaded workspace branch, defaults relative names to the current branch when no parent is supplied, and rejects top-level paths unless `allowRootBranch=true` is explicit.
-- `plastic_diff` remains a disabled alias by design; use `plastic_diffFile` or `plastic_diffRevisions` for text-only file diffs.
+- `plastic_diff` remains a disabled alias by design; use `plastic_status` for changed-path listing, `plastic_diffFile` for one file, `plastic_workspaceDiff` for pending review, or `plastic_diffRevisions` for an explicit historical pair.
 - `plastic_patch` generates review patches with `cm patch`, including `clean` and `integration` filters for branch review workflows. It does not expose patch apply.
 - Bash safety rails block `cm diff` and unsafe interactive `cm merge --merge` usage.
 - Merge tooling surfaces Plastic `FILE_CONFLICT` records and merge-state metadata from `cm status`.
@@ -129,9 +130,9 @@ pi install -l <path-to-pi-plastic>
 - Node.js 22.19.0 or newer
 - Pi 0.82.0 or newer; the current development and eval baseline is Pi 0.83
 - Plastic SCM / Unity Version Control CLI (`cm`) available on `PATH`, or `PI_PLASTIC_CM_EXECUTABLE` set to its full executable path
-- A compatible `diff` executable available on `PATH`, or `PI_PLASTIC_DIFF_EXECUTABLE` set to its full executable path, for text-only diff and patch tools
+- GNU/POSIX-compatible `diff` available on `PATH`, or `PI_PLASTIC_DIFF_EXECUTABLE` set to its full executable path (including paths containing spaces), for text-only diff and patch tools. Pi does not discover Git Bash paths automatically.
 - A configured Plastic workspace for workspace-scoped operations
-- `@aefree/pi-repo-search` is an optional peer. When installed, it receives the Plastic ignore/cloak policy; when absent, `pi-plastic` loads without repository-search integration. The tarball does not embed linked sibling workspaces or `node_modules` paths.
+- `pi-file-discovery` is an optional independently loaded integration. When its `discover_candidate_files` tool is active, it receives the advisory Plastic ignore/cloak filter through the shared global capability protocol; when absent, `pi-plastic` loads without file-discovery filtering. The tarball does not embed linked sibling workspaces or `node_modules` paths.
 
 ## Testing
 

package/extensions/bash-cm-diff-guard.ts

@@ -6,7 +6,7 @@ import {
 } from "./shared/bash-command-guards";
 
 const BLOCK_MESSAGE =
-  "`cm diff` is blocked in Pi because it can launch a GUI window and hang CLI automation. Use `plastic_status` to list changed paths, `plastic_diffFile` for a file diff, or `plastic_diffRevisions` for two explicit revisions.";
+  "`cm diff` is blocked in Pi because it can launch a GUI window and hang CLI automation. Use `plastic_status` to list changed paths, `plastic_diffFile` for one file, `plastic_workspaceDiff` for pending review, or `plastic_diffRevisions` for two explicit revisions.";
 
 const DIRECT_CM_DIFF = /^(?:[A-Za-z_][A-Za-z0-9_]*=\S+\s+)*(?:(?:"[^"]*[\\/]cm(?:\.exe)?"|'[^']*[\\/]cm(?:\.exe)?')|(?:[^"'\s]*[\\/])?cm(?:\.exe)?)\s+diff(?:\s|$)/i;
 
@@ -24,6 +24,7 @@ function commandRunsCmDiff(command: string): boolean {
 }
 
 export const __bashCmDiffGuardInternals = {
+  blockMessage: BLOCK_MESSAGE,
   segmentRunsCmDiff,
   commandRunsCmDiff,
   stripAssignments,

package/extensions/file-discovery-filter.ts

@@ -0,0 +1,67 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { createPlasticFileDiscoveryFilterV1, loadPlasticOwnerV1 } from "../src/file-discovery-filter.ts";
+import {
+  createPlasticFileDiscoveryFilterRegistryV1,
+  type PlasticFileDiscoveryRegistrationToken,
+} from "../src/file-discovery-filter-rendezvous.ts";
+
+type ScopeRegistration = Readonly<{ token: PlasticFileDiscoveryRegistrationToken }>;
+type ScopeLifecycle = { generation: number; active: boolean };
+
+function hasFileDiscoveryTool(pi: Pick<ExtensionAPI, "getActiveTools">): boolean {
+  return pi.getActiveTools?.().includes("discover_candidate_files") ?? false;
+}
+
+/**
+ * Session-scoped optional Plastic file-discovery filter registration.
+ *
+ * Independently loaded packages rendezvous through the published global
+ * capability-registry protocol. No import is attempted from Plastic's module
+ * root, so an absent file-discovery package leaves Plastic unchanged.
+ */
+export function createPlasticFileDiscoveryFilterExtension(): (pi: ExtensionAPI) => void {
+  return (pi) => {
+    const registrations = new WeakMap<object, ScopeRegistration>();
+    const lifecycles = new WeakMap<object, ScopeLifecycle>();
+
+    pi.on("session_start", async (_event, ctx) => {
+      if (!hasFileDiscoveryTool(pi)) return;
+      const scope = ctx.sessionManager;
+      const previous = lifecycles.get(scope);
+      const lifecycle = { generation: (previous?.generation ?? 0) + 1, active: true };
+      lifecycles.set(scope, lifecycle);
+
+      const owner = await loadPlasticOwnerV1(import.meta.url);
+      // Do not revive a scope whose shutdown occurred while owner discovery was pending.
+      if (lifecycles.get(scope) !== lifecycle || !lifecycle.active) return;
+      const registry = createPlasticFileDiscoveryFilterRegistryV1();
+      const token = registry.register(scope, createPlasticFileDiscoveryFilterV1(owner));
+      // Registration succeeds before the prior token is retired, preserving a valid
+      // record if construction or validation fails. Nonces make stale retirement safe.
+      const current = registrations.get(scope);
+      if (lifecycles.get(scope) !== lifecycle || !lifecycle.active) {
+        registry.unregister(token);
+        return;
+      }
+      registrations.set(scope, Object.freeze({ token }));
+      if (current !== undefined) registry.unregister(current.token);
+    });
+    pi.on("session_shutdown", (_event, ctx) => {
+      const scope = ctx.sessionManager;
+      const lifecycle = lifecycles.get(scope);
+      if (lifecycle !== undefined) {
+        lifecycle.active = false;
+        lifecycle.generation += 1;
+      }
+      const current = registrations.get(scope);
+      if (current === undefined) return;
+      createPlasticFileDiscoveryFilterRegistryV1().unregister(current.token);
+      // A stale shutdown must not erase a replacement registration.
+      if (registrations.get(scope) === current) registrations.delete(scope);
+    });
+  };
+}
+
+export default function registerPlasticFileDiscoveryFilters(pi: ExtensionAPI): void {
+  createPlasticFileDiscoveryFilterExtension()(pi);
+}

package/index.ts

@@ -64,6 +64,7 @@ const PLASTIC_EXPORTS = [
   "patch",
   "diffRevisions",
   "diffFile",
+  "workspaceDiff",
   "branchCreate",
   "switchBranch",
   "merge",
@@ -181,6 +182,17 @@ const TOOL_CONFIG: Partial<Record<PlasticExportName, ToolConfig>> = {
       return input;
     },
   },
+  workspaceDiff: {
+    prepareArguments(args) {
+      const input = normalizeOutputFormatAlias(normalizeArgs(args));
+      normalizeWorkdirAliases(input);
+      promoteSinglePath(input);
+      assignAlias(input, "paths", ["items", "files"]);
+      assignAlias(input, "includePrivate", ["include_private"]);
+      assignAlias(input, "maxFiles", ["max_files"]);
+      return input;
+    },
+  },
   branchCreate: {
     prepareArguments(args) {
       const input = normalizeArgs(args);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aefree/pi-plastic",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "type": "module",
   "engines": {
     "node": ">=22.19.0"
@@ -17,8 +17,6 @@
     "src/",
     "references/",
     "skills/",
-    "evals/tool-loading/",
-    "tests/",
     "CHANGELOG.md",
     "CONTRIBUTING.md",
     "LICENSE",
@@ -31,24 +29,25 @@
       "./extensions/plastic-branch-status.ts",
       "./extensions/bash-cm-diff-guard.ts",
       "./extensions/bash-cm-merge-guard.ts",
-      "./extensions/repository-search-provider.ts"
+      "./extensions/file-discovery-filter.ts"
     ],
     "skills": [
       "./skills"
     ]
   },
   "scripts": {
-    "test": "npx --yes tsx tests/plastic-tool-validation.ts && npx --yes tsx tests/plastic-checkin-path-resolution.ts && npx --yes tsx tests/plastic-diff-workflow.test.ts && npx --yes tsx tests/plastic-process-lifecycle.test.ts && npx --yes tsx tests/plastic-patch-command.test.ts && npx --yes tsx tests/plastic-extension-registration.test.ts && npx --yes tsx tests/plastic-dynamic-tool-loading.test.ts && npx --yes tsx tests/plastic-tool-rendering.test.ts && npx --yes tsx tests/plastic-branch-query.test.ts && npx --yes tsx tests/plastic-workspace.test.ts && npx --yes tsx tests/plastic-mutation-execution.test.ts && npx --yes tsx tests/repository-search-provider.test.ts && npx --yes tsx tests/repository-search-provider-registration.test.ts && npx --yes tsx tests/packed-copy-owner-conflict.test.ts && npx --yes tsx tests/plastic-branch-status.test.ts && npx --yes tsx tests/plastic-constrained-sampling.test.ts && npx --yes tsx tests/bash-cm-diff-guard-validation.ts",
+    "test": "npx --yes tsx tests/plastic-tool-validation.ts && npx --yes tsx tests/plastic-checkin-path-resolution.ts && npx --yes tsx tests/plastic-diff-workflow.test.ts && npx --yes tsx tests/plastic-workspace-diff.test.ts && npx --yes tsx tests/plastic-process-lifecycle.test.ts && npx --yes tsx tests/plastic-patch-command.test.ts && npx --yes tsx tests/plastic-extension-registration.test.ts && npx --yes tsx tests/plastic-dynamic-tool-loading.test.ts && npx --yes tsx tests/plastic-tool-rendering.test.ts && npx --yes tsx tests/plastic-branch-query.test.ts && npx --yes tsx tests/plastic-workspace.test.ts && npx --yes tsx tests/plastic-mutation-execution.test.ts && npx --yes tsx tests/file-discovery-filter.test.ts && npx --yes tsx tests/file-discovery-filter-registration.test.ts && npx --yes tsx tests/packed-copy-owner-conflict.test.ts && npx --yes tsx tests/plastic-branch-status.test.ts && npx --yes tsx tests/plastic-constrained-sampling.test.ts && npx --yes tsx tests/bash-cm-diff-guard-validation.ts",
     "test:live": "npx --yes tsx tests/plastic-live-smoke.test.ts",
     "test:live:branch-create": "npx --yes tsx tests/plastic-branch-create-live.test.ts",
     "eval:tool-loading": "npx --yes tsx evals/tool-loading/run-eval.ts"
   },
   "devDependencies": {
+    "@aefree/pi-file-discovery": "^0.1.1",
     "@earendil-works/pi-coding-agent": "0.83.0",
     "typebox": "^1.3.8"
   },
   "peerDependencies": {
-    "@aefree/pi-repo-search": "^0.1.0",
+    "@aefree/pi-file-discovery": "^0.1.0",
     "@earendil-works/pi-coding-agent": "*",
     "typebox": "*"
   },
@@ -56,14 +55,14 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+ssh://git@github.com/aefreedman/pi-plastic.git"
+    "url": "git+https://github.com/aefreedman/pi-plastic.git"
   },
   "bugs": {
     "url": "https://github.com/aefreedman/pi-plastic/issues"
   },
   "homepage": "https://github.com/aefreedman/pi-plastic#readme",
   "peerDependenciesMeta": {
-    "@aefree/pi-repo-search": {
+    "@aefree/pi-file-discovery": {
       "optional": true
     },
     "@earendil-works/pi-coding-agent": {

package/skills/_shared/references/conventional-commits.md

@@ -1,198 +1,198 @@
-# Conventional Commits
-
-This reference file documents the conventional commit format used across the project.
-
----
-
-## Format
-
-```
-<type>(<scope>): <subject>
-
-[optional body]
-
-[optional footer]
-```
-
----
-
-## Types
-
-| Type | Description | Example |
-|------|-------------|---------|
-| **feat** | New feature | `feat(auth): add OAuth login` |
-| **fix** | Bug fix | `fix(cart): calculate tax correctly` |
-| **refactor** | Code restructuring (no behavior change) | `refactor(api): extract service layer` |
-| **perf** | Performance improvement | `perf(query): optimize user lookup` |
-| **test** | Adding or updating tests | `test(auth): add login edge cases` |
-| **docs** | Documentation changes | `docs(readme): update installation steps` |
-| **style** | Code style changes (formatting, etc.) | `style(lint): fix indentation` |
-| **chore** | Build process or auxiliary tool changes | `chore(deps): update to Rails 7.1` |
-| **ci** | CI/CD configuration changes | `ci(github): add test workflow` |
-
----
-
-## Scope
-
-The scope is optional but recommended. It specifies which part of the codebase was affected:
-
-**Examples:**
-- `feat(player): add dash mechanic`
-- `fix(inventory): prevent negative quantities`
-- `refactor(ui): simplify menu navigation`
-- `perf(rendering): batch sprite draws`
-
-**Guidelines:**
-- Use lowercase
-- Be specific but concise
-- Match your module/component names
-- Omit if change is global
-
----
-
-## Subject
-
-The subject contains a succinct description of the change:
-
-- **Use imperative mood:** "add" not "added" or "adds"
-- **Don't capitalize first letter:** "add feature" not "Add feature"
-- **No period at the end:** "fix bug" not "fix bug."
-- **Limit to 50 characters**
-
-**Good examples:**
-- `feat(auth): add password reset flow`
-- `fix(api): handle null responses`
-- `refactor(utils): extract string helpers`
-
-**Bad examples:**
-- `feat(auth): Added password reset flow` (not imperative)
-- `feat(auth): Add Password Reset Flow` (capitalized)
-- `feat(auth): add password reset flow.` (period at end)
-
----
-
-## Body (Optional)
-
-Use the body to explain **what** and **why**, not **how**:
-
-```
-feat(player): add dash mechanic
-
-Adds a dash ability to the player character for enhanced mobility.
-Dash has 1-second cooldown and consumes 10 stamina.
-
-Closes #42
-```
-
-**Guidelines:**
-- Wrap at 72 characters
-- Separate from subject with blank line
-- Focus on context and reasoning
-- Link to issues if applicable
-
----
-
-## Footer (Optional)
-
-Use footer for metadata:
-
-**Breaking changes:**
-```
-feat(api)!: change authentication endpoint
-
-BREAKING CHANGE: /api/login now requires email instead of username
-```
-
-**Issue references:**
-```
-fix(cart): calculate tax correctly
-
-Fixes #123
-Closes #124
-Related to #125
-```
-
-**Attribution:**
-```
-feat(dashboard): add analytics widget
-
-Co-Authored-By: <AI Assistant Name (e.g., Codex, Claude, Pi Coding Agent)>
-```
-
----
-
-## Attribution Footer
-
-Add a simple attribution line in the footer when needed:
-
-```
-feat(feature): implement new capability
-
-[Body explaining the change]
-
-Co-Authored-By: <AI Assistant Name (e.g., Codex, Claude, Pi Coding Agent)>
-```
-
----
-
-## Examples
-
-### Simple Feature
-```
-feat(player): add jump mechanic
-```
-
-### Bug Fix with Context
-```
-fix(inventory): prevent item duplication
-
-Items were duplicating when rapidly clicking the pickup button.
-Added debounce logic to prevent double-processing.
-
-Fixes #156
-```
-
-### Refactor with Explanation
-```
-refactor(rendering): extract camera controller
-
-Moved camera logic from PlayerController to dedicated CameraController
-for better separation of concerns and reusability.
-```
-
-### Performance Improvement
-```
-perf(physics): optimize collision detection
-
-Changed from O(n²) all-pairs check to spatial hashing.
-Reduces frame time by ~15ms with 100+ objects.
-```
-
-### Attribution Example
-```
-feat(multiplayer): add lobby system
-
-Implements matchmaking lobby with room creation, joining, and ready-up.
-Uses WebSocket for real-time updates.
-
-Closes #89
-
-Co-Authored-By: <AI Assistant Name (e.g., Codex, Claude, Pi Coding Agent)>
-```
-
----
-
-## Usage in Skills
-
-**Reference this file when:**
-- Creating commits (Git or Plastic)
-- Generating commit messages
-- Validating commit format
-- Writing PR/code review descriptions
-
-**Load this file:**
-```markdown
-Load conventional commit format from ../../_shared/references/conventional-commits.md
-```
-
-Then format all commits according to this standard.
+# Conventional Commits
+
+This reference file documents the conventional commit format used across the project.
+
+---
+
+## Format
+
+```
+<type>(<scope>): <subject>
+
+[optional body]
+
+[optional footer]
+```
+
+---
+
+## Types
+
+| Type | Description | Example |
+|------|-------------|---------|
+| **feat** | New feature | `feat(auth): add OAuth login` |
+| **fix** | Bug fix | `fix(cart): calculate tax correctly` |
+| **refactor** | Code restructuring (no behavior change) | `refactor(api): extract service layer` |
+| **perf** | Performance improvement | `perf(query): optimize user lookup` |
+| **test** | Adding or updating tests | `test(auth): add login edge cases` |
+| **docs** | Documentation changes | `docs(readme): update installation steps` |
+| **style** | Code style changes (formatting, etc.) | `style(lint): fix indentation` |
+| **chore** | Build process or auxiliary tool changes | `chore(deps): update to Rails 7.1` |
+| **ci** | CI/CD configuration changes | `ci(github): add test workflow` |
+
+---
+
+## Scope
+
+The scope is optional but recommended. It specifies which part of the codebase was affected:
+
+**Examples:**
+- `feat(player): add dash mechanic`
+- `fix(inventory): prevent negative quantities`
+- `refactor(ui): simplify menu navigation`
+- `perf(rendering): batch sprite draws`
+
+**Guidelines:**
+- Use lowercase
+- Be specific but concise
+- Match your module/component names
+- Omit if change is global
+
+---
+
+## Subject
+
+The subject contains a succinct description of the change:
+
+- **Use imperative mood:** "add" not "added" or "adds"
+- **Don't capitalize first letter:** "add feature" not "Add feature"
+- **No period at the end:** "fix bug" not "fix bug."
+- **Limit to 50 characters**
+
+**Good examples:**
+- `feat(auth): add password reset flow`
+- `fix(api): handle null responses`
+- `refactor(utils): extract string helpers`
+
+**Bad examples:**
+- `feat(auth): Added password reset flow` (not imperative)
+- `feat(auth): Add Password Reset Flow` (capitalized)
+- `feat(auth): add password reset flow.` (period at end)
+
+---
+
+## Body (Optional)
+
+Use the body to explain **what** and **why**, not **how**:
+
+```
+feat(player): add dash mechanic
+
+Adds a dash ability to the player character for enhanced mobility.
+Dash has 1-second cooldown and consumes 10 stamina.
+
+Closes #42
+```
+
+**Guidelines:**
+- Wrap at 72 characters
+- Separate from subject with blank line
+- Focus on context and reasoning
+- Link to issues if applicable
+
+---
+
+## Footer (Optional)
+
+Use footer for metadata:
+
+**Breaking changes:**
+```
+feat(api)!: change authentication endpoint
+
+BREAKING CHANGE: /api/login now requires email instead of username
+```
+
+**Issue references:**
+```
+fix(cart): calculate tax correctly
+
+Fixes #123
+Closes #124
+Related to #125
+```
+
+**Attribution:**
+```
+feat(dashboard): add analytics widget
+
+Co-Authored-By: <AI Assistant Name (e.g., Codex, Claude, Pi Coding Agent)>
+```
+
+---
+
+## Attribution Footer
+
+Add a simple attribution line in the footer when needed:
+
+```
+feat(feature): implement new capability
+
+[Body explaining the change]
+
+Co-Authored-By: <AI Assistant Name (e.g., Codex, Claude, Pi Coding Agent)>
+```
+
+---
+
+## Examples
+
+### Simple Feature
+```
+feat(player): add jump mechanic
+```
+
+### Bug Fix with Context
+```
+fix(inventory): prevent item duplication
+
+Items were duplicating when rapidly clicking the pickup button.
+Added debounce logic to prevent double-processing.
+
+Fixes #156
+```
+
+### Refactor with Explanation
+```
+refactor(rendering): extract camera controller
+
+Moved camera logic from PlayerController to dedicated CameraController
+for better separation of concerns and reusability.
+```
+
+### Performance Improvement
+```
+perf(physics): optimize collision detection
+
+Changed from O(n²) all-pairs check to spatial hashing.
+Reduces frame time by ~15ms with 100+ objects.
+```
+
+### Attribution Example
+```
+feat(multiplayer): add lobby system
+
+Implements matchmaking lobby with room creation, joining, and ready-up.
+Uses WebSocket for real-time updates.
+
+Closes #89
+
+Co-Authored-By: <AI Assistant Name (e.g., Codex, Claude, Pi Coding Agent)>
+```
+
+---
+
+## Usage in Skills
+
+**Reference this file when:**
+- Creating commits (Git or Plastic)
+- Generating commit messages
+- Validating commit format
+- Writing PR/code review descriptions
+
+**Load this file:**
+```markdown
+Load conventional commit format from ../../_shared/references/conventional-commits.md
+```
+
+Then format all commits according to this standard.