Replace parser surface with a Parsec compatibility layer

.agents/skills/haskell-pro/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: haskell-pro
+description: "Expert Haskell engineer specializing in advanced type systems, pure"
+risk: safe
+source: community
+date_added: "2026-02-27"
+---
+
+## Use this skill when
+
+- Working on haskell pro tasks or workflows
+- Needing guidance, best practices, or checklists for haskell pro
+
+## Do not use this skill when
+
+- The task is unrelated to haskell pro
+- You need a different domain or tool outside this scope
+
+## Instructions
+
+- Clarify goals, constraints, and required inputs.
+- Apply relevant best practices and validate outcomes.
+- Provide actionable steps and verification.
+- If detailed examples are required, open `resources/implementation-playbook.md`.
+
+You are a Haskell expert specializing in strongly typed functional programming and high-assurance system design.
+
+## Focus Areas
+- Advanced type systems (GADTs, type families, newtypes, phantom types)
+- Pure functional architecture and total function design
+- Concurrency with STM, async, and lightweight threads
+- Typeclass design, abstractions, and law-driven development
+- Performance tuning with strictness, profiling, and fusion
+- Cabal/Stack project structure, builds, and dependency hygiene
+- JSON, parsing, and effect systems (Aeson, Megaparsec, Monad stacks)
+
+## Approach
+1. Use expressive types, newtypes, and invariants to model domain logic
+2. Prefer pure functions and isolate IO to explicit boundaries
+3. Recommend safe, total alternatives to partial functions
+4. Use typeclasses and algebraic design only when they add clarity
+5. Keep modules small, explicit, and easy to reason about
+6. Suggest language extensions sparingly and explain their purpose
+7. Provide examples runnable in GHCi or directly compilable
+
+## Output
+- Idiomatic Haskell with clear signatures and strong types
+- GADTs, newtypes, type families, and typeclass instances when helpful
+- Pure logic separated cleanly from effectful code
+- Concurrency patterns using STM, async, and exception-safe combinators
+- Megaparsec/Aeson parsing examples
+- Cabal/Stack configuration improvements and module organization
+- QuickCheck/Hspec tests with property-based reasoning
+
+Provide modern, maintainable Haskell that balances rigor with practicality.
+
+## Limitations
+- Use this skill only when the task clearly matches the scope described above.
+- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
+- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.

.agents/skills/htcc-ci-test-suite-coverage/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: htcc-ci-test-suite-coverage
+description: "Keep htcc CI workflows aligned with the test runner command matrix, especially explicit self/components/subp/docker lists."
+risk: safe
+source: project
+date_added: "2026-05-18"
+---
+
+## Use this skill when
+
+- Editing `.github/workflows/main.yml`, `.travis.yml`, Docker CI scripts, or the htcc test command selector.
+- Adding or renaming test commands such as `self`, `components`, `subp`, or `docker`.
+- Review feedback says a suite runs by default locally but is skipped in CI because CI enumerates commands explicitly.
+
+## Do not use this skill when
+
+- The task is unrelated to CI/test command coverage.
+
+## Required checks
+
+1. Search all CI command lists for explicit `stack test --test-arguments ...` invocations.
+2. Compare those lists to `commandsToRun` / command-selection behavior in the test runner.
+3. If a workflow lists `self` and `subp` explicitly, ensure `components` is also listed when component tests are required.
+4. Do not assume default command selection applies to CI steps that enumerate commands.
+
+## Known CI locations
+
+- `.github/workflows/main.yml`: GitHub Actions compiler tests.
+- `.travis.yml`: Travis compiler tests.
+- Docker-specific commands may remain separate: `stack test --test-arguments docker` and clean variants.
+- The Docker clean test command is `stack test --test-arguments docker --test-arguments --clean`.
+- README examples are documentation, not CI enforcement, unless the task explicitly asks to update docs.
+
+## Verification
+
+- Run the newly added command locally, for example:
+
+```bash
+stack test --test-arguments components
+```
+
+- Run `git diff --check`.
+- Parse changed YAML files. If `yaml-ls` is unavailable, use:
+
+```bash
+ruby -e 'require "yaml"; YAML.load_file(".github/workflows/main.yml"); YAML.load_file(".travis.yml"); puts "yaml ok"'
+```
+
+- Full `stack test` is optional for CI-only command-list changes unless the test runner itself changed.
+- Run Docker commands only when Docker is available locally. If unavailable, report them as unavailable and rely on CI definition inspection/YAML parsing rather than claiming local Docker success.
+
+## Review focus
+
+- Every explicit CI compiler-test list includes the required suite.
+- Added commands are in the same stage as related compiler tests.
+- No secrets, permissions, or checkout credentials are broadened.
+- Docker commands are not mixed into non-Docker stages.

