yaklang-workspace

Imported from wlingze/dotfiles (agents/yaklang-workspace/AGENTS.md). Install upstream with npx skills add wlingze/dotfiles --skill yaklang-workspace. Copyright stays with the author.

Agent Working Protocol: Git Worktree Architecture

The following universal rules are the same as ~/.config/AGENTS.md (also in .cursor/rules/universal-agent-protocol.mdc when you open this root in Cursor).

Time verification (MUST)

Before making any decision, first verify the current real time on the machine.

• Run: date -Iseconds and date
• Record the output in your reasoning/logs (include timezone offset)
• If time seems inconsistent with the user-provided context, call it out explicitly with an absolute timestamp

Web verification (MUST)

For any decision that depends on facts outside the local repository or user-provided text (including versions, policies, specs, security guidance, compatibility claims, recommended tooling, or anything time-sensitive), you MUST verify via the internet using authoritative sources.

• Use web browsing/search before deciding
• Prefer primary/authoritative sources:
  • Official documentation, standards bodies, vendor release notes
  • Reputable institutions (e.g., government, academia, major foundations)
  • Primary papers or RFCs when relevant
• Always include:
  • What was verified
  • Which sources were used (links or clear citations)
  • The exact verification time (from the Time verification step)

If web verification is blocked

If network access/tools are unavailable or the user explicitly forbids browsing:

• Do not guess
• State what cannot be verified and why
• Ask for user-provided source/material, or offer safe fallback options that do not rely on unverified facts

🚨 CRITICAL ARCHITECTURE WARNING 🚨

You are operating in the root directory of a Git Worktree environment. The traditional git clone structure does NOT apply here.

• The actual Git database resides strictly inside the .bare/ directory.
• Other subdirectories (e.g., main/, feature-x/) are independent, linked worktrees.

📌 AGENTS.md Placement (Worktrees)

yaklang-workspace/ is a worktree manager directory (bare repo + multiple linked worktrees). When Codex or Cursor run inside a worktree (e.g. main/), they use files in that folder as the project root and do not reliably inherit this directory’s AGENTS.md or .cursor/.

After adding a new worktree, from this root run:

scripts/ensure-worktree-agent-links.sh

That symlinks AGENTS.md and .cursor from the workspace root into every top-level worktree (same as doing by hand):

• ln -sfn ../AGENTS.md <worktree-dir>/AGENTS.md
• ln -sfn ../.cursor <worktree-dir>/.cursor

🛠️ Execution Rules (MUST FOLLOW)

1. Branch Management (Strictly Worktree)

• FORBIDDEN: You MUST NEVER use git checkout, git switch, or git branch to change branches within any existing directory. This will corrupt the user's isolated contexts.

• NEW TASK / SWITCHING: To start a new feature, fix a bug, or check out a branch, you MUST create a new worktree directory from the root: git worktree add <relative-directory-name> <branch-name> (Example: git worktree add fixup-fuzztag-expand fix/fuzztag-expand)

• AFTER CREATING WORKTREE: Immediately run the linking script to ensure the new worktree has AGENTS.md, CLAUDE.md, .cursorrules, and .cursor symlinks: scripts/ensure-worktree-agent-links.sh This MUST be done automatically after every git worktree add command.

• BRANCH NAME FORMAT: For ordinary development branches, default to: <kind>/<scope>/<short-feature> where:

  • <kind> is one of fix, enhance, feature, doc, ci
  • <scope> is a concise area such as ssa, workflow, or syntaxflow
  • <short-feature> is a short, concrete slug describing the work (Example: fix/ssa/compile_instruction_stability, feature/syntaxflow/yaml_jsonpath_support)

• TEST BRANCH NAME FORMAT: For test-only branches, default to: test-<index>/<tag>/<original-branch-name> where:

  • <index> is the test sequence number for that line of testing, such as 1, 2, 3
  • <tag> is a short self-explanatory marker showing what or who the test is for, such as for-review, for-ci, for-alice, verify-fix
  • <original-branch-name> is the original development branch name kept after the test prefix, so the relationship stays obvious and cleanup is easy (Example: test-1/for-ci/fix/ssa/compile_instruction_stability, test-2/for-review/feature/syntaxflow/yaml_jsonpath_support)

• DIRECTORY DEPTH: Prefer a single-level worktree directory name at the root (no nested paths). Convert branch separators to - when needed. (Example: branch refactor/sfvm/value_condition -> directory refactor-sfvm-value_condition)

• CLEANUP: When a branch is merged or no longer needed, remove its worktree to keep the root directory clean: git worktree remove <relative-directory-name>

• SEMANTICS ("delete branch"/"删除分支"): This means deleting the local branch ref AND removing the corresponding worktree + directory. If meaningful untracked data exists, move it to build/backup/ first.

