Add contributor workflow and templates

.github/ISSUE_TEMPLATE/01-bug.yml

@@ -0,0 +1,77 @@
+name: "Bug report"
+description: "Report reproducible incorrect CLI or guide-validation behavior."
+title: "[Bug]: "
+labels:
+  - "bug"
+body:
+  - type: "markdown"
+    attributes:
+      value: "Do not put vulnerability details, secrets, personal data, or private paths here. Use https://github.com/plx/agentic-navigation-guide/security/advisories/new for a private security report."
+  - type: "input"
+    id: "version"
+    attributes:
+      label: "Version or source commit"
+      description: "Give the installed version or exact source commit and installation method."
+      placeholder: "0.2.0, commit SHA, or trusted source checkout"
+    validations:
+      required: true
+  - type: "dropdown"
+    id: "platform"
+    attributes:
+      label: "Platform"
+      description: "Select the operating-system scope and name relevant filesystem details below."
+      options:
+        - "Linux"
+        - "macOS"
+        - "Windows"
+        - "Multiple or other"
+    validations:
+      required: true
+  - type: "textarea"
+    id: "observed"
+    attributes:
+      label: "Observed behavior"
+      description: "Describe the actual status, stdout, stderr, and filesystem result with sensitive values removed."
+      placeholder: "Command shape, exit status, bounded diagnostic, and resulting state"
+    validations:
+      required: true
+  - type: "textarea"
+    id: "expected"
+    attributes:
+      label: "Expected behavior"
+      description: "Describe the documented behavior or contract row that should apply."
+      placeholder: "Link the maintained contract section when possible"
+    validations:
+      required: true
+  - type: "textarea"
+    id: "reproduction"
+    attributes:
+      label: "Minimal deterministic reproduction"
+      description: "Provide fixed synthetic files and commands that do not touch global Cargo, git, home-directory, or private state."
+      placeholder: "Smallest clean temporary-workspace reproducer"
+    validations:
+      required: true
+  - type: "textarea"
+    id: "regression"
+    attributes:
+      label: "Proposed red-before-fix regression"
+      description: "Name the smallest deterministic test that should fail for this reason before a fix."
+      placeholder: "Test file, test name, expected nonzero status, and failure reason"
+    validations:
+      required: true
+  - type: "textarea"
+    id: "compatibility"
+    attributes:
+      label: "Compatibility and documentation impact"
+      description: "State affected versions, platforms, CLI or guide contracts, documentation, dependencies, and license attribution."
+      placeholder: "None, or an explicit impact list"
+    validations:
+      required: true
+  - type: "textarea"
+    id: "security"
+    attributes:
+      label: "Security assessment"
+      description: "Say whether this is an ordinary public bug. Move suspected vulnerabilities to the private route above before adding details."
+      placeholder: "Ordinary bug with no security impact, or moved to private reporting"
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/02-contract-proposal.yml

@@ -0,0 +1,58 @@
+name: "Contract proposal"
+description: "Propose a reviewed change to the CLI, guide format, compatibility, or trust boundary."
+title: "[Contract]: "
+labels:
+  - "needs-decision"
+  - "domain: compatibility"
+body:
+  - type: "markdown"
+    attributes:
+      value: "Proposals do not change the normative contract until an issue-scoped pull request is reviewed and merged. Do not include private vulnerability details."
+  - type: "textarea"
+    id: "current-contract"
+    attributes:
+      label: "Current contract and evidence"
+      description: "Link the maintained contract text, fixture row, test, or documented absence that governs today."
+      placeholder: "Current rule, evidence ID, and owning issue"
+    validations:
+      required: true
+  - type: "textarea"
+    id: "proposed-contract"
+    attributes:
+      label: "Proposed contract"
+      description: "State one exact new supported or rejected behavior and its success or failure semantics."
+      placeholder: "Normative wording plus an executable example"
+    validations:
+      required: true
+  - type: "textarea"
+    id: "compatibility"
+    attributes:
+      label: "Compatibility and alternatives"
+      description: "Identify migration, versioning, stream, status, package, and rejected-alternative consequences."
+      placeholder: "Compatible, breaking, or unavailable with rationale"
+    validations:
+      required: true
+  - type: "textarea"
+    id: "platforms"
+    attributes:
+      label: "Platform and trust-boundary impact"
+      description: "Cover Linux, macOS, Windows, filesystem capability differences, and stable-tree limitations."
+      placeholder: "Exact platform matrix and unavailable capabilities"
+    validations:
+      required: true
+  - type: "textarea"
+    id: "security"
+    attributes:
+      label: "Security and resource impact"
+      description: "Describe trust anchors, diagnostics, containment limits, resource bounds, and private-reporting needs without exploit details."
+      placeholder: "No change, or an explicit bounded impact"
+    validations:
+      required: true
+  - type: "textarea"
+    id: "dependencies"
+    attributes:
+      label: "Issue graph and implementation dependencies"
+      description: "List native `blocked by` and sub-issue relationships, related decisions, and the one intended implementation issue."
+      placeholder: "Blocked by #N; sub-issues; related but intentionally separate work"
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: "Private vulnerability report"
+    url: "https://github.com/plx/agentic-navigation-guide/security/advisories/new"
+    about: "Report suspected vulnerabilities privately; do not use a public issue."

