Title
SECURITY.md and security model documentation
Summary
Write the public-facing security documentation: SECURITY.md
(vulnerability reporting, supported versions, scope) and
docs/SECURITY-MODEL.md (the user-readable distillation of DESIGN §12:
assets, boundaries, threats, mitigations, and explicit non-guarantees).
Context
An OSS tool that reads shell history and talks to a local LLM will get
security scrutiny (deservedly). The repository is already public, so
publishing the threat model and an honest non-guarantees list builds the
trust the product competes on and gives vulnerability reporters a clear
channel from day one.
Scope
SECURITY.md (repo root), docs/SECURITY-MODEL.md,
docs/SECURITY-MODEL.ja.md (Japanese parity translation).
Detailed Requirements
SECURITY.md:
- Reporting: GitHub Private Vulnerability Reporting (advisories) as the
channel; response target (initial reply ≤ 7 days); no bounty.
- Supported versions table (latest minor only during v0/v1).
- Scope statement: what counts (invariant violations — any external
network I/O, any source-file modification, redaction bypass with
built-in rules, write outside declared paths, secret exposure in
diagnostics) and what does not (bugs in the user's LLM server,
redaction misses for token formats not in the built-in set — those are
ordinary issues, welcome but not vulnerabilities).
- Setup note for the repo owner ([HUMAN], not the implementing agent):
Private Vulnerability Reporting must be enabled in the repository's
security settings for the advisory channel to work — record this as a
checklist line in the PR description.
docs/SECURITY-MODEL.md (≤ 2 pages, user language, no Go symbols):
- What worklog reads / writes / never does (I1–I5 restated concretely),
including verbatim these four "never" statements: (1) "worklog never
sends data anywhere except the loopback LLM endpoint you configure";
(2) "worklog never modifies the files it reads"; (3) "worklog never
writes outside the output path you specify, its config file, and
nothing else"; (4) "worklog never phones home — no telemetry, no
update checks, no crash reporting".
- Trust-boundary diagram (ASCII, adapted from DESIGN §12.1 table).
- Threats table condensed: threat → what worklog does about it → where
it's tested (link docs/INVARIANTS.md sections and CI job names).
- Explicit non-guarantees: redaction is best-effort pattern matching;
the local LLM process itself is outside the trust boundary (whatever
you send it, it has); reports you share are your responsibility;
worklog does not protect against a compromised local machine.
- LLM data-flow paragraph: exactly what fields are serialized into the
prompt (mirror DESIGN §11.2), with the reminder that include_prompts
widens it.
- Cross-consistency requirement: every claim must be traceable to a DESIGN
section or enforcement issue — add HTML-comment breadcrumbs
(<!-- DESIGN §12.2 -->) per paragraph so future edits keep the chain.
- Both files in English (ja translation of SECURITY-MODEL as
docs/SECURITY-MODEL.ja.md — same parity rule as 31).
Acceptance Criteria
Validation
Markdown link check + the claim-mapping table in the PR description.
Reviewer: read SECURITY-MODEL cold and try to find one overclaim; PR
merges only when none found.
Dependencies
01, 30 (docs/INVARIANTS.md is linked and quoted), 31 (README links and
final wording must exist for the consistency pass).
Non-goals
Formal verification claims, compliance frameworks (SOC2 etc.), pentest
reports, bounty program setup.
Design References
docs/DESIGN.md §12 (entire), §11.2docs/INVARIANTS.md (issue 30), ADR-002/003/004
Source of truth: docs/issues/33-security-docs.md (PR #1, branch docs/v1-design). If this issue and the repo docs disagree, the docs win. Execution order and dependencies: docs/ISSUE_PLAN.md (this is issue 33 of 33).
Title
SECURITY.md and security model documentation
Summary
Write the public-facing security documentation:
SECURITY.md(vulnerability reporting, supported versions, scope) and
docs/SECURITY-MODEL.md(the user-readable distillation of DESIGN §12:assets, boundaries, threats, mitigations, and explicit non-guarantees).
Context
An OSS tool that reads shell history and talks to a local LLM will get
security scrutiny (deservedly). The repository is already public, so
publishing the threat model and an honest non-guarantees list builds the
trust the product competes on and gives vulnerability reporters a clear
channel from day one.
Scope
SECURITY.md(repo root),docs/SECURITY-MODEL.md,docs/SECURITY-MODEL.ja.md(Japanese parity translation).Detailed Requirements
SECURITY.md:channel; response target (initial reply ≤ 7 days); no bounty.
network I/O, any source-file modification, redaction bypass with
built-in rules, write outside declared paths, secret exposure in
diagnostics) and what does not (bugs in the user's LLM server,
redaction misses for token formats not in the built-in set — those are
ordinary issues, welcome but not vulnerabilities).
Private Vulnerability Reporting must be enabled in the repository's
security settings for the advisory channel to work — record this as a
checklist line in the PR description.
docs/SECURITY-MODEL.md(≤ 2 pages, user language, no Go symbols):including verbatim these four "never" statements: (1) "worklog never
sends data anywhere except the loopback LLM endpoint you configure";
(2) "worklog never modifies the files it reads"; (3) "worklog never
writes outside the output path you specify, its config file, and
nothing else"; (4) "worklog never phones home — no telemetry, no
update checks, no crash reporting".
it's tested (link
docs/INVARIANTS.mdsections and CI job names).the local LLM process itself is outside the trust boundary (whatever
you send it, it has); reports you share are your responsibility;
worklog does not protect against a compromised local machine.
prompt (mirror DESIGN §11.2), with the reminder that
include_promptswidens it.
section or enforcement issue — add HTML-comment breadcrumbs
(
<!-- DESIGN §12.2 -->) per paragraph so future edits keep the chain.docs/SECURITY-MODEL.ja.md— same parity rule as 31).Acceptance Criteria
the repo slug).
listed in Detailed Requirements, the non-guarantees list, the LLM
data-flow paragraph, and links that all resolve.
DESIGN §/issue (reviewer-checkable).
docs/INVARIANTS.md).Validation
Markdown link check + the claim-mapping table in the PR description.
Reviewer: read SECURITY-MODEL cold and try to find one overclaim; PR
merges only when none found.
Dependencies
01, 30 (
docs/INVARIANTS.mdis linked and quoted), 31 (README links andfinal wording must exist for the consistency pass).
Non-goals
Formal verification claims, compliance frameworks (SOC2 etc.), pentest
reports, bounty program setup.
Design References
docs/DESIGN.md§12 (entire), §11.2docs/INVARIANTS.md(issue 30), ADR-002/003/004Source of truth:
docs/issues/33-security-docs.md(PR #1, branchdocs/v1-design). If this issue and the repo docs disagree, the docs win. Execution order and dependencies:docs/ISSUE_PLAN.md(this is issue 33 of 33).