@event4u/agent-config 1.9.1

package/CHANGELOG.md

@@ -0,0 +1,279 @@
+# Changelog
+
+All notable changes to `event4u/agent-config` are documented here.
+Format loosely follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
+versioning policy is documented in [CONTRIBUTING.md](CONTRIBUTING.md#versioning-policy).
+
+> Entries before 1.3.3 were reconstructed from git history after the fact.
+> Early releases did not maintain release notes.
+
+## [Unreleased]
+
+### Added
+- `scripts/install` — a bash orchestrator that is now the **primary
+  installer entry point**. It chains the two real stages in order:
+  `scripts/install.sh` (payload sync) and `scripts/install.py` (bridge
+  files). The orchestrator exposes `--profile`, `--force`, `--dry-run`,
+  `--verbose`, `--quiet`, `--skip-sync`, and `--skip-bridges` and forwards
+  them correctly to each stage. Bridges are skipped gracefully when
+  Python 3 is unavailable; the payload sync still runs.
+- `tests/test_install_orchestrator.sh` — integration tests for the new
+  orchestrator, the Composer wrapper, and the npm postinstall hook.
+  Wired into `task test`, `task test-install`, and GitHub Actions.
+
+### Changed
+- `scripts/install.sh` no longer invokes the Python bridge installer
+  internally. It now handles payload sync exclusively. Direct callers
+  that relied on the side effect must run `scripts/install` or invoke
+  `scripts/install.py` themselves.
+- `scripts/postinstall.sh` (npm hook) routes through `scripts/install`
+  instead of `scripts/install.sh`. Exit-0-with-loud-error contract is
+  preserved.
+- `docs/installation.md` and `README.md` document the two-stage
+  pipeline and use `scripts/install` as the canonical invocation.
+
+### Fixed
+- `bin/install.php` now delegates to `scripts/install`. Previous
+  versions shelled into `scripts/install.py` only, which meant Composer
+  users never got the payload sync — no `.augment/` tree, no tool
+  directories, no `.windsurfrules`. This latent bug is fixed with the
+  new routing.
+
+### Removed
+- **Observability, feedback, and lifecycle scaffolding.** Road-to-9
+  Phase 4 resolved the "fake depth" layers. Every module that had no
+  production consumer was removed; the dispatcher + shell handler
+  (Phase 1) stays as the only real runtime path. Deleted scripts:
+  `runtime_pipeline`, `runtime_session`, `runtime_execute`,
+  `runtime_errors`, `runtime_metrics`, `runtime_events`,
+  `runtime_logger`, `runtime_hooks`, `feedback_collector`,
+  `feedback_governance`, `skill_lifecycle`, `report_generator`,
+  `persistence`, `event_schema` (≈ 2 000 LoC) plus their tests and
+  Taskfile targets (`runtime-execute`, `lifecycle-report`,
+  `lifecycle-health`, `report`, `report-stdout`). The `lifecycle`
+  frontmatter field on individual skills is kept — it is still a lint
+  signal.
+- Stale design docs describing the removed layers:
+  `docs/observability.md`, `agents/docs/observability-scoping.md`,
+  `agents/docs/feedback-consumption.md`,
+  `agents/docs/runtime-visibility.md`.
+
+### Added (CI)
+- `scripts/runtime_dispatcher.py run` learned `--output FILE`,
+  persisting the `ExecutionResult` as JSON. `scripts/ci_summary.py` was
+  rewritten to consume those files and render a GitHub Step Summary
+  (Markdown table + failure details with stderr tail). `tests.yml`
+  wires the two together, so failing pilot skills now show up in the
+  PR UI even when the job itself fails.
+
+## [1.4.0] — 2026-04-18
+
+### Added
+- **`.agent-src/` replaces `.augment/` as the canonical compressed directory
+  shipped in the package.** The new name is tool-agnostic. The installer on
+  the consumer side still writes into `.augment/`, unchanged.
+- `.augment/` is now a **local projection** of `.agent-src/` for Augment Code
+  (gitignored in this repo, rebuilt by `task sync`). Rules are copied (Augment
+  Code cannot load symlinked rules); everything else is symlinked to save
+  space.
+- `scripts/install.sh` and `scripts/install.py` now read from vendor's
+  `.agent-src/` with automatic fallback to `.augment/` for pre-2.0 packages.
+- `task project-augment` — rebuild the `.augment/` projection from `.agent-src/`.
+- MIT License file in the repository root (previously `license: proprietary` in
+  `composer.json` with no `LICENSE` file).
+- Root-level package docs (`AGENTS.md`, `.github/copilot-instructions.md`) are
+  now the package's own meta docs; consumer scaffolding comes from
+  `.augment/templates/` via the installer or `/copilot-agents-init`.
+- `scripts/install.py` is the canonical installer; `scripts/install.sh` and
+  `bin/install.php` remain as thin compatibility wrappers.
+- Portability checker (`scripts/check_portability.py`) now covers root-level
+  files and supports an optional `AGENT_CONFIG_BLOCKLIST` env var for
+  downstream forks that need to enforce legacy-identifier bans.
+- `/copilot-agents-init` command to scaffold `AGENTS.md` +
+  `.github/copilot-instructions.md` from scratch in consumer projects.
+- `/copilot-agents-optimize` now scans for legacy identifiers from prior
+  repo names, stack drift, and dead commands before deduplicating.
+
+### Changed
+- `composer.json` and `package.json` now declare `license: MIT` (previously
+  `proprietary` / `UNLICENSED`).
+- Experimental layers (runtime, tool adapters, observability) are now clearly
+  labeled in `README.md` and the architecture docs.
+- **Distribution slim-down.** Added `.gitattributes export-ignore` entries
+  and an explicit `files` whitelist in `package.json`. Composer archives
+  drop from 1221 to 433 files (4.45 MB → 1.79 MB); the npm tarball contains
+  313 files (483 kB packed). Dev-only directories (`tests/`, `agents/`,
+  `.agent-src.uncompressed/`, tool mirrors) no longer ship to consumers.
+- **Architecture docs restructured.** Layer 4–6 (observability, feedback,
+  lifecycle) moved out of `docs/architecture.md` into a dedicated opt-in
+  `docs/observability.md`. The main architecture page now focuses on the
+  stable Rules/Skills/Runtime layers.
+- **`ide` default neutralized** in `config/agent-settings.template.ini`:
+  was `ide=phpstorm`, now empty. Consumers fill it in if they want
+  auto-open behavior; empty means the file-editor skill stays inert.
+
+### CI
+- Test matrix expanded: Python 3.10 / 3.11 / 3.12 / 3.13 on `ubuntu-latest`
+  plus Python 3.12 on `macos-latest`. `install.sh` integration tests run on
+  both OS. Matrix enforces the "Python 3.10+, stdlib only" guarantee from
+  `CONTRIBUTING.md`. Documented under `docs/development.md#ci-test-matrix`.
+
+### Community
+- **Maintainer team documented.** `CONTRIBUTING.md` now lists the
+  event4u team (@matze4u lead, @h3xa2, @php-jesus, @phpjob) instead of
+  claiming "single author". Bus-factor is now 2 (Owner + Maintain role).
+- **GitHub Discussions** referenced from `CONTRIBUTING.md` as the channel
+  for scope questions; Issues remain for bugs and feature requests.
+
+### Removed
+- Hardcoded `galawork` references removed from installer and portability
+  checker. No public release ever shipped the legacy `# galawork/agent-config`
+  gitignore marker, so the in-place migration path was also removed.
+
+## [1.3.3] — 2026-04-17
+
+### Changed
+- Plugin name renamed from `governed-agent-system` to `agent-config`.
+
+### Fixed
+- Plugin install commands corrected in README.
+
+## [1.3.2] — 2026-04-17
+
+### Fixed
+- Resolved 10 broken cross-references in roadmap documents.
+
+## [1.3.1] — 2026-04-17
+
+### Added
+- PHP installer (`bin/install.php`) and versioned profile presets.
+- First-run experience script and `docs/getting-started.md`.
+- Marketplace manifests for Augment CLI, Claude Code, and Copilot CLI.
+- Quickstart-first README structure.
+- Standalone documentation pages under `docs/`:
+  `installation.md`, `architecture.md`, `development.md`, `customization.md`,
+  `quality.md`.
+
+### Changed
+- Tool matrix in README differentiates native vs. reference-based command
+  support (`☑️` for the latter).
+- Installation default shifted to project-installed; plugin install is
+  optional for global use.
+
+## [1.3.0] — 2026-04-17
+
+### Added
+- Experimental layers: runtime execution pipeline, tool adapters (GitHub,
+  Jira), observability (persistence, event schema, CLI reports), feedback
+  collector, and skill lifecycle management.
+- `cost_profile` setting (`minimal`, `balanced`, `full`, `custom`) as the
+  primary knob for token/output control.
+- Governance: `upstream-contribute` skill + command,
+  `improve-before-implement` rule, `validate-feature-fit` skill.
+
+### Changed
+- README rewritten to describe the governed agent system.
+
+## [1.2.2] — 2026-04-17
+
+### Fixed
+- `test_install.sh` updated for the `php-coder` skill name.
+
+## [1.2.1] — 2026-04-17
+
+### Added
+- `package-ci-checks` rule + optimized CI task order.
+
+### Fixed
+- `test_install.sh` skill name fix (initial attempt).
+
+## [1.2.0] — 2026-04-17
+
+### Added
+- Linter: execution quality checks, verification maturity mapping, type
+  boundary enforcement, section-based detection, governance/packaging
+  consistency checks.
+- `upstream-contribute` skill + command.
+
+### Fixed
+- CI pipeline failures across multiple checks.
+- Commands no longer overwrite same-name skill symlinks.
+- Missing settings added to the `.agent-settings` template.
+
+## [1.1.1] — 2026-04-16
+
+### Fixed
+- Trailing newlines in 36 command files.
+- Linter bug causing false positives.
+
+## [1.1.0] — 2026-04-16
+
+### Added
+- `readme-reviewer`, `readme-writing`, and `readme-writing-package` skills.
+- README quality linter integrated into CI.
+- Skill improvement pipeline (all 5 phases).
+- Compression quality checker, cross-reference checker, portability checker.
+- `size-and-scope` guideline, `size-enforcement` and `rule-type-governance`
+  rules.
+- `preservation-guard` rule for merges and compression.
+- Phase 3 observability work + feedback category tags.
+- `developer-like-execution` skill and `think-before-action` rule.
+
+### Changed
+- Major README rewrite: governed AI development layer positioning.
+- Portability checker auto-detects project identifiers.
+
+## [1.0.4] — 2026-04-15
+
+### Fixed
+- npm install (#1).
+- Address PR bot feedback.
+- Drop unnecessary `bash -c` wrapper for phpunit in `docker-commands`.
+
+## [1.0.3] — 2026-04-14
+
+### Fixed
+- Address Copilot PR review feedback.
+
+## [1.0.2] — 2026-04-14
+
+### Fixed
+- Handle `realpath` without `--relative-to` support (BusyBox/Alpine).
+
+## [1.0.1] — 2026-04-14
+
+### Added
+- `setup.sh` for automatic post-install/update hook registration.
+- `setup.sh` auto-detects JSON tool (`php → node → jq → python3`).
+
+### Changed
+- Install as dev dependency (documented).
+
+## [1.0.0] — 2026-04-14
+
+Initial public release.
+
+### Added
+- `.augment/` governance content: rules, skills, commands, guidelines,
+  templates.
+- `scripts/install.sh` with symlink strategy, stale symlink cleanup, and
+  per-tool directory layout.
+- `/package-test` and `/package-reset` commands.
+- Initial README with installation instructions for all supported package
+  managers.
+
+[Unreleased]: https://github.com/event4u-app/agent-config/compare/1.3.3...HEAD
+[1.3.3]: https://github.com/event4u-app/agent-config/compare/1.3.2...1.3.3
+[1.3.2]: https://github.com/event4u-app/agent-config/compare/1.3.1...1.3.2
+[1.3.1]: https://github.com/event4u-app/agent-config/compare/1.3.0...1.3.1
+[1.3.0]: https://github.com/event4u-app/agent-config/compare/1.2.2...1.3.0
+[1.2.2]: https://github.com/event4u-app/agent-config/compare/1.2.1...1.2.2
+[1.2.1]: https://github.com/event4u-app/agent-config/compare/1.2.0...1.2.1
+[1.2.0]: https://github.com/event4u-app/agent-config/compare/1.1.1...1.2.0
+[1.1.1]: https://github.com/event4u-app/agent-config/compare/1.1.0...1.1.1
+[1.1.0]: https://github.com/event4u-app/agent-config/compare/1.0.4...1.1.0
+[1.0.4]: https://github.com/event4u-app/agent-config/compare/1.0.3...1.0.4
+[1.0.3]: https://github.com/event4u-app/agent-config/compare/1.0.2...1.0.3
+[1.0.2]: https://github.com/event4u-app/agent-config/compare/1.0.1...1.0.2
+[1.0.1]: https://github.com/event4u-app/agent-config/compare/1.0.0...1.0.1
+[1.0.0]: https://github.com/event4u-app/agent-config/releases/tag/1.0.0

package/CONTRIBUTING.md

@@ -0,0 +1,176 @@
+# Contributing
+
+Thanks for considering a contribution to `event4u/agent-config`. This file
+describes how to propose changes and what the package's conventions are.
+
+## Status and scope
+
+The package is maintained by a small team at event4u:
+[@matze4u](https://github.com/matze4u) (lead),
+[@h3xa2](https://github.com/h3xa2),
+[@php-jesus](https://github.com/php-jesus),
+and [@phpjob](https://github.com/phpjob).
+
+External contributions — bug reports, typo fixes, skill improvements,
+documentation PRs, and new skills / rules — are welcome. Larger changes
+(breaking changes, new architectural layers, new tool adapters) should
+start with an [issue](https://github.com/event4u-app/agent-config/issues)
+or a [discussion](https://github.com/event4u-app/agent-config/discussions)
+so we can align on direction before code is written.
+
+If you are unsure whether a change is in scope: open a discussion first.
+
+## Dependency direction — no circular deps with `agent-memory`
+
+`agent-config` is the upstream, standalone package. It must **never**
+hard-depend on `@event4u/agent-memory`. The optional companion package
+is declared in `suggest` (Composer) / `optionalDependencies` or
+documentation only (npm) — never as a runtime or dev dependency that
+`composer install` / `npm install` would pull automatically.
+
+Reasoning: `agent-memory` depends on `agent-config` for its skills and
+governance. Reversing that would create a circular dependency and break
+installs in consumer projects that only want the rule/skill layer.
+
+See [`agents/roadmaps/road-to-memory-self-consumption.md`](agents/roadmaps/road-to-memory-self-consumption.md)
+for the full conflict-resolution contract between the two packages.
+
+## Quick start for contributors
+
+```bash
+git clone https://github.com/event4u-app/agent-config.git
+cd agent-config
+task ci            # full pipeline — must be green before PR
+```
+
+All checks must pass before a PR is merged:
+`sync-check`, `consistency`, `check-compression`, `check-refs`,
+`check-portability`, `lint-skills`, `test`, `lint-readme`.
+
+## Source of truth
+
+- **Edit** `.agent-src.uncompressed/` — the authoring layer with verbose content.
+- **Do not edit** `.agent-src/` directly — it is the compressed output shipped
+  in the package, generated from the uncompressed layer by `task sync`.
+- **Do not edit** `.augment/` directly either — it is a local projection of
+  `.agent-src/` for Augment Code (gitignored), rebuilt by `task sync`.
+- **Do not edit** `.claude/`, `.cursor/`, `.clinerules/`, `.windsurfrules` —
+  they are generated projections for specific tools.
+
+Helper commands:
+
+```bash
+task sync             # .agent-src.uncompressed/ → .agent-src/, then project → .augment/
+task generate-tools   # Regenerate .claude/, .cursor/, .clinerules/, .windsurfrules
+task test             # pytest tests/ + installer integration tests
+task lint-skills      # python3 scripts/skill_linter.py --all
+```
+
+## Branches, commits, and PRs
+
+- Branch off `main`: `feat/short-description`, `fix/short-description`,
+  `docs/short-description`, `chore/short-description`.
+- Use [Conventional Commits](https://www.conventionalcommits.org/) for commit
+  messages. Scope is optional but helpful — common scopes are `skills`,
+  `rules`, `commands`, `installer`, `ci`, `docs`.
+- Keep commits focused. Split mechanical renames from logic changes.
+- Open the PR against `main` with a short description of the change,
+  motivation, and any notes for reviewers.
+
+## Adding or editing skills, rules, and commands
+
+- Skills, rules, and commands live in `.agent-src.uncompressed/`.
+- Each skill must pass `task lint-skills` — frontmatter, structure, size
+  budgets, and self-containment are enforced by the linter.
+- Size budgets are enforced by the `size-enforcement` rule and the linter.
+  See [`size-enforcement`](.agent-src/rules/size-enforcement.md)
+  for the current limits.
+- After editing content under `.agent-src.uncompressed/`, run `task sync` so
+  `.agent-src/`, `.augment/`, and the tool-specific projections stay in sync.
+- Skills must remain project-agnostic. Nothing in `.agent-src/` may reference a
+  specific consumer project, domain, or stack. The
+  [`augment-portability`](.agent-src/rules/augment-portability.md) rule and
+  `scripts/check_portability.py` enforce this in CI.
+
+## Installer and Python tooling
+
+- Primary installer entry point: `scripts/install` (bash orchestrator).
+  It chains `scripts/install.sh` (payload sync) and `scripts/install.py`
+  (bridge files). `bin/install.php` and `scripts/postinstall.sh` are
+  thin wrappers that route through the orchestrator.
+- Each stage stays independently callable (`bash scripts/install.sh`,
+  `python3 scripts/install.py`) and has its own CLI.
+- Python scripts must work on Python 3.10+ with only the standard library.
+  No third-party runtime dependencies.
+- Add integration tests to `tests/test_install.sh` (payload sync) or
+  `tests/test_install_orchestrator.sh` (orchestrator + wrappers), and
+  Python unit tests under `tests/`.
+
+## Versioning policy
+
+The package follows [Semantic Versioning](https://semver.org). Because the
+surface is mostly content (rules, skills, commands) rather than a classic API,
+the policy is interpreted as follows:
+
+| Bump | Triggers |
+|---|---|
+| **Major** (X.0.0) | Installer layout changes (files created/removed), breaking changes to `.agent-settings.yml` keys, removal of rules or skills that downstream projects relied on, breaking changes to the compressed content format. |
+| **Minor** (x.X.0) | New skills, rules, commands, or guidelines. New tool support. New installer flags. New `.agent-settings.yml` keys with safe defaults. |
+| **Patch** (x.x.X) | Wording fixes and improvements in existing skills, linter fixes, CI changes, documentation updates, internal refactors with no user-visible effect. |
+
+Release notes live in [`CHANGELOG.md`](CHANGELOG.md) and are generated
+automatically by [release-please](https://github.com/googleapis/release-please)
+from [Conventional Commits](#commit-conventions). Contributors do **not** edit
+the changelog by hand; writing clean commit subjects is how notes are authored.
+
+### Release process
+
+Releases are fully automated by the
+[release-please workflow](.github/workflows/release-please.yml):
+
+1. Every push to `main` triggers release-please. It scans Conventional Commits
+   since the last tag and opens (or updates) a **Release PR** — a single PR
+   that bumps `package.json`, `.claude-plugin/marketplace.json`, and
+   `CHANGELOG.md` in one atomic commit.
+2. Review the Release PR when you're ready to ship. Merging it makes
+   release-please push the matching git tag and create the GitHub Release.
+3. On the same workflow run, the `publish-npm` job takes over: it checks
+   out the tagged commit, verifies `package.json.version == tag`, and runs
+   `npm publish` against https://registry.npmjs.org with
+   [npm provenance](https://docs.npmjs.com/generating-provenance-statements)
+   so each tarball is cryptographically linked to the GitHub Actions run that
+   built it.
+4. The [Release Guard workflow](.github/workflows/release-guard.yml) runs on
+   the pushed tag and fails loudly if `package.json.version` or
+   `.claude-plugin/marketplace.json` disagree with the tag — an independent
+   cross-check that stays in place even with release-please driving the flow.
+
+Bump size is derived from commit types:
+`feat:` → minor, `fix:` → patch, `feat!:` / `fix!:` / `BREAKING CHANGE:` → major.
+Commits like `chore:`, `docs:`, `test:`, `ci:`, `refactor:` do not bump the
+version on their own and ride along in the next Release PR.
+
+#### Required repository secrets
+
+| Secret | Purpose |
+|---|---|
+| `NPM_TOKEN` | Granular Access Token for `@event4u/agent-config` with read-write scope. Used by the `publish-npm` job. Create in [npm → Access Tokens](https://www.npmjs.com/settings/event4u/tokens) and store under `Settings → Secrets and variables → Actions`. |
+
+#### Fallback: manual bump
+
+`task release:bump -- X.Y.Z` is kept as an emergency fallback for the rare
+case where release-please is unavailable (workflow disabled, GitHub outage,
+hotfix on a branch other than `main`). In normal operation, do not use it —
+let the Release PR drive every version change. A manual bump does **not**
+publish to npm automatically; run `npm publish` locally after tagging.
+
+## License of contributions
+
+By contributing you agree that your contributions are licensed under the
+[MIT License](LICENSE) that covers the rest of the project.
+
+## Code of conduct
+
+Be kind. Assume good intent. Criticize code, not people. Contributions that
+carry personal attacks or harassment will not be merged, regardless of their
+technical value.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 event4u
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.