docs: implement PLAN_NEXT wave 2 docs and governance

.agents/skills/README.md

@@ -0,0 +1,10 @@
+# Skills Directory Notice
+
+`.agents/skills/` is public transparency content for Wrkr contributor/automation workflows.
+
+Requirements:
+
+1. No secrets, private tokens, or non-public operational endpoints in skill files.
+2. Keep instructions deterministic, contract-safe, and fail-closed.
+3. Use only repository-scoped, auditable command guidance.
+4. Follow governance policy: [`docs/governance/content-visibility.md`](../../docs/governance/content-visibility.md).

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,50 @@
+name: Bug report
+description: Report a reproducible Wrkr defect with contract and environment context.
+title: "[bug] "
+labels:
+  - bug
+body:
+  - type: markdown
+    attributes:
+      value: "Use this template for deterministic reproduction and contract-safe triage."
+  - type: textarea
+    id: summary
+    attributes:
+      label: Summary
+      description: One-sentence defect summary.
+      placeholder: wrkr regress run returns exit 1 instead of exit 5 for drift.
+    validations:
+      required: true
+  - type: textarea
+    id: repro_steps
+    attributes:
+      label: Reproduction steps
+      description: Exact commands and inputs.
+      placeholder: |
+        1. wrkr scan --path ... --json
+        2. wrkr regress init --baseline ... --json
+        3. wrkr regress run --baseline ... --json
+    validations:
+      required: true
+  - type: textarea
+    id: expected_actual
+    attributes:
+      label: Expected vs actual
+      description: Include expected exit code, JSON envelope, and actual output.
+    validations:
+      required: true
+  - type: textarea
+    id: contract_surface
+    attributes:
+      label: Contract surface affected
+      description: Specify CLI flags, JSON keys, schemas, or exit codes impacted.
+      placeholder: exit-code contract, docs/commands/regress.md, schemas/v1/state.schema.json
+    validations:
+      required: true
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: OS, Go version, Wrkr version/commit, and install path.
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security report
+    url: https://github.com/Clyra-AI/wrkr/security/policy
+    about: Use SECURITY.md process for vulnerabilities.

.github/ISSUE_TEMPLATE/docs_change.yml

