[showcase] gitban board & agent reasoning behind #399 (not for merge) - #400

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.gitban/hooks/agent-log.sh:
- Around line 68-80: The _agent_log_derive_path function currently suppresses
mkdir/cd failures which can produce a root-path result; remove the "|| true" and
explicitly check the results of mkdir and cd, returning non-zero if either fails
so we don't silently produce a bad path. Concretely, in _agent_log_derive_path
validate mkdir -p "$log_dir" succeeded (or return 1), then run cd "$log_dir" and
if cd fails return 1 before calling pwd; finally build and printf the path using
the ensured absolute directory and the
${sprint}-${card_id}-${role}-${cycle}.jsonl filename.

In @.gitban/roadmap/roadmap-usage.md:
- Around line 35-40: Update the fenced code block in roadmap-usage.md to include
the language specifier "text" on the opening fence so the hierarchy diagram
renders correctly; locate the block that currently starts with ``` and replace
it with ```text while leaving the inner lines (milestones ... features) and the
closing ``` unchanged.
- Around line 111-114: The fenced code block showing the error example in
roadmap-usage.md should include a language specifier for proper rendering;
change the opening fence from ``` to ```text so the block reads as a text code
fence (leave the closing ``` unchanged). Locate the block around the Error:
Milestone 'm9' not found example and update the fence accordingly; no other
content changes are needed.

