docs: worklog v1 requirements, design, ADRs, and 33-issue implementation plan - #1
docs: worklog v1 requirements, design, ADRs, and 33-issue implementation plan#1Saber5656 wants to merge 3 commits into
Conversation
Requirements baseline approved by user on 2026-07-10: local-only daily/standup report generator (zsh + git + Claude Code + Codex sessions), loopback-only local LLM narrative, redaction default-on, Go implementation. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Key fixes: - llm.enabled defaults to false (opt-in per approved requirement wording); zero-config runs now always validate - unified non-loopback warning taxonomy on llm_blocked_nonloopback - added zsh_lines_skipped / git_root_missing / codex_file_skipped to the canonical DESIGN §13 warning list (issues now reference, not amend) - dependency table corrections (03<-04, 18/24<-17, 27<-22, 30<-26..29, 31<-30+32, 33<-30+31) and wave-0 execution order note - providers emit raw cwd; normalization owned by aggregation (research docs aligned with DESIGN §6.2); agent-session counts are in-range only - sanitize: escape functions documented non-idempotent, single-application - redaction corpus moved to JSON (multiline PEM + exact-want assertions); RedactEvent covers Project and returns (Event, int) - render: project headings and LLM narrative escaped via EscapeText with adversarial goldens; standup buckets carry explicit clamp ranges - LLM prompt marker integrity via encoding/json HTML escaping (no-op replace bug removed); Client.Model() accessor for attribution - output writer exit-code mapping aligned with DESIGN §13; created-parent re-verification; git Runner dir contract + stderr caps - release workflow: glob tag trigger + validated workflow_dispatch dry run - invariant suite pins XDG_*/TMPDIR into the watched tree; hard deps on all commands - ADR-005/DESIGN §16 updated to the already-public repo reality Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- issue 25: llm-on fixture explicitly sets llm.enabled/model - issues 18/24: dependency sections aligned with ISSUE_PLAN (add 17) - ISSUE_PLAN / issues 01,30,33: align remaining go-public wording with the already-public repository reality Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
|
Warning Review limit reached
Next review available in: 16 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (44)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: ab3629d8d1
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| - Tidy check: `go mod tidy && git diff --exit-code go.mod go.sum` (tolerate | ||
| absent `go.sum` while there are no deps). |
There was a problem hiding this comment.
In the issue-01 skeleton there is intentionally no go.sum, but this command is specified without the -- path separator. I checked Git's behavior on a repo with only go.mod: git diff --exit-code go.mod go.sum exits 128 with go.sum: no such path in the working tree, so issue 02's own acceptance criterion (green against the issue-01 tree) will fail until a dependency creates go.sum. Use git diff --exit-code -- go.mod go.sum or gate the missing path.
Useful? React with 👍 / 👎.
| 4. No LLM involvement, no redaction needed (counts only — but note: | ||
| originator strings print raw → pass through `sanitize.Line(…, 60)`). |
There was a problem hiding this comment.
When a Codex session_meta.originator contains a token-like string, worklog sources would print it to stdout after only sanitize.Line. That is still source log content and bypasses invariant I4/ADR-004's redaction-before-user-visible-output rule; sources should run the same redactor (or aggregate path) before printing originator names.
Useful? React with 👍 / 👎.
| - Provider error → converted to a warning | ||
| (`Code = string(id)+"_failed"` unless the provider already returned | ||
| typed warnings; the error message becomes the warning message); | ||
| partial events returned alongside an error are kept. | ||
| - Panic in a provider is recovered → warning (`<id>_panic`), run |
There was a problem hiding this comment.
This creates public warning codes like zsh_failed and zsh_panic that are not in DESIGN §13 or the constants required by issue 03. In any provider-error/panic path the report footer/README will expose undocumented codes, contradicting the stable warning taxonomy; use an existing canonical code or add the new codes to the taxonomy/model issue.
Useful? React with 👍 / 👎.
| - Negatives (must NOT mask, ≥ 20 lines): 12/40-char git hashes; commit | ||
| subject `fix: rotate token handling`; `TOKEN_COUNT=5` (name not in the | ||
| secret-name list — verify the pattern's name list is anchored); |
There was a problem hiding this comment.
The issue also requires implementing DESIGN §8 exactly, whose env-assignment pattern matches any variable name containing TOKEN. Under that regex, TOKEN_COUNT=5 is a match, so this mandatory negative corpus case cannot pass unless the design pattern is changed in the same docs set; either update DESIGN §8 to the anchored name rule or remove this negative.
Useful? React with 👍 / 👎.
| --pretty=format:%H%x1f%an%x1f%ae%x1f%aI%x1f%s%x1e | ||
| --shortstat |
There was a problem hiding this comment.
With Git 2.43, running this exact git log format emits the --shortstat line after the %x1e record separator, so splitting records on 0x1e leaves the first record without stats and prefixes the next record with the previous stats. The parser contract below expects the shortstat bytes inside the same record, so commits with file changes will be parsed incorrectly unless the separator is emitted after the shortstat or the parser associates post-separator stats with the previous commit.
Useful? React with 👍 / 👎.
| - `Makefile` — targets: `build` (`go build -trimpath -o bin/worklog | ||
| ./cmd/worklog`), `test` (`go test -race ./...`), `lint` | ||
| (`gofmt -l . && go vet ./...`; golangci-lint added by issue 02), `clean`. |
There was a problem hiding this comment.
gofmt -h describes -l as listing files whose formatting differs, and an unformatted file still makes gofmt -l exit 0, so this lint target will pass with badly formatted Go code. Wrap it in a non-empty-output check (or use a shell test around gofmt -l) before go vet so local lint matches the intended formatting gate.
Useful? React with 👍 / 👎.
| - Empty → `Run(ctx, "", "config", "--get", "user.email")` once (the | ||
| `dir==""` global form); |
There was a problem hiding this comment.
This invocation is described as the global form, but git config -h shows --global is the option that selects the global config file; without it, running worklog from inside any Git repository can read that repository's local user.email instead. In that context the default author filter will silently select the wrong identity, so use git config --global --get user.email or otherwise avoid local config lookup.
Useful? React with 👍 / 👎.
| 3. Project normalization (DESIGN §6.2): for `agent-session` events whose | ||
| raw Project (cwd) equals or is a subpath of `<root>/<repo>` for any | ||
| configured git root (or matches an explicit repo path), the project key | ||
| is `<repo>` (first path element under the root). A cwd equal to a root | ||
| itself → key = base name of cwd. Otherwise: cleaned absolute path with |
There was a problem hiding this comment.
For users with nested repos like ~/dev/org/foo, this rule maps an agent session under foo to project org, while git commit extraction maps the same repository to foo. That splits one project across two report sections and contradicts DESIGN §6.2's basename-based attribution; match discovered/explicit repos or use the deepest repo directory basename instead of the first path element under the root.
Useful? React with 👍 / 👎.
| - `cli-secret-flag` must handle `--token=x`, `--token x`, `-p=x` forms | ||
| listed in the pattern. |
There was a problem hiding this comment.
The required -p=x case cannot be satisfied while also implementing DESIGN §8's cli-secret-flag pattern exactly, because --?(password|passwd|token|...) matches one- or two-dash long names, not the single-letter -p. Either add -p to the design pattern in the same docs change or drop this acceptance requirement; otherwise the corpus forces a rule that the normative table disallows.
Useful? React with 👍 / 👎.
| - `zsh` (when enabled): file exists+readable (missing → WARN, fix: | ||
| check path/HISTFILE); parse first 2000 entries: ExtendedCount==0 → | ||
| WARN with the exact fix | ||
| `echo 'setopt EXTENDED_HISTORY INC_APPEND_HISTORY' >> ~/.zshrc` | ||
| (new entries only — note that old entries stay undated); else PASS |
There was a problem hiding this comment.
Because existing simple-format entries stay undated after a user enables EXTENDED_HISTORY, parsing only the first 2000 entries can keep warning ExtendedCount==0 on long histories even when all new entries are timestamped. Doctor should sample the tail or scan until it has seen recent entries, otherwise users who already applied the fix get a persistent false warning.
Useful? React with 👍 / 👎.
1 participant
Summary
Documentation-only PR establishing the v1 requirements, architecture, security model, and implementation plan for worklog — a local-only, read-only CLI that generates daily reports and standup summaries from zsh history, git commits, and AI agent session logs (Claude Code / Codex), with an optional loopback-only local LLM narrative.
No product code is included;
docs/is the canonical source of truth, and GitHub Issues #1–#33 (created after this PR) are derived fromdocs/issues/*.md.Contents
docs/DESIGN.mddocs/decisions/ADR-001..005docs/ISSUE_PLAN.mddocs/issues/01..33docs/research/*.mdRequirements baseline (user-approved 2026-07-10)
Review evidence
All documents were reviewed by Codex (
codex exec, read-only sandbox): 6 batches covering the design set and every issue file individually, plus a post-fix verification pass. 2 BLOCKER and ~30 MAJOR findings were found and fixed in 655d79c and ab3629d (see commit messages for the itemized list). Final verification: 14/14 items OK.Open questions for the repository owner
Notes
🤖 Generated with Claude Code