@@ -0,0 +1,28 @@
+name: Docs improvement
+description: Request a docs correction or workflow clarification.
+title: "[docs] "
+labels:
+  - documentation
+body:
+  - type: textarea
+    id: gap
+    attributes:
+      label: Documentation gap
+      description: What is ambiguous, missing, or incorrect?
+    validations:
+      required: true
+  - type: textarea
+    id: source_of_truth
+    attributes:
+      label: Source-of-truth location
+      description: Which canonical file should be changed? (for example README.md, docs/commands/*, docs/map.md)
+    validations:
+      required: true
+  - type: textarea
+    id: validation
+    attributes:
+      label: Validation commands
+      description: Which docs checks should pass after the change?
+      placeholder: make test-docs-consistency && make test-docs-storyline
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,43 @@
+name: Feature request
+description: Propose a new capability with deterministic and contract impact analysis.
+title: "[feature] "
+labels:
+  - enhancement
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem statement
+      description: What operator or governance problem are you solving?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed behavior
+      description: Describe command behavior and expected outputs.
+    validations:
+      required: true
+  - type: textarea
+    id: contract_impact
+    attributes:
+      label: Contract impact
+      description: Note any expected changes to flags, JSON, schemas, exit codes, or docs.
+      placeholder: additive JSON field in scan --json payload
+    validations:
+      required: true
+  - type: textarea
+    id: tests
+    attributes:
+      label: Test expectations
+      description: Specify required lanes and test classes (unit/integration/e2e/contracts/docs).
+      placeholder: fast + core + contract tests
+    validations:
+      required: true
+  - type: textarea
+    id: risks
+    attributes:
+      label: Risks and non-goals
+      description: List determinism/fail-closed/security risks and out-of-scope items.
+    validations:
+      required: true

.github/pull_request_template.md

@@ -0,0 +1,42 @@
+## Summary
+
+Describe the change and operator impact.
+
+## Contract Impact
+
+- [ ] No public contract changes (flags/JSON/schema/exits/help/docs)
+- [ ] Public contract changes are included and documented below
+
+Contract details:
+
+- CLI/flags/help changes:
+- JSON output changes:
+- Schema/versioning changes:
+- Exit code behavior changes:
+
+## Tests and Lane Evidence
+
+List commands you ran and outcomes:
+
+```text
+make lint-fast
+make test-fast
+make test-contracts
+make test-scenarios
+make test-docs-consistency
+```
+
+Additional scoped commands:
+
+- [ ] Acceptance lane evidence included when behavior is operator-facing.
+- [ ] Cross-platform/path behavior reviewed for touched surfaces.
+
+## Docs and Source of Truth
+
+- [ ] User-visible behavior changes include docs updates in the same PR.
+- [ ] Docs updates follow [`docs/map.md`](docs/map.md) source-of-truth guidance.
+
+## Risks and Follow-ups
+
+- Determinism/fail-closed/security risks:
+- Deferred follow-ups (if any):

CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes to Wrkr are documented in this file.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions align with repository release tags.
+
+## [Unreleased]
+
+### Added
+
+- (none yet)
+
+### Changed
+
+- (none yet)
+
+### Fixed
+
+- (none yet)
+
+### Security
+
+- (none yet)
+
+## Changelog maintenance process
+
+1. Update `## [Unreleased]` in every PR that changes user-visible behavior, contracts, or governance process.
+2. Before release tagging, promote relevant entries from `Unreleased` into a versioned section (for example `## [v1.0.1] - 2026-03-04`).
+3. Keep entries concise and operator-facing: what changed, why it matters, and any migration/action notes.
+4. Link release notes and tag artifacts to the finalized changelog section.

CODE_OF_CONDUCT.md

@@ -0,0 +1,43 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Demonstrating empathy and kindness toward other people.
+- Being respectful of differing opinions, viewpoints, and experiences.
+- Giving and gracefully accepting constructive feedback.
+- Accepting responsibility and apologizing to those affected by our mistakes.
+- Focusing on what is best not just for us as individuals, but for the overall community.
+
+Examples of unacceptable behavior:
+
+- The use of sexualized language or imagery, and sexual attention or advances of any kind.
+- Trolling, insulting or derogatory comments, and personal or political attacks.
+- Public or private harassment.
+- Publishing others' private information, such as a physical or email address, without their explicit permission.
+- Other conduct which could reasonably be considered inappropriate in a professional setting.
+
+## Enforcement Responsibilities
+
+Project maintainers are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies within all project spaces, and also applies when an individual is officially representing the project in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported through the process in [`SECURITY.md`](SECURITY.md) or via repository maintainers.
+
+All complaints will be reviewed and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1.

CONTRIBUTING.md

@@ -1,11 +1,90 @@
-# Contributing
+# Contributing to Wrkr
 
-## Requirements
+Wrkr is a deterministic, offline-first OSS CLI for AI tooling discovery, risk scoring, and proof artifacts. Every contribution must preserve contract stability, determinism, and fail-closed behavior.
 
-- Go 1.25.7
-- Python 3.13+
-- Node 22+
+## Required Toolchain
 
-## Development
+- Go `1.25.7`
+- Git
+- Make
 
-Use `make prepush-full` before opening a PR.
+## Optional Toolchain
+
+- Python `3.13+` for script-based checks and some docs validation helpers.
+- Node `22+` only for docs-site development (`docs-site/`).
+- Homebrew for local install-path UAT checks.
+
+Node is not required for the default Go-only contribution path.
+
+## Go-Only Contributor Path (Default)
+
+```bash
+make fmt
+make lint-fast
+make test-fast
+make test-contracts
+make test-scenarios
+make prepush
+```
+
+This path is sufficient for most CLI/runtime changes and does not require Node.
+
+## CI Lane Map
+
+| Lane | Purpose | Local command anchor |
+|---|---|---|
+| Fast | quick contract + lint safety | `make lint-fast && make test-fast` |
+| Core CI | deterministic package and contract coverage | `make prepush` |
+| Acceptance | operator-path scenario flows | `make test-scenarios` |
+| Cross-platform | Linux/macOS/Windows behavior parity | avoid OS-specific assumptions in paths/fixtures |
+| Risk | hardening/perf/chaos lanes for scoped changes | `make test-risk-lane` |
+
+## Determinism Requirements
+
+- Same input must produce the same inventory/risk/proof output, excluding explicit timestamp/version fields.
+- Never add LLM/network-driven nondeterminism in scan/risk/proof paths.
+- Keep JSON key names, exit codes (`0..8`), and schema contracts stable unless explicitly versioned.
+- Prefer additive contract evolution; include migration/compatibility tests for any contract change.
+
+## Detector Authoring Guidance
+
+- Parse structured formats (JSON/YAML/TOML) with typed/schema-backed logic when possible.
+- Avoid regex-only extraction for structured configs.
+- Do not extract secret values; only emit risk context.
+- Keep detector outputs stable and explainable (deterministic ordering, explicit reason codes).
+- Add unit and fixture tests for success, parse failure, and boundary conditions.
+
+## Pull Request Workflow
+
+1. Keep scope tight and mapped to one story/contract change when possible.
+2. Run required local commands for your touched surfaces (at minimum fast + core lane anchors).
+3. Document contract impact:
+   - CLI flags/help/JSON/exits changed?
+   - schema/output changed?
+   - docs updated in same change for user-visible behavior?
+4. Include command evidence in PR description (commands and pass/fail).
+5. If docs are touched, follow [`docs/map.md`](docs/map.md) and run docs validation bundle.
+6. For user-visible changes, update [`CHANGELOG.md`](CHANGELOG.md) under `Unreleased`.
+7. For `product/` or `.agents/skills/` changes, confirm policy conformance per [`docs/governance/content-visibility.md`](docs/governance/content-visibility.md).
+
+Issue/PR templates:
+
+- `.github/ISSUE_TEMPLATE/bug_report.yml`
+- `.github/ISSUE_TEMPLATE/feature_request.yml`
+- `.github/ISSUE_TEMPLATE/docs_change.yml`
+- `.github/pull_request_template.md`
+
+## Docs Source of Truth
+
+Edit canonical docs in this repo first (`README.md` and `docs/`), then validate:
+
+```bash
+make test-docs-consistency
+make test-docs-storyline
+make docs-site-install
+make docs-site-lint
+make docs-site-build
+make docs-site-check
+```
+
+Use issue and PR templates for reproducible reports and contract-aware review context.