In @.gitban/templates/bug-escalation.md:
- Line 107: The document uses h4 (####) for iteration detail headings and the
"Diagnostic Code" section which breaks the hierarchy; change those headings to
h3 (###) so the outline flows h2 → h3 → h4. Specifically update the heading text
like "Iteration 1: [Hypothesis Summary]" and the "Diagnostic Code" blocks (and
any subsequent "Iteration X" headings) to use ### instead of ####; apply the
same change to the other matching iteration/diagnostic headings in the file.

In @.gitban/templates/bug-infrastructure.md:
- Line 174: Several "Iteration" sections jump from h2 to h4 causing a hierarchy
skip; locate the headings like "Iteration 1: [Hypothesis Summary]" and the other
iteration headings (the lines using "#### Iteration ...") and change those from
level-4 headings (####) to level-3 headings (###) so the document uses h2 → h3 →
h4 ordering consistently; update each occurrence (e.g., "Iteration 1:
[Hypothesis Summary]" and the other iteration headings) accordingly.
- Around line 156-158: Update the code block marker in the bug-infrastructure.md
template to include a language specifier for proper syntax highlighting: replace
the bare triple-backtick block delimiter used for the error/stack trace with a
language-tagged delimiter (e.g., change "```" to "```text" or "```log") so the
block that currently contains "[Paste exact error message and stack trace here]"
renders with the chosen highlighting; ensure only the opening fence is modified
and the closing "```" remains.

In @.gitban/templates/bug-pipeline.md:
- Line 127: The Fix Implementation Details header currently uses h4 ("#### Fix
Implementation Details (optional)") which breaks the document hierarchy; change
that specific header line to h3 ("### Fix Implementation Details (optional)") so
it flows H2 → H3 → H4 correctly and preserves proper markdown structure in the
.gitban/templates/bug-pipeline.md file.
- Line 74: The heading "Iteration 1: [Hypothesis Summary]" and other iteration
detail headings currently use an h4 under an h2 (skipping h3); update those
iteration section headings (the lines containing "Iteration 1: [Hypothesis
Summary]" and the similar occurrence at the other location) from h4 (####) to h3
(###) so the hierarchy is h2 → h3 → h4 consistently; locate and replace the
heading markers for the identified iteration headings in the template.
- Around line 83-85: The "Supporting Evidence" fenced code blocks should include
a blank line before and after the content and specify the language for syntax
highlighting; replace each plain ``` block that contains "[Paste relevant log
snippets, query results, or stack traces here]" with a fenced block using
```text, ensuring there is an empty line immediately inside the opening fence
and an empty line before the closing fence — apply this change to both
occurrences of that placeholder block.

In @.gitban/templates/bug-ui.md:
- Around line 43-44: The "Visual Design Review" and other h3 subsection headings
under "UI Investigation Areas" are missing blank lines after the headings;
update the template to insert a single blank line immediately after each h3
heading (e.g., after the "### Visual Design Review" heading and the three other
subsection headings referenced) so every subsection heading is followed by an
empty line for improved readability; apply this change to all four subsection
headings mentioned in the comment.

In @.gitban/templates/bug.md:
- Around line 86-96: Update the example error/stack trace code fence in the bug
template to declare the language (use ```json) so the example renders correctly;
locate the triple-backtick block containing the example JSON error (the block
starting with "[Paste exact error message and stack trace here]" and the sample
500 Internal Server Error object) and replace the opening fence with ```json and
ensure the contained example is valid JSON formatting.

In @.gitban/templates/chore-basic.md:
- Line 51: The "Work Notes" heading in .gitban/templates/chore-basic.md is
currently an h4 (#### Work Notes) placed under an h2, so change it to an h3 (###
Work Notes) to fix the heading hierarchy; locate the "Work Notes" line in the
file and replace the four-pound heading with three pounds so it becomes "###
Work Notes".
- Around line 55-60: Add a single blank line before the fenced code block that
follows the "Commands/Scripts Used:" heading so the Markdown renders correctly;
locate the "Commands/Scripts Used:" heading and insert one empty line
immediately before the ```bash code fence that begins the example commands.

In @.gitban/templates/chore-style.md:
- Line 76: Update the heading "Tooling Configuration" from an h4 (#### Tooling
Configuration) to an h3 (### Tooling Configuration) so the heading hierarchy is
correct under the existing h2; locate the line containing the "Tooling
Configuration" heading and replace the four hashes with three.

In @.gitban/templates/chore-triage.md:
- Line 159: The heading level for the "Card 1" section is incorrect (it uses
"#### Card 1: [Card ID] - [Card Title]" which jumps from h3 to h4); change the
leading "####" to "###" so the heading becomes "### Card 1: [Card ID] - [Card
Title]" to restore the proper h3 level.
- Around line 199-206: The markdown has a code fence for the Python example that
is missing a blank line before the opening ```python fence; add a single blank
line immediately above the line that starts the code block so the block renders
correctly, e.g. ensure the paragraph that precedes the fence is separated by an
empty line before the ```python line that wraps the archive_cards(...) example
(including references to archive_name and card_ids).
- Around line 230-231: Insert a single blank line between the footer marker "===
MANDATORY CARD FOOTER ===" and the heading "### Note on validation" so the
heading is separated by an empty line from the previous line; update the
template around those symbols to ensure the heading has one blank line above it.
- Around line 118-133: The fenced decision-tree code block in chore-triage.md is
missing a language identifier; update the opening triple-backtick for the block
that begins with "Is there intentional work here? (not spam/test/empty)" to
include a language label (e.g., ```text) so the block is explicitly marked as
plain text, leaving the block contents unchanged and keeping the closing
triple-backticks as-is.
- Around line 103-114: The opening code fence "```markdown" in the chore-triage
template must have a blank line before it; update the template so there is an
empty line between the preceding text ("⚠️ **TRIAGED: Intentional work, needs
refinement**" or any preceding paragraph) and the opening fence, ensuring the
fenced block begins on its own line (look for the exact "```markdown" fence in
the template).

In @.gitban/templates/content-article.md:
- Around line 417-418: Insert a blank line immediately above the "### Note on
validation" heading in the template so the footer heading is separated from the
preceding content (the "=== MANDATORY CARD FOOTER ===" block); locate the "###
Note on validation" heading in .gitban/templates/content-article.md and add a
single empty line before it to ensure proper Markdown separation.
- Line 274: Change the incorrect heading level "#### Iteration 1: [Pass Goal
Summary]" (currently an h4) to an h3 by using "### Iteration 1: [Pass Goal
Summary]" so the document's heading hierarchy increments correctly from the
previous h2; update the heading token in the template content-article.md where
that heading appears.

In @.gitban/templates/documentation-adr.md:
- Line 105: The heading "#### ADR Structure Reference" is incorrectly an h4 and
should be h3 to maintain proper sequence; update the heading text from "#### ADR
Structure Reference" to "### ADR Structure Reference" so the document flows h2
-> h3 -> ... and ensure any adjacent headings follow the same level pattern;
verify the heading token change in the template where "ADR Structure Reference"
appears.

In @.gitban/templates/feature-api.md:
- Line 106: The "API Implementation Notes" heading is currently rendered as an
h4 while the previous heading is h2, causing a level jump; change that heading
markup from h4 to h3 so the sequence goes h2 -> h3. Locate the heading text "API
Implementation Notes" in the .gitban template and replace the four-hash ("####")
prefix with three-hash ("###") to fix the heading level.
- Around line 110-118: The markdown section "Middleware Stack:" lacks a blank
line before the opening code fence; update the template so there is an empty
line immediately before the ```python fence above the example that shows
app.use('/api/v2/users', [authMiddleware, rateLimitMiddleware,
validationMiddleware]) to ensure the code block renders correctly.

In @.gitban/templates/feature-infrastructure.md:
- Line 151: The heading "#### IaC Implementation Notes" is incorrectly an h4;
change it to h3 by replacing "#### IaC Implementation Notes" with "### IaC
Implementation Notes" so the document flows from h2 to h3 correctly and
maintains proper heading hierarchy.
- Around line 155-173: The fenced directory example in the template lacks a
blank line before the opening backticks and no language is specified; edit the
feature-infrastructure template to insert a blank line directly above the
opening ``` and change the fence to include a language identifier (e.g.,
```text) so the block reads with an empty line before it and starts with ```text
to render correctly.

In @.gitban/templates/feature-ui.md:
- Line 111: The "Implementation Notes" heading uses h4 (#### Implementation
Notes) which breaks the heading hierarchy; change that heading to h3 by
replacing "#### Implementation Notes" with "### Implementation Notes" so the
document flows correctly from the previous h2 to this subsection.
- Around line 116-125: The fenced code block starting with ```tsx and the React
example lacks a preceding blank line (and ideally a trailing blank line), which
breaks Markdown parsing; add a blank line immediately before the opening ```tsx
and ensure there is a blank line after the closing ``` so the code block is
separated from surrounding text and renders correctly.

In @.gitban/templates/feedback.md:
- Line 107: The heading "#### Iteration 1: [Analysis Goal Summary, e.g., \"Scope
Assessment\"]" violates hierarchy by jumping from h2 to h4; change that markdown
heading marker from '####' to '###' so it becomes a proper h3 ("### Iteration 1:
...") ensuring consistent heading levels in the template.
- Line 117: The heading "Iteration 2: [Analysis Goal Summary, e.g., "Root Cause
Validation"]" is an h4 while previous section uses h2, causing a heading
hierarchy violation; change that heading to an h3 so the sequence goes h2 → h3,
updating the Markdown heading for the line containing "Iteration 2: [Analysis
Goal Summary, e.g., \"Root Cause Validation\"]" (replace the leading "####" with
"###") to restore proper heading structure.
- Line 153: Change the heading "Action Decision" from level 4 to level 3 to fix
the hierarchy gap (replace "#### Action Decision" with "### Action Decision");
locate the literal heading "Action Decision" in the template and update its
markdown prefix so the document flows H2 → H3 → H4 correctly.

In @.gitban/templates/performance.md:
- Line 205: The heading "Implementation Notes" is currently at level h4 (####
Implementation Notes) causing a hierarchy jump from h2; change that heading to
h3 by replacing "#### Implementation Notes" with "### Implementation Notes" so
the document follows proper heading order.
- Line 128: The heading "#### Iteration 1: [Optimization Summary, e.g.,
"Database Index Optimization"]" breaks the hierarchy by jumping from an h2 to an
h4; change this line to an h3 ("### Iteration 1: ...") so it properly follows
the preceding h2 and maintains correct heading structure in
.gitban/templates/performance.md.
- Line 183: The heading "#### Iteration 3: [Optimization Summary]" breaks the
hierarchy by jumping from h2 to h4; change that heading to an h3 (use "###
Iteration 3: [Optimization Summary]") so the document follows proper h2 → h3 →
h4 structure and preserves semantic outline.
- Line 156: The heading "#### Iteration 2: [Optimization Summary, e.g., \"User
Profile Caching\"]" breaks the heading hierarchy by jumping from h2 to h4;
change the "####" to "###" so the line reads "### Iteration 2: [Optimization
Summary, e.g., \"User Profile Caching\"]" and restore proper sequential heading
levels.

In @.gitban/templates/README.md:
- Around line 38-40: The code fences in the README templates are missing
language specifiers and blank lines before the closing backticks which breaks
Markdown rendering; update the block that contains the
`{canonical-type}-{variant-name}.md` example to use a fenced code block with a
language (e.g., ```text or ```md) and ensure there's a blank line before the
closing ```; likewise update the block around the `generate_template_example()`
Python snippet to start with ```python and include a trailing blank line before
the closing ```, so both examples render correctly.

In @.gitban/templates/refactor-large.md:
- Line 196: The heading "Strangler Fig Best Practices" is using an h4 (####)
which violates the heading hierarchy; change that line to an h3 (### Strangler
Fig Best Practices) so it flows correctly from the surrounding h2 and maintains
proper markdown structure in the refactor-large.md template.
- Around line 211-221: The markdown template is missing a blank line before the
fenced code block; update the template so there is a blank line immediately
before the ```python fence that begins the example (the block showing
route_auth_request). Ensure the blank line precedes the code fence that contains
the route_auth_request function and its references to get_rollout_percentage,
should_use_new_service, new_user_service, and old_monolith so the fenced block
renders correctly.

In @.gitban/templates/refactor.md:
- Line 147: The "#### Refactoring Implementation Notes" heading is a level-4
header that breaks the hierarchy after an h2; change that header to a level-3
header ("### Refactoring Implementation Notes") so the document flows h2 → h3 →
... and update any adjacent heading levels if needed to keep consistent
hierarchy around the "Refactoring Implementation Notes" section.
- Around line 167-193: The Markdown in the template has a fenced code block but
is missing a blank line immediately before the triple-backticks; insert a single
blank line above the code fence so the block renders correctly. Locate the shown
refactor example (the code that defines authenticate_user, validate_two_factor,
create_session, and login) and add the blank line just before the opening ``` to
ensure proper Markdown formatting.

In @.gitban/templates/spike-idea.md:
- Line 94: The heading "Exploration 1: [Exploration Summary, e.g., \"Customer
Interest Validation\"]" is using h4 (####) but should be h3 to preserve
hierarchy after the existing h2; update that heading from #### to ### and
likewise change the "Exploration 2" heading to ### so both are proper h3
children under the preceding h2 heading.

In @.gitban/templates/spike-postmortem.md:
- Around line 183-187: The table header defines six columns ("Test | Type |
Location | Status | Permanent Fix | Date Passed") but each data row only has
five cells (e.g., rows with "[title] | [unit/integration/e2e/other] |
[new/updated/removed] | [detailed description...] | [datetime]"), causing a
column mismatch; update each data row to include the missing "Location" cell (or
remove the "Location" header if intended) so rows match the header—look for the
header string and the placeholder rows with "[title]" to correct them
consistently.

In @.gitban/templates/spike.md:
- Line 106: Change the incorrect h4 headings for the iteration sections to h3 so
the document hierarchy is consistent: replace the "#### Iteration 1: [Iteration
Summary, e.g., "Baseline Performance Comparison"]" heading with "### Iteration
1..." and make the same change for the "Iteration 2" and "Iteration 3" headings
so they are all h3 under the existing h2.

In @.gitban/templates/test.md:
- Around line 105-107: The code fence in the template currently lacks a language
identifier for syntax highlighting; update the fenced block containing
"[Pseudocode or actual setup code for test fixtures]" to include an explicit
language (for example use ```text for pseudocode or ```python / ```javascript
for actual fixtures) so the snippet renders with proper highlighting and clarity
in the generated template.