.agents/skills/htcc-ci-test-suite-coverage/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "HTCC CI Test Suite Coverage"
+  short_description: "Keep htcc CI test suites aligned"
+  default_prompt: "Use $htcc-ci-test-suite-coverage to keep htcc CI test command lists aligned with the test runner."

.agents/skills/htcc-output-permission-workflow/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: htcc-output-permission-workflow
+description: "Work safely on htcc output replacement, fallback copy, file mode preservation, rollback, symlink, and hard-link behavior."
+risk: safe
+source: project
+date_added: "2026-05-18"
+---
+
+## Use this skill when
+
+- Editing `src/Htcc/Output.hs` or code that writes `-o` outputs, visualization outputs, staging files, backups, or direct replacement paths.
+- Review feedback mentions `setFileMode`, owner/group/other permissions, read-only directories, fallback copies, stale output, symlinks, hard links, or rollback.
+
+## Do not use this skill when
+
+- The output path is not touched and the task is only parser/codegen logic.
+
+## Key invariants
+
+- Existing output content must not be lost on failed replacement.
+- Existing output mode should be preserved unless the mode strategy intentionally changes executable bits.
+- Direct fallback must not preemptively `chmod` when a write/copy could already succeed through group or other permissions.
+- Hard-linked outputs must remain protected by `ensureInPlaceReplacementSafe`.
+- Symlink behavior must match existing resolution rules; do not add broad symlink rewrites while fixing permission bugs.
+
+## Test patterns
+
+- Component tests belong in `test/Tests/ComponentsTests/AsmOutput.hs` near existing fallback/permission tests.
+- Use custom `copyReplacementOutput` functions to assert ordering, mode at copy time, partial-write rollback, or failure surfacing.
+- Use temp files from `openTempFile`, close handles before mode changes, and cleanup with `catchIOError`-guarded removal.
+- Test file modes with `fileMode <$> getFileStatus` and `intersectFileModes replacedMode 0o777`.
+
+## Manual QA patterns
+
+- For fallback replacement, create a read-only directory so staging in the output directory fails and direct replacement is exercised.
+- Verify:
+  - command exit status,
+  - stdout/stderr,
+  - output file contains expected assembly such as `.global main`,
+  - stale output is preserved when failure is expected,
+  - file mode is restored when mode behavior is the contract.
+
+Example shape:
+
+```bash
+tmpdir=$(mktemp -d /tmp/htcc-output-fallback.XXXXXX)
+target="$tmpdir/out.s"
+cleanup() {
+  chmod u+rw "$target" 2>/dev/null || true
+  chmod u+rwx "$tmpdir" 2>/dev/null || true
+  rm -rf -- "$tmpdir"
+}
+trap cleanup EXIT
+printf 'stale output\n' > "$target"
+chmod 444 "$target"
+chmod 555 "$tmpdir"
+printf 'int main(void) { return 0; }\n' | stack exec htcc -- -o "$target" /dev/stdin
+```
+
+Always restore permissions before cleanup; use a `trap` so interrupted QA does not leave read-only temp paths behind.
+
+## Verification
+
+- `stylish-haskell -i src/Htcc/Output.hs test/Tests/ComponentsTests/AsmOutput.hs`
+- `lsp_diagnostics` on both files when the diagnostics tool is available. If unavailable, state that and substitute `stack build` plus the relevant test command.
+- `stack test --test-arguments components`.
+- Full `stack test` when output replacement affects subprocess behavior.
+- `stack build`.
+- Manual permission/fallback QA.
+
+## Review focus
+
+- Ordering of `copy`, `chmod`, `restore`, and `rollback`.
+- PermissionError-only fallback; non-permission errors should not be silently retried as permission problems.
+- Data loss during partial replacement and restoration failure reporting.