.github/pull_request_template.md

@@ -0,0 +1,64 @@
+# Pull request
+
+## Problem
+
+<!-- Link one selected issue and explain the reported reason for this change. -->
+
+## Before behavior
+
+<!-- State the parent/base behavior. Avoid claims broader than the evidence. -->
+
+## After behavior
+
+<!-- State the smallest issue-scoped result and any intentionally unchanged behavior. -->
+
+## Red-before-fix evidence
+
+<!--
+Record the base commit SHA, exact pre-fix command, nonzero status, and expected
+failure reason. For a defect, the test must fail for the reported reason before
+the implementation changes; do not use an unrelated failure.
+-->
+
+## Validation
+
+<!--
+List the focused post-fix and full post-fix commands and results. Identify which
+of Linux, macOS, and Windows were exercised locally and which were exercised by
+hosted CI.
+-->
+
+## Documentation and compatibility
+
+<!--
+State the documentation impact and compatibility impact. Name every maintained
+contract, README, changelog, package, or release record changed, or write None.
+-->
+
+## Security and sensitive data
+
+<!--
+State the security impact. Confirm that logs, fixtures, paths, and public text
+contain no token, secret, private report detail, personal data, or resolved
+external target.
+-->
+
+## Dependencies and issue graph
+
+<!--
+State the dependency or license impact. Record native blockers, sub-issues, and
+related findings that remain separate from this pull request.
+-->
+
+## Checklist
+
+- [ ] This pull request addresses one issue and contains no unrelated cleanup.
+- [ ] The regression is deterministic, hermetic, bounded, and placed at the
+      narrowest useful layer.
+- [ ] Focused and full validation results are recorded above.
+- [ ] User-facing and normative documentation are aligned where applicable.
+- [ ] Dependency, license, package, release, and security impacts are explicit.
+- [ ] Every review conversation is resolved before merge.
+
+<!-- Replace NUMBER and keep exactly one issue-scoped closing directive. -->
+Closes #NUMBER

.github/workflows/ci.yml

@@ -209,6 +209,12 @@ jobs:
     - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd  # v5.0.1
       with:
         persist-credentials: false
+    - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
+      with:
+        python-version: "3.12"
+    - uses: taiki-e/install-action@c070f87102a1c75b3183910f391c1cb887fe13c8  # v2.77.6
+      with:
+        tool: just@1.51.0
     - name: Install checksum-pinned actionlint 1.7.12
       env:
         ACTIONLINT_SHA256: 8aca8db96f1b94770f1b0d72b6dddcb1ebb8123cb3712530b08cc387b349a3d8
@@ -265,15 +271,20 @@ jobs:
       run: >-
         PYTHONDONTWRITEBYTECODE=1 python3 -m unittest
         tests/test_audit_github_protections.py -v
+    - name: Validate contributor guidance and templates
+      run: |
+        python3 -m py_compile scripts/check_contributor_templates.py
+        just test-contributor-templates
     - name: Lint maintained Markdown
       run: |
         rumdl check --disable MD010,MD013,MD038 README.md
+        rumdl check --disable MD013 CONTRIBUTING.md .github/pull_request_template.md
         rumdl check SECURITY.md docs/security-response-runbook.md
         rumdl check --disable MD010,MD013,MD018,MD031,MD038 docs/v0.2-contract.md docs/release-policy.md docs/maintainer-continuity.md docs/repository-protections.md docs/history/README.md
     - name: Check maintained documentation links
       env:
         GITHUB_TOKEN: ${{ github.token }}
