docs: Phase A public hygiene + dogfood canary prep - #2
Conversation
Adds standard GitHub Actions workflows: - ci.yml: markdown lint + link check (lenient on broken links, warns) - codex-review.yml: posts @codex review on every PR (spam-guarded) Sourced from levineam/clawd templates/github-workflows/ baseline.
- templates/tools-template.md: add 'text' language specifier to unlabeled fenced code block (MD040)
- docs/optional/jsonl-memory.md: add 'correction' to type enum; standardize ID examples to 4-digit format (exp_0001, dec_0001, fail_0001) matching doc pattern
- docs/optional/context-engineering.md: fix inconsistent install paths (manual clone now uses npm root -g); clarify 13 sub-skills table is a subset ('common starters are listed below')
- starter-kit/README.md: fix broken relative links (docs/ → ../docs/)
- starter-kit/workflows/spawn-code-subagent.lobster: fix branch slugification to strip leading/trailing hyphens and fall back to 'untitled-task' if empty; add optional test_command input to replace hardcoded 'npm test'; sanitize log_spawn task output and ensure workspace dir is created
- starter-kit/workflows/write-prose.lobster: fix shell injection in load_draft (quote vars, validate path, use printf); fix heredoc delimiter collision in save_output (random unique delimiter via openssl, single-quoted to prevent content expansion, validate/sanitize outputPath)
- README.md: replace misleading '11-section playbook' with 'multi-section playbook'
- .github/workflows/ci.yml: replace || fallback with explicit file-existence check for markdownlint config; pin gaurav-nelson/github-action-markdown-link-check to commit SHA
- .github/workflows/codex-review.yml: change trigger from pull_request to pull_request_target for fork write-access; remove unnecessary pull-requests: write permission
- write-prose.lobster: replace eval+dynamic-delimiter heredoc in save_output
with a static single-quoted heredoc (PROSE_DRAFT_CONTENT_EOF_7c3a9e1b).
Eliminates the shell re-evaluation risk: template engine interpolates the
draft content before the script runs; single-quoted delimiter then prevents
any further shell expansion of that content. No eval required.
- spawn-code-subagent.lobster: guard task text in generate_branch_name and
log_spawn against shell injection. Previously `printf '%s' "\{\{inputs.task\}\}"`
allowed $(cmd) and backtick sequences in the task value to execute during
command substitution. Fixed by reading task through a single-quoted heredoc
so the template-interpolated text is treated as literal data by the shell.
- .markdownlint.json: add lint config disabling style-only rules (MD022,
MD032, MD060, MD040, etc.) that generated 1100+ false-positive errors
across CHANGELOG, templates, and docs. CI markdown lint now passes clean.
Fixes Codex P1 comments on commit 924581e.
…sync - Restore files removed by automated sync commit (0cba16c): docs/optional/context-engineering.md docs/optional/jsonl-memory.md starter-kit/workflows/spawn-code-subagent.lobster starter-kit/workflows/write-prose.lobster templates/soul-template.md, identity-template.md, tools-template.md, ontology-template.md - Fix CI: add missing trailing newline to templates/AGENTS-template.md (MD047) - Fix CodeRabbit Major (repeated): pin actions/github-script@v7 to commit SHA f28e40c7f34bde8b3046d885e986cb6290c5673b in codex-review.yml - Fix CodeRabbit Major: add session_summary to experiences.jsonl type enum in docs/optional/jsonl-memory.md - Fix CodeRabbit Major: standardize install/lookup paths in docs/optional/context-engineering.md to use $(npm root -g) consistently - Fix Codex P1: replace shell-interpolated {{inputs.task}} in validate_inputs with single-quoted heredoc in spawn-code-subagent.lobster - Fix Codex P1: replace printf '%s' "{{inputs.draft}}" with single-quoted heredoc in write-prose.lobster load_draft step - Fix Codex P1 (README.md line 59): README now correctly references all template files (restored by this commit)
…docs Address 4 P1 comments from Codex on commit c51b053: 1. spawn-code-subagent.lobster (validate_inputs): Load {{inputs.model}} via single-quoted heredoc before shell emptiness check to prevent command substitution and variable expansion in model values. 2. spawn-code-subagent.lobster (generate_branch_name): Load {{inputs.branch}} via single-quoted heredoc before branch-name conditional and echo to prevent shell injection in custom branch names. 3. write-prose.lobster (load_draft): Load {{inputs.draftPath}} via single-quoted heredoc before path validation and realpath call to prevent shell expansion in file path inputs. 4. write-prose.lobster (save_output): Load {{inputs.outputPath}} via single-quoted heredoc before traversal checks to prevent command substitution executing before the path is validated. Pattern: inputs that arrive via {{...}} interpolation are embedded in shell script before execution. Using a single-quoted heredoc captures them as literal text, preventing , $(cmd), and backtick expansion.
P1 (spawn-code-subagent.lobster): Load branch and model via single-quoted heredocs in log_spawn step to prevent shell expansion of $(cmd)/backticks/ $VAR in template-interpolated values. Switch from multiple non-atomic printf appends to a single atomic heredoc append to prevent line interleaving under concurrent workflow runs. P2 (spawn-code-subagent.lobster): Validate user-provided custom branch names with 'git check-ref-format --branch' before emitting. Invalid ref names now exit 1 with a clear error instead of propagating to 'git checkout -b'. P2 (write-prose.lobster): Restrict draftPath to WORKSPACE_PATH (or $HOME as fallback) after realpath resolution. Paths that resolve outside the allowed root are rejected with a clear error, preventing reads of arbitrary files like ../../.env via path traversal.
…edoc audit)
P1 (README.md): Fix template filename casing to match repo contents.
- agents-template.md → AGENTS-template.md
- heartbeat-template.md → HEARTBEAT-template.md
- bootstrap-template.md → BOOTSTRAP-template.md
These files exist in git with uppercase prefixes; lowercase refs caused
file-not-found errors on case-sensitive filesystems.
P1 (write-prose.lobster): Eliminate {{inputs.draft}} from shell heredoc.
Previously, the load_draft step used a single shell script that embedded
{{inputs.draft}} inside a heredoc. Even with a single-quoted delimiter,
a draft containing the delimiter string on its own line terminates the
heredoc early, letting subsequent content execute as shell commands.
Fix: split load_draft into two steps:
1. load_draft_file (action:script) — handles draftPath only. Validates
the path, restricts to ALLOWED_ROOT (narrowed from $HOME to $HOME/clawd
to address P2 traversal-window concern), then cats the file to stdout.
2. load_draft (action:template) — handles both cases via Handlebars
conditional. Inline drafts are processed entirely by the template engine
with NO shell involvement, eliminating heredoc injection entirely.
Full audit — no unguarded template vars remain in shell script context:
- All {{inputs.*}} in scripts are wrapped in single-quoted heredocs.
- {{inputs.draft}} is now in action:template only (no shell).
- {{steps.load_draft.draft_text}} in save_output retains a heredoc (the
template engine must embed it), but: (a) the delimiter is now 64 hex
chars making collision impractical in normal prose, (b) human approval
is required before this step runs, and (c) comments document the residual
risk and recommend draftPath for untrusted automated content.
|
Codex Review: Didn't find any major issues. You're on a roll. ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
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". |
|
@codex review |
|
@coderabbitai review |
✅ Actions performedReview triggered.
|
|
@codex review |
|
@coderabbitai review |
✅ Actions performedReview triggered.
|
|
Codex Review: Didn't find any major issues. More of your lovely PRs please. ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
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". |
|
@codex review |
|
@coderabbitai review |
✅ Actions performedReview triggered.
|
|
Codex Review: Didn't find any major issues. Bravo. ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
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". |
|
@codex review |
|
@coderabbitai review |
✅ Actions performedReview triggered.
|
|
Codex Review: Didn't find any major issues. 🚀 ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
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". |
|
@codex review |
|
@coderabbitai review |
✅ Actions performedReview triggered.
|
|
Codex Review: Didn't find any major issues. 👍 ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
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". |
# Conflicts: # CHANGELOG.md # docs/meta/source-to-export-map.json
Summary\n- complete Phase A hygiene updates for public jarvOS docs\n- fix README/template inventory mismatch\n- add troubleshooting docs for context overload and ACP wrapper workaround\n- add Phase B canary runbook for dogfooding prep\n- sync exported docs/templates metadata\n\n## Validation\n- markdownlint README.md CHANGELOG.md docs//*.md starter-kit//.md templates/**/.md\n- git diff --check\n- python3 -m json.tool docs/meta/source-to-export-map.json\n\n## Notes\n- Public-safe wording and path hygiene preserved.\n- Follow-up Phase B canary execution remains to be done.
Summary by CodeRabbit
New Features
Documentation
Chores