.agents/skills/htcc-output-permission-workflow/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "HTCC Output Permission Workflow"
+  short_description: "Guide htcc output permission fixes"
+  default_prompt: "Use $htcc-output-permission-workflow to handle htcc output replacement and permission regressions safely."

.agents/skills/htcc-parser-regression-workflow/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: htcc-parser-regression-workflow
+description: "Fix htcc parser regressions with focused component tests, malformed-input QA, and nontermination safeguards."
+risk: safe
+source: project
+date_added: "2026-05-18"
+---
+
+## Use this skill when
+
+- Editing `src/Htcc/Parser/**` or parser-facing code in `app/Main.hs`.
+- Review feedback mentions parse acceptance, parse errors, `ATEmpty`, `manyTill`, EOF, `Megaparsec`, scope restoration, declarations, initializers, or implicit calls.
+- A malformed C input can hang, parse successfully by mistake, or produce the wrong diagnostic.
+
+## Do not use this skill when
+
+- The change is pure codegen/output behavior after parsing has already succeeded.
+
+## Investigation steps
+
+1. Read the exact parser function and the nearest combinators it composes with.
+2. Search for zero-width success in recursive or repeated contexts: `M.many`, `M.manyTill`, `M.option`, `ATEmpty`, `M.eof`, `M.try`.
+3. Identify whether the parser must fail, consume input, or produce `ATEmpty` intentionally.
+4. Check existing component tests in `test/Tests/ComponentsTests/Parser/Combinators.hs` before adding new helpers.
+
+## Regression test placement
+
+- Put parser unit regressions in `test/Tests/ComponentsTests/Parser/Combinators.hs` when direct `parseProgram`, `parseAssignExpr`, or helper assertions can reproduce the bug.
+- Put CLI parser regressions in subprocess tests only when stderr/exit-code behavior is the relevant contract.
+- Prefer adding cases under the existing `Parser.Program.*` group matching the construct, such as `function-call`, `scalar-initializer`, or `function-pointer-arithmetic`.
+- For call argument lists, trailing commas such as `f(1,)` are malformed. For initializer lists, check existing accepted C-like trailing-comma behavior before turning a trailing comma into a rejection.
+- For initializer EOF regressions, consider both file-scope and local-scope shapes such as `int g =`, `int g = {1`, and `int main(){ int x =`.
+
+## Nontermination safeguards
+
+- Any bug involving EOF, repeated combinators, or `manyTill` must have a timeout-guarded manual QA command, for example:
+
+```bash
+printf 'int main(){ return f(' | timeout 5s stack exec htcc -- /dev/stdin
+```
+
+- The expected outcome for malformed input is non-zero exit before the timeout, not success.
+- Use `timeout` or `gtimeout`, whichever exists on the host, and report the command used.
+- Do not fix nontermination by accepting malformed input as `ATEmpty`.
+
+## Verification
+
+- `stylish-haskell -i <all changed .hs files, including app/Main.hs when touched> test/Tests/ComponentsTests/Parser/Combinators.hs`
+- `lsp_diagnostics` on edited Haskell files when the diagnostics tool is available. If unavailable, state that and substitute `stack build` plus the relevant test command.
+- `stack test --test-arguments components`.
+- Full `stack test` for parser-wide behavior or when the change affects common expression/statement parsing.
+- `stack build`.
+- Manual CLI QA for malformed inputs when user-visible parser behavior or hangs are involved.
+
+## Review focus
+
+- Does the fix remove the bad acceptance path without breaking intended empty statements or empty `for` sections?
+- Do the tests cover both minimal malformed shape and comma/trailing-argument shape where applicable?
+- Does the parser fail with a parse error rather than looping or producing a misleading successful AST?

.agents/skills/htcc-parser-regression-workflow/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "HTCC Parser Regression Workflow"
+  short_description: "Fix htcc parser regressions safely"
+  default_prompt: "Use $htcc-parser-regression-workflow to fix htcc parser regressions with focused tests and malformed-input QA."