• MERGED-BRANCH SWEEP (worktree-safe :gone] cleanup): When the user asks to clean up branches whose PR was merged / whose remote ref was deleted (i.e. upstream is :gone]), use the worktree-safe two-step sweep below. Do NOT run the common git branch -vv | grep ': gone]' | awk '{print $1}' | xargs git branch -D one-liner directly — it fails on branches that still have a linked worktree and leaves orphaned worktree directories behind.

  1. Sync & prune remote refs (run from inside a worktree, e.g. main/; never run git fetch/prune from the read-only .bare/ root):

     cd <any-worktree>                 # e.g. main
     git fetch --all --prune

  2. For every branch whose upstream is now :gone], remove its worktree (if any) first, then delete the branch ref. A branch may have no worktree (e.g. plain git branch created locally) — git worktree remove is a no-op in that case. Run from the workspace root:

     cd <workspace-root>               # yaklang-workspace/
     git branch -vv | grep ': gone]' | awk '{print $1}' | while read b; do
       wt=$(git worktree list --porcelain | awk -v b="$b" '
            /^branch / { br=substr($0, index($0,$2)); }
            /^worktree / { wt=$2; }
            END { if (br==b) print wt; }')
       # 2a. remove the linked worktree (use --force only if untracked files are not worth backing up)
       [ -n "$wt" ] && git worktree remove "$wt" || git worktree remove --force "$wt"
       # 2b. delete the local branch
       git branch -D "$b"
     done

  • GUARD: Before git worktree remove --force, check git -C <wt> status --short. If there are meaningful untracked/modified files, move them to build/backup/ first (see §7). Trivial agent-generated dot-dirs (.claude/, .cursor symlinks, .db/) may be discarded with --force.
  • VERIFY: After the sweep, confirm no stragglers:

    git branch -vv | grep ': gone]'              # must be empty
    git worktree list                            # must show no orphaned dirs

  • NEVER prune or delete main or the currently checked-out branch; git branch -D refuses them anyway — surface such cases to the user instead of forcing.
  • READ-ONLY .bare/: Because the Git database lives under the read-only .bare/, always run git fetch/prune inside a worktree (e.g. main/), never from the workspace root. git worktree remove / git branch -D may be run from the root.

2. Context Isolation & Pathing

• Command Execution: Before running language servers, compilers, testing frameworks, or standard git commits (git add, git commit, git push), you MUST change your working directory (cd) into the specific target worktree folder.
• Read-Only Zone: NEVER read, modify, or suggest edits to any files inside the .bare/ directory or the .git file at the root.
• Path Awareness: When outputting terminal commands or explaining file modifications, always include the specific worktree prefix (e.g., write main/src/parser.go, NOT src/parser.go).
• Terminology (dev vs main): When the user says dev, treat it as the current development branch/worktree and its directory. Unless the user explicitly names another reference point, treat main as the baseline branch for comparisons, diffs, and summaries.

3. Pre-Commit Quality Gate

Before git commit (and ideally before git push), you MUST:

• Run the formatter(s) relevant to the files you changed (project conventions apply).
• Run the most relevant tests for your change and ensure they pass.

3.1 Testing Convention (MUST FOLLOW)

FORBIDDEN: Do NOT use go test to run tests. Always use the designated test script:

scripts/ssa-test.sh

This ensures consistent test execution across all environments and worktrees.

3.1 Git commit authorship (MUST)

• FORBIDDEN: Do not add Co-authored-by: (or any other co-author / agent attribution trailer) to commit messages.
• Commits must list only the human author; agent-assisted work is described in the message body if needed, not via co-author trailers.
• If git commit / --amend injects a co-author line (IDE hook, template, etc.), remove it before finishing the commit — e.g. rewrite with git commit-tree and git reset --hard, or rebase with a message filter that strips Co-authored-by: lines.
• Before push, verify the branch is clean: git log --format=%B <base>..HEAD | rg -i '^Co-authored-by:' must produce no output.

4. Syncing with Remote

• To update the repository with the latest remote changes, simply run git fetch --all from the root directory or inside any worktree. Because all worktrees share the .bare database, a fetch in one updates all.
• NETWORK FALLBACK: If git fetch, git pull, or git push fails because of network/DNS/proxy issues, prefer using an available proxy and retry the same command before other troubleshooting.

5. IDE / GitLens Compatibility

• DO NOT open the workspace root (yaklang-workspace/) as a Git project in VS Code Git/GitLens. This root is a management directory (bare + worktrees), not a normal worktree.
• Open a concrete worktree directory instead (for example main/ or refactor-ssa-compile_cleanup/), or use a multi-root workspace that includes only worktree folders.
• Exclude .bare/ from IDE repository scanning and never treat .bare/ as an editable project.

6. Database Locks (YAKIT_HOME)

When running any DB-related operations and you hit SQLite errors like database is locked, do NOT use a shared/global DB state across worktrees.

• Maintain a worktree-local database home directory named .db/ under the CURRENT worktree directory.
• Set YAKIT_HOME to this worktree-local .db/ directory before running the command.

Example (run inside a worktree like main/):

• mkdir -p .db
• export YAKIT_HOME="$PWD/.db"

7. Backups (build/backup/)

When you explicitly ask to “备份/backup”, or when the agent believes some data is meaningful to preserve, store it under yaklang-workspace/build/backup/ (from inside a worktree, use ../build/backup/).

8. Yaklang config + option Pattern

When writing Yaklang code that uses a config + option pattern:

• config MUST be a struct.
• option MUST be func(*config) (functional options; e.g. type Option func(*Config)).

9. ANTLR Usage

If you need to regenerate or run ANTLR-related code in this workspace:

• Do NOT download another ANTLR jar by default; use the bundled jar already in the repo.
• The checked path in a worktree is: common/yak/antlr4thirdparty/antlr-4.11.1-complete.jar
• This machine already has Java available, so prefer invoking the bundled jar with java -jar ...
• Example pattern (run inside the relevant worktree/module): java -jar ../antlr4thirdparty/antlr-4.11.1-complete.jar ...

10. Fortify Comparison Runs (~/Target/fortify-vs)

When testing Yaklang scan effectiveness or performance against the Fortify comparison corpus:

• Treat ~/Target/fortify-vs/ as the fixed input corpus. Do not rewrite source packages, Fortify PDF reports, or rules/rules-dencrypt.zip unless the user explicitly asks to refresh the corpus.
• Keep ~/Target/README.md as the top-level target inventory and ~/Target/STATUS.md as the append-only run ledger.
• Before each real run, record current time with date -Iseconds and date.
• Record Yaklang source worktree, branch, full commit hash, commit time, commit subject, yak binary path, and full yak version --json output.
• Prefer existing Yaklang CLI workflows such as code-scan and ssa-compile; do not create a new standalone benchmark tool unless the user asks for one.
• For diagnostics/performance runs, default to YAK_DIAGNOSTICS_LOG_LEVEL=trace unless the user says otherwise.
• Put generated results in a dated directory such as ~/Target/fortify-vs/results/YYYYMMDD-HHMMSS-<yak-commit>/, then link that directory from ~/Target/STATUS.md.
• Each status entry must include command, important environment variables, output path, runtime, memory metrics if collected, Yaklang result counts, Fortify baseline used, match/delta notes, and a clear conclusion.
• If a run touches the Yaklang database, use a worktree-local .db/ through YAKIT_HOME to avoid cross-worktree SQLite locks.
• Do not claim a run is a valid comparison unless the Yaklang command completed and the output was inspected or summarized.

11. SSA Compilation Performance Profiling (MUST FOLLOW)

When running yak code-scan or yak ssa-compile on test projects, you MUST collect performance profiles:

11.1 Pprof Collection (5-minute mark)

After starting yak code-scan or yak ssa-compile, take pprof snapshots at the 5-minute mark:

# CPU profile (30-second sample)
curl -s http://localhost:6060/debug/pprof/profile?seconds=30 > cpu/$(date +%H%M%S).cpu.prof

# Memory heap profile
curl -s http://localhost:6060/debug/pprof/heap > mem/$(date +%H%M%S).mem.prof

# Goroutine profile (for deadlock detection)
curl -s http://localhost:6060/debug/pprof/goroutine > goroutine/$(date +%H%M%S).goroutine.prof

11.2 Profile Storage (per-test directory)

Each test run gets its own directory under build/pprof/:

build/pprof/<test-name>/
├── cpu/
│   ├── 050000.cpu.prof
│   └── 100000.cpu.prof
├── mem/
│   ├── 050000.mem.prof
│   └── 100000.mem.prof
├── goroutine/
│   ├── 050000.goroutine.prof
│   └── 100000.goroutine.prof
└── summary.md          # Human-readable analysis

Example: build/pprof/spring-cve-2024-22243/, build/pprof/go-cms-project/

11.3 Performance Analysis (summary.md)

The summary.md MUST include:

• Runtime: Total execution time, time to first result
• CPU: Top functions by CPU time, hotspots, unexpected busy-waits
• Memory: Heap allocations, top allocators, memory growth pattern
• Goroutines: Count, blocked goroutines, potential deadlocks
• Correctness Check: Verify CPU is NOT spinning in incorrect locations (e.g., infinite loops, stuck goroutines)

11.4 Correctness Verification

After profiling, verify the run is correct:

• CPU usage should correlate with actual work (not idle spinning)
• Memory should not grow unboundedly
• Goroutines should complete or be properly cleaned up
• If CPU is stuck in unexpected location, investigate and fix before proceeding

12. SSA Code Modification Checklist (MUST FOLLOW)

When modifying ANY code under common/yak/ssa/, common/yak/ssaapi/, or SSA-related packages:

12.1 Pre-Commit Gate (BLOCKING)

Before git commit, ensure:

• yak binary compiles successfully: go build -o yak ./common/yak/cmds/yak.go
• No compilation errors in modified SSA packages

12.2 Pre-Push Gate (BLOCKING)

Before git push, ensure:

• yak binary compiles successfully
• scripts/ssa-test.sh passes (pre-existing failures noted in baseline are acceptable)
• Pprof shows no correctness issues (CPU stuck, memory leak, deadlock)

12.3 Test Failure Handling

If SSA tests fail after your changes:

1. Read the failure output carefully
2. Fix the root cause in your code
3. Re-run scripts/ssa-test.sh until clean
4. Do NOT suppress tests, skip tests, or commit with known new failures