-      run: lychee --no-progress README.md SECURITY.md .github/examples/readme-verify.yml docs/v0.2-contract.md docs/release-policy.md docs/security-response-runbook.md docs/maintainer-continuity.md docs/repository-protections.md docs/history/README.md
+      run: lychee --no-progress README.md CONTRIBUTING.md SECURITY.md .github/pull_request_template.md .github/ISSUE_TEMPLATE/*.yml .github/examples/readme-verify.yml docs/v0.2-contract.md docs/release-policy.md docs/security-response-runbook.md docs/maintainer-continuity.md docs/repository-protections.md docs/history/README.md
 
   issue-selector:
     name: Production-readiness issue selector

AGENTIC_NAVIGATION_GUIDE.md

@@ -67,6 +67,7 @@
 - CHANGELOG.md # Complete prepared 0.2.0 changes and published-0.1.4 migration
 - LICENSING.md # Fact-only historical license clarification and yank decision
 - README.md
+- CONTRIBUTING.md # One-issue workflow, deterministic red-before evidence, test rules, validation, and triage
 - SECURITY.md # Supported versions, private vulnerability reporting, trust boundary, and disclosure policy
 - docs/ # Maintained user and contract documentation
   - v0.2-contract.md # Normative v0.2 guide language and filesystem mapping
@@ -89,6 +90,11 @@
   - config.toml # project-local aliases and rust-version-aware dependency resolution
 - .github/
   - dependabot.yml # Weekly review-only Cargo and GitHub Actions update proposals
+  - ISSUE_TEMPLATE/
+    - 01-bug.yml # Structured public bug report without sensitive vulnerability details
+    - 02-contract-proposal.yml # Structured CLI, guide, compatibility, and trust-boundary proposal
+    - config.yml # No blank public issues; private vulnerability-report contact route
+  - pull_request_template.md # One-issue evidence, validation, impacts, graph, and closing-directive prompts
   - examples/
     - readme-verify.yml # Actionlint-checked immutable README workflow example
   - repository-protections/
@@ -109,11 +115,12 @@
 - NOTICE # Apache-2.0 section 4(d) notice for downstream distributors
 - LICENSE-MIT
 - LICENSE-APACHE
-- justfile # Repository task aliases, including production-readiness work selection
+- justfile # Repository task aliases, including work selection and contributor-template checks
 - scripts/
   - check_coverage.py # Fail-closed overall and critical-module branch-aware coverage policy
   - check_mutation_report.py # Reviewed blocker-mutation completeness and survivor gate
   - check_release_identity.py # Fail-closed version/tag/changelog/baseline checker
+  - check_contributor_templates.py # Strict contributor-guide, issue-form, chooser, and PR-template contract
   - audit_github_protections.py # Live ruleset, tag, environment, and secret-name policy audit
   - get_next_production_readiness_issue.py # Select the next remediation issue from live GitHub state
   - run_performance_baseline.py # Fixed-fixture release timing and resource regression harness
@@ -136,6 +143,7 @@
   - issue_68_normative_source.rs # Sole normative claimant, historical rule ledger, links, and contradiction proof
   - issue_71_maintainer_continuity.rs # Single-maintainer exception, candid control status, and policy-alignment regressions
   - issue_69_security_policy.rs # Private report route, support, threat-model, response, and CI policy proof
+  - issue_70_contributor_workflow.rs # Setup, issue graph, red-before, templates, validation, and triage proof
   - issue_55_platform_conformance.rs # Three-platform full-suite, capability, skip, and release-dependency policy
   - issue_47_output_contract.rs # Fixed CLI stream, quiet-mode, and recursive-diagnostic matrix
   - issue_101_parent_explicit_guide.rs # Parent-containing explicit-guide authority and cross-platform ancestor regressions
@@ -144,6 +152,7 @@
   - test_check_coverage.py # Coverage report floor and missing-instrumentation regressions
   - test_check_mutation_report.py # Mutation report completeness and survivor regressions
   - test_check_release_identity.py # Release-identity checker mutation regressions
+  - test_check_contributor_templates.py # Constrained YAML, required-heading, route, and fail-closed regressions
   - test_audit_github_protections.py # Offline GitHub-control comparison and pagination regressions
   - test_get_next_production_readiness_issue.py # Offline selector regression suite
   - test_performance_baseline.py # Performance matrix, scaling, metadata, and reference regressions
@@ -158,6 +167,7 @@
   - 2026-07-27-issue-68-specification-disposition.md # Historical specification and PR #21 disposition evidence
   - 2026-07-27-issue-71-maintainer-continuity.md # Approved sole-maintainer exception and missing-control disposition
   - 2026-07-27-issue-69-security-policy.md # Private route, claim mapping, tabletop, and residual-risk evidence
+  - 2026-07-27-issue-70-contributor-workflow.md # Red-before, clean-checkout, rendered-template, and cold-read evidence
   - 2026-07-27-issue-65-repository-protections.json # Non-sensitive admin-visible hosted-control attestation
   - 2026-07-27-issue-65-repository-protections.md # Required-check, tag, environment, and rejection-probe evidence
   - 2026-07-27-issue-47-output-contract.md # Broken-pipe, quiet-mode, and GitHub diagnostic evidence

CHANGELOG.md

@@ -58,6 +58,11 @@ complete and the final candidate is revalidated.
   owner approval with administrator bypass disabled. The zero independent
   review count and allowed self-review are explicit consequences of the dated
   single-maintainer exception.
+- A root contributor guide, structured bug and contract-proposal issue forms,
+  and a pull request template now require one-issue scope, deterministic
+  red-before-fix evidence, focused/full validation, native dependency links,
+  documentation/compatibility/security review, and dependency/license impact.
+  CI validates their constrained YAML and headings without adding fuzzing.
 - `docs/v0.2-contract.md` is mechanically enforced as the sole normative v0.2
   specification. The original root `Specification.md` is preserved with its
   Git history under `docs/history/`, where an unmistakable dated banner and