diff --git a/.agents/skills/README.md b/.agents/skills/README.md new file mode 100644 index 0000000..ea1a236 --- /dev/null +++ b/.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). diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..bd7f31a --- /dev/null +++ b/.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 diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..c6fb030 --- /dev/null +++ b/.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. diff --git a/.github/ISSUE_TEMPLATE/docs_change.yml b/.github/ISSUE_TEMPLATE/docs_change.yml new file mode 100644 index 0000000..d2b7844 --- /dev/null +++ b/.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 diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..f306db2 --- /dev/null +++ b/.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 diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..89e6c4f --- /dev/null +++ b/.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): diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..564b4a0 --- /dev/null +++ b/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. diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..a550dc3 --- /dev/null +++ b/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. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f012655..899bf27 100644 --- a/CONTRIBUTING.md +++ b/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. diff --git a/README.md b/README.md index 0e58393..93f97b5 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ Most teams don't know what AI dev tools and agents are active across their repos Wrkr is the **See** layer in the Clyra AI governance stack (See -> Prove -> Control -> Build). It discovers AI tooling across repositories and orgs, scores posture, tracks identity lifecycle, and emits signed proof artifacts ready for compliance review or downstream automation. -Docs: [clyra-ai.github.io/wrkr](https://clyra-ai.github.io/wrkr/) | Command contracts: [`docs/commands/`](docs/commands/) | Docs map: [`docs/README.md`](docs/README.md) +Docs: [clyra-ai.github.io/wrkr](https://clyra-ai.github.io/wrkr/) | Command contracts: [`docs/commands/`](docs/commands/) | Docs map: [`docs/map.md`](docs/map.md) ## When To Use Wrkr @@ -31,14 +31,22 @@ Docs: [clyra-ai.github.io/wrkr](https://clyra-ai.github.io/wrkr/) | Command cont brew install Clyra-AI/tap/wrkr ``` -### Go install (pinned to latest release tag) +### Go install (pinned, no extra tools) ```bash -WRKR_VERSION="$(gh release view --repo Clyra-AI/wrkr --json tagName -q .tagName 2>/dev/null || curl -fsSL https://api.github.com/repos/Clyra-AI/wrkr/releases/latest | python3 -c 'import json,sys; print(json.load(sys.stdin)[\"tag_name\"])')" +WRKR_VERSION="v1.0.0" go install github.com/Clyra-AI/wrkr/cmd/wrkr@"${WRKR_VERSION}" ``` -These install commands are validated in release CI against published artifacts. +### Go install (resolve latest tag with `curl` + POSIX tools) + +```bash +WRKR_VERSION="$(curl -fsSL https://api.github.com/repos/Clyra-AI/wrkr/releases/latest | sed -nE 's/.*"tag_name":[[:space:]]*"([^"]+)".*/\1/p' | head -n1)" +test -n "${WRKR_VERSION}" +go install github.com/Clyra-AI/wrkr/cmd/wrkr@"${WRKR_VERSION}" +``` + +No `gh` or `python3` dependency is required for these Go install paths. See [`docs/install/minimal-dependencies.md`](docs/install/minimal-dependencies.md) for the full install contract. ### Verify install path @@ -54,7 +62,7 @@ Common locations: - Intel Homebrew: `/usr/local/bin/wrkr` - Go install: `$(go env GOBIN)/wrkr` (or `$(go env GOPATH)/bin/wrkr` when `GOBIN` is unset) -## Try It (Offline, No Setup) +## First 10 Minutes (Offline, No Setup) Run the full scan-to-evidence workflow locally against the bundled scenarios: @@ -75,8 +83,8 @@ make build ./.tmp/wrkr verify --chain --json # Baseline and drift gate -./.tmp/wrkr regress init --baseline ./.wrkr/last-scan.json --output ./.tmp/wrkr-regress-baseline.json --json -./.tmp/wrkr regress run --baseline ./.tmp/wrkr-regress-baseline.json --json +./.tmp/wrkr regress init --baseline ./.wrkr/last-scan.json --output ./.wrkr/wrkr-regress-baseline.json --json +./.tmp/wrkr regress run --baseline ./.wrkr/wrkr-regress-baseline.json --json ``` Expected JSON keys by command family: @@ -91,6 +99,7 @@ Expected JSON keys by command family: Prompt-channel findings are emitted deterministically with stable reason codes and evidence hashes (no raw secret extraction). When `scan --enrich` is enabled, MCP findings include enrich provenance and quality fields (`source`, `as_of`, `advisory_count`, `registry_status`, `enrich_quality`, schema IDs, and adapter error classes). Evidence bundles include deterministic inventory artifacts at `inventory.json`, `inventory-snapshot.json`, and `inventory.yaml`. +Canonical local path lifecycle for state, baseline, manifest, and proof chain: [`docs/state_lifecycle.md`](docs/state_lifecycle.md). ## What You Get @@ -114,6 +123,11 @@ Signed proof records for `scan_finding`, `risk_assessment`, and lifecycle events Regress baseline and run gates with stable exit behavior. Deterministic remediation planning via `wrkr fix` for top-risk findings. +### `wrkr fix` side-effect contract + +wrkr fix computes a deterministic remediation plan from existing scan state and emits plan metadata; it does not mutate repository files unless --open-pr is set. +When --open-pr is set, wrkr fix writes deterministic artifacts under .wrkr/remediations// and then creates or updates one remediation PR for the target repo. + ## Scan Targets Exactly one source target is required per `scan` invocation: @@ -161,7 +175,7 @@ Render report artifacts from saved state: wrkr report --state ./.tmp/state.json --md --md-path ./.tmp/wrkr-report.md --explain ``` -## CI Adoption (One PR) +## Integration (One PR) ```bash wrkr init --non-interactive --path ./scenarios/wrkr/scan-mixed-org/repos --json @@ -211,6 +225,12 @@ Wrkr is the DMV registration for your AI fleet. It tells you what is on the road Wrkr runs standalone and interoperates through shared `Clyra-AI/proof` contracts. +## Trust and Project Relationship + +- Wrkr is standalone: you can install and run discovery, posture scoring, regress gating, and evidence generation without Axym or Gait. +- Axym and Gait are related projects that consume or enforce around the same proof contracts; they are optional integrations, not runtime prerequisites for Wrkr. +- The interoperability boundary is explicit and file-based via shared `Clyra-AI/proof` contracts. + ## Guarantees - Deterministic scan, risk, and proof pipeline. No LLM calls in these paths, ever. @@ -252,7 +272,10 @@ All commands support `--json`. Human-readable rationale is available via `--expl ## Documentation -- Docs map: [`docs/README.md`](docs/README.md) +- Docs source-of-truth map: [`docs/map.md`](docs/map.md) +- Docs taxonomy: [`docs/README.md`](docs/README.md) +- Shared README contract: [`docs/contracts/readme_contract.md`](docs/contracts/readme_contract.md) +- Cross-repo README follow-ups: [`docs/roadmap/cross-repo-readme-alignment.md`](docs/roadmap/cross-repo-readme-alignment.md) - Mental model: [`docs/concepts/mental_model.md`](docs/concepts/mental_model.md) - Architecture: [`docs/architecture.md`](docs/architecture.md) - Policy authoring: [`docs/policy_authoring.md`](docs/policy_authoring.md) @@ -260,11 +283,14 @@ All commands support `--json`. Human-readable rationale is available via `--expl - Threat model: [`docs/threat_model.md`](docs/threat_model.md) - Compatibility and versioning policy: [`docs/trust/compatibility-and-versioning.md`](docs/trust/compatibility-and-versioning.md) - Compatibility matrix: [`docs/contracts/compatibility_matrix.md`](docs/contracts/compatibility_matrix.md) +- Content visibility governance: [`docs/governance/content-visibility.md`](docs/governance/content-visibility.md) - Trust docs: [`docs/trust/`](docs/trust/) - Intent pages: [`docs/intent/`](docs/intent/) Public docs: [clyra-ai.github.io/wrkr](https://clyra-ai.github.io/wrkr/) +Docs contribution path: edit canonical markdown in this repo first (`README.md` and `docs/`), then run `make test-docs-consistency`, `make test-docs-storyline`, and docs-site checks from [`docs/map.md`](docs/map.md). + ## Developer Workflow ```bash @@ -285,9 +311,11 @@ make docs-site-check make docs-site-audit-prod ``` -## Security and Feedback +## Governance and Support - Security policy: [`SECURITY.md`](SECURITY.md) - Contributing guide: [`CONTRIBUTING.md`](CONTRIBUTING.md) +- Code of conduct: [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md) +- Changelog: [`CHANGELOG.md`](CHANGELOG.md) - License: [`LICENSE`](LICENSE) - Issues: [github.com/Clyra-AI/wrkr/issues](https://github.com/Clyra-AI/wrkr/issues) diff --git a/core/cli/fix.go b/core/cli/fix.go index 6c59dde..8c7b4e5 100644 --- a/core/cli/fix.go +++ b/core/cli/fix.go @@ -23,6 +23,11 @@ var newGitHubPRClient = func(baseURL, token string) githubpr.API { return githubpr.NewGitHubClient(baseURL, token, nil) } +const ( + fixBehaviorContractSentenceOne = "wrkr fix computes a deterministic remediation plan from existing scan state and emits plan metadata; it does not mutate repository files unless --open-pr is set." + fixBehaviorContractSentenceTwo = "When --open-pr is set, wrkr fix writes deterministic artifacts under .wrkr/remediations// and then creates or updates one remediation PR for the target repo." +) + func runFix(args []string, stdout io.Writer, stderr io.Writer) int { jsonRequested := wantsJSONOutput(args) fs := flag.NewFlagSet("fix", flag.ContinueOnError) @@ -46,6 +51,9 @@ func runFix(args []string, stdout io.Writer, stderr io.Writer) int { prTitle := fs.String("pr-title", "", "optional deterministic PR title override") githubAPI := fs.String("github-api", strings.TrimSpace(os.Getenv("WRKR_GITHUB_API_BASE")), "github api base url") fixToken := fs.String("fix-token", "", "fix profile token override") + fs.Usage = func() { + writeFixUsage(fs.Output(), fs) + } if code, handled := parseFlags(fs, args, stderr, jsonRequested || *jsonOut); handled { return code @@ -186,6 +194,22 @@ func runFix(args []string, stdout io.Writer, stderr io.Writer) int { return exitSuccess } +func writeFixUsage(out io.Writer, fs *flag.FlagSet) { + _, _ = fmt.Fprintln(out, "Usage of fix:") + _, _ = fmt.Fprintln(out, " wrkr fix [flags]") + _, _ = fmt.Fprintln(out, "") + _, _ = fmt.Fprintln(out, "Behavior contract:") + _, _ = fmt.Fprintln(out, " "+fixBehaviorContractSentenceOne) + _, _ = fmt.Fprintln(out, " "+fixBehaviorContractSentenceTwo) + _, _ = fmt.Fprintln(out, "") + _, _ = fmt.Fprintln(out, "PR prerequisites:") + _, _ = fmt.Fprintln(out, " - --repo owner/repo (or repo-target state)") + _, _ = fmt.Fprintln(out, " - writable fix profile token via config or --fix-token") + _, _ = fmt.Fprintln(out, "") + _, _ = fmt.Fprintln(out, "Flags:") + fs.PrintDefaults() +} + func loadRankedFindings(snapshot state.Snapshot, top int) []risk.ScoredFinding { if snapshot.RiskReport != nil && len(snapshot.RiskReport.Ranked) > 0 { return append([]risk.ScoredFinding(nil), snapshot.RiskReport.Ranked...) diff --git a/core/cli/fix_test.go b/core/cli/fix_test.go index 6f54fe7..12f4bca 100644 --- a/core/cli/fix_test.go +++ b/core/cli/fix_test.go @@ -4,6 +4,7 @@ import ( "bytes" "context" "encoding/json" + "os" "path/filepath" "strings" "testing" @@ -149,6 +150,42 @@ func TestFixOpenPRWritesRemediationArtifacts(t *testing.T) { } } +func TestFixHelpMatchesBehaviorContract(t *testing.T) { + t.Parallel() + + var out bytes.Buffer + var errOut bytes.Buffer + code := Run([]string{"fix", "--help"}, &out, &errOut) + if code != 0 { + t.Fatalf("expected exit 0, got %d stderr=%q", code, errOut.String()) + } + + helpText := errOut.String() + for _, sentence := range []string{fixBehaviorContractSentenceOne, fixBehaviorContractSentenceTwo} { + if !strings.Contains(helpText, sentence) { + t.Fatalf("fix help missing behavior contract sentence %q", sentence) + } + } + + repoRoot := mustRepoRoot(t) + docsText, err := os.ReadFile(filepath.Join(repoRoot, "docs/commands/fix.md")) + if err != nil { + t.Fatalf("read fix docs: %v", err) + } + readmeText, err := os.ReadFile(filepath.Join(repoRoot, "README.md")) + if err != nil { + t.Fatalf("read README: %v", err) + } + for _, sentence := range []string{fixBehaviorContractSentenceOne, fixBehaviorContractSentenceTwo} { + if !strings.Contains(string(docsText), sentence) { + t.Fatalf("docs/commands/fix.md missing behavior contract sentence %q", sentence) + } + if !strings.Contains(string(readmeText), sentence) { + t.Fatalf("README.md missing behavior contract sentence %q", sentence) + } + } +} + func writeFixStateFixture(t *testing.T) string { t.Helper() @@ -179,6 +216,26 @@ func writeFixStateFixture(t *testing.T) string { return statePath } +func mustRepoRoot(t *testing.T) string { + t.Helper() + + wd, err := os.Getwd() + if err != nil { + t.Fatalf("getwd: %v", err) + } + current := wd + for { + if _, err := os.Stat(filepath.Join(current, "go.mod")); err == nil { + return current + } + parent := filepath.Dir(current) + if parent == current { + t.Fatalf("could not find repo root from %s", wd) + } + current = parent + } +} + type stubPRAPI struct { ensureFileCalls int paths []string diff --git a/core/cli/root.go b/core/cli/root.go index a058255..3cec85e 100644 --- a/core/cli/root.go +++ b/core/cli/root.go @@ -170,7 +170,7 @@ func writeRootUsage(out io.Writer, fs *flag.FlagSet) { _, _ = fmt.Fprintln(out, " score compute posture score and breakdown") _, _ = fmt.Fprintln(out, " verify verify proof chain integrity") _, _ = fmt.Fprintln(out, " evidence build compliance-ready evidence bundles") - _, _ = fmt.Fprintln(out, " fix apply deterministic remediations") + _, _ = fmt.Fprintln(out, " fix plan deterministic remediations (repo writes require --open-pr)") _, _ = fmt.Fprintln(out, " version print wrkr version") _, _ = fmt.Fprintln(out, "") _, _ = fmt.Fprintln(out, "Examples:") diff --git a/core/cli/root_test.go b/core/cli/root_test.go index 893f993..e282d08 100644 --- a/core/cli/root_test.go +++ b/core/cli/root_test.go @@ -56,6 +56,7 @@ func TestRunRootHelpListsCommands(t *testing.T) { " scan discover tools and emit inventory/risk state", " score compute posture score and breakdown", " evidence build compliance-ready evidence bundles", + " fix plan deterministic remediations (repo writes require --open-pr)", "Examples:", "Global flags:", } diff --git a/docs-site/public/llm/faq.md b/docs-site/public/llm/faq.md index 36a4a13..6f2c22f 100644 --- a/docs-site/public/llm/faq.md +++ b/docs-site/public/llm/faq.md @@ -16,6 +16,10 @@ No. Core scan and evidence workflows are local/file-based by default. No. Wrkr is discovery and posture. Runtime control is a separate layer. +## Do I need Axym or Gait to use Wrkr? + +No. Wrkr runs standalone; Axym and Gait are optional integrations that share proof contracts. + ## How do I gate on posture drift in CI? Use `wrkr regress init` then `wrkr regress run`. Exit code `5` indicates drift. diff --git a/docs-site/public/llms.txt b/docs-site/public/llms.txt index 57afba0..2b2c088 100644 --- a/docs-site/public/llms.txt +++ b/docs-site/public/llms.txt @@ -39,8 +39,10 @@ - No secret-value extraction; only risk context signals. - Proof-chain verification support for evidence integrity checks. - Evidence bundles include deterministic inventory artifacts: inventory.json, inventory-snapshot.json, inventory.yaml. +- Wrkr runs standalone; Axym/Gait are optional integrations over shared proof contracts. ## Canonical Docs +- /docs/map/ - /docs/adopt_in_one_pr/ - /docs/integration_checklist/ - /docs/architecture/ diff --git a/docs-site/src/app/docs/page.tsx b/docs-site/src/app/docs/page.tsx index 427f098..a846425 100644 --- a/docs-site/src/app/docs/page.tsx +++ b/docs-site/src/app/docs/page.tsx @@ -16,6 +16,7 @@ const tracks = [ { label: 'Adopt In One PR', href: '/docs/adopt_in_one_pr' }, { label: 'Quickstart', href: '/docs/examples/quickstart' }, { label: 'Integration Checklist', href: '/docs/integration_checklist' }, + { label: 'Docs Source Map', href: '/docs/map' }, { label: 'Command Index', href: '/docs/commands/index' }, { label: 'Scan Command', href: '/docs/commands/scan' }, ], diff --git a/docs-site/src/lib/navigation.ts b/docs-site/src/lib/navigation.ts index 130bf11..e7c6491 100644 --- a/docs-site/src/lib/navigation.ts +++ b/docs-site/src/lib/navigation.ts @@ -13,6 +13,7 @@ export const navigation: NavItem[] = [ { title: 'Adopt In One PR', href: '/docs/adopt_in_one_pr' }, { title: 'Quickstart', href: '/docs/examples/quickstart' }, { title: 'Integration Checklist', href: '/docs/integration_checklist' }, + { title: 'Docs Source Map', href: '/docs/map' }, { title: 'FAQ', href: '/docs/faq' }, ], }, diff --git a/docs/README.md b/docs/README.md index 480e586..a2ce82b 100644 --- a/docs/README.md +++ b/docs/README.md @@ -6,6 +6,7 @@ description: "Canonical map of Wrkr docs, with normative surfaces and ownership # Wrkr Documentation Map This file defines where each topic lives so docs remain contract-aligned and non-duplicative. +For editing/validation workflow, see [`docs/map.md`](map.md). ## Canonical Surface Taxonomy @@ -27,6 +28,7 @@ This file defines where each topic lives so docs remain contract-aligned and non - Architecture: `docs/architecture.md` - Mental model: `docs/concepts/mental_model.md` +- State lifecycle (canonical local artifact paths): `docs/state_lifecycle.md` - Failure taxonomy and exits: `docs/failure_taxonomy_exit_codes.md` - Policy authoring: `docs/policy_authoring.md` - Built-in policy rules: `docs/policy_builtin_rules.md` @@ -38,6 +40,7 @@ This file defines where each topic lives so docs remain contract-aligned and non - Manifest spec: `docs/specs/wrkr-manifest.md` - Compatibility and versioning policy: `docs/trust/compatibility-and-versioning.md` - Compatibility matrix: `docs/contracts/compatibility_matrix.md` +- README cross-repo contract: `docs/contracts/readme_contract.md` - Deterministic guarantees: `docs/trust/deterministic-guarantees.md` - goja AST-only guardrails: `docs/trust/goja-ast-only.md` - MCP enrich quality model: `docs/trust/mcp-enrich-quality-model.md` @@ -58,6 +61,7 @@ This file defines where each topic lives so docs remain contract-aligned and non - Positioning: `docs/positioning.md` - FAQ: `docs/faq.md` - Intent guides: `docs/intent/*.md` +- Cross-repo README alignment tracker: `docs/roadmap/cross-repo-readme-alignment.md` ## Ownership Rules diff --git a/docs/commands/evidence.md b/docs/commands/evidence.md index 36d3a2a..05eb277 100644 --- a/docs/commands/evidence.md +++ b/docs/commands/evidence.md @@ -40,9 +40,11 @@ Recommended operator actions when coverage is low: ## Example ```bash -wrkr evidence --frameworks eu-ai-act,soc2 --state ./.tmp/state.json --output ./.tmp/evidence --json +wrkr evidence --frameworks eu-ai-act,soc2 --state ./.wrkr/last-scan.json --output ./wrkr-evidence --json ``` Expected JSON keys: `status`, `output_dir`, `frameworks`, `manifest_path`, `chain_path`, `framework_coverage`, `report_artifacts`. Evidence bundle includes deterministic inventory exports at `inventory.json`, `inventory-snapshot.json`, and `inventory.yaml`. Evidence bundle includes deterministic attack-path artifact export at `attack-paths.json` when attack-path scoring is present in scan state. + +Canonical state and proof-chain path behavior: [`docs/state_lifecycle.md`](../state_lifecycle.md). diff --git a/docs/commands/fix.md b/docs/commands/fix.md index 902d7f3..a7c81d7 100644 --- a/docs/commands/fix.md +++ b/docs/commands/fix.md @@ -26,9 +26,19 @@ wrkr fix [--top ] [--state ] [--config ] [--open-pr] [--repo /` on the remediation branch before creating/updating the PR. +## Behavior contract + +wrkr fix computes a deterministic remediation plan from existing scan state and emits plan metadata; it does not mutate repository files unless --open-pr is set. +When --open-pr is set, wrkr fix writes deterministic artifacts under .wrkr/remediations// and then creates or updates one remediation PR for the target repo. + +PR prerequisites: + +- `--repo owner/repo` (or a repo-target state file) +- writable fix profile token in config (`auth.fix.token`) or `--fix-token` Expected JSON keys: `status`, `requested_top`, `fingerprint`, `remediation_count`, `non_fixable_count`, `remediations`, `unsupported_findings`; and when `--open-pr` is used: `pull_request`, `remediation_artifacts`. + +Canonical state path behavior: [`docs/state_lifecycle.md`](../state_lifecycle.md). diff --git a/docs/commands/index.md b/docs/commands/index.md index b5b6da6..144474d 100644 --- a/docs/commands/index.md +++ b/docs/commands/index.md @@ -2,6 +2,8 @@ Wrkr CLI surfaces are deterministic and file-based by default. +Canonical local state and artifact path behavior is documented in [`docs/state_lifecycle.md`](../state_lifecycle.md). + ## Command index - `wrkr` (root flags: `--json`, `--quiet`, `--explain`, `--version`) diff --git a/docs/commands/regress.md b/docs/commands/regress.md index e349e91..c22efdf 100644 --- a/docs/commands/regress.md +++ b/docs/commands/regress.md @@ -29,9 +29,11 @@ wrkr regress run --baseline [--state ] [--summary-md ## Example ```bash -wrkr regress init --baseline ./.tmp/state.json --output ./.tmp/wrkr-regress-baseline.json --json -wrkr regress run --baseline ./.tmp/wrkr-regress-baseline.json --state ./.tmp/state.json --summary-md --summary-md-path ./.tmp/regress-summary.md --template operator --json +wrkr regress init --baseline ./.wrkr/last-scan.json --output ./.wrkr/wrkr-regress-baseline.json --json +wrkr regress run --baseline ./.wrkr/wrkr-regress-baseline.json --state ./.wrkr/last-scan.json --summary-md --summary-md-path ./.tmp/regress-summary.md --template operator --json ``` Expected JSON keys include `status`, `baseline_path`, `tool_count` (init) and drift fields plus optional `summary_md_path` (run). When critical attack-path sets diverge above deterministic thresholds, `reasons` includes a single `critical_attack_path_drift` summary entry with machine-readable `attack_path_drift` details (`added`, `removed`, `score_changed`). + +Canonical state/baseline path behavior: [`docs/state_lifecycle.md`](../state_lifecycle.md). diff --git a/docs/commands/scan.md b/docs/commands/scan.md index 4628200..a7bd397 100644 --- a/docs/commands/scan.md +++ b/docs/commands/scan.md @@ -14,6 +14,7 @@ Acquisition behavior is fail-closed by target: - `--repo` and `--org` require real GitHub acquisition via `--github-api` or `WRKR_GITHUB_API_BASE`. - `--repo` and `--org` materialize repository contents into a deterministic local workspace under the scan state directory before detectors run. - When GitHub acquisition is unavailable, `scan` returns `dependency_missing` with exit code `7` (no synthetic repos are emitted). +- `--state` defaults to `.wrkr/last-scan.json`, with manifest/proof artifacts written alongside it. ## Flags @@ -108,3 +109,4 @@ Emerging discovery surfaces are static-only in default deterministic mode: - No live endpoint probing is performed by default. Custom extension detectors are loaded from `.wrkr/detectors/extensions.json` when present in scanned repositories. See [`docs/extensions/detectors.md`](../extensions/detectors.md). +Canonical state and artifact lifecycle: [`docs/state_lifecycle.md`](../state_lifecycle.md). diff --git a/docs/contracts/readme_contract.md b/docs/contracts/readme_contract.md new file mode 100644 index 0000000..a967f21 --- /dev/null +++ b/docs/contracts/readme_contract.md @@ -0,0 +1,50 @@ +# Cross-Repo README Contract (Wrkr-first) + +This document defines the required README structure shared across Wrkr/Proof/Gait repositories. + +## Required sections + +1. Install +2. First 10 Minutes +3. Integration +4. Command Surface +5. Governance and Support + +## Section requirements + +### Install + +- Include at least one pinned install path. +- Include minimal-dependency guidance (no hidden mandatory helpers). +- Include verification command(s) after install. + +### First 10 Minutes + +- Provide copy-paste workflow from initialization to first value output. +- Show deterministic `--json` command anchors. +- Link to canonical state lifecycle behavior. + +### Integration + +- Provide CI-adoption workflow and gate semantics. +- Clarify standalone usage vs optional ecosystem integrations. +- Link to deeper integration docs. + +### Command Surface + +- Enumerate stable command families. +- Reference JSON/exit-code contract expectations. + +### Governance and Support + +- Link contributing, security policy, code of conduct, changelog, and issue workflows. +- Include docs source-of-truth guidance. + +## Validation + +Run: + +```bash +make test-docs-consistency +make test-docs-storyline +``` diff --git a/docs/examples/operator-playbooks.md b/docs/examples/operator-playbooks.md index a080b0b..5d0bf0d 100644 --- a/docs/examples/operator-playbooks.md +++ b/docs/examples/operator-playbooks.md @@ -1,5 +1,7 @@ # Operator Playbooks +Canonical local artifact locations are documented in [`docs/state_lifecycle.md`](../state_lifecycle.md). + ## Scan workflow ```bash @@ -63,8 +65,8 @@ Check `chain.intact` and `chain.head_hash`. ## Regress workflow ```bash -wrkr regress init --baseline ./.wrkr/last-scan.json --output ./.tmp/wrkr-regress-baseline.json --json -wrkr regress run --baseline ./.tmp/wrkr-regress-baseline.json --summary-md --summary-md-path ./.tmp/regress-summary.md --template operator --json +wrkr regress init --baseline ./.wrkr/last-scan.json --output ./.wrkr/wrkr-regress-baseline.json --json +wrkr regress run --baseline ./.wrkr/wrkr-regress-baseline.json --summary-md --summary-md-path ./.tmp/regress-summary.md --template operator --json ``` Use exit `5` and drift reasons as gate criteria. diff --git a/docs/examples/quickstart.md b/docs/examples/quickstart.md index 0388120..e741efe 100644 --- a/docs/examples/quickstart.md +++ b/docs/examples/quickstart.md @@ -14,6 +14,8 @@ Wrkr is useful standalone and interoperates with Axym/Gait through shared proof For hosted source modes, `scan --repo` and `scan --org` require `--github-api` (or `WRKR_GITHUB_API_BASE`) and fail closed when acquisition is unavailable. +Canonical local artifact paths are documented in [`docs/state_lifecycle.md`](../state_lifecycle.md). + ## Deterministic local scan ```bash @@ -48,8 +50,8 @@ Expected outputs: ## Regression baseline ```bash -wrkr regress init --baseline ./.wrkr/last-scan.json --output ./.tmp/wrkr-regress-baseline.json --json -wrkr regress run --baseline ./.tmp/wrkr-regress-baseline.json --json +wrkr regress init --baseline ./.wrkr/last-scan.json --output ./.wrkr/wrkr-regress-baseline.json --json +wrkr regress run --baseline ./.wrkr/wrkr-regress-baseline.json --json ``` Expected outputs: diff --git a/docs/faq.md b/docs/faq.md index b975453..da45de4 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -23,6 +23,11 @@ No. Core operation is local and file-based by default. No. Wrkr is discovery/posture. Runtime enforcement is a separate control layer. +### Do I need Axym or Gait to run Wrkr? + +No. Wrkr runs standalone for discovery, posture scoring, regress gates, and evidence generation. +Axym and Gait are optional companion projects that interoperate through shared `Clyra-AI/proof` contracts. + ### How do I fail CI on posture drift? Use `wrkr regress init` to establish a baseline and `wrkr regress run` in CI. Exit `5` indicates drift. diff --git a/docs/governance/content-visibility.md b/docs/governance/content-visibility.md new file mode 100644 index 0000000..bd3dcdd --- /dev/null +++ b/docs/governance/content-visibility.md @@ -0,0 +1,51 @@ +# Governance: Content Visibility Policy + +This policy defines what content is allowed in `product/` and `.agents/skills/` for the public Wrkr repository. + +## Policy A: `product/` visibility + +`product/` is public by default and is intended for planning, architecture, and product intent artifacts relevant to Wrkr OSS delivery. + +Allowed content: + +- Roadmaps, plans, architecture notes, and execution checklists. +- Publicly shareable requirements and acceptance criteria. +- Redacted audit/review summaries that avoid sensitive operational detail. + +Prohibited content: + +- Secrets, credentials, tokens, internal URLs, or private customer identifiers. +- Unredacted internal security findings that reveal exploit details. +- Personal data or non-public incident details. + +Enforcement: + +- Any sensitive details must be removed or replaced with redacted placeholders before commit. +- If a plan requires private context, store private material outside this repository and link only to a non-sensitive summary. + +## Policy B: `.agents/skills/` visibility + +`.agents/skills/` is public and treated as a transparency artifact for deterministic contributor/automation workflows. + +Allowed content: + +- Skill workflow instructions, deterministic command sequences, and repository-scoped guidance. +- References to public repo paths, tests, and validation commands. + +Prohibited content: + +- Embedded secrets, private API endpoints, non-public tokens, or privileged operational procedures not suitable for OSS disclosure. +- Instructions that weaken fail-closed, determinism, or contract safety guarantees. + +Enforcement: + +- Keep skill files instructional and deterministic; no environment-specific secret handling instructions. +- Review skill updates with the same contract rigor as CLI/docs changes. + +## Directory notices and review checklist + +- `product/README.md` and `.agents/skills/README.md` are required directory notices. +- PRs touching either directory must include: + - policy conformance statement + - redaction confirmation (if applicable) + - docs/test validation evidence diff --git a/docs/install/minimal-dependencies.md b/docs/install/minimal-dependencies.md new file mode 100644 index 0000000..989e647 --- /dev/null +++ b/docs/install/minimal-dependencies.md @@ -0,0 +1,38 @@ +# Install With Minimal Dependencies + +This page is the install contract source for environments that only have Go and standard shell tooling. + +## Go-only pinned install + +```bash +WRKR_VERSION="v1.0.0" +go install github.com/Clyra-AI/wrkr/cmd/wrkr@"${WRKR_VERSION}" +``` + +Use this path for deterministic onboarding and CI scripts that pin a known release. + +## Latest release tag without `gh` or `python3` + +```bash +WRKR_VERSION="$(curl -fsSL https://api.github.com/repos/Clyra-AI/wrkr/releases/latest | sed -nE 's/.*"tag_name":[[:space:]]*"([^"]+)".*/\1/p' | head -n1)" +test -n "${WRKR_VERSION}" +go install github.com/Clyra-AI/wrkr/cmd/wrkr@"${WRKR_VERSION}" +``` + +This path uses `curl`, `sed`, and `head` only. + +## Homebrew path + +```bash +brew install Clyra-AI/tap/wrkr +``` + +## Release-smoke validation commands + +Install commands above are validated by release UAT: + +```bash +scripts/test_uat_local.sh --skip-global-gates +scripts/test_uat_local.sh --release-version v1.0.0 --skip-global-gates +scripts/test_uat_local.sh --release-version v1.0.0 --brew-formula Clyra-AI/tap/wrkr --skip-global-gates +``` diff --git a/docs/map.md b/docs/map.md new file mode 100644 index 0000000..0a2b280 --- /dev/null +++ b/docs/map.md @@ -0,0 +1,35 @@ +# Docs Source-of-Truth Map + +This page defines where to edit and how to validate docs changes. + +## Source-of-truth model + +| Surface | Edit location | Validation commands | +|---|---|---| +| Product/readme landing content | `README.md` | `make test-docs-consistency` | +| Command contracts | `docs/commands/*.md` | `make test-docs-consistency` | +| Workflow and operator docs | `docs/examples/*.md`, `docs/intent/*.md`, `docs/state_lifecycle.md` | `make test-docs-consistency && make test-docs-storyline` | +| Governance/trust docs | `docs/trust/*.md`, `docs/governance/*.md`, `CONTRIBUTING.md`, community health files | `make test-docs-consistency` | +| Docs-site rendering | `docs-site/` (layout and static pages only) | `make docs-site-install && make docs-site-lint && make docs-site-build && make docs-site-check` | +| LLM snapshots for assistants/crawlers | `docs-site/public/llms.txt`, `docs-site/public/llm/*.md` | `make test-docs-consistency && make docs-site-check` | + +## Editing rule + +Edit canonical documentation in repository markdown first (`README.md` + `docs/`), then update docs-site-specific projection files when needed. + +## Required validation bundle + +Run this bundle before merge when docs are touched: + +```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 +``` + +## Trust positioning reference + +Wrkr runs standalone for deterministic discovery/posture/evidence workflows and interoperates with Axym/Gait via shared proof contracts. diff --git a/docs/roadmap/cross-repo-readme-alignment.md b/docs/roadmap/cross-repo-readme-alignment.md new file mode 100644 index 0000000..9c7f5a4 --- /dev/null +++ b/docs/roadmap/cross-repo-readme-alignment.md @@ -0,0 +1,15 @@ +# Cross-Repo README Alignment Follow-ups + +Wrkr is the reference implementation for the shared README contract in [`docs/contracts/readme_contract.md`](../contracts/readme_contract.md). + +## Tracked external follow-ups + +| Repository | Owner | Due date | Scope | +|---|---|---|---| +| `Clyra-AI/proof` | `@clyra-proof-maintainers` | 2026-03-31 | Adopt required README sections (Install, First 10 Minutes, Integration, Command Surface, Governance and Support). | +| `Clyra-AI/gait` | `@clyra-gait-maintainers` | 2026-04-07 | Align README with shared contract and add integration pointers to Wrkr/Proof boundaries. | + +## Notes + +- Follow-ups are tracked here because alignment depends on external repositories outside this merge scope. +- Wrkr README remains the contract baseline until both external repos adopt equivalent section semantics. diff --git a/docs/state_lifecycle.md b/docs/state_lifecycle.md new file mode 100644 index 0000000..d860612 --- /dev/null +++ b/docs/state_lifecycle.md @@ -0,0 +1,37 @@ +# Wrkr State Lifecycle + +This page is the canonical lifecycle reference for Wrkr local state, baseline, manifest, and proof artifacts. + +## Path model + +Wrkr uses two path classes: + +- Managed contract artifacts under `.wrkr/` (state, baseline, manifest, proof chain). +- Operator-selected output paths (for reports/evidence exports), commonly under `.tmp/` or `wrkr-evidence/`. + +## Canonical artifact locations + +| Artifact | Default path | Produced by | Notes | +|---|---|---|---| +| Scan state snapshot | `.wrkr/last-scan.json` | `wrkr scan` | Deterministic input for downstream commands. | +| Regress baseline | `.wrkr/wrkr-regress-baseline.json` | `wrkr regress init` (default output) | Defaults to the same directory as state. | +| Identity manifest | `.wrkr/wrkr-manifest.yaml` | `wrkr scan`, `wrkr manifest generate` | Lifecycle/approval baseline contract. | +| Proof chain | `.wrkr/proof-chain.json` | `wrkr scan` / `wrkr evidence` | Verifiable signed record chain. | +| Evidence bundle | `wrkr-evidence/` | `wrkr evidence` | User-supplied `--output` is allowed; unsafe non-managed non-empty paths fail closed. | +| Human report artifacts | user-selected (`.tmp/*.md`, `.tmp/*.pdf`) | `wrkr report`, `wrkr regress run --summary-md`, `wrkr lifecycle --summary-md` | Keep separate from managed `.wrkr/` contract artifacts. | + +## Lifecycle flow + +1. `wrkr scan` writes/refreshes `.wrkr/last-scan.json`, `.wrkr/wrkr-manifest.yaml`, `.wrkr/proof-chain.json`. +2. `wrkr regress init` snapshots current state into `.wrkr/wrkr-regress-baseline.json` (unless `--output` overrides). +3. `wrkr regress run` compares current state vs baseline and returns deterministic drift reasons. +4. `wrkr evidence` consumes state and emits evidence bundle outputs while preserving chain continuity. +5. `wrkr verify --chain` validates proof-chain integrity from the state directory. + +## Command links + +- [`docs/examples/quickstart.md`](examples/quickstart.md) +- [`docs/commands/scan.md`](commands/scan.md) +- [`docs/commands/regress.md`](commands/regress.md) +- [`docs/commands/evidence.md`](commands/evidence.md) +- [`docs/commands/fix.md`](commands/fix.md) diff --git a/docs/trust/release-integrity.md b/docs/trust/release-integrity.md index 26cd84e..97facfb 100644 --- a/docs/trust/release-integrity.md +++ b/docs/trust/release-integrity.md @@ -10,6 +10,7 @@ description: "Release hardening checks, reproducibility expectations, and integr - Deterministic test gates in release workflow. - Contract and scenario validation before artifact generation. - SBOM generation and vulnerability scanning in release pipeline. +- `CHANGELOG.md` release-note entries updated before tag publication. ## Command anchors @@ -38,6 +39,7 @@ scripts/test_uat_local.sh --release-version v1.0.0 --brew-formula Clyra-AI/tap/w ## Operational note Consumers should verify published release checksums and provenance metadata before promotion. +Maintainers should treat changelog updates as release-gating documentation work, not an optional follow-up. ## Q&A diff --git a/product/README.md b/product/README.md new file mode 100644 index 0000000..a95492e --- /dev/null +++ b/product/README.md @@ -0,0 +1,9 @@ +# Product Directory Notice + +`product/` is public repository content for Wrkr planning and architecture artifacts. + +Before committing updates here: + +1. Remove or redact secrets, private endpoints, customer identifiers, and non-public incident details. +2. Keep content scoped to Wrkr OSS behavior and contracts. +3. Follow governance policy: [`docs/governance/content-visibility.md`](../docs/governance/content-visibility.md). diff --git a/scripts/check_docs_consistency.sh b/scripts/check_docs_consistency.sh index e144b61..1021dba 100755 --- a/scripts/check_docs_consistency.sh +++ b/scripts/check_docs_consistency.sh @@ -61,15 +61,22 @@ extract_exit_codes() { for path in \ "${REPO_ROOT}/README.md" \ + "${REPO_ROOT}/CODE_OF_CONDUCT.md" \ + "${REPO_ROOT}/CHANGELOG.md" \ "${REPO_ROOT}/docs/README.md" \ "${REPO_ROOT}/docs/adopt_in_one_pr.md" \ "${REPO_ROOT}/docs/integration_checklist.md" \ "${REPO_ROOT}/docs/architecture.md" \ + "${REPO_ROOT}/docs/map.md" \ + "${REPO_ROOT}/docs/governance/content-visibility.md" \ + "${REPO_ROOT}/docs/state_lifecycle.md" \ "${REPO_ROOT}/docs/concepts/mental_model.md" \ "${REPO_ROOT}/docs/policy_authoring.md" \ "${REPO_ROOT}/docs/failure_taxonomy_exit_codes.md" \ "${REPO_ROOT}/docs/threat_model.md" \ "${REPO_ROOT}/docs/contracts/compatibility_matrix.md" \ + "${REPO_ROOT}/docs/contracts/readme_contract.md" \ + "${REPO_ROOT}/docs/roadmap/cross-repo-readme-alignment.md" \ "${REPO_ROOT}/docs/positioning.md" \ "${REPO_ROOT}/docs/evidence_templates.md" \ "${REPO_ROOT}/docs/faq.md" \ @@ -95,6 +102,12 @@ for path in \ "${REPO_ROOT}/docs-site/public/llm/security.md" \ "${REPO_ROOT}/docs-site/public/llm/contracts.md" \ "${REPO_ROOT}/docs-site/public/llm/faq.md" \ + "${REPO_ROOT}/.github/ISSUE_TEMPLATE/bug_report.yml" \ + "${REPO_ROOT}/.github/ISSUE_TEMPLATE/feature_request.yml" \ + "${REPO_ROOT}/.github/ISSUE_TEMPLATE/docs_change.yml" \ + "${REPO_ROOT}/.github/pull_request_template.md" \ + "${REPO_ROOT}/product/README.md" \ + "${REPO_ROOT}/.agents/skills/README.md" \ "${REPO_ROOT}/docs-site/public/sitemap.xml" \ "${REPO_ROOT}/docs-site/public/ai-sitemap.xml" \ "${REPO_ROOT}/docs-site/public/robots.txt"; do @@ -186,8 +199,73 @@ require_pattern "${REPO_ROOT}/docs-site/public/robots.txt" "User-agent: ChatGPT- require_pattern "${REPO_ROOT}/README.md" "brew install Clyra-AI/tap/wrkr" "README missing canonical Homebrew install command" require_pattern "${REPO_ROOT}/README.md" "go install github.com/Clyra-AI/wrkr/cmd/wrkr@\"\\$\\{WRKR_VERSION\\}\"" "README missing canonical pinned go install command" +require_pattern "${REPO_ROOT}/README.md" "docs/state_lifecycle.md" "README missing canonical state lifecycle reference" require_pattern "${REPO_ROOT}/docs/trust/release-integrity.md" "scripts/test_uat_local.sh --release-version v1.0.0 --brew-formula Clyra-AI/tap/wrkr" "release integrity doc missing published install-path parity command" require_pattern "${REPO_ROOT}/docs-site/src/app/page.tsx" "/docs/start-here#install" "docs-site homepage missing start-here install pointer" +require_pattern "${REPO_ROOT}/docs/state_lifecycle.md" "^## Canonical artifact locations$" "state lifecycle doc missing canonical artifact table section" +require_pattern "${REPO_ROOT}/docs/state_lifecycle.md" "\\.wrkr/last-scan\\.json" "state lifecycle doc missing canonical state path" +require_pattern "${REPO_ROOT}/docs/state_lifecycle.md" "\\.wrkr/wrkr-regress-baseline\\.json" "state lifecycle doc missing canonical baseline path" +require_pattern "${REPO_ROOT}/docs/state_lifecycle.md" "\\.wrkr/wrkr-manifest\\.yaml" "state lifecycle doc missing canonical manifest path" +require_pattern "${REPO_ROOT}/docs/state_lifecycle.md" "\\.wrkr/proof-chain\\.json" "state lifecycle doc missing canonical proof chain path" +require_pattern "${REPO_ROOT}/docs/examples/quickstart.md" "docs/state_lifecycle.md" "quickstart missing canonical lifecycle reference" +require_pattern "${REPO_ROOT}/docs/commands/scan.md" "docs/state_lifecycle.md" "scan command docs missing lifecycle reference" +require_pattern "${REPO_ROOT}/docs/commands/regress.md" "docs/state_lifecycle.md" "regress command docs missing lifecycle reference" +require_pattern "${REPO_ROOT}/docs/commands/evidence.md" "docs/state_lifecycle.md" "evidence command docs missing lifecycle reference" +require_pattern "${REPO_ROOT}/docs/commands/fix.md" "docs/state_lifecycle.md" "fix command docs missing lifecycle reference" +require_pattern "${REPO_ROOT}/docs/examples/quickstart.md" "\\.wrkr/wrkr-regress-baseline\\.json" "quickstart regress examples missing canonical baseline path" +require_pattern "${REPO_ROOT}/docs/examples/operator-playbooks.md" "\\.wrkr/wrkr-regress-baseline\\.json" "operator playbook regress examples missing canonical baseline path" +require_pattern "${REPO_ROOT}/README.md" "wrkr fix computes a deterministic remediation plan from existing scan state and emits plan metadata; it does not mutate repository files unless --open-pr is set\\." "README missing explicit wrkr fix side-effect contract sentence one" +require_pattern "${REPO_ROOT}/README.md" "When --open-pr is set, wrkr fix writes deterministic artifacts under \\.wrkr/remediations// and then creates or updates one remediation PR for the target repo\\." "README missing explicit wrkr fix side-effect contract sentence two" +require_pattern "${REPO_ROOT}/docs/commands/fix.md" "wrkr fix computes a deterministic remediation plan from existing scan state and emits plan metadata; it does not mutate repository files unless --open-pr is set\\." "fix command docs missing explicit side-effect contract sentence one" +require_pattern "${REPO_ROOT}/docs/commands/fix.md" "When --open-pr is set, wrkr fix writes deterministic artifacts under \\.wrkr/remediations// and then creates or updates one remediation PR for the target repo\\." "fix command docs missing explicit side-effect contract sentence two" +require_pattern "${REPO_ROOT}/README.md" "^## Trust and Project Relationship$" "README missing trust and project relationship section" +require_pattern "${REPO_ROOT}/README.md" "docs/map\\.md" "README missing docs source-of-truth map reference" +require_pattern "${REPO_ROOT}/docs/faq.md" "^### Do I need Axym or Gait to run Wrkr\\?$" "FAQ missing standalone vs ecosystem entry" +require_pattern "${REPO_ROOT}/CONTRIBUTING.md" "^## Docs Source of Truth$" "CONTRIBUTING missing docs source-of-truth section" +require_pattern "${REPO_ROOT}/CONTRIBUTING.md" "make docs-site-install" "CONTRIBUTING missing docs-site validation command guidance" +require_pattern "${REPO_ROOT}/CONTRIBUTING.md" "^## Required Toolchain$" "CONTRIBUTING missing required toolchain section" +require_pattern "${REPO_ROOT}/CONTRIBUTING.md" "^## Optional Toolchain$" "CONTRIBUTING missing optional toolchain section" +require_pattern "${REPO_ROOT}/CONTRIBUTING.md" "^## Go-Only Contributor Path \\(Default\\)$" "CONTRIBUTING missing Go-only contributor path section" +require_pattern "${REPO_ROOT}/CONTRIBUTING.md" "^## CI Lane Map$" "CONTRIBUTING missing CI lane map section" +require_pattern "${REPO_ROOT}/CONTRIBUTING.md" "^## Determinism Requirements$" "CONTRIBUTING missing determinism requirements section" +require_pattern "${REPO_ROOT}/CONTRIBUTING.md" "^## Detector Authoring Guidance$" "CONTRIBUTING missing detector authoring guidance section" +require_pattern "${REPO_ROOT}/CONTRIBUTING.md" "^## Pull Request Workflow$" "CONTRIBUTING missing pull request workflow section" +require_pattern "${REPO_ROOT}/docs/map.md" "^## Source-of-truth model$" "docs map missing source-of-truth model section" +require_pattern "${REPO_ROOT}/docs/map.md" "^## Required validation bundle$" "docs map missing required validation bundle section" +require_pattern "${REPO_ROOT}/docs-site/public/llms.txt" "/docs/map/" "llms.txt missing docs source map reference" +require_pattern "${REPO_ROOT}/.github/ISSUE_TEMPLATE/bug_report.yml" "^name: Bug report$" "bug issue template missing name header" +require_pattern "${REPO_ROOT}/.github/ISSUE_TEMPLATE/bug_report.yml" "Contract surface affected" "bug issue template missing contract surface prompt" +require_pattern "${REPO_ROOT}/.github/ISSUE_TEMPLATE/feature_request.yml" "^name: Feature request$" "feature issue template missing name header" +require_pattern "${REPO_ROOT}/.github/ISSUE_TEMPLATE/feature_request.yml" "Contract impact" "feature issue template missing contract impact prompt" +require_pattern "${REPO_ROOT}/.github/ISSUE_TEMPLATE/docs_change.yml" "^name: Docs improvement$" "docs issue template missing name header" +require_pattern "${REPO_ROOT}/.github/ISSUE_TEMPLATE/docs_change.yml" "Validation commands" "docs issue template missing validation commands prompt" +require_pattern "${REPO_ROOT}/.github/pull_request_template.md" "^## Contract Impact$" "PR template missing contract impact section" +require_pattern "${REPO_ROOT}/.github/pull_request_template.md" "^## Tests and Lane Evidence$" "PR template missing tests/lane evidence section" +require_pattern "${REPO_ROOT}/README.md" "CODE_OF_CONDUCT\\.md" "README missing code of conduct link" +require_pattern "${REPO_ROOT}/README.md" "CHANGELOG\\.md" "README missing changelog link" +require_pattern "${REPO_ROOT}/docs/trust/release-integrity.md" "CHANGELOG\\.md" "release integrity docs missing changelog linkage" +require_pattern "${REPO_ROOT}/CHANGELOG.md" "^## \\[Unreleased\\]$" "CHANGELOG missing Unreleased section" +require_pattern "${REPO_ROOT}/CHANGELOG.md" "^## Changelog maintenance process$" "CHANGELOG missing maintenance process section" +require_pattern "${REPO_ROOT}/README.md" "^## Install$" "README missing install section" +require_pattern "${REPO_ROOT}/README.md" "^## First 10 Minutes \\(Offline, No Setup\\)$" "README missing first 10 minutes section" +require_pattern "${REPO_ROOT}/README.md" "^## Integration \\(One PR\\)$" "README missing integration section" +require_pattern "${REPO_ROOT}/README.md" "^## Command Surface$" "README missing command surface section" +require_pattern "${REPO_ROOT}/README.md" "^## Governance and Support$" "README missing governance and support section" +require_pattern "${REPO_ROOT}/docs/contracts/readme_contract.md" "^## Required sections$" "readme contract doc missing required sections" +require_pattern "${REPO_ROOT}/docs/contracts/readme_contract.md" "^1\\. Install$" "readme contract doc missing install section requirement" +require_pattern "${REPO_ROOT}/docs/contracts/readme_contract.md" "^2\\. First 10 Minutes$" "readme contract doc missing first 10 minutes requirement" +require_pattern "${REPO_ROOT}/docs/contracts/readme_contract.md" "^3\\. Integration$" "readme contract doc missing integration requirement" +require_pattern "${REPO_ROOT}/docs/contracts/readme_contract.md" "^4\\. Command Surface$" "readme contract doc missing command surface requirement" +require_pattern "${REPO_ROOT}/docs/contracts/readme_contract.md" "^5\\. Governance and Support$" "readme contract doc missing governance/support requirement" +require_pattern "${REPO_ROOT}/docs/roadmap/cross-repo-readme-alignment.md" "Clyra-AI/proof" "cross-repo roadmap missing proof follow-up" +require_pattern "${REPO_ROOT}/docs/roadmap/cross-repo-readme-alignment.md" "Clyra-AI/gait" "cross-repo roadmap missing gait follow-up" +require_pattern "${REPO_ROOT}/docs/roadmap/cross-repo-readme-alignment.md" "20[0-9]{2}-[0-9]{2}-[0-9]{2}" "cross-repo roadmap missing explicit due date" +require_pattern "${REPO_ROOT}/docs/governance/content-visibility.md" "^## Policy A: .*product/.*visibility$" "content visibility policy missing product section" +require_pattern "${REPO_ROOT}/docs/governance/content-visibility.md" "^## Policy B: .*\\.agents/skills/.*visibility$" "content visibility policy missing skills section" +require_pattern "${REPO_ROOT}/docs/governance/content-visibility.md" "^## Directory notices and review checklist$" "content visibility policy missing directory notices section" +require_pattern "${REPO_ROOT}/product/README.md" "docs/governance/content-visibility.md" "product directory notice missing governance policy link" +require_pattern "${REPO_ROOT}/.agents/skills/README.md" "docs/governance/content-visibility.md" "skills directory notice missing governance policy link" +require_pattern "${REPO_ROOT}/README.md" "docs/governance/content-visibility.md" "README missing governance policy link" ROOT_SOURCE="${REPO_ROOT}/core/cli/root.go" ROOT_DOC="${REPO_ROOT}/docs/commands/root.md" diff --git a/scripts/test_uat_local.sh b/scripts/test_uat_local.sh index 47e71a9..9d84b07 100755 --- a/scripts/test_uat_local.sh +++ b/scripts/test_uat_local.sh @@ -53,6 +53,52 @@ cleanup() { } trap cleanup EXIT +json_smoke_validator="$tmp_dir/check_json_smoke.go" +cat >"$json_smoke_validator" <<'GO' +package main + +import ( + "encoding/json" + "fmt" + "os" + "strings" +) + +type rootPayload struct { + Status string `json:"status"` + Message string `json:"message"` +} + +func main() { + if len(os.Args) != 3 { + fmt.Fprintln(os.Stderr, "usage: go run