.agents/skills/htcc-review-comment-response/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: htcc-review-comment-response
+description: "Handle htcc review comments end-to-end: reproduce, judge validity, apply minimal fixes, verify, review, and prepare commit/push."
+risk: safe
+source: project
+date_added: "2026-05-18"
+---
+
+## Use this skill when
+
+- Addressing GitHub, Codex, or reviewer comments against this htcc repository.
+- The comment points at parser, CLI, CI, codegen, output replacement, Docker, or test behavior.
+- You need to decide whether a review finding is valid before changing code.
+
+## Do not use this skill when
+
+- The task is only to explain a comment without changing or verifying anything.
+- The task is a generic Haskell question unrelated to htcc review feedback.
+
+## Core workflow
+
+1. Read the exact reviewed file and nearby code before judging the comment.
+2. Reproduce or reason from the current diff; do not assume the reviewer is right.
+3. If valid, make the smallest behavior-preserving fix that addresses exactly the comment.
+4. Add or extend a regression test that fails on the reviewed bug shape.
+5. Run the htcc verification matrix for the touched area.
+6. Launch independent review agents after implementation:
+   - at least two general/code reviewers for behavior and tests,
+   - one security/operational reviewer.
+7. Wait 180-300 seconds when reviewer results are a prerequisite. Treat `No agents completed yet` as pending, not failure, and do not mark review complete while required reviewers are still unfinished.
+8. If a reviewer returns empty output, retry or report that reviewer as unavailable; do not silently replace a required review with an unrelated fallback.
+9. If all review findings are resolved and the user explicitly asks for a commit, commit with `--no-gpg-sign` and follow the current repo/user rules for trailers. Do not add co-author or other trailers unless the current repo/user rules or the user explicitly require them. Push only after explicit request.
+
+## GitHub review threads
+
+- When a GitHub PR URL or unresolved review threads are part of the task, use `gh` or an available GitHub connector to fetch PR metadata, inline review context, and current diff before editing.
+- If thread resolution state matters, prefer a GitHub connector or `gh` GraphQL query that exposes unresolved/resolved thread state; flat review comments alone are not enough.
+- Stop before commit or push when the user asks to fix comments without publishing local changes.
+
+## Validity checklist
+
+- Does the comment cite reachable code on this branch?
+- Does the described bad behavior still exist after earlier commits?
+- Can a focused test or timeout-guarded command distinguish old and fixed behavior?
+- Is the requested behavior consistent with existing htcc patterns?
+- Would the fix broaden scope beyond the review comment? If yes, reduce it.
+
+## Verification requirements
+
+- Always run `stylish-haskell -i` for edited Haskell files.
+- Always run `lsp_diagnostics` on edited Haskell files when the diagnostics tool is available. If unavailable, state that and substitute `stack build` plus the relevant test command.
+- Always run the smallest relevant `stack test --test-arguments ...` command, then full `stack test` when parser/core behavior changed.
+- Always run a real CLI/manual QA command when the change affects the executable, output files, CI commands, or malformed-input behavior.
+- Report any unavailable verifier explicitly, with the substitute used.
+
+## Common htcc review patterns
+
+- Parser nontermination or malformed input: use `timeout` or `gtimeout` around `stack exec htcc -- /dev/stdin` and add component parser tests.
+- CLI diagnostics: assert stderr text, exit code, stdout absence, and absence of Haskell exception internals such as `HasCallStack`.
+- Output replacement and permission handling: test file modes, stale-output preservation, rollback, symlink/hard-link safety, and manual read-only directory scenarios.
+- CI test coverage: check every explicit CI command list; defaults in `commandsToRun` do not affect workflows that enumerate commands.
+
+## Output format
+
+- State whether each review comment was valid.
+- Summarize the minimal fix and regression test.
+- List verification commands and outcomes.
+- List reviewer outcomes and any declined findings with reasons.

.agents/skills/htcc-review-comment-response/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "HTCC Review Comment Response"
+  short_description: "Resolve htcc review comments safely"
+  default_prompt: "Use $htcc-review-comment-response to validate and address htcc review comments end to end."