[daveh-beep]

Add traceable writing workflows and local corpus tools

What observed experience does this improve?

Chalkline describes a small writing system, but growing corpora lack local discovery checks and drafting/review responses do not consistently expose their sources and gaps. This proposal adds optional corpus tools and makes task-level traceability and evidence-backed confidence a default, while retaining a no-install setup path.

Scope and relationship to #17

This is a consolidated draft against main, not a feature branch with hidden prerequisite commits. It includes the previously developed snapshot, calibration, and scoped-approval hardening as well as the new tools and receipt contract.

It overlaps #17's external-language-source safety work. Reviewers should decide whether this proposal supersedes #17 or whether that PR lands first and this diff is reconciled afterward. Do not merge both overlapping versions without reconciliation. This proposal does not close or change #17.

Suggested review order:

1. Trust and approval boundaries: PINNING.md, AGENTS.md, calibration, setup, and learning contracts.
2. Corpus discovery: tools/corpus.py, its tests, fictional Harbor example, and architecture/growth/integration guides.
3. Default receipts: docs/traceability.md, operating/setup instructions, tools/receipt.py, its format and tests.
4. Verification: contract assertions, manual behavioral fixtures, and the optional CI workflow.

Changes

• Keep drafting agents on reviewed local language data, with explicit source records, recovery, and separate consumer deployment decisions.
• Preserve factual strength, scoped approval, recipient-controlled teach-back, held-out calibration, and exact-wording boundaries.
• Distinguish template maintenance from team setup and upstream project governance from an adopter's local ownership.
• Add standard-library Python checks, deterministic manifests, and literal filtered search. No dependencies, model calls, or network access are required by the tools.
• Add a fictional nested corpus demonstrating explicit scope and routing without shipping a real company's writing rules.
• Make a separate usage receipt default for drafting/review, including sources, factual/rule evidence, gaps, unresolved matters, required review, and separate reviewer approval.
• Define confidence as 0 blocked / 1 limited / 2 supported / 3 corroborated across guidance, facts, and verification. Use the lowest applicable score; declared blockers force 0. Scores are not probability, compliance, writer evaluation, or publication permission.
• Add an optional JSON checker for receipt structure, evidence links, and score arithmetic. It cannot determine whether supplied evidence is true or adequate, or whether blockers were omitted.
• Add regression tests, a read-only CI configuration, and isolated manual behavioral fixtures.

Explicitly out of scope

No documentation website or site dependencies; no hosted service, private corpus, accounts, telemetry, automatic policy learning, model runner, snapshot projector, or publishing integration. Cross-tool retrieval remains an extension point requiring a tested adapter.

Verification

Executed on the final tree committed as 4e7c49f2c10ea32d212815934406346c7af0311f, using Python 3.9.6:

• python3 -B -m unittest discover -s tests -q: 34 tests passed.
• bash checks/adversarial-contract.sh: passed contract-text assertions.
• Corpus checks: empty root 0, fictional Meridian 4, fictional Harbor 5 references; all structurally valid.
• git diff --cached --check: passed, covering added files as well as modified files.
• Staged-content screen: no selected private-hostname, private-path, or credential-pattern matches.

Public-portability review found no publication-blocking internal-content leak in its inspected scope. Two issues were corrected: inherited governance settings during template adoption, and implied generic MCP compatibility. This is not a guarantee of publication rights or absence of all confidential material.

Learning check and merge gate

Keep this PR in draft. New behavioral fixtures and confidence-receipt scenarios have not been executed in isolated model sessions. Unit tests verify implementations, not model adherence or improved writing. Historical red-team evidence applies only to its recorded versions and conditions.

Before merging the behavior changes, supply the held-out reproduction and unchanged control required by CONTRIBUTING.md, or record a maintainer-approved evidence exception. Neither is currently recorded. Hosted GitHub Actions checks passed on Python 3.9 and 3.13 for both push and pull-request runs. The DCO check also passed. Python 3.13 was verified in CI, not on the local machine.

Safety and review

• Examples and new test fixtures are fictional; private writing standards and raw session transcripts are excluded.
• Existing public project license, governance, and security references remain.
• Content/design and technical maintainer review are required.
• Approval of an artifact, reusable calibration, reference change, consumer deployment, and publication remain separate.
• Commit 4e7c49f2c10ea32d212815934406346c7af0311f includes the contributor-authorized DCO sign-off. The local commit-time sadscan check passed.

Traceability receipt

Scope: consolidated proposed tree against main 2a8a2c224b8c9393efce9d03de5e8e050c7868d9; excludes publication and behavioral-effectiveness claims.
Sources: committed files named above at 4e7c49f2c10ea32d212815934406346c7af0311f. Git tree identity: 0331fa5285cd66253c95d1a4a26c43653ded792f (byte identity, not approval).
Basis: implementation claims are supported by source inspection and executed local checks; behavior requirements are proposals pending their own evidence.
Missing evidence: held-out model runs, unchanged behavioral controls, hosted CI, and maintainer acceptance.
Unresolved: #17 overlap and final merge strategy.
Confidence: guidance 2, factual support 2, verification 1; overall 1 for release readiness.
Required review: content/design and technical maintainers; merge authorization. Publication of this draft PR was explicitly authorized; merge was not.
Reviewer approval: not recorded.

[github-advanced-security]

You are seeing this message because GitHub Code Scanning has recently been set up for this repository, or this pull request contains the workflow file for the Code Scanning tool.

What Enabling Code Scanning Means:

• The 'Security' tab will display more code scanning analysis results (e.g., for the default branch).
• Depending on your configuration and choice of analysis tool, future pull requests will be annotated with code scanning analysis results.
• You will be able to see the analysis results for the pull request's branch on this overview once the scans have completed and the checks have passed.

For more information about GitHub Code Scanning, check out the documentation.